claude-dev-env 2.3.0 → 2.4.0

package/hooks/git-hooks/test_pre_push.py

@@ -28,6 +28,12 @@ NON_ZERO_REMOTE_SHA_ONE: str = "1" * 40
 NON_ZERO_REMOTE_SHA_TWO: str = "2" * 40
 
 
+def _isolate_code_review_gate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(
+        "CODE_REVIEW_PUSH_GATE_PATH", str(tmp_path / "no_code_review_gate.py")
+    )
+
+
 def test_resolve_base_reference_uses_remote_object_when_non_zero() -> None:
     stdin_text = (
         f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
@@ -73,6 +79,7 @@ def test_main_exits_zero_when_gate_script_missing(
         "CODE_RULES_GATE_PATH",
         str(tmp_path / "does_not_exist.py"),
     )
+    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(sys, "stdin", io.StringIO(""))
 
     exit_code = pre_push.main()
@@ -94,6 +101,7 @@ def test_main_invokes_gate_with_resolved_base_reference(
         encoding="utf-8",
     )
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+    _isolate_code_review_gate(tmp_path, monkeypatch)
     remote_sha = "9" * 40
     monkeypatch.setattr(
         sys,
@@ -312,6 +320,7 @@ def test_invoke_gate_uses_resolved_path(
     symlink_gate_path.symlink_to(real_gate_path)
     resolved_path = symlink_gate_path.resolve()
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(symlink_gate_path))
+    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(sys, "stdin", io.StringIO(
         f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
     ))
@@ -428,6 +437,7 @@ def test_main_allows_main_onto_main_push(
     passing_gate_path = tmp_path / "gate.py"
     passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
     monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    _isolate_code_review_gate(tmp_path, monkeypatch)
     monkeypatch.setattr(
         sys,
         "stdin",
@@ -439,3 +449,96 @@ def test_main_allows_main_onto_main_push(
     exit_code = pre_push.main()
 
     assert exit_code == 0
+
+
+CODE_REVIEW_STUB_BLOCK_REASON: str = "CODE_REVIEW_STUB_BLOCK_REASON"
+
+
+def _write_passing_code_rules_gate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    passing_gate_path = tmp_path / "code_rules_gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feature {NON_ZERO_LOCAL_SHA} refs/heads/feature {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+
+def _write_code_review_gate_stub(tmp_path: Path, returned_reason_literal: str) -> Path:
+    stub_gate_path = tmp_path / "code_review_push_gate.py"
+    stub_gate_path.write_text(
+        "def deny_reason_for_directory(target_directory):\n"
+        f"    return {returned_reason_literal}\n",
+        encoding="utf-8",
+    )
+    return stub_gate_path
+
+
+def test_main_blocks_when_code_review_gate_returns_reason(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    _write_passing_code_rules_gate(tmp_path, monkeypatch)
+    stub_gate_path = _write_code_review_gate_stub(
+        tmp_path, repr(CODE_REVIEW_STUB_BLOCK_REASON)
+    )
+    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.CODE_REVIEW_STAMP_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert CODE_REVIEW_STUB_BLOCK_REASON in captured.err
+
+
+def test_main_allows_when_code_review_gate_returns_none(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _write_passing_code_rules_gate(tmp_path, monkeypatch)
+    stub_gate_path = _write_code_review_gate_stub(tmp_path, "None")
+    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+
+
+def test_main_code_review_check_fails_open_when_gate_module_absent(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _write_passing_code_rules_gate(tmp_path, monkeypatch)
+    monkeypatch.setenv(
+        "CODE_REVIEW_PUSH_GATE_PATH", str(tmp_path / "does_not_exist.py")
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+
+
+def test_main_allows_deletion_push_even_when_code_review_gate_would_block(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    passing_gate_path = tmp_path / "code_rules_gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    stub_gate_path = _write_code_review_gate_stub(
+        tmp_path, repr(CODE_REVIEW_STUB_BLOCK_REASON)
+    )
+    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(stub_gate_path))
+    deletion_stdin = (
+        f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME} "
+        f"refs/heads/feature {ALL_ZEROS_OBJECT_NAME}\n"
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(deletion_stdin))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0

package/hooks/hooks.json

@@ -57,6 +57,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__plugin_github_github__create_pull_request",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_review_pr_create_gate.py",
+            "timeout": 20
+          }
+        ]
+      },
       {
         "matcher": "mcp__plugin_github_github__.*",
         "hooks": [
@@ -79,7 +89,12 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_converge_bugteam_enforcer.py",
             "timeout": 10
-          },
+          }
+        ]
+      },
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_verifier_spawn_preflight_gate.py",

package/hooks/hooks_constants/CLAUDE.md

@@ -60,6 +60,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
 | `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
 | `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
+| `pyproject_config_discovery_constants.py` | Table names (``tool`` key, ``mypy``, ``ruff``) for resolving a validator's config from a pyproject.toml `[tool.<name>]` table |
 | `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
 | `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
 | `reviewer_spawn_gate_constants.py` | Bash tool name, the sentinel marker, the Copilot and Bugbot trigger markers, the availability-script relative path and override env-var name, and the deny-message template for the reviewer-spawn gate |

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -75,4 +75,12 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry(
         "blocking/verdict_directory_write_blocker.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES
     ),
+    BashHostedHookEntry("blocking/code_review_push_gate.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES),
+    BashHostedHookEntry(
+        "blocking/code_review_pr_create_gate.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES
+    ),
+    BashHostedHookEntry(
+        "blocking/code_review_stamp_directory_write_blocker.py",
+        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -22,6 +22,7 @@ ALL_CONFIG_DIRECTORY_NAMES = frozenset(
         "pr_converge_scripts_constants",
         "bugteam_scripts_constants",
         "usage_pause_constants",
+        "prototype_scripts_constants",
         "codex_review_scripts_constants",
         "dev_env_scripts_constants",
         "fresh_branch_scripts_constants",

package/hooks/hooks_constants/code_verifier_spawn_preflight_gate_constants.py

@@ -1,21 +1,29 @@
 """Configuration constants for the code_verifier_spawn_preflight_gate hook.
 
-The gate denies an ``Agent`` spawn whose ``subagent_type`` is ``code-verifier``
-when the branch carries a merge conflict against its base ref or a CODE_RULES
-violation on a line added in the working tree since the merge base (committed on
-the branch or uncommitted). It runs two
-pre-flight checks before the expensive verification spawn and addresses its
-deny reason to the spawning agent so that agent fixes the named issues and
-re-spawns. Every literal the hook body reads lives here; the hook imports
-``AGENT_TOOL_NAME`` from ``pr_converge_bugteam_enforcer_constants`` rather than
-redefining it.
+The gate denies an ``Agent`` or ``Task`` spawn whose ``subagent_type`` is
+``code-verifier`` when the branch carries a merge conflict against its base
+ref, a CODE_RULES violation on a line added in the working tree since the merge
+base (committed on the branch or uncommitted), or a CODE_RULES engine
+import/load failure. It runs those pre-flight checks before the expensive
+verification spawn and addresses its deny reason to the spawning agent so that
+agent fixes the named issues and re-spawns. Environmental git failures stay
+fail-open; engine import/load failure is fail-closed. Every literal the hook
+body reads lives here; ``AGENT_TOOL_NAME`` comes from
+``pr_converge_bugteam_enforcer_constants`` and joins ``TASK_TOOL_NAME`` in
+``ALL_CODE_VERIFIER_SPAWN_TOOL_NAMES`` so both spawn tool names share one source.
 """
 
 from __future__ import annotations
 
 from pathlib import Path
 
+from hooks_constants.pr_converge_bugteam_enforcer_constants import AGENT_TOOL_NAME
+
 CODE_VERIFIER_SUBAGENT_TYPE: str = "code-verifier"
+TASK_TOOL_NAME: str = "Task"
+ALL_CODE_VERIFIER_SPAWN_TOOL_NAMES: frozenset[str] = frozenset(
+    {AGENT_TOOL_NAME, TASK_TOOL_NAME}
+)
 
 ALL_MERGE_TREE_COMMAND_FLAGS: tuple[str, ...] = (
     "merge-tree",
@@ -39,11 +47,18 @@ ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS: tuple[str, ...] = (
 ALL_UNIFIED_ZERO_DIFF_FLAGS: tuple[str, ...] = ("diff", "--unified=0")
 
 DENY_REASON_LEAD: str = (
-    "BLOCKED [code-verifier-spawn-preflight]: an Agent spawn with subagent_type "
-    "code-verifier is blocked because the branch is not in a committable state. "
+    "BLOCKED [code-verifier-spawn-preflight]: a code-verifier spawn "
+    "(Agent or Task tool, subagent_type code-verifier) is blocked because "
+    "the branch is not in a committable state. "
     "Fix these, then re-spawn the code-verifier:"
 )
 MERGE_CONFLICT_SECTION_HEADER: str = "Merge conflicts vs {base_ref}:"
 CODE_RULES_SECTION_HEADER: str = "CODE_RULES violations on changed lines:"
+ENGINE_LOAD_FAILURE_SECTION: str = (
+    "CODE_RULES engine failed to load:\n"
+    "  The CODE_RULES validate_content engine could not be imported or loaded "
+    "(package import/load failure). Repair the enforcer so load_validate_content "
+    "succeeds, then re-spawn code-verifier."
+)
 
 GATE_SCRIPTS_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts"

package/hooks/hooks_constants/convergence_gate_blocker_constants.py

@@ -25,12 +25,29 @@ chained command does not bind the gate to the wrong PR::
 
 GH_PR_READY_ANCHOR_PATTERN: str = r"\bgh\s+pr\s+ready\b(?![^&|;\n]*--undo)"
 
-COMMAND_SEPARATOR_PATTERN: str = r"&&|\|\||;|\||\n"
+COMMAND_SEPARATOR_PATTERN: str = r"&&|\|\||;|\||\n|(?<![>&])&(?![>&])"
+
+BASH_LINE_CONTINUATION_PATTERN: str = r"\\\r?\n[ \t]*"
 
 PR_URL_OWNER_REPO_NUMBER_PATTERN: str = (
-    r"https://github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
+    r"https?://[^/]+/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
 )
 
 REPO_OVERRIDE_FLAG_PATTERN: str = (
-    r"(?:^|\s)(?:--repo|-R)(?:=|\s+)(?:[\w.-]+/)*(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)"
+    r"(?:^|\s)(?:--repo(?:=|\s+)|-R(?:=|\s+)?)"
+    r"(?:https?://[^/\s]+/|git@[^:\s]+:|(?:[\w.-]+/)*)"
+    r"(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)"
+)
+
+ALL_GH_PR_VIEW_NUMBER_COMMAND: tuple[str, ...] = (
+    "gh",
+    "pr",
+    "view",
+    "--json",
+    "number",
+    "--jq",
+    ".number",
 )
+GH_REPO_FLAG: str = "--repo"
+REPO_SLUG_TEMPLATE: str = "{owner}/{repo}"
+GIT_URL_SUFFIX: str = ".git"

package/hooks/hooks_constants/destructive_command_segment_constants.py

@@ -1,4 +1,4 @@
-"""Segment-splitting and command-name constants for the destructive command blocker compound rm guard."""
+"""Segment-splitting, command-name, and deny-mode constants for the destructive command blocker."""
 
 ALL_SHELL_CONTROL_OPERATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|&", "|", "&", "\n", "\r"})
 ALL_COMMAND_LAUNCHER_WRAPPER_COMMANDS: frozenset[str] = frozenset(
@@ -191,3 +191,5 @@ ALL_KNOWN_TEMPORARY_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
         "CLAUDE_JOB_DIR",
     }
 )
+DESTRUCTIVE_DENY_MODE_ENV_VAR: str = "CLAUDE_DESTRUCTIVE_DENY_MODE"
+ALL_TRUTHY_ENV_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})

package/hooks/hooks_constants/pr_description_proof_of_work_constants.py

@@ -22,8 +22,6 @@ GH_SLURP_FLAG: str = "--slurp"
 PR_COMMENTS_API_PATH_TEMPLATE: str = "repos/{{owner}}/{{repo}}/issues/{pr_number}/comments"
 ALL_PR_DIFF_SUBCOMMANDS: tuple[str, ...] = ("pr", "diff")
 PR_DIFF_NAME_ONLY_FLAG: str = "--name-only"
-ALL_PR_VIEW_NUMBER_ARGUMENTS: tuple[str, ...] = ("pr", "view", "--json", "number")
-PR_NUMBER_JSON_FIELD: str = "number"
 COMMENT_BODY_JSON_FIELD: str = "body"
 GH_COMMAND_TIMEOUT_SECONDS: int = 6
 MAX_DIFF_SCAN_CHARS: int = 200000
@@ -83,7 +81,6 @@ __all__ = [
     "ALL_HONEST_GAP_PHRASES",
     "ALL_PROOF_HEADING_KEYWORDS",
     "ALL_PR_DIFF_SUBCOMMANDS",
-    "ALL_PR_VIEW_NUMBER_ARGUMENTS",
     "ALL_VISUAL_FILE_SUFFIXES",
     "COMMENT_BODY_JSON_FIELD",
     "DIGIT_PATTERN",
@@ -104,7 +101,6 @@ __all__ = [
     "PROOF_PART_VISUAL_MESSAGE",
     "PR_COMMENTS_API_PATH_TEMPLATE",
     "PR_DIFF_NAME_ONLY_FLAG",
-    "PR_NUMBER_JSON_FIELD",
     "PR_READY_GATE_MESSAGE_TEMPLATE",
     "PR_READY_INVOCATION_PATTERN",
     "PR_READY_UNDO_FLAG",

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -80,6 +80,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/sensitive_file_protector.py",
         applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/code_review_stamp_directory_write_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
     HostedHookEntry(
         script_relative_path="blocking/pii_prevention_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,

package/hooks/hooks_constants/pyproject_config_discovery_constants.py

@@ -0,0 +1,16 @@
+"""Table names used when a validator resolves its config from a pyproject.toml.
+
+A ``pyproject.toml`` nests each tool's settings under ``[tool.<name>]``, so the
+top-level table key is ``tool`` and each tool matches its own name below it.
+These names live here so the discovery module carries no inline table literals.
+"""
+
+__all__ = [
+    "TOOL_TABLE_KEY",
+    "MYPY_TOOL_TABLE_NAME",
+    "RUFF_TOOL_TABLE_NAME",
+]
+
+TOOL_TABLE_KEY: str = "tool"
+MYPY_TOOL_TABLE_NAME: str = "mypy"
+RUFF_TOOL_TABLE_NAME: str = "ruff"

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -40,12 +40,18 @@ _EXPECTED_BASH_ORDER = (
     "blocking/gh_pr_author_enforcer.py",
     "blocking/verified_commit_gate.py",
     "blocking/verdict_directory_write_blocker.py",
+    "blocking/code_review_push_gate.py",
+    "blocking/code_review_pr_create_gate.py",
+    "blocking/code_review_stamp_directory_write_blocker.py",
 )
 
 _POWERSHELL_APPLICABLE = (
     "blocking/pii_prevention_blocker.py",
     "blocking/verified_commit_gate.py",
     "blocking/verdict_directory_write_blocker.py",
+    "blocking/code_review_push_gate.py",
+    "blocking/code_review_pr_create_gate.py",
+    "blocking/code_review_stamp_directory_write_blocker.py",
 )
 
 
@@ -80,6 +86,24 @@ def test_powershell_hooks_carry_the_shared_tool_set() -> None:
             assert each_entry.applicable_tool_names == ALL_BASH_AND_POWERSHELL_TOOL_NAMES
 
 
+def test_code_review_gate_family_registered_for_bash_and_powershell() -> None:
+    """The three code-review shell gates run on both Bash and PowerShell."""
+    code_review_gate_paths = (
+        "blocking/code_review_push_gate.py",
+        "blocking/code_review_pr_create_gate.py",
+        "blocking/code_review_stamp_directory_write_blocker.py",
+    )
+    entry_by_path = {
+        each_entry.script_relative_path: each_entry
+        for each_entry in ALL_BASH_HOSTED_HOOK_ENTRIES
+    }
+    for each_gate_path in code_review_gate_paths:
+        assert each_gate_path in entry_by_path
+        assert entry_by_path[each_gate_path].applicable_tool_names == (
+            ALL_BASH_AND_POWERSHELL_TOOL_NAMES
+        )
+
+
 def test_every_roster_path_points_at_an_existing_hook() -> None:
     """Each roster path names a hook script present on disk, catching a typo."""
     hooks_root = Path(__file__).resolve().parent.parent

package/hooks/hooks_constants/test_pre_tool_use_dispatcher_constants.py

@@ -63,6 +63,12 @@ def test_duplicate_rmtree_helper_blocker_runs_via_runpy() -> None:
     assert entry.native_module_name is None
 
 
+def test_code_review_stamp_write_blocker_registered_for_all_file_tools() -> None:
+    entry = _entry_for("blocking/code_review_stamp_directory_write_blocker.py")
+    assert entry is not None
+    assert {"Write", "Edit", "MultiEdit"} <= entry.applicable_tool_names
+
+
 def test_windows_rmtree_blocker_still_registered() -> None:
     entry = _entry_for("blocking/windows_rmtree_blocker.py")
     assert entry is not None

package/hooks/hooks_constants/volatile_path_in_post_blocker_constants.py

@@ -19,9 +19,16 @@ ALL_GH_POST_SUBCOMMANDS: dict[str, frozenset[str]] = {
     "issue": frozenset({"create", "comment", "edit"}),
 }
 
-ALL_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
+PATH_ANCHOR_CHARACTER: str = "/"
+
+PATH_SEGMENT_START_CHARACTERS: str = "_-"
+
+ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
     ".claude-editor/jobs/",
     ".claude/worktrees/",
+)
+
+ALL_BARE_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
     "appdata/local/temp",
     "/tmp/",
     "%temp%",

package/hooks/validators/CLAUDE.md

@@ -12,6 +12,7 @@ A library of check modules used by the validation hooks. Each module focuses on
 | `output_formatter.py` | Formats `Violation` lists into human-readable output |
 | `run_all_validators.py` | Entry point — runs every check module and aggregates results |
 | `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
+| `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
 | `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
 
 ## Check modules

package/hooks/validators/mypy_integration.py

@@ -4,19 +4,33 @@ import contextlib
 import subprocess
 import sys
 import tempfile
-import tomllib
 from collections.abc import Iterator
 from dataclasses import dataclass
 from pathlib import Path
 
+_validators_directory = str(Path(__file__).resolve().parent)
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
 
+try:
+    from pyproject_config_discovery import (
+        ancestor_directories,
+        find_pyproject_configuring_tool,
+    )
+except ModuleNotFoundError:
+    if _validators_directory not in sys.path:
+        sys.path.insert(0, _validators_directory)
+    from pyproject_config_discovery import (
+        ancestor_directories,
+        find_pyproject_configuring_tool,
+    )
+
 try:
     from hooks_constants.mypy_integration_constants import (
         GIT_DIRECTORY_NAME,
         PYPROJECT_FILENAME,
         PYTHON_SOURCE_SUFFIX,
     )
+    from hooks_constants.pyproject_config_discovery_constants import MYPY_TOOL_TABLE_NAME
 except ModuleNotFoundError:
     if _hooks_directory not in sys.path:
         sys.path.insert(0, _hooks_directory)
@@ -25,6 +39,7 @@ except ModuleNotFoundError:
         PYPROJECT_FILENAME,
         PYTHON_SOURCE_SUFFIX,
     )
+    from hooks_constants.pyproject_config_discovery_constants import MYPY_TOOL_TABLE_NAME
 
 
 @dataclass
@@ -48,38 +63,6 @@ def check_mypy_available() -> bool:
         return False
 
 
-def _pyproject_contains_tool_mypy(pyproject_path: Path) -> bool:
-    try:
-        with pyproject_path.open("rb") as readable_handle:
-            parsed_toml = tomllib.load(readable_handle)
-    except (OSError, tomllib.TOMLDecodeError):
-        return False
-    tool_table = parsed_toml.get("tool", {})
-    return isinstance(tool_table, dict) and "mypy" in tool_table
-
-
-def _ancestor_directories(starting_file: Path) -> list[Path]:
-    """Return *starting_file*'s directory and every parent, nearest first.
-
-    ::
-
-        repo/pkg/mod.py -> [repo/pkg, repo, ... , filesystem root]
-        repo/pkg/       -> [repo/pkg, repo, ... , filesystem root]
-
-    A file resolves to its containing directory; a directory resolves to
-    itself, so both ancestor walks below start from the same first candidate.
-
-    Args:
-        starting_file: The file (or directory) the walk begins from.
-
-    Returns:
-        The resolved starting directory followed by each of its parents.
-    """
-    resolved_starting_file = starting_file.resolve()
-    walk_origin = resolved_starting_file.parent if resolved_starting_file.is_file() else resolved_starting_file
-    return [walk_origin, *walk_origin.parents]
-
-
 def find_pyproject_with_mypy_config(starting_file: Path) -> Path | None:
     """Walk up from a starting file to locate a pyproject.toml that configures mypy.
 
@@ -97,12 +80,7 @@ def find_pyproject_with_mypy_config(starting_file: Path) -> Path | None:
         table, or ``None`` when no such file exists between ``starting_file``
         and the filesystem root.
     """
-    pyproject_filename_for_lookup = PYPROJECT_FILENAME
-    for each_candidate_directory in _ancestor_directories(starting_file):
-        candidate_pyproject = each_candidate_directory / pyproject_filename_for_lookup
-        if candidate_pyproject.is_file() and _pyproject_contains_tool_mypy(candidate_pyproject):
-            return candidate_pyproject
-    return None
+    return find_pyproject_configuring_tool(starting_file, MYPY_TOOL_TABLE_NAME)
 
 
 def find_module_resolution_root(starting_file: Path) -> Path | None:
@@ -127,7 +105,7 @@ def find_module_resolution_root(starting_file: Path) -> Path | None:
     """
     git_entry_name = GIT_DIRECTORY_NAME
     pyproject_filename = PYPROJECT_FILENAME
-    for each_candidate_directory in _ancestor_directories(starting_file):
+    for each_candidate_directory in ancestor_directories(starting_file):
         has_git_entry = (each_candidate_directory / git_entry_name).exists()
         has_pyproject = (each_candidate_directory / pyproject_filename).is_file()
         if has_git_entry or has_pyproject:
@@ -171,7 +149,7 @@ def mypy_working_directory(all_py_files: list[str]) -> Iterator[str]:
         yield isolated_directory
 
 
-def _mypy_config_argument(all_py_files: list[str]) -> list[str]:
+def _native_mypy_config_argument(all_py_files: list[str]) -> list[str]:
     """Return the ``--config-file`` argument for the first file with a mypy config."""
     for each_py_file in all_py_files:
         discovered_pyproject = find_pyproject_with_mypy_config(Path(each_py_file))
@@ -180,9 +158,39 @@ def _mypy_config_argument(all_py_files: list[str]) -> list[str]:
     return []
 
 
-def _run_mypy_subprocess(all_py_files: list[str]) -> subprocess.CompletedProcess[str]:
+def _mypy_config_argument(
+    all_py_files: list[str], config_source_path: Path | None
+) -> list[str]:
+    """Return the ``--config-file`` argument, resolved from the original path when given.
+
+    ::
+
+        config_source_path resolves .../hooks/pyproject.toml
+            -> ["--config-file", ".../hooks/pyproject.toml"]
+        config_source_path given, no [tool.mypy] up-tree -> [] (native discovery)
+        config_source_path None -> native per-file discovery over all_py_files
+
+    Args:
+        all_py_files: The resolved paths mypy will check.
+        config_source_path: The original target path the staged copy stands in
+            for, or ``None`` for a native multi-file run.
+
+    Returns:
+        The ``--config-file`` argument vector, empty when no config resolves.
+    """
+    if config_source_path is None:
+        return _native_mypy_config_argument(all_py_files)
+    resolved_pyproject = find_pyproject_with_mypy_config(config_source_path)
+    if resolved_pyproject is not None:
+        return ["--config-file", str(resolved_pyproject)]
+    return _native_mypy_config_argument(all_py_files)
+
+
+def _run_mypy_subprocess(
+    all_py_files: list[str], config_source_path: Path | None
+) -> subprocess.CompletedProcess[str]:
     """Run mypy over *all_py_files* from each file's own project root."""
-    config_argument = _mypy_config_argument(all_py_files)
+    config_argument = _mypy_config_argument(all_py_files, config_source_path)
     with mypy_working_directory(all_py_files) as working_directory:
         return subprocess.run(
             ["mypy", *config_argument, "--ignore-missing-imports", "--no-error-summary"]
@@ -194,24 +202,29 @@ def _run_mypy_subprocess(all_py_files: list[str]) -> subprocess.CompletedProcess
         )
 
 
-def run_mypy_check(files: list[Path]) -> MypyResult:
-    """Run mypy on files."""
-    if not files:
+def run_mypy_check(
+    all_files: list[Path], config_source_path: Path | None = None
+) -> MypyResult:
+    """Run mypy on files, resolving config from *config_source_path* when given.
+
+    A given ``config_source_path`` walks ``--config-file`` up from the original
+    target rather than the staged copy's own ancestors.
+    """
+    if not all_files:
         return MypyResult(passed=True, output="No files to check", error_count=0)
 
     if not check_mypy_available():
         return MypyResult(passed=True, output="Mypy not installed - skipping", error_count=0)
 
-    python_source_suffix = PYTHON_SOURCE_SUFFIX
     all_py_files = [
         str(each_file.resolve())
-        for each_file in files
-        if each_file.suffix == python_source_suffix
+        for each_file in all_files
+        if each_file.suffix == PYTHON_SOURCE_SUFFIX
     ]
     if not all_py_files:
         return MypyResult(passed=True, output="No Python files", error_count=0)
 
-    completed_process = _run_mypy_subprocess(all_py_files)
+    completed_process = _run_mypy_subprocess(all_py_files, config_source_path)
     error_count = completed_process.stdout.count(": error:")
 
     return MypyResult(