claude-dev-env 2.30.1 → 2.31.0

package/hooks/blocking/pii_payload_scan.py

@@ -19,6 +19,11 @@ try:
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
     from code_rules_shared import is_ephemeral_path
+    from codex_apply_patch import (
+        CodexPatchError,
+        parse_codex_apply_patch,
+        payload_patch_command,
+    )
     from pii_prevention_blocker_parts.repository_exemption import (
         repository_allowlisted_values,
     )
@@ -48,6 +53,62 @@ except ImportError as import_error:
     ) from import_error
 
 
+def _apply_patch_post_contents(
+    command: str, working_directory: str | None
+) -> list[tuple[str, str]]:
+    """Return (file_path, post_content) pairs for a Codex apply_patch command."""
+    if not command:
+        return []
+    try:
+        all_patch_files = parse_codex_apply_patch(command, working_directory)
+    except CodexPatchError:
+        return []
+    return [
+        (each_patch_file.file_path, each_patch_file.post_content)
+        for each_patch_file in all_patch_files
+        if each_patch_file.post_content
+    ]
+
+
+def _apply_patch_target_deny_reason(
+    each_file_path: str,
+    each_post_content: str,
+    hook_payload: dict | None,
+) -> str | None:
+    """Return the deny reason for one apply_patch target, or None when it is clean or exempt."""
+    if is_path_exempt_from_pii_scan(each_file_path):
+        return None
+    if _target_is_ephemeral_outside_repository(each_file_path, hook_payload):
+        return None
+    return _write_deny_reason_for_texts([each_post_content], each_file_path, frozenset())
+
+
+def evaluate_apply_patch_payload(
+    all_tool_input: dict[str, object],
+    hook_payload: dict | None = None,
+) -> str | None:
+    """Return a deny reason when a Codex apply_patch payload's post content carries PII.
+
+    Args:
+        all_tool_input: The apply_patch payload's ``command`` and other input fields.
+        hook_payload: The PreToolUse payload carrying ``cwd`` and the session id.
+
+    Returns:
+        Deny reason text for the first target carrying non-allowlisted PII, or
+        None when every target is clean or out of scope.
+    """
+    command, working_directory = payload_patch_command(hook_payload, all_tool_input)
+    for each_file_path, each_post_content in _apply_patch_post_contents(
+        command, working_directory
+    ):
+        deny_reason = _apply_patch_target_deny_reason(
+            each_file_path, each_post_content, hook_payload
+        )
+        if deny_reason is not None:
+            return deny_reason
+    return None
+
+
 def _target_is_ephemeral_outside_repository(
     file_path: str, hook_payload: dict | None
 ) -> bool:

package/hooks/blocking/pii_prevention_blocker.py

@@ -40,6 +40,7 @@ try:
     )
     from pii_payload_scan import (
         build_deny_reason,
+        evaluate_apply_patch_payload,
         evaluate_post_body_texts,
         evaluate_write_edit_payload,
     )
@@ -66,6 +67,7 @@ try:
         ALL_STAGED_BLOB_SHOW_COMMAND_PREFIX,
         ALL_STAGED_FILES_COMMAND,
         ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+        APPLY_PATCH_TOOL_NAME,
         BODY_FILE_ENCODING,
         GIT_COMMAND_TIMEOUT_SECONDS,
         HOOK_SCRIPT_BASENAME,
@@ -92,6 +94,7 @@ except ImportError as import_error:
 
 __all__ = [
     "evaluate",
+    "evaluate_apply_patch_payload",
     "evaluate_bash_command",
     "evaluate_post_body_texts",
     "evaluate_staged_commit",
@@ -332,6 +335,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
         return evaluate_write_edit_payload(
             tool_name, all_tool_input, hook_payload=payload_by_key
         )
+    if tool_name == APPLY_PATCH_TOOL_NAME:
+        return evaluate_apply_patch_payload(all_tool_input, hook_payload=payload_by_key)
     if tool_name in ALL_SHELL_TOOL_NAMES:
         return _evaluate_shell_tool(all_tool_input, payload_by_key)
     if tool_name.startswith(MCP_GITHUB_TOOL_PREFIX):

package/hooks/blocking/pr_description_writer_gate.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block gh pr create when no pr-description-writer spawn is recorded.
+
+Picture a reviewer opening a fresh pull request and meeting a body that repeats
+the branch name. The ``pr-description-writer`` agent exists to write that body
+from the diff, and the spawn tracker records each time this session runs it.
+
+This gate reads that record when the session runs ``gh pr create``::
+
+    gh pr create --body-file body.md            flag: no spawn recorded
+    gh pr create --body-file body.md            ok:   a spawn recorded earlier
+    gh pr create ... # pr-description-skip      ok:   the author opted out
+
+Detection strategy: tokenize the command, then check each position that opens a
+command segment for a ``gh`` executable followed by ``pr`` and ``create``. The
+bypass marker counts only as the command's final tokens, so the same text
+inside a quoted title leaves the gate running.
+
+The gate fails OPEN on anything it cannot read: a command that will not
+tokenize, a payload that is not a shell tool, or a missing command. Only a
+recognized ``gh pr create`` with no recorded spawn and no bypass marker denies.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import sys
+import tempfile
+from pathlib import Path
+
+_blocking_dir = str(Path(__file__).resolve().parent)
+if _blocking_dir not in sys.path:
+    sys.path.insert(0, _blocking_dir)
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import (  # noqa: E402
+    ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pr_description_writer_gate_constants import (  # noqa: E402
+    ALL_GH_EXECUTABLE_BASENAMES,
+    COMMAND_FIELD_NAME,
+    CORRECTIVE_MESSAGE,
+    CREATE_SUBCOMMAND_TOKEN,
+    GH_PR_CREATE_MINIMUM_TOKEN_COUNT,
+    PR_SUBCOMMAND_TOKEN,
+    SPAWN_BYPASS_MARKER,
+    SPAWN_MARKER_FILE_PREFIX,
+    SPAWN_MARKER_FILE_SUFFIX,
+    TOOL_INPUT_FIELD_NAME,
+    TOOL_NAME_FIELD_NAME,
+)
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_COMMAND_SEPARATOR_TOKENS,
+    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
+)
+
+
+def _all_command_tokens(shell_command: str) -> list[str] | None:
+    """Return the command's tokens, or None when it will not tokenize.
+
+    Args:
+        shell_command: The raw shell command string.
+
+    Returns:
+        The token list, or None when shlex rejects the command.
+    """
+    try:
+        return shlex.split(shell_command, posix=True)
+    except ValueError:
+        return None
+
+
+def _carries_trailing_bypass_marker(all_tokens: list[str]) -> bool:
+    """Report whether the bypass marker sits at the very end of the command.
+
+    The marker opts out only as a trailing shell comment the author adds on
+    purpose, so its parts are the command's final tokens. The same text inside
+    a quoted title tokenizes into the middle of the list and does not match.
+
+    Args:
+        all_tokens: The tokens of the whole command.
+
+    Returns:
+        True when the marker's tokens close the command.
+    """
+    all_marker_tokens = SPAWN_BYPASS_MARKER.split()
+    marker_length = len(all_marker_tokens)
+    if marker_length > len(all_tokens):
+        return False
+    return all_tokens[-marker_length:] == all_marker_tokens
+
+
+def _opens_pull_request_creation(all_leading_tokens: list[str]) -> bool:
+    """Report whether these leading tokens open a gh pr create invocation.
+
+    Args:
+        all_leading_tokens: The tokens that open one command segment.
+
+    Returns:
+        True when they name a gh executable, then ``pr``, then ``create``.
+    """
+    if len(all_leading_tokens) < GH_PR_CREATE_MINIMUM_TOKEN_COUNT:
+        return False
+    executable_basename = Path(all_leading_tokens[0]).name
+    if executable_basename not in ALL_GH_EXECUTABLE_BASENAMES:
+        return False
+    return all_leading_tokens[1:] == [PR_SUBCOMMAND_TOKEN, CREATE_SUBCOMMAND_TOKEN]
+
+
+def _all_command_segments(all_tokens: list[str]) -> list[list[str]]:
+    """Return the command's token segments in their original order.
+
+    A shell separator ends the current segment and starts the next one.
+
+    Args:
+        all_tokens: The tokens of the whole command.
+
+    Returns:
+        One token list for each command segment.
+    """
+    all_segments: list[list[str]] = [[]]
+    for each_token in all_tokens:
+        if each_token in ALL_COMMAND_SEPARATOR_TOKENS:
+            all_segments.append([])
+            continue
+        all_segments[-1].append(each_token)
+    return all_segments
+
+
+def _all_pull_request_creation_segment_indexes(all_segments: list[list[str]]) -> list[int]:
+    """Return indexes for segments that open a gh pr create command.
+
+    Args:
+        all_segments: The shell command's token segments.
+
+    Returns:
+        The indexes of segments that open a gh pr create command.
+    """
+    return [
+        each_index
+        for each_index, each_segment in enumerate(all_segments)
+        if _opens_pull_request_creation(each_segment[:GH_PR_CREATE_MINIMUM_TOKEN_COUNT])
+    ]
+
+
+def _only_final_create_carries_bypass(
+    all_tokens: list[str], all_creation_segment_indexes: list[int]
+) -> bool:
+    """Report whether one final gh pr create carries the final bypass comment.
+
+    The marker belongs to the command segment that creates the pull request.
+    A marker after another command, or after a second create, cannot opt an
+    earlier create out.
+
+    Args:
+        all_tokens: The tokens of the whole command.
+        all_creation_segment_indexes: Indexes of segments that create pull requests.
+
+    Returns:
+        True when one final create segment carries the final bypass marker.
+    """
+    if not _carries_trailing_bypass_marker(all_tokens):
+        return False
+    final_segment_index = len(_all_command_segments(all_tokens)) - 1
+    return all_creation_segment_indexes == [final_segment_index]
+
+
+def _spawn_is_recorded(session_id: str) -> bool:
+    """Report whether this session recorded a pr-description-writer spawn.
+
+    A payload naming no session reads as no record, so the gate denies rather
+    than falling back to a shared marker a different session could have left.
+
+    Args:
+        session_id: Raw ``session_id`` from the hook payload.
+
+    Returns:
+        True when this session's marker file is present.
+    """
+    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
+    if not sanitized_session_id:
+        return False
+    file_name = f"{SPAWN_MARKER_FILE_PREFIX}{sanitized_session_id}{SPAWN_MARKER_FILE_SUFFIX}"
+    return (Path(tempfile.gettempdir()) / file_name).exists()
+
+
+def _shell_command_or_none(all_hook_payload: dict[str, object]) -> str | None:
+    """Return the shell command this payload carries, or None.
+
+    Args:
+        all_hook_payload: The parsed PreToolUse payload.
+
+    Returns:
+        The command string, or None when the payload runs no shell command.
+    """
+    if all_hook_payload.get(TOOL_NAME_FIELD_NAME, "") not in ALL_BASH_AND_POWERSHELL_TOOL_NAMES:
+        return None
+    tool_input = all_hook_payload.get(TOOL_INPUT_FIELD_NAME, {})
+    if not isinstance(tool_input, dict):
+        return None
+    shell_command = tool_input.get(COMMAND_FIELD_NAME, "")
+    if not isinstance(shell_command, str) or not shell_command:
+        return None
+    return shell_command
+
+
+def _emit_denial() -> None:
+    """Write the PreToolUse deny payload to stdout and log the block."""
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": CORRECTIVE_MESSAGE,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="pr_description_writer_gate.py",
+        hook_event="PreToolUse",
+        block_reason=CORRECTIVE_MESSAGE,
+    )
+    sys.stdout.write(json.dumps(deny_payload) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> None:
+    """Deny a gh pr create that no recorded agent spawn or bypass marker covers.
+
+    Reads the PreToolUse payload from stdin and exits zero on every branch. A
+    tool that runs no shell, a missing command, a command that will not
+    tokenize, a command opening no pull request, a trailing bypass marker, and
+    a recorded spawn each pass through untouched.
+    """
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_payload, dict):
+        sys.exit(0)
+    shell_command = _shell_command_or_none(hook_payload)
+    if shell_command is None:
+        sys.exit(0)
+    all_tokens = _all_command_tokens(shell_command)
+    if all_tokens is None:
+        sys.exit(0)
+    all_segments = _all_command_segments(all_tokens)
+    all_creation_segment_indexes = _all_pull_request_creation_segment_indexes(all_segments)
+    if not all_creation_segment_indexes:
+        sys.exit(0)
+    if _only_final_create_carries_bypass(all_tokens, all_creation_segment_indexes):
+        sys.exit(0)
+    if _spawn_is_recorded(str(hook_payload.get("session_id") or "")):
+        sys.exit(0)
+    _emit_denial()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""PreToolUse dispatcher that hosts Write, Edit, and MultiEdit blocking hooks.
+"""PreToolUse dispatcher that hosts Write, Edit, MultiEdit, and apply_patch blocking hooks.
 
 Reads the tool payload from stdin once, selects the hosted hooks applicable to
 the payload's tool name, runs each hook in-process via runpy in the fixed order

package/hooks/blocking/sensitive_file_protector.py

@@ -34,9 +34,11 @@ import sys
 
 import _path_setup  # noqa: F401
 
+from codex_apply_patch import payload_patch_target_paths
 from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_dispatcher_constants import (
-    ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES,
+    APPLY_PATCH_TOOL_NAME,
 )
 from hooks_constants.sensitive_file_protector_constants import (
     ALL_SENSITIVE_PATTERNS,
@@ -108,7 +110,7 @@ def deny_write(file_path: str, matched_pattern: str) -> None:
     """Record the block in the hook-blocks log and emit the deny decision.
 
     Args:
-        file_path: The path the Write, Edit, or MultiEdit targets.
+        file_path: The path the Write, Edit, MultiEdit, or apply_patch targets.
         matched_pattern: The sensitive pattern the basename matched.
     """
     deny_reason = DENY_REASON_TEMPLATE.format(
@@ -124,6 +126,15 @@ def deny_write(file_path: str, matched_pattern: str) -> None:
     sys.stdout.write(json.dumps(build_deny_response(deny_reason)))
 
 
+def _deny_apply_patch_sensitive_target(hook_input: dict, tool_input: dict) -> None:
+    """Deny the first apply_patch target path whose basename names a sensitive file."""
+    for each_target_path in payload_patch_target_paths(hook_input, tool_input):
+        matched_pattern = is_sensitive_file(each_target_path)
+        if matched_pattern is not None:
+            deny_write(each_target_path, matched_pattern)
+            return
+
+
 def main() -> None:
     """Deny the write when the stdin payload targets a sensitive filename."""
     try:
@@ -134,7 +145,11 @@ def main() -> None:
     tool_name = hook_input.get("tool_name", "")
     tool_input = hook_input.get("tool_input", {})
 
-    if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES:
+    if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES:
+        sys.exit(0)
+
+    if tool_name == APPLY_PATCH_TOOL_NAME:
+        _deny_apply_patch_sensitive_target(hook_input, tool_input)
         sys.exit(0)
 
     file_path = tool_input.get("file_path", "")

package/hooks/blocking/shell_substitution_blocker.py

@@ -54,53 +54,31 @@ import json
 import sys
 from pathlib import Path
 
-try:
-    from hooks_constants.shell_substitution_blocker_constants import (
-        BASH_TOOL_NAME,
-        CLOSE_PAREN_CHARACTER,
-        COMMAND_KEY,
-        CORRECTIVE_MESSAGE,
-        DENY_DECISION,
-        DOLLAR_PAREN_PATTERN,
-        EVEN_BACKSLASH_BACKTICK_PATTERN,
-        HOOK_EVENT_NAME,
-        HOOK_EVENT_NAME_KEY,
-        HOOK_SPECIFIC_OUTPUT_KEY,
-        OPEN_PAREN_CHARACTER,
-        PAREN_DEPTH_AFTER_DOUBLE_OPEN,
-        PERMISSION_DECISION_KEY,
-        PERMISSION_DECISION_REASON_KEY,
-        PROCESS_SUBSTITUTION_PATTERN,
-        SINGLE_QUOTED_RUN_PATTERN,
-        STRIPPED_RUN_REPLACEMENT,
-        TOOL_INPUT_KEY,
-        TOOL_NAME_KEY,
-    )
-except ModuleNotFoundError:
-    _hooks_dir = str(Path(__file__).resolve().parent.parent)
-    if _hooks_dir not in sys.path:
-        sys.path.insert(0, _hooks_dir)
-    from hooks_constants.shell_substitution_blocker_constants import (
-        BASH_TOOL_NAME,
-        CLOSE_PAREN_CHARACTER,
-        COMMAND_KEY,
-        CORRECTIVE_MESSAGE,
-        DENY_DECISION,
-        DOLLAR_PAREN_PATTERN,
-        EVEN_BACKSLASH_BACKTICK_PATTERN,
-        HOOK_EVENT_NAME,
-        HOOK_EVENT_NAME_KEY,
-        HOOK_SPECIFIC_OUTPUT_KEY,
-        OPEN_PAREN_CHARACTER,
-        PAREN_DEPTH_AFTER_DOUBLE_OPEN,
-        PERMISSION_DECISION_KEY,
-        PERMISSION_DECISION_REASON_KEY,
-        PROCESS_SUBSTITUTION_PATTERN,
-        SINGLE_QUOTED_RUN_PATTERN,
-        STRIPPED_RUN_REPLACEMENT,
-        TOOL_INPUT_KEY,
-        TOOL_NAME_KEY,
-    )
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
+    BASH_TOOL_NAME,
+    CLOSE_PAREN_CHARACTER,
+    COMMAND_KEY,
+    CORRECTIVE_MESSAGE,
+    DENY_DECISION,
+    DOLLAR_PAREN_PATTERN,
+    EVEN_BACKSLASH_BACKTICK_PATTERN,
+    HOOK_EVENT_NAME,
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    OPEN_PAREN_CHARACTER,
+    PAREN_DEPTH_AFTER_DOUBLE_OPEN,
+    PERMISSION_DECISION_KEY,
+    PERMISSION_DECISION_REASON_KEY,
+    PROCESS_SUBSTITUTION_PATTERN,
+    SINGLE_QUOTED_RUN_PATTERN,
+    STRIPPED_RUN_REPLACEMENT,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
 
 
 def _strip_single_quoted_runs(command: str) -> str:

package/hooks/blocking/stale_comment_reference_blocker.py

@@ -11,28 +11,95 @@ directly above it, denying the edit when that line is a standalone ``#``
 comment naming an identifier ``old_string`` carries and ``new_string`` drops.
 """
 
+import functools
 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)
+try:
+    _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,
-)
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.multi_edit_reconstruction import edits_for_tool
+    from hooks_constants.pre_tool_use_dispatcher_constants import (
+        EDIT_TOOL_NAME,
+        MULTI_EDIT_TOOL_NAME,
+    )
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.stale_comment_reference_blocker_constants import (
+        ALL_COMMENT_STOPWORDS,
+        COMMENT_IDENTIFIER_PATTERN,
+        COMMENT_LINE_PREFIX,
+        PYTHON_FILE_SUFFIX,
+        STALE_COMMENT_ADDITIONAL_CONTEXT,
+        STALE_COMMENT_DENY_TEMPLATE,
+        STALE_COMMENT_SYSTEM_MESSAGE,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "stale_comment_reference_blocker: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _edit_step_fields(each_edit: object) -> tuple[str, str, bool] | None:
+    """Return (old_string, new_string, is_replace_all) for one usable MultiEdit step."""
+    if not isinstance(each_edit, dict):
+        return None
+    old_string = each_edit.get("old_string", "")
+    new_string = each_edit.get("new_string", "")
+    if not isinstance(old_string, str) or not isinstance(new_string, str) or not old_string:
+        return None
+    return old_string, new_string, each_edit.get("replace_all") is True
+
+
+def _evaluate_multi_edit(file_path: str, all_tool_input: dict[str, object]) -> str | None:
+    """Judge each MultiEdit step against the content the prior steps already left.
+
+    Args:
+        file_path: The destination path the MultiEdit targets.
+        all_tool_input: The MultiEdit payload's input mapping.
+
+    Returns:
+        The deny-reason text for the first step whose kept comment orphans an
+        identifier, or None when every step stays consistent.
+    """
+    try:
+        current_content = Path(file_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    for each_edit in edits_for_tool(MULTI_EDIT_TOOL_NAME, all_tool_input):
+        edit_fields = _edit_step_fields(each_edit)
+        if edit_fields is None:
+            continue
+        old_string, new_string, is_replace_all = edit_fields
+        if old_string not in current_content:
+            continue
+        deny_reason = _find_stale_comment_reference(
+            current_content, old_string, new_string, is_replace_all, file_path
+        )
+        if deny_reason is not None:
+            return deny_reason
+        current_content = current_content.replace(old_string, new_string, -1 if is_replace_all else 1)
+    return None
+
+
+@functools.lru_cache
+def _bounded_identifier_pattern(identifier: str) -> re.Pattern[str]:
+    """Return the compiled whole-word pattern for one comment-named identifier.
+
+    Args:
+        identifier: The identifier the comment names.
+
+    Returns:
+        The compiled pattern matching identifier with no adjoining word
+        character on either side.
+    """
+    return re.compile("(?<![A-Za-z0-9_])" + re.escape(identifier) + "(?![A-Za-z0-9_])")
 
 
 def _first_orphaned_identifier(
@@ -57,9 +124,7 @@ def _first_orphaned_identifier(
     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_])"
-        )
+        bounded_pattern = _bounded_identifier_pattern(each_identifier)
         if bounded_pattern.search(original_block_text) and not bounded_pattern.search(
             revised_block_text
         ):
@@ -159,13 +224,15 @@ def _find_stale_comment_reference(
 
 
 def evaluate(payload_by_key: dict[str, object]) -> str | None:
-    """Decide whether an Edit payload orphans a comment above a changed line.
+    """Decide whether an Edit or MultiEdit 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.
+    occurrence a step rewrites for a kept standalone comment whose named
+    identifier the step carries and drops. A MultiEdit's steps are judged in
+    order against the content the prior steps already left, so a step that
+    only reads as stale once an earlier step in the same payload has run is
+    still caught. Non-Edit/MultiEdit 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.
@@ -175,7 +242,7 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     """
     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:
+    if tool_name not in (EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME):
         return None
 
     raw_tool_input = payload_by_key.get("tool_input", {})
@@ -185,6 +252,9 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     if not isinstance(file_path, str) or not file_path.endswith(PYTHON_FILE_SUFFIX):
         return None
 
+    if tool_name == MULTI_EDIT_TOOL_NAME:
+        return _evaluate_multi_edit(file_path, tool_input)
+
     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 ""