claude-dev-env 1.82.0 → 1.83.0

package/hooks/blocking/code_rules_naming_collection.py

@@ -271,6 +271,147 @@ def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _comprehension_rebinds_name(comprehension_node: ast.expr, target_name: str) -> bool:
+    """True when any generator of the comprehension binds its own target_name-named variable."""
+    generators = getattr(comprehension_node, "generators", [])
+    for each_generator in generators:
+        for each_name_node in _walk_assignment_targets(each_generator.target):
+            if each_name_node.id == target_name:
+                return True
+    return False
+
+
+def _function_binds_name(
+    function_node: ast.Lambda | ast.FunctionDef | ast.AsyncFunctionDef, target_name: str
+) -> bool:
+    """True when a lambda or nested def has a parameter named target_name."""
+    argument_specification = function_node.args
+    all_argument_nodes = [
+        *argument_specification.posonlyargs,
+        *argument_specification.args,
+        *argument_specification.kwonlyargs,
+    ]
+    if argument_specification.vararg is not None:
+        all_argument_nodes.append(argument_specification.vararg)
+    if argument_specification.kwarg is not None:
+        all_argument_nodes.append(argument_specification.kwarg)
+    return any(each_argument.arg == target_name for each_argument in all_argument_nodes)
+
+
+def _function_enclosing_scope_expressions(
+    function_node: ast.Lambda | ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[ast.expr]:
+    """Return the sub-expressions a lambda or def evaluates in its enclosing scope.
+
+    Parameter defaults and decorators run before the parameters bind, so a Load of
+    the outer name there still reads the outer name; the body never does once a
+    parameter shadows it.
+    """
+    argument_specification = function_node.args
+    enclosing_expressions: list[ast.expr] = [*argument_specification.defaults]
+    enclosing_expressions.extend(
+        each_default
+        for each_default in argument_specification.kw_defaults
+        if each_default is not None
+    )
+    if isinstance(function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        enclosing_expressions.extend(function_node.decorator_list)
+    return enclosing_expressions
+
+
+def _loop_rebinds_name(loop_node: ast.For | ast.AsyncFor, target_name: str) -> bool:
+    """True when the loop's own target rebinds target_name."""
+    return any(
+        each_name_node.id == target_name
+        for each_name_node in _walk_assignment_targets(loop_node.target)
+    )
+
+
+def _node_reads_name(node: ast.AST, target_name: str) -> bool:
+    """True when node contains a genuine Load of target_name, honoring scope shadowing.
+
+    A comprehension, a lambda, a nested def, or a nested loop that rebinds
+    target_name owns that name inside its body, so a Load there reads the inner
+    variable, not the outer loop variable. Only the parts each construct evaluates
+    in the enclosing scope can still read the outer name: a comprehension's or
+    nested loop's iterable, and a function's parameter defaults and decorators.
+    """
+    comprehension_node_types = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+    if isinstance(node, comprehension_node_types) and _comprehension_rebinds_name(
+        node, target_name
+    ):
+        outermost_iterable = node.generators[0].iter
+        return _node_reads_name(outermost_iterable, target_name)
+    if isinstance(node, (ast.Lambda, ast.FunctionDef, ast.AsyncFunctionDef)) and _function_binds_name(
+        node, target_name
+    ):
+        return any(
+            _node_reads_name(each_expression, target_name)
+            for each_expression in _function_enclosing_scope_expressions(node)
+        )
+    if isinstance(node, (ast.For, ast.AsyncFor)) and _loop_rebinds_name(node, target_name):
+        return _node_reads_name(node.iter, target_name)
+    if isinstance(node, ast.Name) and node.id == target_name and isinstance(node.ctx, ast.Load):
+        return True
+    for each_child_node in ast.iter_child_nodes(node):
+        if _node_reads_name(each_child_node, target_name):
+            return True
+    return False
+
+
+def _loop_body_references_name(loop_node: ast.For | ast.AsyncFor, target_name: str) -> bool:
+    for each_statement in [*loop_node.body, *loop_node.orelse]:
+        if _node_reads_name(each_statement, target_name):
+            return True
+    return False
+
+
+def check_referenced_underscore_loop_variable(content: str, file_path: str) -> list[str]:
+    """Flag a leading-underscore loop variable the loop body reads.
+
+    A leading underscore marks a name as a throwaway the reader can ignore, so
+    ``for _foreign_module_name in names:`` promises the body never touches it.
+    When the body then reads ``del sys.modules[_foreign_module_name]``, the
+    marker lies: the value carries meaning and earns a real name. This check
+    fires in test files too — a conftest that reuses an underscore-marked loop
+    variable is the exact shape this closes — because the misleading marker is a
+    naming smell everywhere, not a convention the test-file exemption waives.
+    Workflow-registry and migration files are exempt. A bare ``_`` target and a
+    genuinely unread ``_unused`` throwaway both pass.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per leading-underscore loop variable that its loop body reads.
+    """
+    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 each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.For, ast.AsyncFor)):
+            continue
+        for each_name_node in _collect_target_names(each_node.target):
+            target_name = each_name_node.id
+            if not target_name.startswith("_"):
+                continue
+            if target_name.strip("_") == "":
+                continue
+            if not _loop_body_references_name(each_node, target_name):
+                continue
+            issues.append(
+                f"Line {each_name_node.lineno}: loop variable {target_name!r} is read"
+                f" in its body - drop the leading underscore throwaway marker and"
+                f" give it a real name (CODE_RULES §5)"
+            )
+    return issues
+
+
 def _name_carries_token(name: str, token: str) -> bool:
     """True when name carries token as a whole underscore-delimited word."""
     return re.search(POLARITY_TOKEN_BOUNDARY_PATTERN % re.escape(token), name) is not None

package/hooks/blocking/code_rules_string_magic.py

@@ -123,6 +123,74 @@ def check_string_literal_magic(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def check_join_separator_string_magic(content: str, file_path: str) -> list[str]:
+    """Flag a bare string-literal separator passed to ``str.join`` in a body.
+
+    A call like ``", ".join(all_paths)`` hard-codes the delimiter that stitches
+    a list into one string. That delimiter is a magic value: change the wording
+    once and every reader has to grep the whole file for the stray literal. A
+    named constant in ``config/`` gives the delimiter one home. The empty
+    separator ``"".join(...)`` is left alone because it carries no delimiter —
+    it is the idiomatic way to concatenate parts. Config files, test files,
+    workflow-registry files, and migration files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per non-empty string-literal ``.join`` separator found in a
+        function body.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_config_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] = []
+    flagged_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Call):
+                    continue
+                separator_literal = _join_call_string_separator(each_descendant)
+                if separator_literal is None:
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                issues.append(
+                    f"Line {each_descendant.lineno}: string separator"
+                    f" {separator_literal!r} passed to .join(...)"
+                    f" - extract to a named constant in config/"
+                )
+    return issues
+
+
+def _join_call_string_separator(call_node: ast.Call) -> str | None:
+    called = call_node.func
+    if not isinstance(called, ast.Attribute):
+        return None
+    if called.attr != "join":
+        return None
+    separator_node = called.value
+    if not isinstance(separator_node, ast.Constant):
+        return None
+    if not isinstance(separator_node.value, str):
+        return None
+    if separator_node.value == "":
+        return None
+    return separator_node.value
+
+
 def check_inline_literal_collections(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -8,9 +8,9 @@ decision when any hook denied (carrying every denying reason) or exits zero to
 allow.
 
 The per-hook coverage matrix:
-- Write  -> Group A (11 hooks) + Group B (7 hooks) = 18 hooks
-- Edit   -> Group A (11 hooks) + Group B (7 hooks) = 18 hooks
-- MultiEdit -> Group B only (7 hooks)
+- Write  -> Group A (11 hooks) + Group B (8 hooks) = 19 hooks
+- Edit   -> Group A (11 hooks) + Group B (8 hooks) + the Edit-only hook = 20 hooks
+- MultiEdit -> Group B only (8 hooks)
 """
 
 from __future__ import annotations

package/hooks/blocking/reviewer_spawn_gate.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block a reviewer-spawn trigger when that reviewer is down.
+
+autoconverge already skips a reviewer step when its own pre-check reports
+that reviewer unavailable. That skip only protects the trigger commands the
+workflow generates and inspects itself. This hook is the backstop: it reads
+the Bash command a tool call is about to run and blocks it when the matched
+reviewer reports unavailable.
+
+The gate only inspects a command carrying the literal sentinel marker
+`CLAUDE_REVIEWER_GATE=autoconverge`. autoconverge prepends this marker to its
+own trigger commands. A command without the marker is never inspected, so a
+manual or unrelated `gh` call always passes through untouched.
+
+A Copilot trigger is a command containing both `requested_reviewers` and
+`copilot-pull-request-reviewer[bot]`. A Bugbot trigger is a command
+containing `post_fix_reply.py` and a `--body "bugbot run"` argument.
+
+For the matched reviewer, the gate runs
+`reviewer_availability.py --reviewer copilot|bugbot` and denies the call only
+when that script exits with the documented reviewer-down code (3). Any other
+exit code is an unexpected script failure, not a down report, so the call is
+allowed (fail open). The deny reason names the reviewer and carries
+the script's output. The script path resolves relative to this hook's
+install location by default, or from the
+`REVIEWER_SPAWN_GATE_AVAILABILITY_SCRIPT_PATH` environment variable when set.
+A missing script, a timeout, or a failure to launch it allows the call
+(fail open), so a broken availability check never blocks a legitimate run.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.reviewer_spawn_gate_constants import (  # noqa: E402
+    ALL_COPILOT_TRIGGER_MARKERS,
+    AVAILABILITY_DOWN_EXIT_CODE,
+    AVAILABILITY_REVIEWER_FLAG,
+    AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME,
+    AVAILABILITY_SCRIPT_RELATIVE_PATH,
+    AVAILABILITY_SCRIPT_TIMEOUT_SECONDS,
+    BASH_TOOL_NAME,
+    BUGBOT_REVIEWER_LABEL,
+    BUGBOT_REVIEWER_TOKEN,
+    BUGBOT_RUN_BODY_PATTERN,
+    BUGBOT_TRIGGER_SCRIPT_MARKER,
+    COPILOT_REVIEWER_LABEL,
+    COPILOT_REVIEWER_TOKEN,
+    DENY_REASON_TEMPLATE,
+    GATE_SENTINEL_MARKER,
+)
+
+
+def _matches_copilot_trigger(command: str) -> bool:
+    return all(each_marker in command for each_marker in ALL_COPILOT_TRIGGER_MARKERS)
+
+
+def _matches_bugbot_trigger(command: str) -> bool:
+    return BUGBOT_TRIGGER_SCRIPT_MARKER in command and bool(
+        BUGBOT_RUN_BODY_PATTERN.search(command)
+    )
+
+
+def _reviewer_trigger(command: str) -> tuple[str, str] | None:
+    """Return the reviewer token and label a scoped command triggers.
+
+    Args:
+        command: The Bash command text carrying the gate's sentinel marker.
+
+    Returns:
+        The matched reviewer's CLI token paired with its display label, or
+        None when the command matches neither the Copilot review-request
+        shape nor the Bugbot rerun-comment shape.
+    """
+    if _matches_copilot_trigger(command):
+        return COPILOT_REVIEWER_TOKEN, COPILOT_REVIEWER_LABEL
+    if _matches_bugbot_trigger(command):
+        return BUGBOT_REVIEWER_TOKEN, BUGBOT_REVIEWER_LABEL
+    return None
+
+
+def _resolve_availability_script_path() -> Path:
+    override_path = os.environ.get(AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, "")
+    if override_path:
+        return Path(override_path)
+    plugin_root = Path(__file__).resolve().parents[2]
+    return plugin_root / AVAILABILITY_SCRIPT_RELATIVE_PATH
+
+
+def _probe_reviewer_availability(reviewer_token: str) -> tuple[bool, str]:
+    """Run the shared availability script for a reviewer and report the outcome.
+
+    Args:
+        reviewer_token: The reviewer's CLI token (copilot or bugbot) passed to
+            the availability script's --reviewer flag.
+
+    Returns:
+        A pair of (is_available, detail_text). is_available is False only
+        when the script exits with the documented reviewer-down code;
+        detail_text carries the script's combined stdout and stderr for the
+        deny message. A missing script, a timeout, an OS-level failure to
+        launch the script, or any exit code other than the documented down
+        code reports available (fail open), so an availability-check crash
+        never blocks a legitimate run.
+    """
+    script_path = _resolve_availability_script_path()
+    if not script_path.is_file():
+        return True, f"availability script not found at {script_path}"
+    try:
+        completed_process = subprocess.run(
+            [sys.executable, str(script_path), AVAILABILITY_REVIEWER_FLAG, reviewer_token],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=AVAILABILITY_SCRIPT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as availability_error:
+        return True, f"availability script failed to run: {availability_error}"
+    availability_detail_text = (completed_process.stdout + completed_process.stderr).strip()
+    is_reviewer_down = completed_process.returncode == AVAILABILITY_DOWN_EXIT_CODE
+    return not is_reviewer_down, availability_detail_text
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_input, dict):
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name != BASH_TOOL_NAME:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if not command or GATE_SENTINEL_MARKER not in command:
+        sys.exit(0)
+
+    reviewer_trigger = _reviewer_trigger(command)
+    if reviewer_trigger is None:
+        sys.exit(0)
+    reviewer_token, reviewer_label = reviewer_trigger
+
+    is_available, availability_detail = _probe_reviewer_availability(reviewer_token)
+    if is_available:
+        sys.exit(0)
+
+    deny_reason = DENY_REASON_TEMPLATE.format(
+        reviewer_label=reviewer_label, availability_detail=availability_detail
+    )
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="reviewer_spawn_gate.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name=tool_name,
+        offending_input_preview=command,
+    )
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/stale_comment_reference_blocker.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: blocks an Edit that rewrites a Python code line while keeping a contradicting comment above it.
+
+Say a comment reads ``# Mock asyncio`` right above a line that patches
+``asyncio.sleep``. An Edit that rewrites just that line to patch something
+else, but leaves the comment untouched, orphans the comment: it still names
+``asyncio``, but the code below no longer does. The same gap opens when the
+Edit deletes the line outright instead of rewriting it. The hook locates
+each occurrence of the edit's ``old_string`` in the file and reads the line
+directly above it, denying the edit when that line is a standalone ``#``
+comment naming an identifier ``old_string`` carries and ``new_string`` drops.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pre_tool_use_dispatcher_constants import EDIT_TOOL_NAME  # noqa: E402
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
+from hooks_constants.stale_comment_reference_blocker_constants import (  # noqa: E402
+    ALL_COMMENT_STOPWORDS,
+    COMMENT_IDENTIFIER_PATTERN,
+    COMMENT_LINE_PREFIX,
+    PYTHON_FILE_SUFFIX,
+    STALE_COMMENT_ADDITIONAL_CONTEXT,
+    STALE_COMMENT_DENY_TEMPLATE,
+    STALE_COMMENT_SYSTEM_MESSAGE,
+)
+
+
+def _first_orphaned_identifier(
+    overlying_comment: str,
+    all_old_block_lines: list[str],
+    all_new_block_lines: list[str],
+) -> str | None:
+    """Return the first comment identifier the edit removes from the block.
+
+    Args:
+        overlying_comment: The stripped standalone comment text above the block.
+        all_old_block_lines: The replaced lines as they read before the edit.
+        all_new_block_lines: The replacement lines as they read after the edit.
+
+    Returns:
+        The first identifier the comment names that matches the old block and
+        not the new block, or None when the comment stays consistent.
+    """
+    words_in_comment = overlying_comment.lstrip(COMMENT_LINE_PREFIX).strip()
+    original_block_text = "\n".join(all_old_block_lines)
+    revised_block_text = "\n".join(all_new_block_lines)
+    for each_identifier in COMMENT_IDENTIFIER_PATTERN.findall(words_in_comment):
+        if each_identifier.lower() in ALL_COMMENT_STOPWORDS:
+            continue
+        bounded_pattern = re.compile(
+            "(?<![A-Za-z0-9_])" + re.escape(each_identifier) + "(?![A-Za-z0-9_])"
+        )
+        if bounded_pattern.search(original_block_text) and not bounded_pattern.search(
+            revised_block_text
+        ):
+            return each_identifier
+    return None
+
+
+def _occurrence_start_offsets(
+    old_content: str,
+    old_string: str,
+    is_replace_all: bool,
+) -> list[int]:
+    """List the character offsets where old_string starts in old_content.
+
+    Walks old_content left to right the same way str.replace does, so the
+    offsets line up with the occurrences the edit actually rewrites.
+
+    Args:
+        old_content: The file text before the edit.
+        old_string: The text the edit replaces.
+        is_replace_all: Whether every occurrence is collected, matching the
+            Edit tool's replace_all flag, or only the first one.
+
+    Returns:
+        The offset of each matching occurrence, in file order.
+    """
+    all_offsets: list[int] = []
+    search_from = 0
+    while True:
+        found_at = old_content.find(old_string, search_from)
+        if found_at == -1:
+            return all_offsets
+        all_offsets.append(found_at)
+        if not is_replace_all:
+            return all_offsets
+        search_from = found_at + len(old_string)
+
+
+def _preceding_line_text(old_content: str, occurrence_start: int) -> str | None:
+    """Return the stripped line directly above the line an occurrence sits in.
+
+    Args:
+        old_content: The file text before the edit.
+        occurrence_start: The character offset where the occurrence begins.
+
+    Returns:
+        The stripped text of the line above the occurrence's line, or None
+        when that line is the first line in the file.
+    """
+    containing_line_start = old_content.rfind("\n", 0, occurrence_start) + 1
+    if containing_line_start == 0:
+        return None
+    preceding_line_end = containing_line_start - 1
+    preceding_line_start = old_content.rfind("\n", 0, preceding_line_end) + 1
+    return old_content[preceding_line_start:preceding_line_end].strip()
+
+
+def _find_stale_comment_reference(
+    old_content: str,
+    old_string: str,
+    new_string: str,
+    is_replace_all: bool,
+    file_path: str,
+) -> str | None:
+    """Check each occurrence old_string rewrites for an orphaned comment above it.
+
+    Args:
+        old_content: The file text before the edit.
+        old_string: The text the edit replaces.
+        new_string: The text the edit substitutes in, empty for a straight
+            deletion.
+        is_replace_all: Whether every occurrence of old_string is checked,
+            matching the Edit tool's replace_all flag.
+        file_path: The target path, named in the deny reason.
+
+    Returns:
+        The deny-reason text for the first occurrence whose kept comment
+        names an identifier old_string carries and new_string drops, or None
+        when every kept comment stays consistent with the rewritten line.
+    """
+    all_old_block_lines = old_string.splitlines()
+    all_new_block_lines = new_string.splitlines()
+    for each_occurrence_start in _occurrence_start_offsets(old_content, old_string, is_replace_all):
+        preceding_line = _preceding_line_text(old_content, each_occurrence_start)
+        if preceding_line is None or not preceding_line.startswith(COMMENT_LINE_PREFIX):
+            continue
+        maybe_identifier = _first_orphaned_identifier(
+            preceding_line, all_old_block_lines, all_new_block_lines
+        )
+        if maybe_identifier is not None:
+            return STALE_COMMENT_DENY_TEMPLATE.format(
+                file_path=file_path,
+                contradicted_comment=preceding_line,
+                orphaned_name=maybe_identifier,
+            )
+    return None
+
+
+def evaluate(payload_by_key: dict[str, object]) -> str | None:
+    """Decide whether an Edit payload orphans a comment above a changed line.
+
+    Reads the target file from disk and checks the line directly above each
+    occurrence the edit rewrites for a kept standalone comment whose named
+    identifier the edit removes from the line below it. Non-Edit tools,
+    non-Python targets, unreadable files, and an old_string absent from the
+    file all pass.
+
+    Args:
+        payload_by_key: The PreToolUse payload with tool_name and tool_input.
+
+    Returns:
+        The deny-reason text when the edit is denied, or None when allowed.
+    """
+    raw_tool_name = payload_by_key.get("tool_name", "")
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    if tool_name != EDIT_TOOL_NAME:
+        return None
+
+    raw_tool_input = payload_by_key.get("tool_input", {})
+    tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
+
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path.endswith(PYTHON_FILE_SUFFIX):
+        return None
+
+    raw_old_string = tool_input.get("old_string", "")
+    raw_new_string = tool_input.get("new_string", "")
+    old_string = raw_old_string if isinstance(raw_old_string, str) else ""
+    new_string = raw_new_string if isinstance(raw_new_string, str) else ""
+    if not old_string:
+        return None
+
+    try:
+        old_content = Path(file_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    if old_string not in old_content:
+        return None
+
+    is_replace_all = tool_input.get("replace_all") is True
+    return _find_stale_comment_reference(
+        old_content, old_string, new_string, is_replace_all, file_path
+    )
+
+
+def build_deny_payload(deny_reason: str) -> dict[str, object]:
+    """Build the full deny payload the hook writes for a deny-reason string.
+
+    Logs the block, then returns the permission decision with the corrective
+    guidance in additionalContext, the user-facing systemMessage, and output
+    suppression, matching the deny shape the sibling blockers write.
+
+    Args:
+        deny_reason: The permissionDecisionReason text for the denial.
+
+    Returns:
+        The deny payload dictionary the hook serializes to stdout.
+    """
+    log_hook_block(
+        calling_hook_name="stale_comment_reference_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+            "additionalContext": STALE_COMMENT_ADDITIONAL_CONTEXT,
+        },
+        "systemMessage": STALE_COMMENT_SYSTEM_MESSAGE,
+        "suppressOutput": True,
+    }
+
+
+def main() -> None:
+    """Run the gate over the stdin payload dictionary and emit any denial.
+    """
+    payload_dictionary = read_hook_input_dictionary_from_stdin()
+    if payload_dictionary is None:
+        sys.exit(0)
+
+    deny_reason = evaluate(payload_dictionary)
+    if deny_reason is None:
+        sys.exit(0)
+
+    _emit_deny_line(build_deny_payload(deny_reason), sys.stdout)
+    sys.exit(0)
+
+
+def _emit_deny_line(
+    all_deny_payload_fields: dict[str, object], destination_stream: TextIO
+) -> None:
+    """Write the deny payload JSON as one line to the given stream.
+
+    Args:
+        all_deny_payload_fields: The deny payload to serialize.
+        destination_stream: The stream the JSON line is written to.
+    """
+    destination_stream.write(json.dumps(all_deny_payload_fields) + "\n")
+    destination_stream.flush()
+
+
+if __name__ == "__main__":
+    main()