claude-dev-env 1.89.0 → 1.92.0

package/hooks/hooks_constants/volatile_path_in_post_blocker_constants.py

@@ -0,0 +1,48 @@
+"""Configuration constants for the volatile_path_in_post_blocker PreToolUse hook."""
+
+BASH_TOOL_NAME: str = "Bash"
+
+MCP_GITHUB_TOOL_PREFIX: str = "mcp__plugin_github_github__"
+
+ALL_MCP_BODY_PARAM_NAMES: tuple[str, ...] = ("body", "comment")
+
+GH_COMMAND_NAME: str = "gh"
+
+MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT: int = 2
+
+TOKEN_JOIN_SEPARATOR: str = " "
+
+BODY_FILE_ENCODING: str = "utf-8"
+
+ALL_GH_POST_SUBCOMMANDS: dict[str, frozenset[str]] = {
+    "pr": frozenset({"create", "comment", "edit", "review"}),
+    "issue": frozenset({"create", "comment", "edit"}),
+}
+
+ALL_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
+    ".claude-editor/jobs/",
+    ".claude/worktrees/",
+    "appdata/local/temp",
+    "/tmp/",
+    "%temp%",
+    "$env:temp",
+    "$claude_job_dir",
+)
+
+GH_ARTIFACT_UPLOAD_INVOCATION: str = (
+    "python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>"
+)
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [durable-post-artifacts]: this post body references a volatile path "
+    "(a job scratch dir, worktree, or system temp location). The post is durable "
+    "and outlives that scratch, so the reference breaks the moment the directory "
+    "is cleaned.\n\n"
+    "Fix it before posting:\n"
+    "  1. Text data (logs, tables, diffs): paste the actual content inline in the "
+    "post instead of linking a scratch file path.\n"
+    "  2. Binary artifacts (images, archives): upload the file to the repo's "
+    "durable 'artifacts' release and link the permanent asset URL it prints:\n"
+    f"       {GH_ARTIFACT_UPLOAD_INVOCATION}\n\n"
+    "See ~/.claude/rules/durable-post-artifacts.md for the full contract."
+)

package/hooks/lifecycle/CLAUDE.md

@@ -7,12 +7,14 @@ Hooks that run at session or config-change boundaries rather than on individual
 | File | Event | What it does |
 |---|---|---|
 | `config_change_guard.py` | PostToolUse (Write/Edit on `settings.json`) | Counts hooks in the edited `settings.json` and logs any change to `~/.claude/cache/config-change-audit.log`; alerts when the hook count drops below the last known value |
+| `enter_worktree_origin_prefetch.py` | PreToolUse (EnterWorktree) | Fetches origin's default branch before a worktree creation call, keeping the `refs/remotes/origin/<default-branch>` ref that `fresh` mode reads current; never blocks on fetch failure |
 | `pr_converge_bugteam_skill_tracker.py` | PreToolUse (Skill) | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
 | `session_end_cleanup.py` | SessionEnd | Purges stale cache entries from `~/.claude/cache/` (entries older than the configured threshold) and old backup files |
 | `test_config_change_guard.py` | — | Tests for `config_change_guard.py` |
+| `test_enter_worktree_origin_prefetch.py` | — | Tests for `enter_worktree_origin_prefetch.py` |
 | `test_pr_converge_bugteam_skill_tracker.py` | — | Tests for `pr_converge_bugteam_skill_tracker.py` |
 
 ## Conventions
 
-- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/pr_converge_bugteam_enforcer_constants.py`.
+- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file, EnterWorktree prefetch tuning) live in `hooks_constants/session_env_cleanup_constants.py`, `hooks_constants/pr_converge_bugteam_enforcer_constants.py`, and `hooks_constants/enter_worktree_prefetch_constants.py`.
 - Tests run with `python -m pytest lifecycle/test_<name>.py`.

package/hooks/lifecycle/enter_worktree_origin_prefetch.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: fetch origin's default branch before EnterWorktree creates one.
+
+``EnterWorktree`` in its default ``fresh`` mode bases a new worktree on the
+locally cached ``refs/remotes/origin/<default-branch>`` ref and only runs
+``git fetch`` when that ref is missing entirely -- so a worktree created
+without a recent fetch silently starts behind the remote. This hook fetches
+that ref immediately before the tool resolves its base, so the ref it reads
+is current.
+
+::
+
+    EnterWorktree({})                              # tool_input has no "path"
+             |
+             v
+    this hook: git fetch origin <default-branch>   # best-effort, never blocks
+             |
+             v
+    EnterWorktree resolves refs/remotes/origin/<default-branch>  # now fresh
+
+The hook is a no-op when ``tool_input`` carries a ``path`` (switching into an
+already-existing worktree needs no fresh base) and always exits 0 -- a failed
+or slow fetch never blocks worktree creation.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+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 hooks_constants.enter_worktree_prefetch_constants import (  # noqa: E402
+    ENTER_WORKTREE_PATH_INPUT_KEY,
+    ENTER_WORKTREE_TOOL_NAME,
+    GIT_FETCH_TIMEOUT_SECONDS,
+    GIT_SYMBOLIC_REF_TIMEOUT_SECONDS,
+    ORIGIN_HEAD_SYMBOLIC_REF,
+    ORIGIN_REMOTE_NAME,
+    ORIGIN_REMOTE_REF_PREFIX,
+)
+
+
+def is_enter_worktree_creation(payload_by_field: dict[str, object]) -> bool:
+    """Return True when this hook invocation is an EnterWorktree creation call.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload (already JSON-parsed),
+            keyed by top-level field name.
+
+    Returns:
+        True when ``tool_name == "EnterWorktree"`` and ``tool_input`` carries
+        no ``path`` key. A ``path`` value means the call switches into an
+        already-existing worktree rather than creating one, so it is False
+        for that case and for every other tool.
+    """
+    if payload_by_field.get("tool_name", "") != ENTER_WORKTREE_TOOL_NAME:
+        return False
+    tool_input = payload_by_field.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return True
+    return not tool_input.get(ENTER_WORKTREE_PATH_INPUT_KEY)
+
+
+def resolve_origin_default_branch(repo_directory: str) -> str | None:
+    """Return the branch name origin's HEAD points at, or None if unresolved.
+
+    Args:
+        repo_directory: Working directory to run ``git`` in.
+
+    Returns:
+        The branch name (for example ``"main"``) parsed from
+        ``refs/remotes/origin/HEAD``, or None when the symbolic ref is
+        unset, git is unavailable, or the command times out.
+    """
+    try:
+        completed_process = subprocess.run(
+            ["git", "symbolic-ref", ORIGIN_HEAD_SYMBOLIC_REF],
+            capture_output=True,
+            text=True,
+            timeout=GIT_SYMBOLIC_REF_TIMEOUT_SECONDS,
+            cwd=repo_directory,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    resolved_ref = completed_process.stdout.strip()
+    if not resolved_ref.startswith(ORIGIN_REMOTE_REF_PREFIX):
+        return None
+    return resolved_ref[len(ORIGIN_REMOTE_REF_PREFIX):]
+
+
+def fetch_origin_branch(repo_directory: str, branch_name: str) -> None:
+    """Best-effort ``git fetch origin <branch_name>``; never raises.
+
+    Args:
+        repo_directory: Working directory to run ``git`` in.
+        branch_name: Branch to fetch from the ``origin`` remote.
+    """
+    try:
+        subprocess.run(
+            ["git", "fetch", ORIGIN_REMOTE_NAME, branch_name],
+            capture_output=True,
+            text=True,
+            timeout=GIT_FETCH_TIMEOUT_SECONDS,
+            cwd=repo_directory,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return
+
+
+def main() -> None:
+    """Entry point for the PreToolUse:EnterWorktree hook.
+
+    Reads the PreToolUse payload from stdin, and when it is an EnterWorktree
+    creation call, fetches origin's default branch in the session's ``cwd``
+    before returning. Always exits 0: a fetch failure self-heals on the next
+    fetch rather than blocking worktree creation.
+    """
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_payload, dict):
+        sys.exit(0)
+    if not is_enter_worktree_creation(hook_payload):
+        sys.exit(0)
+    repo_directory = hook_payload.get("cwd")
+    if not isinstance(repo_directory, str) or not repo_directory:
+        sys.exit(0)
+    default_branch = resolve_origin_default_branch(repo_directory)
+    if default_branch is None:
+        sys.exit(0)
+    fetch_origin_branch(repo_directory, default_branch)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/lifecycle/test_enter_worktree_origin_prefetch.py

@@ -0,0 +1,178 @@
+"""Unit tests for the enter_worktree_origin_prefetch PreToolUse hook.
+
+Uses real git repositories (a "remote" repo cloned into a "local" one) so the
+fetch behavior is exercised against actual git plumbing, not mocked calls.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "enter_worktree_origin_prefetch",
+    _HOOK_DIR / "enter_worktree_origin_prefetch.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+
+def _run_git(repo_directory: pathlib.Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_directory,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+
+def _init_repo_with_commit(repo_directory: pathlib.Path) -> None:
+    repo_directory.mkdir(parents=True, exist_ok=True)
+    _run_git(repo_directory, "init", "--quiet", "--initial-branch=main")
+    _run_git(repo_directory, "config", "user.email", "test@example.com")
+    _run_git(repo_directory, "config", "user.name", "Test")
+    _run_git(repo_directory, "commit", "--allow-empty", "--quiet", "-m", "init")
+
+
+def _clone_as_local(remote_directory: pathlib.Path, local_directory: pathlib.Path) -> None:
+    subprocess.run(
+        ["git", "clone", "--quiet", str(remote_directory), str(local_directory)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    _run_git(local_directory, "config", "user.email", "test@example.com")
+    _run_git(local_directory, "config", "user.name", "Test")
+
+
+def test_is_enter_worktree_creation_true_when_no_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_true_with_name_only() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"name": "my-branch"}}
+    assert hook_module.is_enter_worktree_creation(payload) is True
+
+
+def test_is_enter_worktree_creation_false_when_path_given() -> None:
+    payload = {"tool_name": "EnterWorktree", "tool_input": {"path": "/some/worktree"}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_is_enter_worktree_creation_false_for_other_tool() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {}}
+    assert hook_module.is_enter_worktree_creation(payload) is False
+
+
+def test_resolve_origin_default_branch_reads_cloned_head(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(local_directory))
+
+    assert resolved_branch == "main"
+
+
+def test_resolve_origin_default_branch_returns_none_without_origin(
+    tmp_path: pathlib.Path,
+) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    resolved_branch = hook_module.resolve_origin_default_branch(str(solo_directory))
+
+    assert resolved_branch is None
+
+
+def test_fetch_origin_branch_updates_stale_local_ref(tmp_path: pathlib.Path) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+    local_cached_sha_before = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_before != remote_head_sha
+
+    hook_module.fetch_origin_branch(str(local_directory), "main")
+
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_fetch_origin_branch_never_raises_when_remote_missing(tmp_path: pathlib.Path) -> None:
+    solo_directory = tmp_path / "solo"
+    _init_repo_with_commit(solo_directory)
+
+    hook_module.fetch_origin_branch(str(solo_directory), "main")
+
+
+def test_main_fetches_stale_ref_and_exits_zero(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    remote_directory = tmp_path / "remote"
+    local_directory = tmp_path / "local"
+    _init_repo_with_commit(remote_directory)
+    _clone_as_local(remote_directory, local_directory)
+    _run_git(remote_directory, "commit", "--allow-empty", "--quiet", "-m", "second")
+    remote_head_sha = _run_git(remote_directory, "rev-parse", "HEAD").stdout.strip()
+
+    payload = {
+        "tool_name": "EnterWorktree",
+        "tool_input": {},
+        "cwd": str(local_directory),
+    }
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+    local_cached_sha_after = _run_git(
+        local_directory, "rev-parse", "refs/remotes/origin/main"
+    ).stdout.strip()
+    assert local_cached_sha_after == remote_head_sha
+
+
+def test_main_exits_zero_for_non_enter_worktree_tool(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    payload = {"tool_name": "Bash", "tool_input": {"command": "ls"}, "cwd": "/tmp"}
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0
+
+
+def test_main_exits_zero_on_malformed_json(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+
+    with pytest.raises(SystemExit) as exit_info:
+        hook_module.main()
+
+    assert exit_info.value.code == 0

package/hooks/validators/run_all_validators.py

@@ -6,6 +6,7 @@ Exit code 0 = all checks pass, 1 = violations found.
 # pragma: no-tdd-gate
 
 import argparse
+import json
 import os
 import subprocess
 import sys
@@ -27,6 +28,15 @@ VALIDATORS_DIR = Path(__file__).parent
 hooks_dir = VALIDATORS_DIR.parent
 package_name = VALIDATORS_DIR.name
 
+_hooks_directory_on_path = str(hooks_dir.resolve())
+if _hooks_directory_on_path not in sys.path:
+    sys.path.insert(0, _hooks_directory_on_path)
+
+from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
+    apply_edits,
+    edits_for_tool,
+)
+
 
 def _windows_non_unc_working_directory_string(
     candidate_directory_strings: list[str | None],
@@ -99,8 +109,19 @@ def invoke_validator_module(module_stem: str, forwarded_file_paths: List[str]) -
 
 def run_validators_entrypoint_subprocess(
     extra_arguments: List[str],
+    stdin_text: Optional[str] = None,
 ) -> subprocess.CompletedProcess[str]:
-    """Run ``python -m validators.run_all_validators`` with a Windows-safe cwd."""
+    """Run ``python -m validators.run_all_validators`` with a Windows-safe cwd.
+
+    Args:
+        extra_arguments: Argument vector appended after the module name.
+        stdin_text: Text replayed as the subprocess stdin, or None to leave
+            stdin empty. The PreToolUse gate mode reads its payload from stdin,
+            so a caller exercising ``--pre-tool-use`` passes the payload here.
+
+    Returns:
+        The completed subprocess carrying its captured stdout and stderr.
+    """
     working_directory_string, environment = (
         _hooks_subprocess_working_directory_and_environment()
     )
@@ -111,6 +132,7 @@ def run_validators_entrypoint_subprocess(
         text=True,
         cwd=working_directory_string,
         env=environment,
+        input=stdin_text,
     )
 
 
@@ -375,9 +397,9 @@ def run_comment_checks(files: List[Path]) -> ValidatorResult:
     """Comment preservation is enforced by code_rules_enforcer hook.
 
     The hook compares old vs new content to block NEW comments and
-    block DELETION of existing comments. This standalone validator
-    is disabled because it flags ALL comments in existing files,
-    which forces agents to remove them to pass validation.
+    print a stderr advisory when an existing comment is removed. This
+    standalone validator is disabled because it flags ALL comments in
+    existing files, which forces agents to remove them to pass validation.
     """
     return ValidatorResult(
         name="No Comments",
@@ -658,6 +680,188 @@ def get_changed_files() -> List[Path]:
     return [Path(f) for f in files if f]
 
 
+def _read_target_file_content(file_path: str) -> Optional[str]:
+    """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 readable_file:
+            return readable_file.read()
+    except (FileNotFoundError, OSError, UnicodeDecodeError):
+        return None
+
+
+def reconstruct_proposed_content(
+    tool_name: str, tool_input: Dict[str, object]
+) -> Optional[str]:
+    """Return the post-edit content one Write, Edit, or MultiEdit payload leaves on disk.
+
+    ::
+
+        Write     -> tool_input["content"] verbatim
+        Edit      -> existing file, each old_string rewritten to new_string
+        MultiEdit -> existing file, each edit applied in order
+
+    The Edit and MultiEdit reconstruction reuses the shared applier so this gate
+    judges the same post-edit content the standalone blockers judge.
+
+    Args:
+        tool_name: The intercepted tool — Write, Edit, or MultiEdit.
+        tool_input: The tool's input payload.
+
+    Returns:
+        The proposed post-edit content, or None when the payload carries no
+        readable target for an edit or no string content for a write.
+    """
+    if tool_name == "Write":
+        written_content = tool_input.get("content", "")
+        return written_content if isinstance(written_content, str) else None
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return None
+    existing_content = _read_target_file_content(file_path)
+    if existing_content is None:
+        return None
+    return apply_edits(existing_content, edits_for_tool(tool_name, dict(tool_input)))
+
+
+def run_file_scoped_validators(all_files: List[Path]) -> List[ValidatorResult]:
+    """Run every validator scoped to individual files against *all_files*.
+
+    Excludes the branch-scoped File Structure and Git validators, which grade
+    the whole project rather than a single proposed file.
+
+    Args:
+        all_files: The files under validation — a single reconstructed file in
+            gate mode.
+
+    Returns:
+        One ValidatorResult per file-scoped validator, in run order.
+    """
+    return [
+        run_python_style_checks(all_files),
+        run_test_safety_checks(all_files),
+        run_react_checks(all_files),
+        run_ruff_checks(all_files),
+        run_mypy_checks(all_files),
+        run_abbreviation_checks(all_files),
+        run_pr_reference_checks(all_files),
+        run_magic_value_checks(all_files),
+        run_useless_test_checks(all_files),
+        run_security_checks(all_files),
+        run_code_quality_checks(all_files),
+        run_python_antipattern_checks(all_files),
+        run_todo_checks(all_files),
+        run_type_safety_checks(all_files),
+    ]
+
+
+def validate_proposed_file(
+    file_path: str, proposed_content: str
+) -> List[ValidatorResult]:
+    """Validate *proposed_content* as if written to *file_path*.
+
+    Writes the content to a temporary file that carries the target's basename so
+    suffix-based and test-name-based validator filtering matches the real path,
+    then runs the file-scoped validators against it.
+
+    Args:
+        file_path: The destination path the write or edit targets.
+        proposed_content: The reconstructed post-edit content of that file.
+
+    Returns:
+        One ValidatorResult per file-scoped validator.
+    """
+    base_name = Path(file_path).name
+    with tempfile.TemporaryDirectory() as temporary_directory:
+        temporary_file = Path(temporary_directory) / base_name
+        temporary_file.write_text(proposed_content, encoding="utf-8")
+        return run_file_scoped_validators([temporary_file])
+
+
+def _proposed_content_deny_reason(failed_results: List[ValidatorResult]) -> str:
+    """Compose the deny reason naming each failing validator and its output.
+
+    Args:
+        failed_results: The validator results that did not pass.
+
+    Returns:
+        The composed ``permissionDecisionReason`` text.
+    """
+    violation_summaries = [
+        f"{each_result.name} (checks {each_result.checks}): {each_result.output.strip()}"
+        for each_result in failed_results
+    ]
+    deny_reason_item_separator = " | "
+    joined_summaries = deny_reason_item_separator.join(violation_summaries)
+    return (
+        f"BLOCKED: [validators] {len(failed_results)} "
+        f"validator(s) failed: {joined_summaries}"
+    )
+
+
+def _emit_pre_tool_use_deny(deny_reason: str) -> None:
+    """Write one PreToolUse deny JSON payload carrying *deny_reason* to stdout."""
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+    sys.stdout.write(json.dumps(deny_payload) + "\n")
+    sys.stdout.flush()
+
+
+def _evaluate_pre_tool_use_payload() -> None:
+    """Read the PreToolUse payload from stdin and deny a violating file write.
+
+    Reconstructs the proposed post-edit content of the one target file and runs
+    the file-scoped validators against it. Emits a deny decision naming each
+    failing validator when any fires; writes nothing for a clean file, an
+    unparseable payload, or a payload no validator covers.
+    """
+    pre_tool_use_payload = json.load(sys.stdin)
+    if not isinstance(pre_tool_use_payload, dict):
+        return
+    tool_name = pre_tool_use_payload.get("tool_name", "")
+    tool_input = pre_tool_use_payload.get("tool_input", {})
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return
+    proposed_content = reconstruct_proposed_content(tool_name, tool_input)
+    if not proposed_content:
+        return
+    all_results = validate_proposed_file(file_path, proposed_content)
+    failed_results = [
+        each_result
+        for each_result in all_results
+        if not each_result.passed and not each_result.skipped
+    ]
+    if failed_results:
+        _emit_pre_tool_use_deny(_proposed_content_deny_reason(failed_results))
+
+
+def run_pre_tool_use_gate() -> int:
+    """Run the PreToolUse gate, never crashing the tool call on an internal error.
+
+    A hook that raises is rendered by the harness as a tool malfunction, so an
+    unexpected failure here logs to stderr and returns 0 rather than propagating.
+
+    Returns:
+        Always 0 — the gate signals a block through the deny payload, not an
+        exit code.
+    """
+    try:
+        _evaluate_pre_tool_use_payload()
+    except json.JSONDecodeError:
+        return 0
+    except Exception as error:
+        sys.stderr.write(f"[run_all_validators] pre-tool-use gate error: {error}\n")
+        sys.stderr.flush()
+    return 0
+
+
 def main() -> int:
     """Run all validators and report results."""
     parser = argparse.ArgumentParser(description="Run pre-push validators")
@@ -687,8 +891,16 @@ def main() -> int:
         default=2,
         help="Lines of context around violations",
     )
+    parser.add_argument(
+        "--pre-tool-use",
+        action="store_true",
+        help="Run as a PreToolUse gate on the single proposed file write from stdin",
+    )
     args = parser.parse_args()
 
+    if args.pre_tool_use:
+        return run_pre_tool_use_gate()
+
     if args.health:
         health = get_system_health()
         print_health_report(health)