claude-dev-env 2.31.0 → 2.32.0

package/hooks/blocking/code_rules_enforcer.py

@@ -247,11 +247,11 @@ def _validated_phase(phase: str) -> str:
     return phase
 
 
-def _codex_patch_issues(each_patch_file: CodexPatchFile) -> list[str]:
+def _codex_patch_issues(each_patch_file: CodexPatchFile, repository_root: str = "") -> list[str]:
     """Run the existing code-rules verdict over one Codex patch view."""
     if not each_patch_file.post_content and each_patch_file.operation == "delete":
         return []
-    if _is_hook_infrastructure_python_target(each_patch_file.file_path):
+    if _is_hook_infrastructure_python_target(each_patch_file.file_path, repository_root):
         all_issues = _hook_infrastructure_blocking_issues(
             each_patch_file.post_content,
             each_patch_file.file_path,
@@ -259,7 +259,7 @@ def _codex_patch_issues(each_patch_file: CodexPatchFile) -> list[str]:
             each_patch_file.prior_content,
             phase=EDIT_LANE_PHASE,
         )
-    elif _is_validated_target(each_patch_file.file_path):
+    elif _is_validated_target(each_patch_file.file_path, repository_root):
         all_issues = validate_content_for_edit_lane(
             each_patch_file.post_content,
             each_patch_file.file_path,
@@ -306,7 +306,7 @@ def _report_codex_patch_payload(
     all_issues = [
         each_issue
         for each_patch_file in all_patch_files
-        for each_issue in _codex_patch_issues(each_patch_file)
+        for each_issue in _codex_patch_issues(each_patch_file, working_directory or "")
     ]
     if all_issues:
         _write_deny_payload(
@@ -708,14 +708,16 @@ def validate_content_for_full_gate(
 
 
 def prior_and_post_edit_content(
-    file_path: str, old_string: str, new_string: str,
+    file_path: str, old_string: str, new_string: str, is_replace_all: bool = False,
 ) -> tuple[str | None, str | None]:
     """Return the pre-edit and post-edit file content from a single disk read.
 
     Reads ``file_path`` once and derives both views from that single read so the
     prior and the reconstruction never diverge across two independent reads.
-    The post-edit view replaces the first occurrence of ``old_string`` with
-    ``new_string``, mirroring how the Edit tool itself applies a single
+    The post-edit view comes from apply_edits, the same reconstruction the
+    MultiEdit lane uses, so one payload never reconstructs two ways. It replaces
+    the first occurrence of ``old_string`` with ``new_string``, or every occurrence
+    when the Edit carries ``replace_all``, mirroring how the Edit tool applies a
     replacement.
 
     Returns ``(None, None)`` when the file cannot be read, ``old_string`` is
@@ -729,6 +731,7 @@ def prior_and_post_edit_content(
         file_path: The path of the file the Edit targets.
         old_string: The Edit's ``old_string`` fragment.
         new_string: The Edit's ``new_string`` fragment.
+        is_replace_all: Whether the Edit carries ``replace_all``.
 
     Returns:
         A ``(prior_content, post_edit_content)`` pair, or ``(None, None)`` when
@@ -741,14 +744,22 @@ def prior_and_post_edit_content(
         return None, None
     if old_string not in existing_content:
         return None, None
-    return existing_content, existing_content.replace(old_string, new_string, 1)
+    one_edit = {
+        "old_string": old_string,
+        "new_string": new_string,
+        "replace_all": is_replace_all,
+    }
+    return existing_content, apply_edits(existing_content, [one_edit])
 
 
-def _is_validated_target(file_path: str) -> bool:
+def _is_validated_target(file_path: str, repository_root: str = "") -> bool:
     """Return whether the path is subject to code-rules validation.
 
     Args:
         file_path: The destination path of the write, edit, or pre-check target.
+        repository_root: The session's working directory (the PreToolUse
+            payload's ``cwd``), so a path inside it is never exempted as
+            scratch merely because the repository sits under ``/tmp``.
 
     Returns:
         True when the path is non-empty, outside hook infrastructure, and
@@ -756,14 +767,14 @@ def _is_validated_target(file_path: str) -> bool:
     """
     if not file_path:
         return False
-    if is_ephemeral_script_path(file_path):
+    if is_ephemeral_script_path(file_path, repository_root):
         return False
     if is_hook_infrastructure(file_path):
         return False
     return get_file_extension(file_path) in ALL_CODE_EXTENSIONS
 
 
-def _is_hook_infrastructure_python_target(file_path: str) -> bool:
+def _is_hook_infrastructure_python_target(file_path: str, repository_root: str = "") -> bool:
     """Return whether the path is a hook-infrastructure Python file.
 
     The full code-rules suite exempts hook-infrastructure files, but the
@@ -773,13 +784,16 @@ def _is_hook_infrastructure_python_target(file_path: str) -> bool:
 
     Args:
         file_path: The destination path of the write, edit, or pre-check target.
+        repository_root: The session's working directory (the PreToolUse
+            payload's ``cwd``), so a path inside it is never exempted as
+            scratch merely because the repository sits under ``/tmp``.
 
     Returns:
         True when the path names a Python file inside hook infrastructure.
     """
     if not file_path:
         return False
-    if is_ephemeral_script_path(file_path):
+    if is_ephemeral_script_path(file_path, repository_root):
         return False
     if not is_hook_infrastructure(file_path):
         return False
@@ -1170,6 +1184,7 @@ def _contents_for_validation(
     if tool_name == "Edit":
         prior_content, full_file_content_after_edit = prior_and_post_edit_content(
             file_path, old_string, new_string,
+            is_replace_all=all_tool_input.get("replace_all") is True,
         )
         if full_file_content_after_edit is None:
             full_file_content_after_edit = existing_file_content(file_path)
@@ -1372,8 +1387,11 @@ def main(all_arguments: list[str]) -> None:
     if is_under_session_scratchpad(file_path, pretooluse_payload):
         sys.exit(0)
 
-    runs_full_verdict = _is_validated_target(file_path)
-    if not runs_full_verdict and not _is_hook_infrastructure_python_target(file_path):
+    repository_root = str(pretooluse_payload.get("cwd") or "")
+    runs_full_verdict = _is_validated_target(file_path, repository_root)
+    if not runs_full_verdict and not _is_hook_infrastructure_python_target(
+        file_path, repository_root
+    ):
         sys.exit(0)
 
     validation_contents = _contents_for_validation(

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_shared.py

@@ -251,10 +251,50 @@ def _extract_fstring_literal_parts(
     return "".join(display_segments), "".join(shape_segments)
 
 
-def is_ephemeral_script_path(file_path: str) -> bool:
+def _normalized_absolute_comparison_path(raw_path: str) -> str:
+    """Return raw_path as an absolute, lowercase, forward-slash path for root comparison.
+
+    Strips a leading Windows drive letter after normalizing, so a POSIX root
+    check and a Windows root check compare on the same shape.
+
+    Args:
+        raw_path: The path to normalize.
+
+    Returns:
+        The absolute, lowercase, forward-slash path with any leading drive
+        letter removed.
+    """
+    return LEADING_DRIVE_LETTER_PATTERN.sub("", os.path.abspath(raw_path).replace("\\", "/").lower())
+
+
+def _is_at_or_under_root(normalized_candidate: str, normalized_root: str) -> bool:
+    """Return whether normalized_candidate sits at or under normalized_root.
+
+    Requires a path-segment boundary (an exact match or a ``/`` before the
+    remainder), so ``/tmp/repo-sibling`` never counts as under ``/tmp/repo``.
+
+    Args:
+        normalized_candidate: A path already run through
+            ``_normalized_absolute_comparison_path``.
+        normalized_root: A root path already run through
+            ``_normalized_absolute_comparison_path``.
+
+    Returns:
+        True when normalized_candidate equals normalized_root or names a
+        descendant of it.
+    """
+    return normalized_candidate == normalized_root or normalized_candidate.startswith(normalized_root + "/")
+
+
+def is_ephemeral_script_path(file_path: str, repository_root: str = "") -> bool:
     """Return True when the path is rooted at a throwaway scratch directory.
 
     Checks these sources in order:
+    - ``repository_root`` — when given, a path inside it is never ephemeral,
+      whatever directory the repository itself is checked out under. This
+      keeps a repository placed under ``/tmp`` fully gated: the exemption
+      below is for scratch outside every repository, not for the repository's
+      own files.
     - ``$CLAUDE_JOB_DIR/tmp`` — only when ``CLAUDE_JOB_DIR`` is set.
     - Root-anchored ``/tmp`` and ``/temp`` (drive-letter tolerant).
 
@@ -262,20 +302,28 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     its sandbox fixtures there, so matching it would exempt the suite's own
     targets. Returns False when ``CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT``
     is truthy, when ``file_path`` is empty, and when no root matches. Path
-    classification is string-only; the file need not exist.
+    classification is string-only; neither path need exist.
 
     Args:
         file_path: The candidate path to classify.
+        repository_root: The session's working directory — typically the
+            PreToolUse payload's ``cwd`` — or empty when no such directory is
+            known. A path outside this directory is unaffected by it.
 
     Returns:
-        True when the path is rooted at a recognized ephemeral scratch directory.
+        True when the path is rooted at a recognized ephemeral scratch
+        directory and does not sit inside ``repository_root``.
     """
     if not file_path:
         return False
     disable_value = os.environ.get(EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME, "").strip().lower()
     if disable_value in ALL_EPHEMERAL_EXEMPT_DISABLE_TRUTHY_VALUES:
         return False
-    normalized = LEADING_DRIVE_LETTER_PATTERN.sub("", os.path.abspath(file_path).replace("\\", "/").lower())
+    normalized = _normalized_absolute_comparison_path(file_path)
+    if repository_root and _is_at_or_under_root(
+        normalized, _normalized_absolute_comparison_path(repository_root)
+    ):
+        return False
     all_temp_roots: list[str] = []
     job_dir = os.environ.get(CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME)
     if job_dir:
@@ -286,7 +334,7 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     for each_root in ALL_ROOT_ANCHORED_EPHEMERAL_DIRECTORIES:
         all_temp_roots.append(each_root)
     for each_temp_root in all_temp_roots:
-        if normalized == each_temp_root or normalized.startswith(each_temp_root + "/"):
+        if _is_at_or_under_root(normalized, each_temp_root):
             return True
     return False
 
@@ -426,23 +474,25 @@ def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
     Combines the path families a repo gate skips: the root-anchored ephemeral
     scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``), the harness
     session scratchpad, and a coding agent's own home-directory tooling such as
-    ``~/.grok/runs/``. The session scratchpad match reads the session id from the
-    payload when one is supplied, and from the harness environment variable
-    otherwise, so a caller that holds no payload still gets the match. The
-    run_all_validators PreToolUse gate calls this predicate to skip an exempt
-    target before it validates. The code-rules and TDD gates call the underlying
-    predicates ``is_ephemeral_script_path``, ``is_agent_home_tooling``, and
+    ``~/.grok/runs/``. A path inside the payload's own working directory
+    (``cwd``) is never treated as scratch, so a repository checked out under
+    ``/tmp`` still receives full enforcement. The scratchpad match reads the
+    session id from the payload when supplied, else the harness environment
+    variable. The code-rules and TDD gates call the underlying predicates
+    ``is_ephemeral_script_path``, ``is_agent_home_tooling``, and
     ``is_under_session_scratchpad`` directly.
 
     Args:
         file_path: The candidate path to classify.
-        hook_payload: The PreToolUse payload carrying the session id, or None to
-            read the session id from the environment alone.
+        hook_payload: The PreToolUse payload carrying the session id and the
+            working directory (``cwd``), or None to read the session id from
+            the environment alone.
 
     Returns:
         True when the path is scratch, agent tooling, or the session scratchpad.
     """
-    if is_ephemeral_script_path(file_path):
+    repository_root = str((hook_payload or {}).get("cwd") or "")
+    if is_ephemeral_script_path(file_path, repository_root):
         return True
     if is_agent_home_tooling(file_path):
         return True

package/hooks/blocking/pr_description_writer_gate.py

@@ -26,7 +26,6 @@ from __future__ import annotations
 import json
 import shlex
 import sys
-import tempfile
 from pathlib import Path
 
 _blocking_dir = str(Path(__file__).resolve().parent)
@@ -41,6 +40,9 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (  # noqa: E4
     ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
 )
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
 from hooks_constants.pr_description_writer_gate_constants import (  # noqa: E402
     ALL_GH_EXECUTABLE_BASENAMES,
     COMMAND_FIELD_NAME,
@@ -49,15 +51,14 @@ from hooks_constants.pr_description_writer_gate_constants import (  # noqa: E402
     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,
+    spawn_marker_path,
 )
 from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
     ALL_COMMAND_SEPARATOR_TOKENS,
-    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
 )
+from sensitive_file_protector import build_deny_response  # noqa: E402
 
 
 def _all_command_tokens(shell_command: str) -> list[str] | None:
@@ -149,7 +150,9 @@ def _all_pull_request_creation_segment_indexes(all_segments: list[list[str]]) ->
 
 
 def _only_final_create_carries_bypass(
-    all_tokens: list[str], all_creation_segment_indexes: list[int]
+    all_tokens: list[str],
+    all_segments: list[list[str]],
+    all_creation_segment_indexes: list[int],
 ) -> bool:
     """Report whether one final gh pr create carries the final bypass comment.
 
@@ -159,6 +162,7 @@ def _only_final_create_carries_bypass(
 
     Args:
         all_tokens: The tokens of the whole command.
+        all_segments: The command's token segments, already split by the caller.
         all_creation_segment_indexes: Indexes of segments that create pull requests.
 
     Returns:
@@ -166,7 +170,7 @@ def _only_final_create_carries_bypass(
     """
     if not _carries_trailing_bypass_marker(all_tokens):
         return False
-    final_segment_index = len(_all_command_segments(all_tokens)) - 1
+    final_segment_index = len(all_segments) - 1
     return all_creation_segment_indexes == [final_segment_index]
 
 
@@ -182,11 +186,8 @@ def _spawn_is_recorded(session_id: str) -> bool:
     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()
+    marker_file = spawn_marker_path(session_id)
+    return marker_file is not None and marker_file.exists()
 
 
 def _shell_command_or_none(all_hook_payload: dict[str, object]) -> str | None:
@@ -211,19 +212,12 @@ def _shell_command_or_none(all_hook_payload: dict[str, object]) -> str | None:
 
 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.write(json.dumps(build_deny_response(CORRECTIVE_MESSAGE)) + "\n")
     sys.stdout.flush()
 
 
@@ -235,11 +229,8 @@ def main() -> None:
     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):
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
         sys.exit(0)
     shell_command = _shell_command_or_none(hook_payload)
     if shell_command is None:
@@ -251,7 +242,9 @@ def main() -> None:
     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):
+    if _only_final_create_carries_bypass(
+        all_tokens, all_segments, all_creation_segment_indexes
+    ):
         sys.exit(0)
     if _spawn_is_recorded(str(hook_payload.get("session_id") or "")):
         sys.exit(0)

package/hooks/blocking/shell_substitution_blocker.py

@@ -23,6 +23,12 @@ ignored because bash performs no substitution inside them (for example
 are treated as literal only when the count of preceding backslashes is odd;
 an even count (including zero) means the backtick is a live substitution.
 
+A quoted heredoc body is stripped for the same reason. `<<'EOF'`, `<<"EOF"`
+and `<<\\EOF` each tell bash to expand nothing between the opener and the
+terminator, so a backtick there is text the file receives rather than a
+command the shell runs. A bare `<<EOF` expands its body and keeps its scan,
+and text outside any heredoc is scanned either way.
+
 Bash arithmetic expansion ``$((...))`` is explicitly NOT blocked: it does not
 spawn a subshell and does not defeat the allowlist matcher. Telling it apart
 from a disguised command substitution takes more than counting two open
@@ -41,11 +47,6 @@ another ``)`` (an ``))`` pair), the expansion is arithmetic and passes. When
 the closer that brings depth to zero is a lone ``)``, bash has fallen back to
 running a parenthesized command inside the substitution, so it is blocked.
 This hook applies that walk, tracking paren depth from the opening ``$((``.
-
-False positives are still possible when the user is intentionally writing
-shell-script content (for example, authoring a .sh file via heredoc) and the
-substitution is literal payload rather than something to execute. In that
-case, author the file with the Write tool, not a Bash heredoc.
 """
 
 from __future__ import annotations
@@ -53,6 +54,7 @@ from __future__ import annotations
 import json
 import sys
 from pathlib import Path
+from re import Match
 
 _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
@@ -74,6 +76,11 @@ from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
     PERMISSION_DECISION_KEY,
     PERMISSION_DECISION_REASON_KEY,
     PROCESS_SUBSTITUTION_PATTERN,
+    BACKSLASH_CHARACTER,
+    COMMAND_LINE_SEPARATOR,
+    DOUBLE_QUOTE_CHARACTER,
+    NO_TERMINATOR_INDEX,
+    SINGLE_QUOTE_CHARACTER,
     SINGLE_QUOTED_RUN_PATTERN,
     STRIPPED_RUN_REPLACEMENT,
     TOOL_INPUT_KEY,
@@ -81,10 +88,169 @@ from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
 )
 
 
+from hooks_constants.piped_pytest_blocker_constants import (  # noqa: E402
+    HEREDOC_ESCAPE_GROUP,
+    HEREDOC_OPENER_PATTERN,
+    HEREDOC_QUOTE_GROUP,
+    HEREDOC_TAB_STRIP_GROUP,
+    HEREDOC_TAB_STRIP_MARKER,
+    HEREDOC_TERMINATOR_GROUP,
+    HEREDOC_UNQUOTED_MARKER,
+)
+from hooks_constants.shell_command_pipeline import (  # noqa: E402
+    PendingHeredoc,
+    closes_the_heredoc,
+)
+
+
 def _strip_single_quoted_runs(command: str) -> str:
     return SINGLE_QUOTED_RUN_PATTERN.sub(STRIPPED_RUN_REPLACEMENT, command)
 
 
+def _opener_suppresses_expansion(opener_match: Match[str]) -> bool:
+    """Return whether an opener's delimiter is quoted or backslash-escaped.
+
+    ::
+
+        <<'EOF'  -> True   quoted, the body is literal
+        <<EOF    -> False  bare, bash expands the body
+
+    Args:
+        opener_match: One HEREDOC_OPENER_PATTERN match from a command line.
+
+    Returns:
+        True when bash expands nothing down to this opener's terminator.
+    """
+    is_quoted = opener_match.group(HEREDOC_QUOTE_GROUP) != HEREDOC_UNQUOTED_MARKER
+    is_escaped = opener_match.group(HEREDOC_ESCAPE_GROUP) != HEREDOC_UNQUOTED_MARKER
+    return is_quoted or is_escaped
+
+
+def _sits_outside_quotes(command_line: str, character_index: int) -> bool:
+    """Return whether a position on a line sits outside every quoted run.
+
+    ::
+
+        cat <<'EOF'      index of << -> True   bash reads an opener
+        echo "<<'EOF'"   index of << -> False  bash reads a string
+
+    Counting unescaped quotes before the position tells the two apart: an even
+    count of each quote character means every run opened before it also closed.
+
+    Args:
+        command_line: One line of the command.
+        character_index: Position of the candidate opener on that line.
+
+    Returns:
+        True when bash reads this position as shell syntax.
+    """
+    single_quote_count = 0
+    double_quote_count = 0
+    is_escaped = False
+    for each_character in command_line[:character_index]:
+        if is_escaped:
+            is_escaped = False
+            continue
+        if each_character == BACKSLASH_CHARACTER:
+            is_escaped = True
+            continue
+        if each_character == SINGLE_QUOTE_CHARACTER:
+            single_quote_count += 1
+        elif each_character == DOUBLE_QUOTE_CHARACTER:
+            double_quote_count += 1
+    return single_quote_count % 2 == 0 and double_quote_count % 2 == 0
+
+
+def _first_literal_opener(command_line: str) -> Match[str] | None:
+    """Return the line's first heredoc opener whose body bash leaves literal.
+
+    An opener spelled inside a quoted string is text bash passes on, so it
+    opens nothing and the lines below it stay in the scan.
+
+    Args:
+        command_line: One line of the command.
+
+    Returns:
+        The matching opener, or None when the line opens no literal heredoc.
+    """
+    for each_opener in HEREDOC_OPENER_PATTERN.finditer(command_line):
+        if not _sits_outside_quotes(command_line, each_opener.start()):
+            continue
+        if _opener_suppresses_expansion(each_opener):
+            return each_opener
+    return None
+
+
+def _index_past_literal_body(
+    all_lines: list[str], body_start_index: int, opener_match: Match[str]
+) -> int:
+    """Return the index of the line that closes a literal heredoc body.
+
+    The terminator match, including the ``<<-`` tab-strip rule, comes from
+    ``closes_the_heredoc`` so this hook and the shared pipeline agree on what
+    ends a body.
+
+    Args:
+        all_lines: Every line of the command.
+        body_start_index: Index of the body's first line.
+        opener_match: The opener whose terminator closes this body.
+
+    Returns:
+        The index of the terminator line, or NO_TERMINATOR_INDEX when the
+        command holds none.
+    """
+    pending_heredoc = PendingHeredoc(
+        terminator=opener_match.group(HEREDOC_TERMINATOR_GROUP),
+        allows_leading_tabs=(
+            opener_match.group(HEREDOC_TAB_STRIP_GROUP) == HEREDOC_TAB_STRIP_MARKER
+        ),
+    )
+    for each_index in range(body_start_index, len(all_lines)):
+        if closes_the_heredoc(all_lines[each_index], pending_heredoc):
+            return each_index
+    return NO_TERMINATOR_INDEX
+
+
+def _strip_quoted_heredoc_bodies(command: str) -> str:
+    """Return the command holding its openers, terminators, and shell text.
+
+    ::
+
+        cat <<'EOF'        ->  cat <<'EOF'
+        inert text             EOF
+        EOF
+
+    A quoted or escaped delimiter makes the lines below it text the shell hands
+    on, so a scan of those lines reports a substitution bash never runs. A bare
+    delimiter keeps its body, and text outside any heredoc keeps its scan.
+
+    An opener with no terminator returns the command whole. Bash consumes the
+    rest of the input in that case, and dropping those lines would hide a live
+    substitution among them.
+
+    Args:
+        command: The raw Bash command string from the tool input.
+
+    Returns:
+        The command with each literal heredoc body dropped.
+    """
+    all_lines = command.split(COMMAND_LINE_SEPARATOR)
+    all_kept_lines: list[str] = []
+    each_index = 0
+    while each_index < len(all_lines):
+        current_line = all_lines[each_index]
+        all_kept_lines.append(current_line)
+        each_index += 1
+        opener_match = _first_literal_opener(current_line)
+        if opener_match is None:
+            continue
+        terminator_index = _index_past_literal_body(all_lines, each_index, opener_match)
+        if terminator_index == NO_TERMINATOR_INDEX:
+            return command
+        each_index = terminator_index
+    return COMMAND_LINE_SEPARATOR.join(all_kept_lines)
+
+
 def _closes_as_arithmetic_expansion(command: str, scan_start_index: int) -> bool:
     """Return True when a ``$((`` expansion closes on an ``))`` pair.
 
@@ -132,8 +298,9 @@ def has_shell_substitution(command: str) -> bool:
         echo '$(not-executed)'         ok:   single-quoted, inert
         echo $((2 + 2))                ok:   arithmetic expansion
 
-    Single-quoted runs are stripped first because bash substitutes nothing
-    inside them. A backtick preceded by an odd backslash count is escaped.
+    Literal heredoc bodies are dropped first, then single-quoted runs are
+    stripped, because bash substitutes nothing inside either. A backtick
+    preceded by an odd backslash count is escaped.
     A `$((` pair is walked to its terminator (module docstring) to tell
     real arithmetic from a disguised subshell.
 
@@ -143,7 +310,7 @@ def has_shell_substitution(command: str) -> bool:
     Returns:
         True when a substitution the matcher cannot descend into is present.
     """
-    scannable_command = _strip_single_quoted_runs(command)
+    scannable_command = _strip_single_quoted_runs(_strip_quoted_heredoc_bodies(command))
     if _has_unsafe_dollar_paren_expansion(scannable_command):
         return True
     if EVEN_BACKSLASH_BACKTICK_PATTERN.search(scannable_command):