claude-dev-env 2.30.1 → 2.31.1

package/hooks/blocking/code_rules_enforcer.py

@@ -16,7 +16,6 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 ``code_rules_*`` module family, so the suffix files satisfy its gate.
 """
 import json
-import os
 import sys
 from collections import Counter
 from collections.abc import Callable
@@ -186,11 +185,42 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     PRECHECK_USAGE_MESSAGE,
     UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
     VIOLATION_SEPARATOR,
+    apply_edits,
+    edits_for_tool,
 )
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.setup_project_paths_constants import (  # noqa: E402
     UTF8_BYTE_ORDER_MARK,
 )
+from hooks_constants.subprocess_budget_completeness_content import (  # noqa: E402
+    existing_file_content,
+)
+
+
+def _multiedit_post_edit_view(
+    file_path: str, all_tool_input: dict[str, object]
+) -> tuple[str, str] | None:
+    """Return the prior and reconstructed post-edit content for a MultiEdit payload.
+
+    Reads ``file_path`` once and applies every edit in the payload's ``edits``
+    list in order, so a violation introduced by any edit — not only the
+    first — is judged against the file's real prior and post-edit state.
+
+    Args:
+        file_path: The destination path the MultiEdit targets.
+        all_tool_input: The MultiEdit payload's input mapping.
+
+    Returns:
+        A ``(prior_content, post_edit_content)`` pair, or None when the target
+        file cannot be read.
+    """
+    existing_content = existing_file_content(file_path)
+    if existing_content is None:
+        return None
+    post_edit_content = apply_edits(
+        existing_content, edits_for_tool("MultiEdit", all_tool_input)
+    )
+    return existing_content, post_edit_content
 
 
 class _ValidationContext(NamedTuple):
@@ -217,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,
@@ -229,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,
@@ -263,9 +293,8 @@ def _report_codex_patch_payload(
             deny_stream,
         )
         return
-    working_directory = all_pretooluse_payload.get("cwd")
-    if not isinstance(working_directory, str):
-        working_directory = os.getcwd()
+    raw_working_directory = all_pretooluse_payload.get("cwd")
+    working_directory = raw_working_directory if isinstance(raw_working_directory, str) else None
     try:
         all_patch_files = parse_codex_apply_patch(patch_command, working_directory)
     except CodexPatchError as error:
@@ -277,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(
@@ -325,7 +354,7 @@ def _python_magic_value_and_constant_issues(context: _ValidationContext) -> list
     )
     all_issues.extend(check_fstring_structural_literals(content, file_path))
     all_issues.extend(check_constants_outside_config(content, file_path))
-    all_issues.extend(check_constants_outside_config_advisory(content, file_path))
+    check_constants_outside_config_advisory(content, file_path)
     all_issues.extend(check_file_global_constants_use_count(content, file_path))
     return all_issues
 
@@ -678,24 +707,17 @@ def validate_content_for_full_gate(
     )
 
 
-def _read_existing_file_content(file_path: str) -> str | None:
-    """Return the on-disk content of *file_path*, or None when it cannot be read."""
-    try:
-        with open(file_path, "r", encoding="utf-8") as existing_file:
-            return existing_file.read()
-    except (FileNotFoundError, OSError, UnicodeDecodeError):
-        return None
-
-
 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
@@ -709,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
@@ -716,19 +739,27 @@ def prior_and_post_edit_content(
     """
     if not old_string:
         return None, None
-    existing_content = _read_existing_file_content(file_path)
+    existing_content = existing_file_content(file_path)
     if existing_content is None:
         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
@@ -736,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
@@ -753,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
@@ -1048,13 +1082,13 @@ def _run_precheck(
     runs_hook_duplicate_body = _is_hook_infrastructure_python_target(target_path)
     if not runs_full_verdict and not runs_hook_duplicate_body:
         return 0
-    candidate_content = _read_existing_file_content(candidate_path)
+    candidate_content = existing_file_content(candidate_path)
     if candidate_content is None:
         error_stream.write(f"error: cannot read candidate file: {candidate_path}\n")
         return 1
     candidate_content = candidate_content.lstrip(UTF8_BYTE_ORDER_MARK)
     if runs_full_verdict:
-        old_content = _read_existing_file_content(target_path) or ""
+        old_content = existing_file_content(target_path) or ""
         all_issues = validate_content_for_full_gate(candidate_content, target_path, old_content)
     else:
         all_issues = _hook_infrastructure_blocking_issues(
@@ -1127,18 +1161,16 @@ def _run_precheck_command(
 
 def _contents_for_validation(
     tool_name: str,
-    new_string: str,
-    old_string: str,
-    written_content: str,
+    all_tool_input: dict[str, object],
     file_path: str,
 ) -> tuple[str, str, str | None, str] | None:
     """Resolve the content views the verdict needs for the given tool payload.
 
     Args:
         tool_name: The tool named in the PreToolUse payload.
-        new_string: The Edit payload's replacement fragment.
-        old_string: The Edit payload's fragment to replace.
-        written_content: The Write payload's whole file body.
+        all_tool_input: The PreToolUse payload's tool_input mapping, carrying
+            ``new_string``/``old_string`` for Edit, ``content`` for Write, and
+            the ``edits`` list for MultiEdit.
         file_path: The destination path of the write or edit.
 
     Returns:
@@ -1146,17 +1178,27 @@ def _contents_for_validation(
         prior_full_file_content)`` tuple, or None when no validatable view
         exists — an unreadable edit target, or a write over an existing file.
     """
+    new_string = str(all_tool_input.get("new_string", "") or "")
+    old_string = str(all_tool_input.get("old_string", "") or "")
+    written_content = str(all_tool_input.get("content", "") or "")
     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 = _read_existing_file_content(file_path)
+            full_file_content_after_edit = existing_file_content(file_path)
             if full_file_content_after_edit is None:
                 return None
         return new_string, old_string, full_file_content_after_edit, prior_content or ""
+    if tool_name == "MultiEdit":
+        multiedit_view = _multiedit_post_edit_view(file_path, all_tool_input or {})
+        if multiedit_view is None:
+            return None
+        prior_content, post_edit_content = multiedit_view
+        return post_edit_content, prior_content, post_edit_content, prior_content
     content = written_content or new_string
-    old_content = _read_existing_file_content(file_path) or ""
+    old_content = existing_file_content(file_path) or ""
     if old_content:
         return None
     return content, old_content, None, ""
@@ -1176,7 +1218,7 @@ def _deny_reason_for_issues(
         tool_name: The tool named in the PreToolUse payload.
         file_path: The destination path used for forecast classification.
         full_file_content_after_edit: The whole post-edit file content when the
-            edit reconstructs one, used to run the full-file forecast.
+            edit reconstructs one, for the full-file forecast.
         prior_full_file_content: The whole file content before the edit applied.
             Empty when the edit's old_string is absent and no reliable prior
             exists; the forecast is skipped in that case so a comment diff
@@ -1192,7 +1234,7 @@ def _deny_reason_for_issues(
     )
     has_reconstructed_prior = bool(prior_full_file_content)
     if (
-        tool_name == "Edit"
+        tool_name in ("Edit", "MultiEdit")
         and full_file_content_after_edit is not None
         and has_reconstructed_prior
     ):
@@ -1250,7 +1292,8 @@ def _report_blocking_violations(
         content: The fragment or whole-file body under validation.
         tool_name: The tool named in the PreToolUse payload.
         file_path: The destination path of the write or edit.
-        old_content: The fragment the edit replaces, or empty for a write.
+        old_content: The fragment named by the edit's old_string, or empty for
+            a write.
         full_file_content_after_edit: The reconstructed post-edit file body,
             or None when the payload is not an Edit.
         prior_full_file_content: The on-disk content before the edit.
@@ -1344,15 +1387,16 @@ 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(
         tool_name,
-        tool_input.get("new_string", ""),
-        tool_input.get("old_string", ""),
-        tool_input.get("content", ""),
+        tool_input,
         file_path,
     )
     if validation_contents is None:

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/codex_apply_patch.py

@@ -2,9 +2,21 @@
 
 import os
 import re
+import sys
 from dataclasses import dataclass
+from functools import cache
 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.codex_apply_patch_constants import (  # noqa: E402
+    CODEX_ADD_OPERATION,
+    CODEX_DELETE_OPERATION,
+    CODEX_UPDATE_OPERATION,
+)
+
 _codex_patch_begin_marker = "*** Begin Patch"
 _codex_patch_end_marker = "*** End Patch"
 _codex_update_marker = "*** Update File:"
@@ -14,9 +26,6 @@ _codex_hunk_marker = "@@"
 _codex_end_of_file_marker = "*** End of File"
 _codex_no_newline_marker = "\"
 _codex_minimum_patch_line_count = 2
-_codex_update_operation = "update"
-_codex_add_operation = "add"
-_codex_delete_operation = "delete"
 
 
 class CodexPatchError(ValueError):
@@ -70,6 +79,11 @@ def _codex_patch_sections(command: str) -> list[tuple[str, str, list[str]]]:
         raise CodexPatchError("patch requires a begin marker")
     if _codex_marker_text(all_lines[-1]) != _codex_patch_end_marker:
         raise CodexPatchError("patch requires an end marker")
+    all_marker_by_operation = {
+        CODEX_UPDATE_OPERATION: _codex_update_marker,
+        CODEX_ADD_OPERATION: _codex_add_marker,
+        CODEX_DELETE_OPERATION: _codex_delete_marker,
+    }
     all_sections: list[tuple[str, str, list[str]]] = []
     current_section: tuple[str, str, list[str]] | None = None
     for each_line in all_lines[1:-1]:
@@ -77,11 +91,7 @@ def _codex_patch_sections(command: str) -> list[tuple[str, str, list[str]]]:
         operation = next(
             (
                 each_operation
-                for each_operation, each_marker in (
-                    (_codex_update_operation, _codex_update_marker),
-                    (_codex_add_operation, _codex_add_marker),
-                    (_codex_delete_operation, _codex_delete_marker),
-                )
+                for each_operation, each_marker in all_marker_by_operation.items()
                 if marker_text.startswith(each_marker)
             ),
             None,
@@ -89,12 +99,7 @@ def _codex_patch_sections(command: str) -> list[tuple[str, str, list[str]]]:
         if operation is not None:
             if current_section is not None:
                 all_sections.append(current_section)
-            marker_by_operation = {
-                _codex_update_operation: _codex_update_marker,
-                _codex_add_operation: _codex_add_marker,
-                _codex_delete_operation: _codex_delete_marker,
-            }
-            path_text = marker_text[len(marker_by_operation[operation]) :].strip()
+            path_text = marker_text[len(all_marker_by_operation[operation]) :].strip()
             if not path_text:
                 raise CodexPatchError("patch operation requires a path")
             current_section = (operation, path_text, [])
@@ -190,15 +195,15 @@ def _codex_read_patch_file(
     try:
         prior_content = target_path.read_text(encoding="utf-8")
     except (FileNotFoundError, IsADirectoryError, OSError, UnicodeDecodeError, ValueError) as error:
-        if operation == _codex_add_operation and isinstance(error, FileNotFoundError):
+        if operation == CODEX_ADD_OPERATION and isinstance(error, FileNotFoundError):
             prior_content = ""
         else:
             raise CodexPatchError("patch target requires readable UTF-8 content") from error
-    if operation == _codex_add_operation:
+    if operation == CODEX_ADD_OPERATION:
         if target_path.exists():
             raise CodexPatchError("add target requires a new path")
         post_content = _codex_add_content(all_section_lines)
-    elif operation == _codex_update_operation:
+    elif operation == CODEX_UPDATE_OPERATION:
         post_content = _codex_apply_update(prior_content, all_section_lines)
     else:
         if any(
@@ -210,15 +215,125 @@ def _codex_read_patch_file(
     return CodexPatchFile(str(target_path), prior_content, post_content, operation)
 
 
-def parse_codex_apply_patch(
-    command: str, working_directory: str | None = None
-) -> tuple[CodexPatchFile, ...]:
-    """Return pre-edit and post-edit views for every Codex patch path."""
+def payload_patch_command(hook_payload: dict, tool_input: dict) -> tuple[str, str | None]:
+    """Pull the patch text and its working directory out of an apply_patch payload.
+
+    ::
+
+        hook_payload = {"cwd": "/repo"}
+        tool_input   = {"command": "*** Begin Patch ..."}
+        payload_patch_command(...)  ->  ("*** Begin Patch ...", "/repo")
+
+    A payload whose command or cwd is missing, or carries a non-string value,
+    yields an empty command and a None directory. An empty command tells the
+    caller there is no patch to parse.
+
+    Args:
+        hook_payload: The whole PreToolUse payload, carrying the cwd.
+        tool_input: The tool input mapping, carrying the command text.
+
+    Returns:
+        The command text and the working directory to resolve paths against.
+    """
+    raw_command = (tool_input or {}).get("command", "")
+    command = raw_command if isinstance(raw_command, str) else ""
+    raw_working_directory = (hook_payload or {}).get("cwd")
+    working_directory = raw_working_directory if isinstance(raw_working_directory, str) else None
+    return command, working_directory
+
+
+def _codex_working_directory(command: str, working_directory: str | None) -> Path:
+    """Validate the patch command text and working directory, then resolve it.
+
+    Args:
+        command: The raw Codex apply_patch command text.
+        working_directory: The directory patch paths resolve against, or None
+            to use the current working directory.
+
+    Returns:
+        The resolved, existing working directory.
+    """
     if not isinstance(command, str) or not command.strip():
         raise CodexPatchError("patch command requires text")
     resolved_working_directory = Path(working_directory or os.getcwd()).expanduser().resolve()
     if not resolved_working_directory.is_dir():
         raise CodexPatchError("patch working directory requires an existing directory")
+    return resolved_working_directory
+
+
+@cache
+def codex_patch_operation_targets(
+    command: str, working_directory: str | None = None
+) -> tuple[tuple[str, str], ...]:
+    """Return each (operation, resolved path) pair a Codex patch command names.
+
+    Resolves every section's target path the same way ``parse_codex_apply_patch``
+    does, without reading any file's prior content, so a caller that only needs
+    each target path (a sensitive-path check, an already-exists check) is not
+    tripped up by a prior file it never needs to read.
+
+    Args:
+        command: The raw Codex apply_patch command text.
+        working_directory: The directory patch paths resolve against, or None
+            to use the current working directory.
+
+    Returns:
+        The ordered ``(operation, resolved_path)`` pairs the patch names.
+    """
+    resolved_working_directory = _codex_working_directory(command, working_directory)
+    return tuple(
+        (each_operation, _codex_resolve_patch_path(each_relative_path, resolved_working_directory))
+        for each_operation, each_relative_path, _each_section_lines in _codex_patch_sections(command)
+    )
+
+
+def _target_paths_for_command(command: str, working_directory: str | None) -> tuple[str, ...]:
+    """Return each resolved target path one patch command names.
+
+    An empty command, and a command this parser rejects, both yield an empty
+    tuple, so the caller reads one result shape either way.
+
+    Args:
+        command: The raw Codex apply_patch command text, or an empty string.
+        working_directory: The directory patch paths resolve against, or None.
+
+    Returns:
+        The ordered resolved target paths the patch names.
+    """
+    if not command:
+        return ()
+    try:
+        all_operation_targets = codex_patch_operation_targets(command, working_directory)
+    except CodexPatchError:
+        return ()
+    return tuple(each_path for _each_operation, each_path in all_operation_targets)
+
+
+def payload_patch_target_paths(hook_payload: dict, tool_input: dict) -> tuple[str, ...]:
+    """Return every resolved target path an apply_patch payload names.
+
+    The wrapper a hook wants when it needs target paths and nothing else. It
+    reads the command out of the payload, then resolves paths without reading
+    any target file's prior content.
+
+    Args:
+        hook_payload: The whole hook payload, carrying the cwd.
+        tool_input: The tool input mapping, carrying the command text.
+
+    Returns:
+        The ordered resolved target paths the patch names, empty when the
+        payload names no patch or the patch will not parse.
+    """
+    command, working_directory = payload_patch_command(hook_payload, tool_input)
+    return _target_paths_for_command(command, working_directory)
+
+
+@cache
+def parse_codex_apply_patch(
+    command: str, working_directory: str | None = None
+) -> tuple[CodexPatchFile, ...]:
+    """Return pre-edit and post-edit views for every Codex patch path."""
+    resolved_working_directory = _codex_working_directory(command, working_directory)
     all_patch_files: list[CodexPatchFile] = []
     seen_paths: set[str] = set()
     for each_operation, each_relative_path, each_section_lines in _codex_patch_sections(command):