claude-dev-env 2.31.1 → 2.32.0

package/hooks/validators/test_run_all_validators_mutation_tool_parity.py

@@ -0,0 +1,249 @@
+"""Behavioral tests for validator coverage across every mutation tool.
+
+The PreToolUse gate has to reach a MultiEdit and a Codex apply_patch the same
+way it reaches a Write and an Edit. Two things carry that: the hooks.json
+matcher the harness dispatches on, and the payload shape the gate reconstructs
+post-edit content from.
+"""
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from hooks_constants.pre_tool_use_dispatcher_constants import (
+    ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES,
+)
+
+from .run_all_validators import run_validators_entrypoint_subprocess
+
+pytestmark = pytest.mark.usefixtures("ephemeral_exempt_off")
+
+HOOKS_JSON_PATH = Path(__file__).resolve().parents[1] / "hooks.json"
+VALIDATORS_RUNNER_COMMAND_MARKER = "validators.run_all_validators"
+MATCHER_TOOL_NAME_SEPARATOR = "|"
+DENY_DECISION_FRAGMENT = '"permissionDecision": "deny"'
+MAGIC_VALUE_VALIDATOR_NAME = "Magic Values"
+
+CLEAN_MODULE_SOURCE = (
+    "def clean_marker() -> int:\n    computed_value = 1\n    return computed_value\n"
+)
+CLEAN_SECOND_MODULE_SOURCE = (
+    "def second_marker() -> int:\n    counted_value = 1\n    return counted_value\n"
+)
+CLEAN_RETURN_LINE = "    return computed_value\n"
+MAGIC_VALUE_RETURN_LINE = "    return computed_value * 199\n"
+CLEAN_REWRITTEN_RETURN_LINE = "    return computed_value + 1\n"
+
+UPDATE_PATCH_TEMPLATE = (
+    "*** Begin Patch\n"
+    "*** Update File: {relative_path}\n"
+    "@@\n"
+    "-{removed_line}"
+    "+{added_line}"
+    "*** End Patch\n"
+)
+ADD_VIOLATING_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n"
+    "*** Add File: added_module.py\n"
+    "+def added_marker() -> int:\n"
+    "+    return 199\n"
+    "*** End Patch\n"
+)
+DELETE_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n*** Delete File: legacy_module.py\n*** End of File\n*** End Patch\n"
+)
+UNPARSEABLE_PATCH_COMMAND = "not a codex patch at all\n"
+TWO_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n"
+    "*** Update File: first_module.py\n"
+    "@@\n"
+    "-    return computed_value\n"
+    "+    return computed_value + 1\n"
+    "*** Update File: second_module.py\n"
+    "@@\n"
+    "-    return counted_value\n"
+    "+    return counted_value * 199\n"
+    "*** End Patch\n"
+)
+
+
+def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
+    """Drive the real --pre-tool-use entry point with one payload."""
+    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+
+
+def update_patch_command(relative_path: str, added_line: str) -> str:
+    """Build an Update File patch rewriting the module's return line."""
+    return UPDATE_PATCH_TEMPLATE.format(
+        relative_path=relative_path,
+        removed_line=CLEAN_RETURN_LINE,
+        added_line=added_line,
+    )
+
+
+def write_clean_module(target_directory: Path, module_name: str) -> Path:
+    """Write the clean Python module the payloads target."""
+    target_file = target_directory / module_name
+    target_file.write_text(CLEAN_MODULE_SOURCE, encoding="utf-8")
+    return target_file
+
+
+class TestMutationToolRegistration:
+    def test_validators_gate_is_registered_on_every_mutation_tool(self) -> None:
+        hooks_document = json.loads(HOOKS_JSON_PATH.read_text(encoding="utf-8"))
+        all_matchers = [
+            each_group["matcher"]
+            for each_group in hooks_document["hooks"]["PreToolUse"]
+            for each_hook in each_group.get("hooks", [])
+            if VALIDATORS_RUNNER_COMMAND_MARKER in each_hook.get("command", "")
+        ]
+        assert len(all_matchers) == 1, all_matchers
+        assert (
+            set(all_matchers[0].split(MATCHER_TOOL_NAME_SEPARATOR))
+            == ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES
+        )
+
+
+class TestMultiEditPayloadLane:
+    def test_multi_edit_introducing_a_violation_denies(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "MultiEdit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "edits": [
+                        {
+                            "old_string": CLEAN_RETURN_LINE,
+                            "new_string": MAGIC_VALUE_RETURN_LINE,
+                        }
+                    ],
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_multi_edit_leaving_clean_content_allows(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "clean_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "MultiEdit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "edits": [
+                        {
+                            "old_string": CLEAN_RETURN_LINE,
+                            "new_string": CLEAN_REWRITTEN_RETURN_LINE,
+                        }
+                    ],
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+
+class TestApplyPatchPayloadLane:
+    def test_apply_patch_introducing_a_violation_denies(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("legacy_module.py", MAGIC_VALUE_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_apply_patch_deny_reason_names_the_patched_file(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("legacy_module.py", MAGIC_VALUE_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert target_file.name in completed.stdout
+
+    def test_apply_patch_leaving_clean_content_allows(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "clean_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("clean_module.py", CLEAN_REWRITTEN_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_apply_patch_adding_a_violating_file_denies(self, tmp_path: Path) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": ADD_VIOLATING_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_apply_patch_deleting_a_file_allows(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": DELETE_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_unparseable_apply_patch_command_allows(self, tmp_path: Path) -> None:
+        """A patch this lane cannot read is the enforcer's to deny, not this gate's.
+
+        ``code_rules_enforcer`` denies a payload whose patch markers it cannot
+        parse. Both hooks run on the same call and any denial wins, so this lane
+        allows rather than raising a second denial for one cause. Moving that
+        denial out of the enforcer leaves a malformed patch with no reader.
+        """
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": UNPARSEABLE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_apply_patch_denies_a_violation_in_its_second_file(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "first_module.py")
+        second_file = tmp_path / "second_module.py"
+        second_file.write_text(CLEAN_SECOND_MODULE_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": TWO_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert second_file.name in completed.stdout

package/hooks/validators/test_run_all_validators_reporting.py

@@ -0,0 +1,66 @@
+"""Tests for the run report run_all_validators renders after a full run.
+
+Timing metrics and the version header are the two pieces of that report. They
+moved out of test_run_all_validators.py so the paired file keeps room for the
+gate behavior it exists to pin.
+"""
+
+import pytest
+
+from .run_all_validators import (
+    add_timing,
+    build_json_output,
+    create_timing_metrics,
+    format_timing_report,
+    print_header,
+)
+
+
+class TestTimingMetrics:
+    def test_create_timing_metrics_empty(self) -> None:
+        metrics = create_timing_metrics({})
+        assert metrics.total_seconds == 0.0
+        assert metrics.validator_times == {}
+
+    def test_create_timing_metrics_with_data(self) -> None:
+        timings = {"Validator A": 1.5, "Validator B": 2.0}
+        metrics = create_timing_metrics(timings)
+        assert metrics.total_seconds == 3.5
+        assert metrics.validator_times == timings
+
+    def test_add_timing_returns_new_instance(self) -> None:
+        metrics1 = create_timing_metrics({})
+        metrics2 = add_timing(metrics1, "Test", 1.5)
+
+        assert metrics1.total_seconds == 0.0
+        assert metrics2.total_seconds == 1.5
+        assert "Test" not in metrics1.validator_times
+        assert metrics2.validator_times["Test"] == 1.5
+
+    def test_format_report_includes_all_timings(self) -> None:
+        metrics = create_timing_metrics({"Fast": 0.1, "Slow": 2.5})
+        report = format_timing_report(metrics)
+
+        assert "Fast" in report
+        assert "Slow" in report
+        assert "2.6" in report
+
+
+class TestVersionHeader:
+    def test_print_header_includes_version(self, capsys: pytest.CaptureFixture[str]) -> None:
+        print_header()
+        captured = capsys.readouterr()
+
+        assert "PRE-PUSH VALIDATOR RESULTS" in captured.out
+        assert "(v" in captured.out
+
+    def test_build_json_output_includes_version(self) -> None:
+        json_output = build_json_output(
+            results=[],
+            metrics=create_timing_metrics({}),
+            include_timing=False,
+        )
+
+        assert "version" in json_output
+        assert "timestamp" in json_output
+        assert isinstance(json_output["version"], str)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.31.1",
+    "version": "2.32.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/shell-invocation.md

@@ -18,4 +18,4 @@ When a script file's literal body needs `$(...)`, author it with the Write tool,
 
 ## Enforcement
 
-`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes.
+`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes. A quoted heredoc body is dropped for the same reason: the opener forms that quote or escape the delimiter tell bash to expand nothing down to the terminator, so a backtick there is text the file receives. A bare delimiter expands its body and keeps its scan.

package/rules/testing.md

@@ -26,3 +26,7 @@ Tests exercise real behavior, real data, and production code paths. A test that
 ## The File-Level TDD Gate Reads Content
 
 `tdd_enforcer.py` records each candidate test's content hash at every sighting and compares that hash on the next write. A first sighting requires content that differs from HEAD.
+
+## The Gate Reads a Recorded Failing Run First
+
+`hooks/observability/test_failure_recorder.py` runs on every Bash call and records a single unchained pytest run that names a real test file path and reports a failing exit status. It stores the command, that exit status, and the path in the same content-hash store the gate reads. The gate consults that record before its freshness fallback, and honours it while the candidate's content still matches what failed. `content_hash_store.py`'s module docstring holds the full contract.

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -8,6 +8,15 @@ here rather than inline in the modules.
 
 from __future__ import annotations
 
+# The installed tree's own shape is shared with every other reader of it.
+from dev_env_scripts_constants.shared_tree_constants import (  # noqa: F401
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    PROCESS_TREE_DIRECTORY_NAME,
+    PROCESS_TREE_KILL_MODULE_FILENAME,
+    SCRIPTS_DIRECTORY_NAME,
+    SHARED_PACKAGE_DIRECTORY_NAME,
+)
+
 GROK_BINARY_NAME: str = "grok"
 """Executable name resolved on PATH for the headless grok tier."""
 
@@ -56,19 +65,14 @@ DEFAULT_PING_TIMEOUT_SECONDS: int = 120
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds Claude config."""
 
-CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
 """Environment variable naming the managed Claude config root."""
 
-PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"
 """Filename of the shared process-tree kill helper."""
 
-SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
 """Directory name of the shared install tree under the managed root."""
 
-PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
 """Directory name of the process-tree helper package under ``_shared``."""
 
-SCRIPTS_DIRECTORY_NAME: str = "scripts"
 """Directory name holding Python helpers under a process-tree package."""
 
 MANIFEST_FILENAME: str = ".claude-dev-env-manifest.json"

package/scripts/dev_env_scripts_constants/shared_tree_constants.py

@@ -0,0 +1,17 @@
+"""Constants for resolving directories inside the installed shared tree.
+
+These name the shape of the installed tree itself, not any one worker or
+skill that reads it, so every caller of shared_tree_paths shares them.
+"""
+
+from __future__ import annotations
+
+CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
+
+SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
+
+SCRIPTS_DIRECTORY_NAME: str = "scripts"
+
+PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
+
+PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"

package/scripts/shared_tree_paths.py

@@ -1,11 +1,16 @@
-"""Resolve directories inside the installed shared tree."""
+"""Resolve a scripts directory inside the installed shared tree.
+
+An install can place a managed directory behind a directory junction. Path
+resolution walks that link, so a parent computed from the resolved path
+names the link target's parent, where the shared tree does not sit.
+"""
 
 from __future__ import annotations
 
 from collections.abc import Mapping
 from pathlib import Path
 
-from dev_env_scripts_constants.grok_worker_constants import (
+from dev_env_scripts_constants.shared_tree_constants import (
     CLAUDE_CONFIG_DIR_ENV_VAR,
     PROCESS_TREE_DIRECTORY_NAME,
     PROCESS_TREE_KILL_MODULE_FILENAME,
@@ -14,57 +19,86 @@ from dev_env_scripts_constants.grok_worker_constants import (
 )
 
 
-def _process_tree_scripts_directory(from_root: Path) -> Path:
+def _shared_scripts_directory(from_root: Path, shared_subpackage_name: str) -> Path:
+    """Return the scripts directory one named sub-package holds under a root."""
     return (
         from_root
         / SHARED_PACKAGE_DIRECTORY_NAME
-        / PROCESS_TREE_DIRECTORY_NAME
+        / shared_subpackage_name
         / SCRIPTS_DIRECTORY_NAME
     )
 
 
-def _has_process_tree_kill_module(from_directory: Path) -> bool:
-    return (from_directory / PROCESS_TREE_KILL_MODULE_FILENAME).is_file()
-
-
-def resolve_shared_process_tree_scripts_directory(
+def resolve_shared_scripts_directory(
     module_file: str | Path,
     all_environment: Mapping[str, str],
+    shared_subpackage_name: str,
+    marker_filename: str,
+    anchor_depth: int,
 ) -> Path:
-    """Return the first process-tree scripts directory that holds the kill helper.
+    """Return the first shared scripts directory that holds the marker file.
 
     ::
 
-        scripts dir is a junction; the kill helper sits beside the un-resolved parent
-        ok:   Path(module_file).absolute().parent.parent then the _shared scripts dir
-        flag: Path(module_file).resolve().parents[1] walks the junction and misses it
+        the managed scripts directory is a junction
+        ok:   an un-resolved parent keeps the link side, where _shared sits
+        flag: a resolved parent walks the link and misses _shared entirely
 
-    Tries the un-resolved parent first, then the configured managed root, then
-    the resolved parent. When none hold the helper, return the un-resolved
-    candidate so import failure names a readable path.
+    Tries the un-resolved parent first, then the configured managed root,
+    then the resolved parent. When none holds the marker, returns the
+    un-resolved candidate, so an import failure names a readable path.
 
     Args:
         module_file: Path of the importing module (``__file__``).
         all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+        shared_subpackage_name: Directory under ``_shared`` to resolve.
+        marker_filename: File whose presence marks the right directory.
+        anchor_depth: Parent levels above the module to treat as the root.
 
     Returns:
-        Directory that should hold ``process_tree_kill.py``.
+        Directory that should hold the marker file.
     """
-    un_resolved_candidate = _process_tree_scripts_directory(
-        Path(module_file).absolute().parent.parent
+    module_path = Path(module_file)
+    un_resolved_candidate = _shared_scripts_directory(
+        module_path.absolute().parents[anchor_depth], shared_subpackage_name
     )
     all_candidates = [un_resolved_candidate]
-    configured_root_text = all_environment.get(
-        CLAUDE_CONFIG_DIR_ENV_VAR, ""
-    ).strip()
+    configured_root_text = all_environment.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
     if configured_root_text:
         all_candidates.append(
-            _process_tree_scripts_directory(Path(configured_root_text))
+            _shared_scripts_directory(Path(configured_root_text), shared_subpackage_name)
         )
     all_candidates.append(
-        _process_tree_scripts_directory(Path(module_file).resolve().parents[1])
+        _shared_scripts_directory(
+            module_path.resolve().parents[anchor_depth], shared_subpackage_name
+        )
     )
     for each_candidate in all_candidates:
-        if _has_process_tree_kill_module(each_candidate):
+        if (each_candidate / marker_filename).is_file():
             return each_candidate
     return un_resolved_candidate
+
+
+def resolve_shared_process_tree_scripts_directory(
+    module_file: str | Path,
+    all_environment: Mapping[str, str],
+) -> Path:
+    """Return the process-tree scripts directory that holds the kill helper.
+
+    Names the process-tree sub-package for a caller sitting one level under
+    the installed root, such as a script in the managed ``scripts`` directory.
+
+    Args:
+        module_file: Path of the importing module (``__file__``).
+        all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+
+    Returns:
+        Directory that should hold ``process_tree_kill.py``.
+    """
+    return resolve_shared_scripts_directory(
+        module_file,
+        all_environment,
+        PROCESS_TREE_DIRECTORY_NAME,
+        PROCESS_TREE_KILL_MODULE_FILENAME,
+        1,
+    )

package/scripts/test_shared_tree_paths.py

@@ -141,3 +141,33 @@ def test_missing_module_returns_unresolved_candidate(tmp_path: Path) -> None:
     assert not (
         expected_scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME
     ).is_file()
+
+
+def test_generalized_resolver_serves_a_deeper_anchor(tmp_path: Path) -> None:
+    """A caller three levels under the root resolves its own sub-package.
+
+    This is the shape the pr-loop and codex-review scripts carry, which the
+    process-tree wrapper's own anchor of one level cannot reach.
+    """
+    installed_root = tmp_path / "root"
+    module_directory = installed_root / "_shared" / "pr-loop" / "scripts"
+    module_directory.mkdir(parents=True)
+    module_file = str(module_directory / "run_codex_review.py")
+    expected_scripts_directory = (
+        installed_root
+        / SHARED_PACKAGE_DIRECTORY_NAME
+        / PROCESS_TREE_DIRECTORY_NAME
+        / SCRIPTS_DIRECTORY_NAME
+    )
+    expected_scripts_directory.mkdir(parents=True)
+    (expected_scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME).write_text(
+        "", encoding="utf-8"
+    )
+    resolved_scripts_directory = shared_tree_paths.resolve_shared_scripts_directory(
+        module_file,
+        {},
+        PROCESS_TREE_DIRECTORY_NAME,
+        PROCESS_TREE_KILL_MODULE_FILENAME,
+        3,
+    )
+    assert resolved_scripts_directory == expected_scripts_directory