claude-dev-env 2.31.1 → 2.32.0

package/hooks/blocking/test_state_description_blocker.py

@@ -29,31 +29,16 @@ from state_description_blocker import (  # noqa: E402
 )
 from state_description_blocker import evaluate as _evaluate_without_opt_in  # noqa: E402
 
+from code_rules_enforcer_test_support import (
+    repository_file_path,
+    repository_root,
+)
+
 HOOK_SCRIPT_PATH = os.path.join(
     os.path.dirname(__file__), "state_description_blocker.py"
 )
 
-_REPOSITORY_ROOT = str(Path(__file__).resolve().parents[4])
-
-
-def _repository_file_path(relative_path: str) -> str:
-    """Return the absolute path of a repository-relative file in this checkout.
-
-    The hook resolves a bare relative path against the process working
-    directory, so a payload carrying one answers to the directory pytest was
-    invoked from. An absolute path under the repository root, paired with a
-    payload ``cwd`` naming that root, keeps the decision stable for a
-    checkout under a temporary root as well.
-
-    Args:
-        relative_path: The path of the target file relative to the repository
-            root.
-
-    Returns:
-        The absolute path of that file inside this repository.
-    """
-    return str(Path(_REPOSITORY_ROOT) / relative_path)
-
+_REPOSITORY_ROOT = str(repository_root())
 
 CLEAN_PYTHON = "x = 1  # Uses a default timeout"
 CLEAN_MD = "# Config\n\nThe API uses port 8080."
@@ -116,7 +101,7 @@ def test_historical_phrase_scan_runs_with_the_env_flag_unset(
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
         is_prose_style_enabled=False,
@@ -127,7 +112,7 @@ def test_historical_phrase_scan_runs_with_the_env_flag_unset(
         {
             "tool_name": "Write",
             "tool_input": {
-                "file_path": _repository_file_path("src/main.py"),
+                "file_path": repository_file_path("src/main.py"),
                 "content": VIOLATION_INSTEAD_OF_COMMENT,
             },
             "cwd": _REPOSITORY_ROOT,
@@ -141,7 +126,7 @@ def test_block_clean_python_comment_passes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": CLEAN_PYTHON,
         },
     )
@@ -153,7 +138,7 @@ def test_block_clean_markdown_passes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("docs/README.md"),
+            "file_path": repository_file_path("docs/README.md"),
             "content": CLEAN_MD,
         },
     )
@@ -165,7 +150,7 @@ def test_block_clean_comment_passes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": CLEAN_COMMENT,
         },
     )
@@ -177,7 +162,7 @@ def test_block_irrelevant_file_passes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("data.txt"),
+            "file_path": repository_file_path("data.txt"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
     )
@@ -189,7 +174,7 @@ def test_block_empty_content_passes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": "",
         },
     )
@@ -213,7 +198,7 @@ def test_detects_instead_of_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
     )
@@ -227,7 +212,7 @@ def test_detects_previously_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": VIOLATION_PREVIOUSLY_COMMENT,
         },
     )
@@ -241,7 +226,7 @@ def test_detects_now_uses_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/client.py"),
+            "file_path": repository_file_path("src/client.py"),
             "content": VIOLATION_NOW_USES_COMMENT,
         },
     )
@@ -255,7 +240,7 @@ def test_detects_instead_of_in_markdown():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("docs/api.md"),
+            "file_path": repository_file_path("docs/api.md"),
             "content": VIOLATION_MD_INSTEAD,
         },
     )
@@ -268,7 +253,7 @@ def test_detects_previously_in_markdown():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("docs/config.md"),
+            "file_path": repository_file_path("docs/config.md"),
             "content": VIOLATION_MD_PREVIOUSLY,
         },
     )
@@ -281,7 +266,7 @@ def test_detects_now_uses_in_markdown():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("docs/auth.md"),
+            "file_path": repository_file_path("docs/auth.md"),
             "content": VIOLATION_MD_NOW_USES,
         },
     )
@@ -307,7 +292,7 @@ def test_detects_edit_new_string():
     result = _run_hook(
         "Edit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "old_string": "old_comment",
             "new_string": VIOLATION_PREVIOUSLY_COMMENT,
         },
@@ -322,7 +307,7 @@ def test_clean_edit_passes():
     result = _run_hook(
         "Edit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "old_string": "x = 1",
             "new_string": CLEAN_PYTHON,
         },
@@ -336,7 +321,7 @@ def test_detects_multi_edit_second_new_string() -> None:
     result = _run_hook(
         "MultiEdit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "edits": [
                 {"old_string": "a = 1", "new_string": CLEAN_PYTHON},
                 {"old_string": "old_comment", "new_string": VIOLATION_PREVIOUSLY_COMMENT},
@@ -353,7 +338,7 @@ def test_clean_multi_edit_passes() -> None:
     result = _run_hook(
         "MultiEdit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "edits": [
                 {"old_string": "a = 1", "new_string": CLEAN_PYTHON},
                 {"old_string": "b = 2", "new_string": CLEAN_COMMENT},
@@ -375,7 +360,7 @@ def test_multi_edit_new_strings_join_on_a_separator_not_concatenation() -> None:
     result = _run_hook(
         "MultiEdit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "edits": [
                 {"old_string": "a = 1", "new_string": "# describes the previous"},
                 {"old_string": "b = 2", "new_string": "ly implemented step."},
@@ -390,7 +375,7 @@ def test_multi_edit_with_a_single_edit_still_denies() -> None:
     result = _run_hook(
         "MultiEdit",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "edits": [{"old_string": "old_comment", "new_string": VIOLATION_PREVIOUSLY_COMMENT}],
         },
     )
@@ -403,7 +388,7 @@ def test_system_message_and_suppress_output():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
     )
@@ -418,7 +403,7 @@ def test_detects_no_longer_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": "# No longer supports legacy mode",
         },
     )
@@ -432,7 +417,7 @@ def test_detects_used_to_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": "# Used to be hardcoded",
         },
     )
@@ -446,7 +431,7 @@ def test_detects_switched_to_in_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": "# Switched to async processing",
         },
     )
@@ -464,7 +449,7 @@ def test_detects_comment_with_close_block_token():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.py"),
+            "file_path": repository_file_path("src/config.py"),
             "content": VIOLATION_COMMENT_WITH_CLOSE_BLOCK,
         },
     )
@@ -481,7 +466,7 @@ def test_detects_inline_trailing_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": "max_retries = 3  # No longer needed since async retry handles it",
         },
     )
@@ -497,7 +482,7 @@ def test_ignores_c_preprocessor_directive():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/config.h"),
+            "file_path": repository_file_path("src/config.h"),
             "content": '#error "This code previously used replaced API"',
         },
     )
@@ -513,7 +498,7 @@ def test_ignores_hash_in_javascript_inline():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.js"),
+            "file_path": repository_file_path("src/main.js"),
             "content": 'const selector = "#originally-dark"  // Use dark as default',
         },
     )
@@ -529,7 +514,7 @@ def test_ignores_double_slash_in_js_url():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/fetch.ts"),
+            "file_path": repository_file_path("src/fetch.ts"),
             "content": 'fetch("https://api.example.com/replaces")',
         },
     )
@@ -545,7 +530,7 @@ def test_block_comment_continuation_with_nested_glob():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/cache.ts"),
+            "file_path": repository_file_path("src/cache.ts"),
             "content": content,
         },
     )
@@ -562,7 +547,7 @@ def test_detects_inline_after_url_on_same_line():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/fetch.ts"),
+            "file_path": repository_file_path("src/fetch.ts"),
             "content": 'const url = "https://api.com"; // no longer used',
         },
     )
@@ -579,7 +564,7 @@ def test_ignores_code_before_block_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/cache.ts"),
+            "file_path": repository_file_path("src/cache.ts"),
             "content": "cache.replaces(old); /* Use fresh cache */",
         },
     )
@@ -595,7 +580,7 @@ def test_ignores_url_with_double_slash_in_python():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": 'url = "https://api.example.com/replaces/v1"',
         },
     )
@@ -610,7 +595,7 @@ def test_ignores_instead_of_in_code_string_with_inline_comment():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": "msg = 'instead of'  # Use the default timeout",
         },
     )
@@ -626,7 +611,7 @@ def test_ignores_glob_pattern_with_star_in_python():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": content,
         },
     )
@@ -642,7 +627,7 @@ def test_ignores_comment_with_glob_pattern():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": content,
         },
     )
@@ -657,7 +642,7 @@ def test_single_line_block_comment_closes():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/cache.ts"),
+            "file_path": repository_file_path("src/cache.ts"),
             "content": content,
         },
     )
@@ -675,7 +660,7 @@ def test_block_comment_with_url_closes_correctly():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/cache.ts"),
+            "file_path": repository_file_path("src/cache.ts"),
             "content": content,
         },
     )
@@ -692,7 +677,7 @@ def test_same_line_block_comment_with_trailing_inline():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/fetch.ts"),
+            "file_path": repository_file_path("src/fetch.ts"),
             "content": content,
         },
     )
@@ -710,7 +695,7 @@ def test_multi_line_block_comment_close_with_trailing_inline():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/cache.ts"),
+            "file_path": repository_file_path("src/cache.ts"),
             "content": content,
         },
     )
@@ -727,7 +712,7 @@ def test_detects_earliest_inline_marker_in_php():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/index.php"),
+            "file_path": repository_file_path("src/index.php"),
             "content": 'echo $x; // previously used #tag',
         },
     )
@@ -741,7 +726,7 @@ def test_additional_context_contains_examples():
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
     )
@@ -789,7 +774,7 @@ def test_handles_non_string_tool_name():
     payload = json.dumps(
         {
             "tool_name": 123,
-            "tool_input": {"file_path": _repository_file_path("src/main.py")},
+            "tool_input": {"file_path": repository_file_path("src/main.py")},
             "cwd": _REPOSITORY_ROOT,
         }
     )
@@ -816,7 +801,7 @@ def test_detects_used_to_in_python_module_docstring() -> None:
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("tests/test_exports.py"),
+            "file_path": repository_file_path("tests/test_exports.py"),
             "content": written_source,
         },
     )
@@ -837,7 +822,7 @@ def test_detects_previously_in_python_function_docstring() -> None:
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/configuration.py"),
+            "file_path": repository_file_path("src/configuration.py"),
             "content": written_source,
         },
     )
@@ -854,7 +839,7 @@ def test_ignores_transitional_phrase_in_regular_python_string() -> None:
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/messages.py"),
+            "file_path": repository_file_path("src/messages.py"),
             "content": 'PADDING_NOTE = "used to pad with a flat sleep"\n',
         },
     )
@@ -873,7 +858,7 @@ def test_ignores_quoted_mention_inside_python_docstring() -> None:
     result = _run_hook(
         "Write",
         {
-            "file_path": _repository_file_path("src/scanner.py"),
+            "file_path": repository_file_path("src/scanner.py"),
             "content": written_source,
         },
     )
@@ -889,7 +874,7 @@ def test_detects_docstring_at_start_of_unparseable_edit_fragment() -> None:
     result = _run_hook(
         "Edit",
         {
-            "file_path": _repository_file_path("src/exports.py"),
+            "file_path": repository_file_path("src/exports.py"),
             "old_string": "placeholder",
             "new_string": fragment,
         },
@@ -911,7 +896,7 @@ def test_detects_docstring_after_def_header_in_unparseable_fragment() -> None:
     result = _run_hook(
         "Edit",
         {
-            "file_path": _repository_file_path("src/reporting.py"),
+            "file_path": repository_file_path("src/reporting.py"),
             "old_string": "placeholder",
             "new_string": fragment,
         },
@@ -930,7 +915,7 @@ def test_ignores_assigned_triple_quoted_string_in_unparseable_fragment() -> None
     result = _run_hook(
         "Edit",
         {
-            "file_path": _repository_file_path("src/fixtures.py"),
+            "file_path": repository_file_path("src/fixtures.py"),
             "old_string": "placeholder",
             "new_string": fragment,
         },
@@ -950,7 +935,7 @@ def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
     deny_payload = {
         "tool_name": "Write",
         "tool_input": {
-            "file_path": _repository_file_path("src/main.py"),
+            "file_path": repository_file_path("src/main.py"),
             "content": VIOLATION_INSTEAD_OF_COMMENT,
         },
         "cwd": _REPOSITORY_ROOT,

package/hooks/blocking/test_tdd_enforcer.py

@@ -1,4 +1,9 @@
-"""Tests for tdd-enforcer hook (blocking behavior)."""
+"""Tests for tdd-enforcer hook (blocking behavior).
+
+Includes the recorded-test-failure evidence path: a genuinely recorded
+failure unlocks a production write, and never unlocks it for a test file
+the failing command did not name.
+"""
 
 import importlib.util
 import io
@@ -1352,6 +1357,67 @@ def test_should_allow_repeat_production_write_within_window_without_further_test
     assert _decision_from(second_write) == "allow"
 
 
+def _seed_recorded_test_failure(
+    test_file: Path, session_id: str, repository_root: Path, command: str, exit_status: int
+) -> None:
+    """Plant a failure record as if a PostToolUse hook had genuinely seen it fail."""
+    content_hash_store.record_test_command_failure(
+        [test_file], command, exit_status, session_id, str(repository_root)
+    )
+
+
+def test_should_allow_production_write_when_recorded_test_failure_matches_content(
+    tmp_path: Path,
+) -> None:
+    """RED evidence outranks a stale mtime: a genuinely recorded failure unlocks GREEN."""
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("def test_fulfill(): assert fulfill() == 1\n")
+    stale_timestamp = time.time() - STALE_MTIME_OFFSET_SECONDS
+    os.utime(sibling_test, (stale_timestamp, stale_timestamp))
+    session_id = "recorded-failure-session"
+    _seed_recorded_test_failure(
+        sibling_test, session_id, sandbox, "pytest test_orders.py", 1
+    )
+
+    completed = _run_hook_with_payload(
+        _make_write_payload_for_session(
+            production_file, "def fulfill(): return 1\n", session_id, sandbox
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_production_write_when_recorded_failure_names_a_different_file(
+    tmp_path: Path,
+) -> None:
+    """Anti-bypass: a failure recorded for one test file must not unlock a sibling's gate."""
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("def test_fulfill(): assert fulfill() == 1\n")
+    stale_timestamp = time.time() - STALE_MTIME_OFFSET_SECONDS
+    os.utime(sibling_test, (stale_timestamp, stale_timestamp))
+    unrelated_test = sandbox / "test_unrelated.py"
+    unrelated_test.write_text("def test_other(): pass\n")
+    session_id = "recorded-failure-unrelated-session"
+    _seed_recorded_test_failure(
+        unrelated_test, session_id, sandbox, "pytest test_unrelated.py", 1
+    )
+
+    completed = _run_hook_with_payload(
+        _make_write_payload_for_session(
+            production_file, "def fulfill(): return 1\n", session_id, sandbox
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
 def test_should_deny_apply_patch_that_adds_test_and_production_file_in_one_transaction(
     tmp_path: Path,
 ) -> None:

package/hooks/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -264,7 +264,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_restore.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/bash_post_call_dispatcher.py",
             "timeout": 60
           }
         ]

package/hooks/hooks_constants/bash_post_call_dispatcher_constants.py

@@ -0,0 +1,22 @@
+"""Constants for the Bash PostToolUse dispatcher.
+
+Holds the ordered hosted-hook roster this dispatcher runs after a Bash call
+finishes. Reuses ``BashHostedHookEntry`` and the Bash-only tool-name set from
+``bash_pre_tool_use_dispatcher_constants`` -- the entry shape and the tool-name
+membership question are identical on the PostToolUse side, so this module adds
+no second copy of either.
+"""
+
+from __future__ import annotations
+
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+    ALL_BASH_ONLY_TOOL_NAMES,
+    BashHostedHookEntry,
+)
+
+__all__ = ["ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES"]
+
+ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
+    BashHostedHookEntry("blocking/gh_pr_author_restore.py", ALL_BASH_ONLY_TOOL_NAMES),
+    BashHostedHookEntry("observability/test_failure_recorder.py", ALL_BASH_ONLY_TOOL_NAMES),
+)

package/hooks/hooks_constants/hosted_hook_runner.py

@@ -13,16 +13,27 @@ blocking the tool call.
     run = run_hook_capturing_output("/hooks/blocking/gate.py", '{"tool_name": "Bash"}')
     ok:   run.captured_stdout carries the gate's deny JSON, run.did_crash is False
     flag: run.did_crash is True when the gate raised, run.captured_stdout is ""
+
+``run_dispatcher_main`` holds the entry-point shell a hosted-hook dispatcher's
+own ``main`` needs: read one stdin payload, resolve its tool_name, and hand
+both to the dispatcher's own ``dispatch`` callback. Every dispatcher's
+``main`` reduces to one call into this shared shell, so the read-resolve-exit
+boilerplate lives in one place rather than once per dispatcher.
 """
 
 from __future__ import annotations
 
 import io
+import json
 import runpy
 import sys
+from pathlib import Path
 import traceback
+from collections.abc import Callable
 from dataclasses import dataclass
 
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
 
 @dataclass
 class HostedHookRun:
@@ -71,3 +82,45 @@ def run_hook_capturing_output(hook_script_path: str, payload_text: str) -> Hoste
     finally:
         sys.stdin, sys.stdout, sys.argv = original_stdin, original_stdout, original_argv
     return HostedHookRun(captured_stdout=captured_output.getvalue(), did_crash=did_crash)
+
+
+def resolved_hook_script_path(relative_path: str) -> str:
+    """Resolve a hooks/-relative path to the absolute script path to run.
+
+    ::
+
+        "observability/test_failure_recorder.py" -> <hooks>/observability/...
+
+    The root comes from this module's own location, so every dispatcher
+    resolves against the same directory however deep it sits.
+
+    Args:
+        relative_path: A path relative to the hooks directory.
+
+    Returns:
+        The absolute path of that script.
+    """
+    hooks_root = Path(__file__).resolve().parent.parent
+    return str(hooks_root / relative_path)
+
+
+def run_dispatcher_main(dispatch: Callable[[str, str], None]) -> None:
+    """Read one stdin payload and hand its JSON text and tool_name to dispatch.
+
+    Every hosted-hook dispatcher's own ``main`` reduces to this one call.
+    Exits 0 before ever calling dispatch when stdin is empty, malformed, or
+    names no tool_name string; always exits 0 afterward, since a dispatcher
+    signals its own outcome, if any, through what dispatch itself writes.
+
+    Args:
+        dispatch: The dispatcher's own ``dispatch(payload_text, tool_name)``.
+    """
+    payload_dictionary = read_hook_input_dictionary_from_stdin()
+    if payload_dictionary is None:
+        sys.exit(0)
+    payload_text = json.dumps(payload_dictionary)
+    tool_name = payload_dictionary.get("tool_name", "")
+    if not isinstance(tool_name, str) or not tool_name:
+        sys.exit(0)
+    dispatch(payload_text, tool_name)
+    sys.exit(0)