claude-dev-env 2.29.0 → 2.30.0

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,12 +17,17 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
+    ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES,
+    ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
+    EDIT_LANE_PHASE,
+    FULL_GATE_PHASE,
     FUNCTION_WITH_JSDOC_PATTERN,
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
+    UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
 )
 
 
@@ -98,3 +103,19 @@ def test_schema_property_key_pattern_matches_only_the_options_key() -> None:
 def test_constants_module_suffix_and_config_directory_segment_are_defined() -> None:
     assert CONSTANTS_MODULE_SUFFIX == "_constants.py"
     assert CONFIG_DIRECTORY_SEGMENT == "config"
+
+
+def test_validation_phase_constants_are_reexported_and_render() -> None:
+    assert ALL_VALIDATION_PHASES == {EDIT_LANE_PHASE, FULL_GATE_PHASE}
+    rendered_message = UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE.format(
+        phase="bogus_phase", all_phases=sorted(ALL_VALIDATION_PHASES)
+    )
+    assert "bogus_phase" in rendered_message
+
+
+def test_hook_infrastructure_edit_lane_check_names_are_reexported() -> None:
+    assert ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES == {
+        "check_same_file_inline_duplicate_body",
+        "check_zero_payload_function_alias",
+        "check_unanchored_command_dispatch",
+    }

package/hooks/hooks_constants/validation_phase_constants.py

@@ -0,0 +1,34 @@
+"""Constants for the validate_content edit-lane and full-gate phase split.
+
+The edit lane and the full gate share every check except six that read
+sibling modules from disk. These names identify each phase, name the checks
+the full gate alone runs, name the hook-infrastructure checks the edit lane
+still runs, and template the error for an unrecognized phase.
+"""
+
+EDIT_LANE_PHASE: str = "edit_lane"
+FULL_GATE_PHASE: str = "full_gate"
+ALL_VALIDATION_PHASES: frozenset[str] = frozenset({EDIT_LANE_PHASE, FULL_GATE_PHASE})
+
+ALL_FULL_GATE_ONLY_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_duplicate_function_body_across_files",
+        "advise_cross_skill_duplicate_helper",
+        "check_public_function_missing_paired_test",
+        "check_test_file_omits_module_public_function",
+        "check_orphan_css_classes",
+        "check_config_duplicate_path_anchor",
+    }
+)
+
+ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_same_file_inline_duplicate_body",
+        "check_zero_payload_function_alias",
+        "check_unanchored_command_dispatch",
+    }
+)
+
+UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE: str = (
+    "unrecognized validation phase {phase!r}; expected one of {all_phases}"
+)

package/hooks/validators/README.md

@@ -2,7 +2,7 @@
 
 AST-based Python style checks for code quality enforcement.
 
-The checks live in `python_style_checks.py`; the shared source-line splitting and function-discovery helpers they build on live in `python_style_helpers.py`.
+The checks live in `python_style_checks.py`; the shared source-line splitting and function-discovery helpers they build on live in `python_style_helpers.py`. `hook_timing_harness.py` measures real wall-clock time for the Write/Edit hooks `hooks.json` registers, reporting p50 and p95 over a configurable run count.
 
 ## Checks Implemented
 

package/hooks/validators/config/hook_timing_harness_constants.py

@@ -0,0 +1,16 @@
+"""Constants for hook_timing_harness.py.
+
+Extracted to satisfy the constants-location rule: production constants outside
+``config/`` move here rather than sitting at module scope in the harness.
+"""
+
+DEFAULT_RUN_COUNT = 7
+P50_FRACTION = 0.50
+P95_FRACTION = 0.95
+DEFAULT_TARGET_RELATIVE_PATH = "hooks/blocking/code_rules_shared.py"
+SUBPROCESS_TIMEOUT_SECONDS = 60.0
+ALL_WRITE_EDIT_MATCHER_PATTERNS = frozenset({"Write|Edit", "Write|Edit|MultiEdit"})
+ALL_TIMED_EVENT_NAMES = ("PreToolUse", "PostToolUse")
+RUN_ALL_VALIDATORS_LABEL = "run_all_validators"
+CLAUDE_PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"
+PARENT_LEVELS_TO_PACKAGE_ROOT = 2

package/hooks/validators/hook_timing_harness.py

@@ -0,0 +1,287 @@
+"""Measure real wall-clock time for the hooks.json-registered Write/Edit hooks.
+
+Each timed command is the literal ``hooks.json`` command string with
+``${CLAUDE_PLUGIN_ROOT}`` resolved to the real package root, run as its own
+subprocess against a real repository file, timed over a configurable run
+count, and reported as p50 and p95 milliseconds.
+
+::
+
+    $ python3 hook_timing_harness.py --runs 7
+    run_all_validators         p50=1948.3ms  p95=3020.1ms
+    pre_tool_use_dispatcher    p50=180.2ms   p95=230.4ms
+    post_tool_use_dispatcher   p50=80.1ms    p95=1200.5ms
+    session_file_edit_tracker  p50=31.0ms    p95=34.2ms
+
+A target under the OS temp root would return before any validator ran, so this
+harness refuses one. It always runs the whole command line ``hooks.json``
+registers, never a single hosted check module standing in for it, so neither
+shortcut can distort the numbers.
+
+The timed payload carries no ``session_id``, so ``session_file_edit_tracker``
+writes its edit record to the default-session file rather than to a
+caller-specific one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+from types import ModuleType
+from typing import TextIO
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name.
+
+    Loads by absolute path rather than a package-qualified import, so this
+    harness resolves its own constants module the same way whether it runs
+    standalone (``python3 hook_timing_harness.py``) or loaded by a test —
+    neither invocation shape needs ``hooks/validators`` on ``sys.path``.
+    """
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_harness_constants = _load_module_from_path(
+    "hook_timing_harness_constants",
+    Path(__file__).resolve().parent / "config" / "hook_timing_harness_constants.py",
+)
+_system_temporary_roots = _load_module_from_path(
+    "hook_timing_harness_system_temporary_roots",
+    Path(__file__).resolve().parent / "system_temporary_roots.py",
+)
+
+
+def _hook_label_for_command(command: str) -> str:
+    """Return the short name a wall-time report row uses for one hook command.
+
+    ::
+
+        'python3 .../pre_tool_use_dispatcher.py'      -> 'pre_tool_use_dispatcher'
+        'python3 -c "... run_all_validators ..." ...' -> 'run_all_validators'
+    """
+    if _harness_constants.RUN_ALL_VALIDATORS_LABEL in command:
+        return _harness_constants.RUN_ALL_VALIDATORS_LABEL
+    script_basename_pattern = re.compile(r"([A-Za-z0-9_]+)\.py")
+    all_basename_matches = script_basename_pattern.findall(command)
+    if not all_basename_matches:
+        raise ValueError(f"cannot derive a hook label from command: {command!r}")
+    return all_basename_matches[-1]
+
+
+def _commands_in_matcher_group(all_matcher_group: dict[str, object]) -> list[tuple[str, str]]:
+    """Return the (label, command) pairs one hooks.json matcher group registers."""
+    if all_matcher_group.get("matcher") not in _harness_constants.ALL_WRITE_EDIT_MATCHER_PATTERNS:
+        return []
+    all_hosted_hooks = all_matcher_group.get("hooks", [])
+    if not isinstance(all_hosted_hooks, list):
+        return []
+    all_commands: list[tuple[str, str]] = []
+    for each_hook in all_hosted_hooks:
+        command = each_hook.get("command", "") if isinstance(each_hook, dict) else ""
+        all_commands.append((_hook_label_for_command(command), command))
+    return all_commands
+
+
+def write_edit_hook_commands(hooks_json_path: Path) -> list[tuple[str, str]]:
+    """Return the (label, command) pairs hooks.json registers for Write/Edit.
+
+    Reads the real ``PreToolUse`` and ``PostToolUse`` sections and keeps only
+    the matcher groups that fire on a Write or Edit tool call, so the harness
+    times the same roster a live edit exercises rather than every hook in the
+    file (session, lifecycle, and Bash-only hooks included).
+
+    Args:
+        hooks_json_path: Path to the ``hooks.json`` file to read.
+
+    Returns:
+        One ``(label, command)`` pair per Write/Edit-matching hook, in the
+        file's own declaration order.
+    """
+    hooks_document = json.loads(hooks_json_path.read_text(encoding="utf-8"))
+    all_commands: list[tuple[str, str]] = []
+    for each_event_name in _harness_constants.ALL_TIMED_EVENT_NAMES:
+        for each_matcher_group in hooks_document["hooks"].get(each_event_name, []):
+            all_commands.extend(_commands_in_matcher_group(each_matcher_group))
+    return all_commands
+
+
+def _is_under_directory(candidate: Path, directory: Path) -> bool:
+    """Return whether *candidate* equals *directory* or sits under it."""
+    return candidate == directory or directory in candidate.parents
+
+
+def ensure_real_repository_target(
+    target_path: Path, repository_root: Path | None = None
+) -> Path:
+    """Return *target_path* resolved, after refusing an ephemeral scratch path.
+
+    A target under a system temporary root (``tempfile.gettempdir()`` plus any
+    set ``TEMP`` / ``TMP`` / ``TMPDIR`` / ``RUNNER_TEMP``) trips
+    ``is_ephemeral_path`` inside the hooks and returns before any validator
+    runs. A target inside *repository_root* is always real, even when the
+    checkout itself sits under a system temporary root.
+
+    Raises:
+        ValueError: When the path sits under a system temporary root and
+            outside *repository_root*.
+    """
+    resolved_target = target_path.resolve()
+    if repository_root is not None and _is_under_directory(
+        resolved_target, repository_root.resolve()
+    ):
+        return resolved_target
+    enclosing_temporary_root = _system_temporary_roots.enclosing_system_temporary_root(
+        resolved_target
+    )
+    if enclosing_temporary_root is None:
+        return resolved_target
+    raise ValueError(
+        f"refusing an ephemeral timing target under {enclosing_temporary_root}: "
+        f"{resolved_target}"
+    )
+
+
+def _write_tool_payload(target_path: Path) -> str:
+    """Build a Write-tool PreToolUse/PostToolUse payload naming *target_path*."""
+    return json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": str(target_path),
+                "content": target_path.read_text(encoding="utf-8"),
+            },
+        }
+    )
+
+
+def run_hosted_command_once_milliseconds(
+    command_template: str, package_root: Path, payload_text: str
+) -> float:
+    """Run one registered hooks.json command once and return its wall time.
+
+    Args:
+        command_template: The ``hooks.json`` command string, ``${CLAUDE_PLUGIN_ROOT}``
+            still unresolved.
+        package_root: The real package root ``${CLAUDE_PLUGIN_ROOT}`` resolves to.
+        payload_text: The JSON payload piped to the command's stdin.
+
+    Returns:
+        The wall-clock time the subprocess took, in milliseconds.
+    """
+    resolved_command = command_template.replace(
+        _harness_constants.CLAUDE_PLUGIN_ROOT_PLACEHOLDER, str(package_root)
+    )
+    started_at = time.perf_counter()
+    subprocess.run(
+        resolved_command,
+        shell=True,
+        input=payload_text,
+        capture_output=True,
+        text=True,
+        timeout=_harness_constants.SUBPROCESS_TIMEOUT_SECONDS,
+        check=False,
+    )
+    finished_at = time.perf_counter()
+    return (finished_at - started_at) * 1000.0
+
+
+def percentile(
+    all_sorted_wall_times_milliseconds: list[float], fraction: float
+) -> float:
+    """Return the nearest-rank percentile of an already-sorted sample.
+
+    ::
+
+        percentile([10, 20, 30, 40, 50, 60, 70], 0.95) -> 70  (rank 7 of 7)
+        percentile([10, 20, 30, 40, 50, 60, 70], 0.50) -> 40  (rank 4 of 7)
+
+    Args:
+        all_sorted_wall_times_milliseconds: Ascending wall-time samples.
+        fraction: The percentile as a fraction between 0 and 1.
+
+    Returns:
+        The nearest-rank percentile value.
+
+    Raises:
+        ValueError: When the sample is empty.
+    """
+    if not all_sorted_wall_times_milliseconds:
+        raise ValueError("cannot compute a percentile of an empty sample")
+    sample_size = len(all_sorted_wall_times_milliseconds)
+    rank_index = math.ceil(fraction * sample_size) - 1
+    return all_sorted_wall_times_milliseconds[max(0, min(rank_index, sample_size - 1))]
+
+
+def measure_hosted_command_wall_times(
+    hooks_json_path: Path,
+    package_root: Path,
+    target_path: Path,
+    run_count: int,
+    *,
+    repository_root: Path | None = None,
+) -> dict[str, list[float]]:
+    """Time every Write/Edit hooks.json command over *run_count* runs each.
+
+    ``repository_root`` is the root ``ensure_real_repository_target`` judges
+    ephemerality against; it defaults to ``package_root``.
+    """
+    real_target = ensure_real_repository_target(
+        target_path, repository_root if repository_root is not None else package_root
+    )
+    payload_text = _write_tool_payload(real_target)
+    all_wall_times_by_label: dict[str, list[float]] = {}
+    for each_label, each_command_template in write_edit_hook_commands(hooks_json_path):
+        all_wall_times_by_label[each_label] = [
+            run_hosted_command_once_milliseconds(each_command_template, package_root, payload_text)
+            for _ in range(run_count)
+        ]
+    return all_wall_times_by_label
+
+
+def _report_line(label: str, all_wall_times_milliseconds: list[float]) -> str:
+    sorted_wall_times_milliseconds = sorted(all_wall_times_milliseconds)
+    p50 = percentile(sorted_wall_times_milliseconds, _harness_constants.P50_FRACTION)
+    p95 = percentile(sorted_wall_times_milliseconds, _harness_constants.P95_FRACTION)
+    return f"{label:<26} p50={p50:.1f}ms  p95={p95:.1f}ms"
+
+
+def main(
+    all_arguments: list[str],
+    report_stream: TextIO = sys.stdout,
+    repository_root: Path | None = None,
+) -> int:
+    """Run the harness CLI; report_stream and repository_root are injectable seams."""
+    package_root = Path(__file__).resolve().parents[
+        _harness_constants.PARENT_LEVELS_TO_PACKAGE_ROOT
+    ]
+    hooks_json_path = Path(__file__).resolve().parent.parent / "hooks.json"
+    default_target_path = package_root / _harness_constants.DEFAULT_TARGET_RELATIVE_PATH
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--runs", type=int, default=_harness_constants.DEFAULT_RUN_COUNT)
+    parser.add_argument("--target", type=Path, default=default_target_path)
+    arguments = parser.parse_args(all_arguments)
+    effective_repository_root = repository_root if repository_root is not None else package_root
+    all_wall_times_by_label = measure_hosted_command_wall_times(
+        hooks_json_path, package_root, arguments.target, arguments.runs,
+        repository_root=effective_repository_root,
+    )
+    for each_label, each_wall_times in all_wall_times_by_label.items():
+        report_stream.write(_report_line(each_label, each_wall_times) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/hooks/validators/test_hook_timing_harness.py

@@ -0,0 +1,251 @@
+"""Tests for hook_timing_harness.py."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import sys
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name."""
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_VALIDATORS_DIRECTORY = Path(__file__).resolve().parent
+_PACKAGE_ROOT = _VALIDATORS_DIRECTORY.parents[1]
+_HOOKS_JSON_PATH = _VALIDATORS_DIRECTORY.parent / "hooks.json"
+_REAL_TARGET_FILE = _PACKAGE_ROOT / "hooks" / "blocking" / "code_rules_shared.py"
+
+if str(_VALIDATORS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_VALIDATORS_DIRECTORY))
+hook_timing_harness = _load_module_from_path(
+    "hook_timing_harness", _VALIDATORS_DIRECTORY / "hook_timing_harness.py"
+)
+
+
+def test_hook_label_for_command_names_run_all_validators() -> None:
+    command = (
+        'python3 -c "import sys; from validators.run_all_validators import main; '
+        'sys.exit(main())" --pre-tool-use'
+    )
+    assert hook_timing_harness._hook_label_for_command(command) == "run_all_validators"
+
+
+def test_hook_label_for_command_names_the_script_basename() -> None:
+    command = "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py"
+    assert hook_timing_harness._hook_label_for_command(command) == "pre_tool_use_dispatcher"
+
+
+def test_write_edit_hook_commands_reads_the_real_hooks_json_roster() -> None:
+    all_commands = hook_timing_harness.write_edit_hook_commands(_HOOKS_JSON_PATH)
+    all_labels = [each_label for each_label, _each_command in all_commands]
+    assert all_labels == [
+        "run_all_validators",
+        "pre_tool_use_dispatcher",
+        "post_tool_use_dispatcher",
+        "session_file_edit_tracker",
+    ]
+
+
+def test_percentile_returns_the_nearest_rank_value() -> None:
+    sample = [10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0]
+    assert hook_timing_harness.percentile(sample, 0.50) == 40.0
+    assert hook_timing_harness.percentile(sample, 0.95) == 70.0
+
+
+def test_percentile_raises_on_an_empty_sample() -> None:
+    with pytest.raises(ValueError):
+        hook_timing_harness.percentile([], 0.50)
+
+
+def test_ensure_real_repository_target_refuses_an_os_temp_path(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("TMPDIR", str(tmp_path))
+    ephemeral_target = Path(tempfile.gettempdir()) / "scratch.py"
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(ephemeral_target)
+
+
+def test_ensure_real_repository_target_accepts_a_real_repository_file() -> None:
+    resolved = hook_timing_harness.ensure_real_repository_target(
+        _REAL_TARGET_FILE, _PACKAGE_ROOT
+    )
+    assert resolved == _REAL_TARGET_FILE.resolve()
+
+
+def test_ensure_real_repository_target_accepts_a_repo_file_under_the_os_temp_root(
+    tmp_path: Path,
+) -> None:
+    """A checkout placed under the OS temp root still accepts its own real files.
+
+    Ephemerality is judged relative to the given repository root, not the OS
+    temp root alone, so a checkout that itself sits under the OS temp root (a
+    common sandbox layout) does not misclassify every real file inside it as
+    a throwaway scratch target.
+    """
+    repository_root = tmp_path / "repo"
+    real_file = repository_root / "hooks" / "blocking" / "code_rules_shared.py"
+    real_file.parent.mkdir(parents=True)
+    real_file.write_text("x = 1\n", encoding="utf-8")
+
+    resolved = hook_timing_harness.ensure_real_repository_target(real_file, repository_root)
+
+    assert resolved == real_file.resolve()
+
+
+def test_ensure_real_repository_target_refuses_a_scratch_path_outside_the_repository_root(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    scratch_target = tmp_path / "scratch.py"
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(scratch_target, repository_root)
+
+
+def test_ensure_real_repository_target_refuses_a_path_under_runner_temp_alone(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """GitHub Actions puts pytest basetemp under RUNNER_TEMP, not gettempdir().
+
+    ``gettempdir()`` stays ``/tmp`` on the hosted runner while pytest's own
+    ``tmp_path`` lives under ``RUNNER_TEMP`` (``/home/runner/work/_temp``), a
+    directory ``gettempdir()`` never reports. A refusal that judges
+    ephemerality against ``gettempdir()`` alone misses that target and reads
+    the runner's own scratch file as a real repository file.
+    """
+    fake_os_temporary_root = tmp_path / "os-temp"
+    fake_os_temporary_root.mkdir()
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(fake_os_temporary_root))
+    runner_temporary_root = tmp_path / "runner-temp"
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temporary_root))
+    ephemeral_target = runner_temporary_root / "scratch.py"
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.ensure_real_repository_target(ephemeral_target)
+
+
+def test_run_hosted_command_once_milliseconds_drives_the_real_tracker() -> None:
+    """A live subprocess run against a real repository file measures a positive time.
+
+    ::
+
+        session_file_edit_tracker is the fastest hosted command, so this is the
+        cheap live end-to-end proof: it drives the actual registered
+        ``hooks.json`` command line, not a standalone hosted check module.
+    """
+    all_commands = hook_timing_harness.write_edit_hook_commands(_HOOKS_JSON_PATH)
+    tracker_command = next(
+        each_command
+        for each_label, each_command in all_commands
+        if each_label == "session_file_edit_tracker"
+    )
+    payload_text = hook_timing_harness._write_tool_payload(_REAL_TARGET_FILE)
+    elapsed_milliseconds = hook_timing_harness.run_hosted_command_once_milliseconds(
+        tracker_command, _PACKAGE_ROOT, payload_text
+    )
+    assert 0.0 < elapsed_milliseconds < 5000.0
+
+
+def test_measure_hosted_command_wall_times_covers_the_real_roster() -> None:
+    """A live run against the real hooks.json roster returns all four hooks.
+
+    Runs each registered command once against a real repository file,
+    including ``run_all_validators``, so this is the one place the suite pays
+    its full wall time to prove the roster end to end.
+    """
+    all_wall_times_by_label = hook_timing_harness.measure_hosted_command_wall_times(
+        _HOOKS_JSON_PATH, _PACKAGE_ROOT, _REAL_TARGET_FILE, 1
+    )
+    assert set(all_wall_times_by_label) == {
+        "run_all_validators",
+        "pre_tool_use_dispatcher",
+        "post_tool_use_dispatcher",
+        "session_file_edit_tracker",
+    }
+    assert all(
+        each_time > 0.0
+        for each_times in all_wall_times_by_label.values()
+        for each_time in each_times
+    )
+
+
+def test_measure_hosted_command_wall_times_honors_a_repository_root_override(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """The wrapper forwards repository_root to the delegate, not just accepts it.
+
+    ``ensure_real_repository_target`` already accepts ``repository_root``, but
+    until the wrapper's own signature exposes and forwards it, no caller of
+    ``measure_hosted_command_wall_times`` can reach that parameter — the exact
+    gap the wrapper-plumb-through check caught.
+    """
+    monkeypatch.setattr(hook_timing_harness, "write_edit_hook_commands", lambda path: [])
+    repository_root = tmp_path / "repo"
+    real_file = repository_root / "hooks" / "blocking" / "code_rules_shared.py"
+    real_file.parent.mkdir(parents=True)
+    real_file.write_text("x = 1\n", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="ephemeral"):
+        hook_timing_harness.measure_hosted_command_wall_times(
+            _HOOKS_JSON_PATH, _PACKAGE_ROOT, real_file, 1
+        )
+
+    all_wall_times_by_label = hook_timing_harness.measure_hosted_command_wall_times(
+        _HOOKS_JSON_PATH, _PACKAGE_ROOT, real_file, 1, repository_root=repository_root
+    )
+    assert all_wall_times_by_label == {}
+
+
+def test_main_writes_one_report_line_per_label(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_wall_times_by_label = {"pre_tool_use_dispatcher": [100.0, 200.0]}
+    monkeypatch.setattr(
+        hook_timing_harness,
+        "measure_hosted_command_wall_times",
+        lambda *args, **kwargs: fake_wall_times_by_label,
+    )
+    report_stream = io.StringIO()
+    exit_code = hook_timing_harness.main(["--runs", "2"], report_stream=report_stream)
+    report_text = report_stream.getvalue()
+    assert exit_code == 0
+    assert "pre_tool_use_dispatcher" in report_text
+    assert "p50=" in report_text and "p95=" in report_text
+
+
+def test_main_forwards_its_own_repository_root_to_the_wrapper(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """main() forwards a caller-supplied repository_root, not just accepts it.
+
+    Mirrors the wrapper-level gap: adding ``repository_root`` to
+    ``measure_hosted_command_wall_times`` alone leaves ``main`` as a second
+    wrapper dropping the same optional keyword.
+    """
+    all_captured_kwargs: dict[str, object] = {}
+
+    def _spy_measure_hosted_command_wall_times(*args: object, **kwargs: object) -> dict[str, list[float]]:
+        all_captured_kwargs.update(kwargs)
+        return {}
+
+    monkeypatch.setattr(
+        hook_timing_harness,
+        "measure_hosted_command_wall_times",
+        _spy_measure_hosted_command_wall_times,
+    )
+    override_root = tmp_path / "repo"
+    exit_code = hook_timing_harness.main([], repository_root=override_root)
+    assert exit_code == 0
+    assert all_captured_kwargs.get("repository_root") == override_root

package/package.json

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