claude-dev-env 1.34.1 → 1.36.0

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -0,0 +1,244 @@
+"""Tests for unused module-level import detection.
+
+Bot reviewers on PR #257 and PR #289 flagged FLAG_INCREMENTAL,
+ALL_REPOSITORY_ROOT_MARKER_FILENAMES, VENV_DIRECTORY_NAME and other
+imports that survived into a PR without ever being referenced.
+
+The detector is intentionally narrow: it only flags `from X import Y`
+or `import X` where Y/X is never referenced in the file body, the file
+does not declare `__all__`, and the file does not use TYPE_CHECKING
+conditional imports. The narrow scope keeps false positives low.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_enforcer",
+    _HOOK_DIRECTORY / "code_rules_enforcer.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)
+check_unused_module_level_imports = _hook_module.check_unused_module_level_imports
+
+
+PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+TEST_FILE_PATH = "packages/app/tests/test_loader.py"
+
+
+def test_should_flag_unused_from_import() -> None:
+    source = (
+        "from config.preflight_constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("VENV_DIRECTORY_NAME" in each_issue for each_issue in issues), (
+        f"Expected VENV_DIRECTORY_NAME flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_used_from_import() -> None:
+    source = (
+        "from config.preflight_constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        "def run() -> str:\n"
+        "    return VENV_DIRECTORY_NAME\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Used import must not be flagged, got: {issues}"
+
+
+def test_should_flag_unused_plain_import() -> None:
+    source = "import json\n\ndef run() -> None:\n    return None\n"
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("json" in each_issue for each_issue in issues), (
+        f"Expected unused 'import json' flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_alias_is_used() -> None:
+    source = "import json as _json\n\ndef run() -> str:\n    return _json.dumps({})\n"
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Aliased import referenced via alias must not flag, got: {issues}"
+    )
+
+
+def test_should_skip_file_with_dunder_all() -> None:
+    source = (
+        "from config.preflight_constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        "__all__ = ['something']\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Files declaring __all__ may re-export — skip to avoid false positives, got: {issues}"
+    )
+
+
+def test_should_skip_file_with_dunder_all_annotated_assignment() -> None:
+    source = (
+        "from config.preflight_constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        '__all__: list[str] = ["VENV_DIRECTORY_NAME"]\n'
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "Annotated __all__ must skip unused-import scan like plain __all__, "
+        f"got: {issues}"
+    )
+
+
+def test_should_skip_file_using_type_checking_block() -> None:
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from config.constants import UNUSED_NAME\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from somewhere import OtherName\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"TYPE_CHECKING-using files have annotation-only imports — skip, got: {issues}"
+    )
+
+
+def test_should_skip_test_files() -> None:
+    source = (
+        "from config.constants import UNUSED_NAME\n"
+        "\n"
+        "def test_thing() -> None:\n"
+        "    assert True\n"
+    )
+    issues = check_unused_module_level_imports(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "from config import (\n  not python\n"
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Parse failure must return empty, got: {issues}"
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = (
+        "\n"
+        "from config.preflight_constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("Line 2" in each_issue for each_issue in issues), (
+        f"Expected line 2 reference, got: {issues}"
+    )
+
+
+def test_should_flag_each_unused_in_multi_import() -> None:
+    source = (
+        "from config.constants import USED_ONE, UNUSED_TWO\n"
+        "\n"
+        "def run() -> str:\n"
+        "    return USED_ONE\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED_TWO" in each_issue for each_issue in issues), (
+        f"Expected UNUSED_TWO flagged independently, got: {issues}"
+    )
+    assert not any("USED_ONE" in each_issue for each_issue in issues), (
+        f"USED_ONE is referenced — must not flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_referenced_in_string_annotation() -> None:
+    source = (
+        "from typing import List\n\ndef run(xs: List[int]) -> None:\n    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"List used in annotation must count as a reference, got: {issues}"
+    )
+
+
+def test_should_skip_noqa_marked_imports() -> None:
+    source = (
+        "from config.constants import UNUSED_BUT_DELIBERATE  # noqa: F401\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"noqa-marked imports are deliberate side-effect imports, skip, got: {issues}"
+    )
+
+
+def test_should_skip_noqa_on_from_keyword_line_for_multiline_import() -> None:
+    source = (
+        "from config.constants import (  # noqa: F401\n"
+        "    SOME_CONSTANT,\n"
+        "    ANOTHER_CONSTANT,\n"
+        ")\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"noqa on the from-keyword line must suppress every alias in the block, got: {issues}"
+    )
+
+
+def test_should_skip_future_annotations_import() -> None:
+    source = (
+        "from __future__ import annotations\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"__future__ imports are behavior-changing side-effect imports whose "
+        f"binding name is never referenced — skip, got: {issues}"
+    )
+
+
+def test_should_skip_all_future_imports_regardless_of_name() -> None:
+    source = (
+        "from __future__ import annotations, division\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"All __future__ imports must be skipped regardless of binding name, got: {issues}"
+    )
+
+
+def test_should_skip_star_import() -> None:
+    source = (
+        "from os.path import *\n"
+        "\n"
+        "def run() -> str:\n"
+        "    return join('a', 'b')\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Star imports cannot be meaningfully tracked - skip to avoid false positives, got: {issues}"
+    )

package/hooks/blocking/test_es_exe_path_rewriter.py

@@ -39,9 +39,8 @@ OTHER_REPO_NAME = "other-repo"
 OTHER_REPO_PATH = "C:\\Dev\\other-repo"
 
 
-def _run_main_with_input(hook_input: dict) -> tuple[str, str, int]:
-    """Return (stdout, stderr, exit_code) from running main() with the given hook input."""
-    stdin_text = json.dumps(hook_input)
+def _run_main_with_stdin_text(stdin_text: str) -> tuple[str, str, int]:
+    """Return (stdout, stderr, exit_code) from running main() with the given stdin text."""
     captured_stdout = StringIO()
     captured_stderr = StringIO()
     exit_code = 0
@@ -57,6 +56,11 @@ def _run_main_with_input(hook_input: dict) -> tuple[str, str, int]:
     return captured_stdout.getvalue(), captured_stderr.getvalue(), exit_code
 
 
+def _run_main_with_input(hook_input: dict) -> tuple[str, str, int]:
+    """Return (stdout, stderr, exit_code) from running main() with the given hook input."""
+    return _run_main_with_stdin_text(json.dumps(hook_input))
+
+
 def _make_bash_input(command: str, description: str = "search files") -> dict:
     return {
         "tool_name": "Bash",
@@ -231,6 +235,80 @@ class TestEmittedJsonShape:
                 assert decision != "deny", f"deny returned for command: {command!r}"
 
 
+class TestStdinParsingRobustness:
+    def test_empty_stdin_exits_zero_without_stdout_or_stderr(self) -> None:
+        stdout, stderr, exit_code = _run_main_with_stdin_text("")
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+    def test_whitespace_only_stdin_exits_zero_without_stdout_or_stderr(self) -> None:
+        stdout, stderr, exit_code = _run_main_with_stdin_text("  \n\t ")
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+    def test_invalid_json_stdin_exits_zero_without_stdout_or_stderr(self) -> None:
+        stdout, stderr, exit_code = _run_main_with_stdin_text("{not valid")
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+
+class TestMalformedHookPayloadTypes:
+    def test_null_tool_input_exits_zero_without_stdout_or_stderr(self) -> None:
+        hook_input = {
+            "tool_name": "Bash",
+            "tool_input": None,
+        }
+        with patch(
+            "es_exe_path_rewriter.load_registry", return_value=REGISTRY_WITH_ONE_REPO
+        ):
+            stdout, stderr, exit_code = _run_main_with_input(hook_input)
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+    def test_list_tool_input_exits_zero_without_stdout_or_stderr(self) -> None:
+        hook_input = {
+            "tool_name": "Bash",
+            "tool_input": ["es.exe", KNOWN_REPO_NAME],
+        }
+        with patch(
+            "es_exe_path_rewriter.load_registry", return_value=REGISTRY_WITH_ONE_REPO
+        ):
+            stdout, stderr, exit_code = _run_main_with_input(hook_input)
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+    def test_string_tool_input_exits_zero_without_stdout_or_stderr(self) -> None:
+        hook_input = {
+            "tool_name": "Bash",
+            "tool_input": f"es.exe {KNOWN_REPO_NAME}",
+        }
+        with patch(
+            "es_exe_path_rewriter.load_registry", return_value=REGISTRY_WITH_ONE_REPO
+        ):
+            stdout, stderr, exit_code = _run_main_with_input(hook_input)
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+    def test_non_string_command_exits_zero_without_stdout_or_stderr(self) -> None:
+        hook_input = {
+            "tool_name": "Bash",
+            "tool_input": {"command": 12345, "description": "search"},
+        }
+        with patch(
+            "es_exe_path_rewriter.load_registry", return_value=REGISTRY_WITH_ONE_REPO
+        ):
+            stdout, stderr, exit_code = _run_main_with_input(hook_input)
+        assert exit_code == 0
+        assert stdout.strip() == ""
+        assert stderr.strip() == ""
+
+
 class TestNoOutputCases:
     def test_non_es_exe_command_produces_no_output(self) -> None:
         hook_input = _make_bash_input("git status")

package/hooks/blocking/test_windows_rmtree_blocker.py

@@ -5,7 +5,7 @@ import json
 import io
 import pathlib
 import sys
-from contextlib import redirect_stdout
+from contextlib import redirect_stderr, redirect_stdout
 
 _HOOK_DIR = pathlib.Path(__file__).parent
 if str(_HOOK_DIR) not in sys.path:
@@ -82,13 +82,23 @@ def test_blocks_rmtree_with_nested_parens_in_args() -> None:
     )
 
 
+DANGEROUS_RMTREE_SNIPPET = "shutil.rm" + "tree(path, ignore_errors" + "=True)"
+DANGEROUS_RMTREE_SNIPPET_WITH_TARGET = (
+    "shutil.rm" + "tree(target_path, ignore_errors" + "=True)"
+)
+
+
 def test_extract_payload_handles_write_content() -> None:
-    extracted = extract_payload_text("Write", {"content": "abc"})
+    extracted = extract_payload_text(
+        "Write", {"file_path": "foo.py", "content": "abc"}
+    )
     assert extracted == "abc"
 
 
 def test_extract_payload_handles_edit_new_string() -> None:
-    extracted = extract_payload_text("Edit", {"new_string": "abc"})
+    extracted = extract_payload_text(
+        "Edit", {"file_path": "foo.py", "new_string": "abc"}
+    )
     assert extracted == "abc"
 
 
@@ -102,19 +112,80 @@ def test_extract_payload_returns_empty_for_unknown_tool() -> None:
     assert extracted == ""
 
 
-def _run_hook(hook_input: dict) -> tuple[str, int]:
-    captured = io.StringIO()
+def test_extract_payload_returns_empty_for_write_to_non_python_file() -> None:
+    extracted = extract_payload_text(
+        "Write",
+        {
+            "file_path": "agents/clean-coder.md",
+            "content": DANGEROUS_RMTREE_SNIPPET,
+        },
+    )
+    assert extracted == ""
+
+
+def test_extract_payload_returns_empty_for_edit_to_non_python_file() -> None:
+    extracted = extract_payload_text(
+        "Edit",
+        {
+            "file_path": "docs/something.md",
+            "new_string": DANGEROUS_RMTREE_SNIPPET,
+        },
+    )
+    assert extracted == ""
+
+
+def test_extract_payload_returns_content_for_write_to_python_file() -> None:
+    extracted = extract_payload_text(
+        "Write",
+        {
+            "file_path": "hooks/blocking/my_hook.py",
+            "content": DANGEROUS_RMTREE_SNIPPET_WITH_TARGET,
+        },
+    )
+    assert extracted == DANGEROUS_RMTREE_SNIPPET_WITH_TARGET
+
+
+def test_python_file_extension_constant_drives_python_filter() -> None:
+    python_extension = hook_module.PYTHON_FILE_EXTENSION
+    extracted_for_python = extract_payload_text(
+        "Write",
+        {
+            "file_path": f"hooks/blocking/sample{python_extension}",
+            "content": DANGEROUS_RMTREE_SNIPPET_WITH_TARGET,
+        },
+    )
+    assert extracted_for_python == DANGEROUS_RMTREE_SNIPPET_WITH_TARGET
+
+
+def test_extract_payload_returns_content_for_write_without_file_path() -> None:
+    extracted = extract_payload_text(
+        "Write",
+        {"content": "some python code"},
+    )
+    assert extracted == "some python code"
+
+
+def _run_hook_with_stdin_text(stdin_text: str) -> tuple[str, str, int]:
+    captured_stdout = io.StringIO()
+    captured_stderr = io.StringIO()
     exit_code = 0
-    sys.stdin = io.StringIO(json.dumps(hook_input))
+    sys.stdin = io.StringIO(stdin_text)
     try:
-        with redirect_stdout(captured):
+        with redirect_stdout(captured_stdout), redirect_stderr(captured_stderr):
             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
+    return captured_stdout.getvalue(), captured_stderr.getvalue(), exit_code
+
+
+def _run_hook(hook_input: dict) -> tuple[str, int]:
+    stdout_text, _stderr_text, exit_code = _run_hook_with_stdin_text(
+        json.dumps(hook_input)
+    )
+    return stdout_text, exit_code
 
 
 def test_main_blocks_unsafe_bash_command() -> None:
@@ -153,3 +224,44 @@ def test_main_passes_through_unrelated_tool() -> None:
     )
     assert exit_code == 0
     assert stdout_text == ""
+
+
+def test_main_passes_through_unsafe_write_to_non_python_file() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "agents/clean-coder.md",
+                "content": DANGEROUS_RMTREE_SNIPPET,
+            },
+        }
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_blocks_write_with_missing_file_path_and_unsafe_content() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {"content": DANGEROUS_RMTREE_SNIPPET_WITH_TARGET},
+        }
+    )
+    assert exit_code == 0
+    response_payload = json.loads(stdout_text)
+    decision_block = response_payload["hookSpecificOutput"]
+    assert decision_block["permissionDecision"] == "deny"
+
+
+def test_main_with_empty_stdin_exits_silently() -> None:
+    stdout_text, stderr_text, exit_code = _run_hook_with_stdin_text("")
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""
+
+
+def test_main_with_invalid_json_stdin_exits_silently() -> None:
+    stdout_text, stderr_text, exit_code = _run_hook_with_stdin_text("{broken")
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""

package/hooks/blocking/windows_rmtree_blocker.py

@@ -15,6 +15,20 @@ blocks it with a corrective message pointing to the force_rmtree replacement.
 import json
 import re
 import sys
+from pathlib import Path
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().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.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from config.windows_rmtree_blocker_constants import PYTHON_FILE_EXTENSION
 
 
 def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
@@ -29,6 +43,9 @@ def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
 
 def extract_payload_text(tool_name: str, tool_input: dict) -> str:
     if tool_name in {"Write", "Edit"}:
+        file_path = tool_input.get("file_path", "")
+        if file_path and not file_path.endswith(PYTHON_FILE_EXTENSION):
+            return ""
         return tool_input.get("content", "") or tool_input.get("new_string", "") or ""
     if tool_name == "Bash":
         return tool_input.get("command", "") or ""
@@ -72,14 +89,14 @@ def main() -> None:
         "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")
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
         sys.exit(0)
 
-    tool_name = hook_input.get("tool_name", "")
-    tool_input = hook_input.get("tool_input", {})
+    raw_tool_name = hook_input.get("tool_name", "")
+    raw_tool_input = hook_input.get("tool_input", {})
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
 
     payload_text = extract_payload_text(tool_name, tool_input)
 

package/hooks/config/banned_identifiers_constants.py

@@ -0,0 +1,24 @@
+"""Configuration constants for the banned-identifier check in code_rules_enforcer."""
+
+ALL_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
+    {
+        "result",
+        "data",
+        "output",
+        "response",
+        "value",
+        "item",
+        "temp",
+        "argv",
+        "args",
+        "kwargs",
+        "argc",
+    }
+)
+MAX_BANNED_IDENTIFIER_ISSUES: int = 3
+BANNED_IDENTIFIER_MESSAGE_SUFFIX: str = (
+    "use descriptive name (see CODE_RULES Naming section)"
+)
+BANNED_IDENTIFIER_SKIP_ADVISORY: str = (
+    "banned-identifier check skipped: file did not parse as Python"
+)

package/hooks/config/hardcoded_user_path_constants.py

@@ -0,0 +1,12 @@
+"""Configuration constants for the hardcoded-user-path check in code_rules_enforcer."""
+
+import re
+
+HARDCODED_USER_PATH_PATTERN: re.Pattern[str] = re.compile(
+    r"(?:"
+    r"[A-Za-z]:[\\/](?i:users)[\\/](?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
+    r"|(?<![A-Za-z:])/Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
+    r"|/home/[^/]+(?=/|$))"
+)
+MAX_HARDCODED_USER_PATH_ISSUES: int = 25
+HARDCODED_USER_PATH_GUIDANCE: str = "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"

package/hooks/config/hook_log_extractor_constants.py

@@ -226,7 +226,7 @@ STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE: str = str(
 )
 
 WINDOWS_OS_NAME: str = "nt"
-WINDOWS_DETACHED_PROCESS_FLAG: int = 0x00000008
+WINDOWS_CREATE_NO_WINDOW_FLAG: int = 0x08000000
 WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG: int = 0x00000200
 
 LOCK_MAXIMUM_RETRY_COUNT: int = 30

package/hooks/config/pre_tool_use_stdin.py

@@ -0,0 +1,48 @@
+"""Shared stdin parsing for PreToolUse hooks that expect one JSON object."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from config.setup_project_paths_constants import (
+    DECODE_ERRORS_POLICY,
+    UTF8_BYTE_ORDER_MARK,
+    UTF8_ENCODING,
+)
+
+
+def _read_stdin_text() -> str | None:
+    try:
+        raw_bytes = sys.stdin.buffer.read()
+    except (AttributeError, OSError):
+        try:
+            decoded_text = sys.stdin.read()
+        except (AttributeError, OSError):
+            return None
+        if decoded_text is None:
+            return None
+        return decoded_text
+    return raw_bytes.decode(UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
+
+
+def read_hook_input_dictionary_from_stdin() -> dict[str, object] | None:
+    """Return the hook payload dict, or None when stdin is empty or not a JSON object.
+
+    Reads the full stdin stream, strips a UTF-8 BOM and surrounding whitespace, then
+    parses JSON. Malformed JSON, non-object roots, and empty payloads yield None so
+    callers can exit zero without treating the hook as a hard failure.
+    """
+    decoded_text = _read_stdin_text()
+    if decoded_text is None:
+        return None
+    normalized_text = decoded_text.strip().removeprefix(UTF8_BYTE_ORDER_MARK).strip()
+    if not normalized_text:
+        return None
+    try:
+        parsed_payload = json.loads(normalized_text)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed_payload, dict):
+        return None
+    return parsed_payload

package/hooks/config/setup_project_paths_constants.py

@@ -32,6 +32,10 @@ META_KEY = "_meta"
 
 UTF8_ENCODING = "utf-8"
 
+DECODE_ERRORS_POLICY = "replace"
+
+UTF8_BYTE_ORDER_MARK = "\ufeff"
+
 CONFIRMATION_PROMPT_TEXT = "Write this mapping to the config file? (yes/no): "
 
 ABORTED_NOTHING_WRITTEN_MESSAGE = "Aborted. Nothing written."

package/hooks/config/stuttering_check_config.py

@@ -0,0 +1,14 @@
+"""Constants for the stuttering ``all_``/``ALL_`` prefix detector.
+
+Lives under the hooks-tree ``config/`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration
+(``messages``, ``dynamic_stderr_handler``, ``project_paths_reader``).
+"""
+
+import re
+
+STUTTERING_ALL_PREFIX_PATTERN: re.Pattern[str] = re.compile(
+    r"^_?(?:all_){2,}|^_?(?:ALL_){2,}"
+)
+MAX_STUTTERING_PREFIX_ISSUES: int = 50