claude-dev-env 2.30.0 → 2.31.0

package/hooks/blocking/hook_prose_detector_consistency.py

@@ -35,25 +35,33 @@ import re
 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 blocking.config.prose_style_enforcement_constants import (  # noqa: E402
-    prose_style_enforcement_enabled_in_environment,
-)
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-from hooks_constants.hook_prose_detector_consistency_constants import (  # noqa: E402
-    CONSTANTS_MODULE_SUFFIX,
-    CORRECTIVE_MESSAGE,
-    EDIT_TOOL_NAME,
-    HOOK_MODULE_PATH_SEGMENT,
-    OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN,
-    PATH_SEPARATOR_CLASS_PATTERN,
-    PYTHON_FILE_SUFFIX,
-    TEST_MODULE_PREFIX,
-    WRITE_TOOL_NAME,
-)
+try:
+    _hooks_dir = str(Path(__file__).resolve().parent.parent)
+    if _hooks_dir not in sys.path:
+        sys.path.insert(0, _hooks_dir)
+
+    from blocking.config.prose_style_enforcement_constants import (
+        prose_style_enforcement_enabled_in_environment,
+    )
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.hook_prose_detector_consistency_constants import (
+        CONSTANTS_MODULE_SUFFIX,
+        CORRECTIVE_MESSAGE,
+        EDIT_TOOL_NAME,
+        HOOK_MODULE_PATH_SEGMENT,
+        MULTI_EDIT_TOOL_NAME,
+        OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN,
+        PATH_SEPARATOR_CLASS_PATTERN,
+        PYTHON_FILE_SUFFIX,
+        TEST_MODULE_PREFIX,
+        WRITE_TOOL_NAME,
+    )
+    from hooks_constants.multi_edit_reconstruction import joined_new_strings
+except ImportError as import_error:
+    raise ImportError(
+        "hook_prose_detector_consistency: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
 
 
 def written_content(tool_name: str, all_tool_input: dict[str, object]) -> str:
@@ -63,6 +71,8 @@ def written_content(tool_name: str, all_tool_input: dict[str, object]) -> str:
     if tool_name == EDIT_TOOL_NAME:
         new_string = all_tool_input.get("new_string", "")
         return new_string if isinstance(new_string, str) else ""
+    if tool_name == MULTI_EDIT_TOOL_NAME:
+        return joined_new_strings(all_tool_input)
     return ""
 
 
@@ -125,7 +135,7 @@ def main() -> None:
         sys.exit(0)
 
     tool_name = hook_input.get("tool_name", "")
-    if tool_name not in (WRITE_TOOL_NAME, EDIT_TOOL_NAME):
+    if tool_name not in (WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME):
         sys.exit(0)
 
     all_tool_input = hook_input.get("tool_input", {})

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

@@ -24,13 +24,28 @@ 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.
 
 Bash arithmetic expansion ``$((...))`` is explicitly NOT blocked: it does not
-spawn a subshell and does not defeat the allowlist matcher, so the
-``$(`` pattern uses a negative lookahead to skip the ``$((`` case.
+spawn a subshell and does not defeat the allowlist matcher. Telling it apart
+from a disguised command substitution takes more than counting two open
+parens, because bash itself falls back from arithmetic to command
+substitution when the expansion body does not close as arithmetic. Observed
+against real bash:
+
+    echo $((1 + 2))            prints 3            (arithmetic; not blocked)
+    echo $((cd /tmp) && pwd)   prints the new cwd   (command substitution; blocked)
+    echo $((1+2) )             runs "1+2" as a command, rc=0, no output
+                                                     (command substitution; blocked)
+
+Bash's own rule is the terminator: walk forward from ``$((`` tracking paren
+depth; when depth returns to zero on a closer immediately preceded by
+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, write via the Write tool instead of a Bash heredoc.
+case, author the file with the Write tool, not a Bash heredoc.
 """
 
 from __future__ import annotations
@@ -45,6 +60,7 @@ if _hooks_dir not in sys.path:
 
 from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
     BASH_TOOL_NAME,
+    CLOSE_PAREN_CHARACTER,
     COMMAND_KEY,
     CORRECTIVE_MESSAGE,
     DENY_DECISION,
@@ -53,6 +69,8 @@ from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
     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,
@@ -67,6 +85,42 @@ def _strip_single_quoted_runs(command: str) -> str:
     return SINGLE_QUOTED_RUN_PATTERN.sub(STRIPPED_RUN_REPLACEMENT, command)
 
 
+def _closes_as_arithmetic_expansion(command: str, scan_start_index: int) -> bool:
+    """Return True when a ``$((`` expansion closes on an ``))`` pair.
+
+    See the module docstring for the real-bash evidence behind this rule.
+    """
+    paren_depth = PAREN_DEPTH_AFTER_DOUBLE_OPEN
+    was_previous_character_close_paren = False
+    for each_index in range(scan_start_index, len(command)):
+        current_character = command[each_index]
+        if current_character == OPEN_PAREN_CHARACTER:
+            paren_depth += 1
+            was_previous_character_close_paren = False
+            continue
+        if current_character != CLOSE_PAREN_CHARACTER:
+            was_previous_character_close_paren = False
+            continue
+        paren_depth -= 1
+        if paren_depth == 0:
+            return was_previous_character_close_paren
+        was_previous_character_close_paren = True
+    return False
+
+
+def _has_unsafe_dollar_paren_expansion(command: str) -> bool:
+    """Return True for a `$(` that is not a safe `$((...))` arithmetic pair."""
+    for each_match in DOLLAR_PAREN_PATTERN.finditer(command):
+        is_arithmetic_style_open = (
+            command[each_match.end() : each_match.end() + 1] == OPEN_PAREN_CHARACTER
+        )
+        if not is_arithmetic_style_open:
+            return True
+        if not _closes_as_arithmetic_expansion(command, each_match.end() + 1):
+            return True
+    return False
+
+
 def has_shell_substitution(command: str) -> bool:
     """Return True when a Bash command carries a live shell substitution.
 
@@ -79,18 +133,18 @@ def has_shell_substitution(command: str) -> bool:
         echo $((2 + 2))                ok:   arithmetic expansion
 
     Single-quoted runs are stripped first because bash substitutes nothing
-    inside them. A backtick preceded by an odd number of backslashes is escaped
-    and stays allowed.
+    inside them. 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.
 
     Args:
         command: The raw Bash command string from the tool input.
 
     Returns:
-        True when a substitution the allowlist matcher cannot descend into is
-        present outside single quotes.
+        True when a substitution the matcher cannot descend into is present.
     """
     scannable_command = _strip_single_quoted_runs(command)
-    if DOLLAR_PAREN_PATTERN.search(scannable_command):
+    if _has_unsafe_dollar_paren_expansion(scannable_command):
         return True
     if EVEN_BACKSLASH_BACKTICK_PATTERN.search(scannable_command):
         return True