claude-dev-env 2.31.1 → 2.33.0

package/hooks/blocking/bash_post_call_dispatcher.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""PostToolUse dispatcher that hosts the Bash hook chain running after a call.
+
+Named ``bash_post_call_dispatcher`` rather than the more obvious
+``bash_post_tool_use_dispatcher``: ``bin/install.test.mjs`` counts every
+PostToolUse command whose text contains the literal substring
+``post_tool_use_dispatcher.py`` and asserts exactly one match, against the
+unrelated Write/Edit dispatcher in ``validation/post_tool_use_dispatcher.py``.
+That check carries no basename anchor (its PreToolUse sibling does), so a
+correctly-named Bash-side sibling here would read as a second match of an
+unrelated dispatcher. This name carries the same meaning without the
+collision, and needs no change to that shared, out-of-scope test file.
+
+Reads the tool payload from stdin once, selects the hosted hooks applicable to
+the payload's tool name, and runs each one in-process via the shared
+hosted-hook runner. A hosted PostToolUse hook here carries no permission
+decision -- it is a side-effecting observer, not a gate -- so this dispatcher
+runs the whole roster unconditionally and emits nothing itself, matching every
+hosted hook's own empty-stdout contract.
+
+A single hosted hook crash fails open: ``run_hook_capturing_output`` isolates
+it, so it contributes nothing and does not stop the remaining hosted hooks.
+
+One interpreter start here serves the whole roster: every hosted hook's
+imports load once into this process rather than once per hook.
+"""
+
+from __future__ import annotations
+
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.bash_post_call_dispatcher_constants import (
+    ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES,
+)
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import BashHostedHookEntry
+from hooks_constants.hosted_hook_runner import (
+    run_hook_capturing_output,
+    resolved_hook_script_path,
+    run_dispatcher_main,
+)
+
+
+def select_applicable_entries(tool_name: str) -> list[BashHostedHookEntry]:
+    """Return the ordered hosted-hook entries that apply to tool_name."""
+    return [
+        each_entry
+        for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
+        if tool_name in each_entry.applicable_tool_names
+    ]
+
+
+def dispatch(payload_text: str, tool_name: str) -> None:
+    """Run every hosted hook applicable to tool_name, in registration order.
+
+    Each hosted hook's crash is isolated by ``run_hook_capturing_output``, so
+    one hook failing never stops a later one in the same roster.
+    """
+    for each_entry in select_applicable_entries(tool_name):
+        script_path = resolved_hook_script_path(each_entry.script_relative_path)
+        run_hook_capturing_output(script_path, payload_text)
+
+
+def main() -> None:
+    """Read stdin once and dispatch the Bash PostToolUse hosted-hook roster."""
+    run_dispatcher_main(dispatch)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/bash_pre_tool_use_dispatcher.py

@@ -22,7 +22,6 @@ from __future__ import annotations
 import json
 import sys
 from dataclasses import dataclass, field
-from pathlib import Path
 
 import _path_setup  # noqa: F401
 
@@ -36,8 +35,12 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
     REASON_JOIN_SEPARATOR,
     BashHostedHookEntry,
 )
-from hooks_constants.hosted_hook_runner import HostedHookRun, run_hook_capturing_output
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.hosted_hook_runner import (
+    run_dispatcher_main,
+    run_hook_capturing_output,
+    HostedHookRun,
+    resolved_hook_script_path,
+)
 
 _PERMISSION_DECISION_KEY = "permissionDecision"
 _PERMISSION_REASON_KEY = "permissionDecisionReason"
@@ -203,12 +206,6 @@ def aggregate_bash_hook_results(
     )
 
 
-def _resolve_hook_script_path(relative_path: str) -> str:
-    """Resolve a hooks/-relative path to an absolute script path."""
-    hooks_root = Path(__file__).resolve().parent.parent
-    return str(hooks_root / relative_path)
-
-
 def _emit_decision(decision: BashDispatcherDecision) -> None:
     """Write one PreToolUse permission payload to stdout when an outcome exists."""
     if not decision.decision:
@@ -251,7 +248,7 @@ def dispatch(payload_text: str, tool_name: str) -> None:
     applicable_entries = select_applicable_entries(tool_name)
     all_runs: list[HostedHookRun] = []
     for each_entry in applicable_entries:
-        script_path = _resolve_hook_script_path(each_entry.script_relative_path)
+        script_path = resolved_hook_script_path(each_entry.script_relative_path)
         hook_run = run_hook_capturing_output(script_path, payload_text)
         all_runs.append(hook_run)
         if _run_is_deny(hook_run):
@@ -264,17 +261,7 @@ def dispatch(payload_text: str, tool_name: str) -> None:
 
 def main() -> None:
     """Read stdin once and dispatch the Bash/PowerShell hosted-hook chain."""
-    payload_dictionary = read_hook_input_dictionary_from_stdin()
-    if payload_dictionary is None:
-        sys.exit(0)
-
-    payload_text = json.dumps(payload_dictionary)
-    tool_name = payload_dictionary.get("tool_name", "")
-    if not isinstance(tool_name, str) or not tool_name:
-        sys.exit(0)
-
-    dispatch(payload_text, tool_name)
-    sys.exit(0)
+    run_dispatcher_main(dispatch)
 
 
 if __name__ == "__main__":

package/hooks/blocking/code_rules_comments.py

@@ -1,10 +1,14 @@
 """Comment-presence and comment-change checks for Python and JavaScript sources."""
 
+import difflib
+import importlib
 import io
 import sys
 import tokenize
+from collections import Counter
 from collections.abc import Iterator
 from pathlib import Path
+from typing import cast
 
 _blocking_directory = str(Path(__file__).resolve().parent)
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
@@ -20,7 +24,6 @@ from code_rules_shared import (  # noqa: E402
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_FREE_FORM_EXEMPT_COMMENT_BODIES,
     ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES,
-    ALL_JAVASCRIPT_EXEMPT_INLINE_COMMENT_PREFIXES,
     ALL_JAVASCRIPT_EXTENSIONS,
     ALL_PYTHON_EXTENSIONS,
     ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS,
@@ -29,6 +32,10 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     CHAINED_INLINE_COMMENT_PATTERN,
     MAX_COMMENT_ISSUES,
 )
+_javascript_comment_scanner = importlib.import_module("javascript_comment_scanner")
+extract_javascript_comment_occurrences = (
+    _javascript_comment_scanner.extract_javascript_comment_occurrences
+)
 
 
 def check_comments_python(content: str) -> list[str]:
@@ -93,7 +100,9 @@ def check_comments_javascript(content: str) -> list[str]:
     return issues
 
 
-def extract_comment_texts(content: str, file_path: str) -> tuple[set[str], set[str]]:
+def extract_comment_texts(
+    content: str, file_path: str, include_directive_comments: bool = False
+) -> tuple[set[str], set[str]]:
     """Extract normalized comment text strings from content for comparison.
 
     Returns:
@@ -108,46 +117,58 @@ def extract_comment_texts(content: str, file_path: str) -> tuple[set[str], set[s
         return inline_comments, standalone_comments
 
     if extension in ALL_PYTHON_EXTENSIONS:
-        inline_comments, standalone_comments, _ = _extract_python_comment_sets(content)
+        inline_comments, standalone_comments, _ = _extract_python_comment_sets(
+            content, include_directive_comments
+        )
         return inline_comments, standalone_comments
 
-    lines = content.split("\n")
-
     if extension in ALL_JAVASCRIPT_EXTENSIONS:
-        is_in_multiline = False
-        for each_line in lines:
-            stripped = each_line.strip()
-            if not stripped:
-                continue
-            if is_in_multiline:
-                if "*/" in stripped:
-                    is_in_multiline = False
-                continue
-            if stripped.startswith("/*"):
-                is_in_multiline = "*/" not in stripped
-                if not stripped.startswith("/**"):
-                    standalone_comments.add(stripped)
-                continue
-            if stripped.startswith("//"):
-                if not stripped.startswith(ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES):
-                    standalone_comments.add(stripped)
-            elif "//" in each_line:
-                before_slash = each_line[:each_line.index("//")]
-                if before_slash.strip():
-                    comment_start = stripped.index("//")
-                    comment_text = stripped[comment_start + 2 :].strip()
-                    if not comment_text.startswith(ALL_JAVASCRIPT_EXEMPT_INLINE_COMMENT_PREFIXES):
-                        inline_comments.add(stripped[comment_start:])
+        all_occurrences: list[tuple[str, int, bool]] = cast(
+            list[tuple[str, int, bool]],
+            extract_javascript_comment_occurrences(content, include_directive_comments),
+        )
+        inline_comments = {
+            each_text
+            for each_text, _each_line_number, is_inline in all_occurrences
+            if is_inline
+        }
+        standalone_comments = {
+            each_text
+            for each_text, _each_line_number, is_inline in all_occurrences
+            if not is_inline
+        }
 
     return inline_comments, standalone_comments
 
 
+def _python_comment_occurrences(
+    content: str,
+) -> tuple[list[tuple[str, int, bool]], bool]:
+    """Return Python comments with exact lines and a tokenize status."""
+    source_lines = content.split("\n")
+    try:
+        all_tokens = list(_python_tokens(content))
+    except ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS:
+        return [], False
+    all_occurrences: list[tuple[str, int, bool]] = []
+    for each_token in all_tokens:
+        if each_token.type != tokenize.COMMENT:
+            continue
+        if each_token.string.startswith("#!") and each_token.start == (1, 0):
+            continue
+        source_line = source_lines[each_token.start[0] - 1]
+        is_inline = bool(source_line[: each_token.start[1]].strip())
+        all_occurrences.append(
+            (each_token.string.strip(), each_token.start[0], is_inline)
+        )
+    return all_occurrences, True
+
+
 def check_comment_changes(old_content: str, new_content: str, file_path: str) -> list[str]:
     """Check for comment additions or removals between old and new content.
 
-    Inline comments (after code on same line): BLOCK when added.
-    Standalone comment lines: NUDGE (print advisory) when added.
-    Existing comments being removed: NUDGE (print advisory) — comment preservation is advisory.
+    Inline and standalone comments are blocking findings when added.
+    Existing comments can be removed when the touched code no longer needs them.
 
     When the file is Python and either *old_content* or *new_content* cannot
     be tokenized (common for mid-edit Edit fragments), the comparison is
@@ -161,38 +182,71 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
 
     extension = get_file_extension(file_path)
     if extension in ALL_PYTHON_EXTENSIONS:
-        old_inline, old_standalone, old_tokenize_ok = _extract_python_comment_sets(old_content)
-        new_inline, new_standalone, new_tokenize_ok = _extract_python_comment_sets(new_content)
+        old_occurrences, old_tokenize_ok = _python_comment_occurrences(old_content)
+        new_occurrences, new_tokenize_ok = _python_comment_occurrences(new_content)
         if not (old_tokenize_ok and new_tokenize_ok):
             return issues
     else:
-        old_inline, old_standalone = extract_comment_texts(old_content, file_path)
-        new_inline, new_standalone = extract_comment_texts(new_content, file_path)
-
-    added_inline = new_inline - old_inline
-    if added_inline:
-        sample = next(iter(added_inline))
-        issues.append(f"Inline comment added: {sample[:60]} - refactor to self-documenting code")
-
-    added_standalone = new_standalone - old_standalone
-    if added_standalone:
-        sample = next(iter(added_standalone))
-        print(f"[CODE_RULES advisory] Standalone comment added: {sample[:60]} - prefer self-documenting code", file=sys.stderr)
-
-    all_old = old_inline | old_standalone
-    all_new = new_inline | new_standalone
-    removed_comments = all_old - all_new
-    if removed_comments:
-        old_line_count = len([line for line in old_content.split("\n") if line.strip()])
-        new_line_count = len([line for line in new_content.split("\n") if line.strip()])
-        code_was_removed = new_line_count < old_line_count - len(removed_comments)
-        if not code_was_removed:
-            sample = next(iter(removed_comments))
-            print(f"[CODE_RULES advisory] Existing comment removed: {sample[:60]} - comment preservation is advisory", file=sys.stderr)
+        old_occurrences = extract_javascript_comment_occurrences(old_content, True)
+        new_occurrences = extract_javascript_comment_occurrences(new_content, True)
+
+    old_occurrence_counts = Counter(
+        (each_text, is_inline)
+        for each_text, _line_number, is_inline in old_occurrences
+    )
+    seen_occurrence_counts: Counter[tuple[str, bool]] = Counter()
+    for each_text, each_line_number, each_is_inline in new_occurrences:
+        occurrence_key = (each_text, each_is_inline)
+        if seen_occurrence_counts[occurrence_key] >= old_occurrence_counts[occurrence_key]:
+            comment_kind = "Inline" if each_is_inline else "Standalone"
+            issues.append(
+                f"Line {each_line_number}: {comment_kind} comment added: "
+                f"{each_text[:60]} - refactor to self-documenting code"
+            )
+        seen_occurrence_counts[occurrence_key] += 1
+        if len(issues) >= MAX_COMMENT_ISSUES:
+            break
+    issues.extend(_retained_comment_issues(old_content, new_content, file_path))
 
     return issues
 
 
+def _changed_line_numbers(old_content: str, new_content: str) -> set[int]:
+    matcher = difflib.SequenceMatcher(
+        None, old_content.splitlines(), new_content.splitlines(), autojunk=False
+    )
+    return {
+        each_line_number
+        for each_tag, _, _, each_new_start, each_new_end in matcher.get_opcodes()
+        if each_tag != "equal"
+        for each_line_number in range(each_new_start + 1, each_new_end + 1)
+    }
+
+
+def _retained_comment_issues(
+    old_content: str, new_content: str, file_path: str
+) -> list[str]:
+    old_inline, old_standalone = extract_comment_texts(old_content, file_path, True)
+    new_inline, new_standalone = extract_comment_texts(new_content, file_path, True)
+    shared_inline = set(Counter(old_inline) & Counter(new_inline))
+    shared_standalone = old_standalone & new_standalone
+    if not shared_inline and not shared_standalone:
+        return []
+    changed_lines = _changed_line_numbers(old_content, new_content)
+    new_lines = new_content.splitlines()
+    issues: list[str] = []
+    for each_line_number in sorted(changed_lines):
+        inline_comment = next((each_comment for each_comment in shared_inline if each_comment in new_lines[each_line_number - 1]), None)
+        if inline_comment is not None:
+            issues.append(f"Line {each_line_number}: Inline comment retained on changed code: {inline_comment} - remove the comment")
+        preceding_line_number = each_line_number - 1
+        if preceding_line_number > 0 and new_lines[preceding_line_number - 1].strip() in shared_standalone:
+            issues.append(f"Line {each_line_number}: Standalone comment retained on changed code at line {preceding_line_number}: {new_lines[preceding_line_number - 1].strip()} - remove the comment")
+        if len(issues) >= MAX_COMMENT_ISSUES:
+            break
+    return issues[:MAX_COMMENT_ISSUES]
+
+
 def _python_tokens(source: str) -> Iterator[tokenize.TokenInfo]:
     """Yield Python tokens from *source* one at a time.
 
@@ -304,7 +358,9 @@ def _starts_with_bounded_token_anchored_directive(directive_body: str) -> bool:
     return False
 
 
-def _extract_python_comment_sets(content: str) -> tuple[set[str], set[str], bool]:
+def _extract_python_comment_sets(
+    content: str, include_directive_comments: bool = False
+) -> tuple[set[str], set[str], bool]:
     """Return (inline_comments, standalone_comments, tokenize_succeeded).
 
     Streams *content* once via ``_python_tokens``. A tokenize failure
@@ -321,7 +377,10 @@ def _extract_python_comment_sets(content: str) -> tuple[set[str], set[str], bool
         for each_token in _python_tokens(content):
             if each_token.type != tokenize.COMMENT:
                 continue
-            if _is_exempt_python_comment(each_token):
+            is_shebang = each_token.string.startswith("#!") and each_token.start == (1, 0)
+            if is_shebang or (
+                not include_directive_comments and _is_exempt_python_comment(each_token)
+            ):
                 continue
             line_number = each_token.start[0]
             column_offset = each_token.start[1]

package/hooks/blocking/code_rules_duplicate_body.py

@@ -492,6 +492,7 @@ def _total_reachable_statement_count(
 
 def _helper_match_window_dumps(
     function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    dump_by_statement: dict[ast.stmt, str],
 ) -> list[str] | None:
     """Return the helper's substantive block as per-statement dumps, or None.
 
@@ -541,7 +542,10 @@ def _helper_match_window_dumps(
     )
     if not has_substantial_compound:
         return None
-    return [_normalized_statement_dump(each) for each in match_window]
+    return [
+        _memoized_statement_dump(each_statement, dump_by_statement)
+        for each_statement in match_window
+    ]
 
 
 def check_same_file_inline_duplicate_body(
@@ -763,14 +767,14 @@ def _inline_duplicate_violation(
 
 
 def _violations_for_qualifying_helpers(
-    window_by_function: dict[_ModuleScopeFunction, list[str] | None],
+    window_by_function: dict[_ModuleScopeFunction, list[str]],
     profile_by_function: dict[_ModuleScopeFunction, _FunctionScanProfile],
     maximum_issue_count: int,
 ) -> list[tuple[frozenset[int], str]]:
     """Walk the helpers in source order and report the first inliner of each.
 
     Args:
-        window_by_function: Each function's helper match window, or None.
+        window_by_function: Each qualifying function's helper match window.
         profile_by_function: Each function's readings, keyed in source order.
         maximum_issue_count: The report ceiling the walk stops at.
 
@@ -779,8 +783,6 @@ def _violations_for_qualifying_helpers(
     """
     all_violations_in_walk_order: list[tuple[frozenset[int], str]] = []
     for each_helper, each_window_dumps in window_by_function.items():
-        if each_window_dumps is None:
-            continue
         each_enclosing = _first_enclosing_inliner(
             each_helper, each_window_dumps, profile_by_function
         )
@@ -811,10 +813,14 @@ def _inline_duplicate_violations(
     """
     dump_by_statement: dict[ast.stmt, str] = {}
     window_by_function = {
-        each_function: _helper_match_window_dumps(each_function)
+        each_function: each_window
         for each_function in all_top_level_functions
+        if (
+            each_window := _helper_match_window_dumps(each_function, dump_by_statement)
+        )
+        is not None
     }
-    if all(each_window is None for each_window in window_by_function.values()):
+    if not window_by_function:
         return []
     profile_by_function = {
         each_function: _function_scan_profile(each_function, dump_by_statement)

package/hooks/blocking/code_rules_enforcer.py

@@ -196,6 +196,8 @@ from hooks_constants.subprocess_budget_completeness_content import (  # noqa: E4
     existing_file_content,
 )
 
+__all__ = ("is_test_file",)
+
 
 def _multiedit_post_edit_view(
     file_path: str, all_tool_input: dict[str, object]
@@ -234,6 +236,7 @@ class _ValidationContext(NamedTuple):
     defer_scope_to_caller: bool
     sibling_directory: Path | None
     phase: str
+    include_comment_policy: bool = True
 
 
 def _validated_phase(phase: str) -> str:
@@ -325,7 +328,7 @@ def _python_comment_and_logging_issues(context: _ValidationContext) -> list[str]
         context.file_path,
     )
     all_issues: list[str] = []
-    if not is_test_file(file_path):
+    if context.phase == FULL_GATE_PHASE and context.include_comment_policy:
         all_issues.extend(check_comment_changes(old_content, content, file_path))
     all_issues.extend(check_imports_at_top(content))
     all_issues.extend(check_logging_fstrings(content))
@@ -366,7 +369,15 @@ def _python_duplicate_body_and_banned_issues(context: _ValidationContext) -> lis
     all_issues = check_same_file_inline_duplicate_body(
         effective_content, file_path, changed, defer
     )
-    all_issues.extend(check_type_escape_hatches(effective_content, file_path))
+    all_issues.extend(
+        check_type_escape_hatches(
+            effective_content,
+            file_path,
+            include_type_ignore_comments=(
+                context.phase == FULL_GATE_PHASE and context.include_comment_policy
+            ),
+        )
+    )
     all_issues.extend(
         check_banned_identifiers(effective_content, file_path, changed, defer)
     )
@@ -576,7 +587,7 @@ def _javascript_comment_and_naming_issues(context: _ValidationContext) -> list[s
         context.file_path,
     )
     all_issues: list[str] = []
-    if not is_test_file(file_path):
+    if context.phase == FULL_GATE_PHASE and context.include_comment_policy:
         all_issues.extend(check_comment_changes(old_content, content, file_path))
     all_issues.extend(check_e2e_test_naming(content, file_path))
     all_issues.extend(
@@ -642,6 +653,7 @@ def validate_content_for_phase(
     sibling_directory: Path | None = None,
     *,
     phase: str,
+    include_comment_policy: bool = True,
 ) -> list[str]:
     """Run all applicable validators on content for one named validation phase."""
     validated_phase = _validated_phase(phase)
@@ -649,10 +661,7 @@ def validate_content_for_phase(
     effective_content, all_changed_lines = _effective_content_and_changed_lines(
         content, full_file_content, prior_full_file_content
     )
-    context = _ValidationContext(
-        content, old_content, effective_content, file_path, all_changed_lines,
-        defer_scope_to_caller, sibling_directory, validated_phase,
-    )
+    context = _ValidationContext(content, old_content, effective_content, file_path, all_changed_lines, defer_scope_to_caller, sibling_directory, validated_phase, include_comment_policy)
     all_issues: list[str] = []
     if extension in ALL_PYTHON_EXTENSIONS:
         all_issues = _python_extension_issues(context)
@@ -693,6 +702,8 @@ def validate_content_for_full_gate(
     prior_full_file_content: str = "",
     defer_scope_to_caller: bool = False,
     sibling_directory: Path | None = None,
+    *,
+    include_comment_policy: bool = True,
 ) -> list[str]:
     """Run the full-gate phase, including the six checks that read sibling files."""
     return validate_content_for_phase(
@@ -704,6 +715,7 @@ def validate_content_for_full_gate(
         defer_scope_to_caller,
         sibling_directory,
         phase=FULL_GATE_PHASE,
+        include_comment_policy=include_comment_policy,
     )
 
 

package/hooks/blocking/code_rules_enforcer_test_support.py

@@ -14,6 +14,45 @@ from pathlib import Path
 _ENFORCER_SCRIPT_PATH = Path(__file__).with_name("code_rules_enforcer.py")
 
 
+def repository_root() -> Path:
+    """Return the root of the checkout these tests run inside.
+
+    ::
+
+        <checkout>/packages/claude-dev-env/hooks/blocking/test_x.py -> <checkout>
+
+    Found by walking up for a ``.git`` entry rather than by counting
+    directories, so moving a test file does not silently anchor it somewhere
+    else. Falls back to the four-levels-up ancestor when no marker is found,
+    which is where the checkout root sits for this directory.
+
+    Returns:
+        The checkout root directory.
+    """
+    all_ancestors = Path(__file__).resolve().parents
+    for each_ancestor in all_ancestors:
+        if (each_ancestor / ".git").exists():
+            return each_ancestor
+    return all_ancestors[3]
+
+
+def repository_file_path(relative_path: str) -> str:
+    """Return the absolute path of a repository-relative file in this checkout.
+
+    A hook resolves a bare relative path against the process working
+    directory, so a payload carrying one answers to wherever pytest was
+    invoked from. An absolute path under the checkout root keeps the
+    decision stable however the suite is launched.
+
+    Args:
+        relative_path: The target file's path relative to the checkout root.
+
+    Returns:
+        That file's absolute path inside this checkout.
+    """
+    return str(repository_root() / relative_path)
+
+
 def build_write_payload(file_path: str, content: str) -> str:
     """Build the JSON payload sent by a Write tool call."""
     return json.dumps(

package/hooks/blocking/code_rules_type_escape.py

@@ -79,23 +79,13 @@ def _find_any_annotation_lines(source: str) -> list[int]:
     return offending_line_numbers
 
 
-def _find_unjustified_type_ignore_lines(source: str) -> list[int]:
-    """Return line numbers of # type: ignore comments lacking a trailing reason."""
+def _find_type_ignore_lines(source: str) -> list[int]:
+    """Return line numbers of all type-ignore comments."""
     ignore_pattern = re.compile(r"#\s*type:\s*ignore(?:\[[^\]]*\])?(.*)$")
-    minimum_justification_characters = len("xxxxx")
     offending_line_numbers: list[int] = []
     for each_comment_token in _comment_tokens(source):
-        matched = ignore_pattern.search(each_comment_token.string)
-        if not matched:
-            continue
-        line_number = each_comment_token.start[0]
-        trailing_text = matched.group(1).strip()
-        if not trailing_text.startswith("#"):
-            offending_line_numbers.append(line_number)
-            continue
-        justification_text = trailing_text.lstrip("#").strip()
-        if len(justification_text) < minimum_justification_characters:
-            offending_line_numbers.append(line_number)
+        if ignore_pattern.search(each_comment_token.string):
+            offending_line_numbers.append(each_comment_token.start[0])
     return offending_line_numbers
 
 
@@ -625,12 +615,20 @@ def _find_object_annotated_parameter_lines(source: str) -> list[tuple[int, str]]
     return offending_parameters
 
 
-def check_type_escape_hatches(content: str, file_path: str) -> list[str]:
-    """Flag Any annotations, Any imports, cast() calls, object-typed dereferenced parameters, and unjustified # type: ignore."""
+def check_type_escape_hatches(
+    content: str, file_path: str, include_type_ignore_comments: bool = True
+) -> list[str]:
+    """Flag type escape hatches and every type-ignore comment."""
+    issues: list[str] = []
+    type_ignore_issues: list[str] = []
+    if include_type_ignore_comments:
+        for each_ignore_line in _find_type_ignore_lines(content):
+            type_ignore_issues.append(
+                f"Line {each_ignore_line}: # type: ignore is not allowed - remove it and use a typed boundary or real type"
+            )
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
-        return []
+        return type_ignore_issues
 
-    issues: list[str] = []
     is_any_exempt = _file_path_matches_any_exemption(file_path)
 
     if not is_any_exempt:
@@ -670,11 +668,6 @@ def check_type_escape_hatches(content: str, file_path: str) -> list[str]:
             )
         issues.extend(object_parameter_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
 
-    type_ignore_issues: list[str] = []
-    for each_ignore_line in _find_unjustified_type_ignore_lines(content):
-        type_ignore_issues.append(
-            f"Line {each_ignore_line}: Unjustified # type: ignore - add trailing '# reason' explaining why"
-        )
     issues.extend(type_ignore_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
 
     return issues