claude-dev-env 2.18.0 → 2.19.0

package/hooks/blocking/test_pii_scanner.py

@@ -61,6 +61,87 @@ def test_flags_unix_home_path() -> None:
     assert any(each.category == "home-path" for each in all_unix_hits)
 
 
+def test_flags_raw_escaped_windows_home_path() -> None:
+    all_home_hits = scan_text_for_pii(r"path is C:\\Users\\concrete-user\\file")
+    assert [each.matched_text for each in all_home_hits] == [
+        r"C:\\Users\\concrete-user"
+    ]
+
+
+def test_flags_unc_windows_home_path_at_each_share_depth() -> None:
+    all_home_hits = scan_text_for_pii(
+        r"path is \\server\Users\concrete-user\file"
+        "\n"
+        r"path is \\server name\My Share\Users\other-user\file"
+    )
+    assert [each.matched_text for each in all_home_hits] == [
+        r"\\server\Users\concrete-user",
+        r"\\server name\My Share\Users\other-user",
+    ]
+
+
+def test_flags_forward_slash_unc_home_paths() -> None:
+    all_home_hits = scan_text_for_pii(
+        "path is //server/Users/concrete-user/file"
+        "\n"
+        "path is //server/share/Users/other-user/file"
+    )
+    assert [each.matched_text for each in all_home_hits] == [
+        "//server/Users/concrete-user",
+        "//server/share/Users/other-user",
+    ]
+
+
+def test_allows_http_urls_with_users_segments() -> None:
+    all_home_hits = scan_text_for_pii(
+        "https://docs-7.example.com/Users/concrete-user/file"
+    ) + scan_text_for_pii("http://server-2/share/Users/concrete-user/file")
+    assert all_home_hits == []
+
+
+def test_allows_http_urls_with_home_segments() -> None:
+    assert scan_text_for_pii("https://home/user/file") == []
+    assert scan_text_for_pii("https://Users/user/file") == []
+    assert scan_text_for_pii("https://[::1]/home/user/file") == []
+    assert scan_text_for_pii("https://[2001:db8::1]/Users/user/file") == []
+    assert scan_text_for_pii("https://docs-7.example.com/home/concrete-user/file") == []
+
+
+def test_flags_absolute_and_file_uri_home_paths() -> None:
+    all_home_hits = scan_text_for_pii("path is /home/concrete-user/file")
+    all_home_hits += scan_text_for_pii("path is file:///home/concrete-user/file")
+    all_home_hits += scan_text_for_pii("path is file://server/home/concrete-user/file")
+    all_home_hits += scan_text_for_pii("path is FILE://server/home/other-user/file")
+    all_home_hits += scan_text_for_pii(
+        "path is FILE://server/share/home/third-user/file"
+    )
+    assert [each.matched_text for each in all_home_hits] == [
+        "/home/concrete-user",
+        "file:///home/concrete-user",
+        "file://server/home/concrete-user",
+        "FILE://server/home/other-user",
+        "FILE://server/share/home/third-user",
+    ]
+
+
+def test_flags_file_uri_home_path() -> None:
+    all_home_hits = scan_text_for_pii(
+        "path is file:///Users/concrete-user/file"
+        "\n"
+        "path is file://server/Users/concrete-user/file"
+        "\n"
+        "path is FILE:///Users/other-user/file"
+        "\n"
+        "path is FILE://server/share/Users/third-user/file"
+    )
+    assert [each.matched_text for each in all_home_hits] == [
+        "file:///Users/concrete-user",
+        "file://server/Users/concrete-user",
+        "FILE:///Users/other-user",
+        "FILE://server/share/Users/third-user",
+    ]
+
+
 def test_flags_private_ip_and_allows_public_ip() -> None:
     all_lan_hits = scan_text_for_pii(f"host {SYNTHETIC_PRIVATE_IP}")
     all_dns_hits = scan_text_for_pii(f"dns {SYNTHETIC_PUBLIC_IP}")

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -42,6 +42,7 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402, I
 from pre_tool_use_dispatcher import (  # noqa: E402, I001
     DispatcherDecision,
     HostedHookResult,
+    _emit_allow_decision,
     _emit_deny_decision,
     aggregate_hosted_hook_results,
     run_hosted_hook,
@@ -649,6 +650,28 @@ def test_emit_deny_does_not_cross_collapse_reason_and_context(
     assert parsed["hookSpecificOutput"]["additionalContext"] == shared_text
 
 
+def test_emit_allow_preserves_system_message_and_additional_context(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """An allow payload carries the advisory's system and context messages."""
+    decision = DispatcherDecision(
+        should_deny=False,
+        should_allow=True,
+        all_deny_reasons=[],
+        all_system_messages=["system-a", "system-b"],
+        all_additional_context=["context-a", "context-b"],
+        should_suppress_output=False,
+    )
+
+    _emit_allow_decision(decision)
+
+    parsed = json.loads(capsys.readouterr().out)
+    hook_specific = parsed["hookSpecificOutput"]
+    assert hook_specific["permissionDecision"] == "allow"
+    assert hook_specific["additionalContext"] == "context-a\ncontext-b"
+    assert parsed["systemMessage"] == "system-a\nsystem-b"
+
+
 def test_later_hook_deny_survives_early_hook_exit() -> None:
     """Dispatcher denies even when an earlier hook exits cleanly before a later hook denies.
 
@@ -698,10 +721,16 @@ def test_dispatcher_edit_applies_both_groups() -> None:
 
 
 def test_dispatcher_multi_edit_applies_only_group_b() -> None:
-    """MultiEdit tool triggers only Group B (8 hooks), not Group A."""
+    """MultiEdit applies to 9 hosted Group-B hooks, including the sensitive protector."""
     all_multi_edit_entries = _applicable_entries_for_tool(MULTI_EDIT_TOOL_NAME)
-    assert len(all_multi_edit_entries) == 8, (
-        f"MultiEdit tool must apply to exactly 8 Group-B hooks, got {len(all_multi_edit_entries)}"
+    all_multi_edit_script_paths = {
+        each_entry.script_relative_path for each_entry in all_multi_edit_entries
+    }
+    assert "blocking/sensitive_file_protector.py" in all_multi_edit_script_paths, (
+        "sensitive_file_protector belongs in the MultiEdit applicable set"
+    )
+    assert len(all_multi_edit_entries) == 9, (
+        f"MultiEdit tool must apply to exactly 9 Group-B hooks, got {len(all_multi_edit_entries)}"
     )
 
 

package/hooks/blocking/test_precommit_code_rules_gate.py

@@ -1,8 +1,8 @@
-"""Behavior tests for the precommit_code_rules_gate PreToolUse hook.
+"""Behavior tests for the pass-through precommit_code_rules_gate hook.
 
 Each test builds a real git repository in a temporary directory, stages
 real files, and runs the hook script as a subprocess with a PreToolUse
-JSON payload on stdin — the exact production invocation path.
+JSON payload on stdin through the exact production invocation path.
 """
 
 import json
@@ -140,10 +140,6 @@ def run_hook(bash_command: str, working_directory: Path) -> subprocess.Completed
     )
 
 
-def parse_denial(hook_stdout: str) -> dict:
-    return json.loads(hook_stdout)["hookSpecificOutput"]
-
-
 def test_non_commit_command_passes_through(tmp_path: Path) -> None:
     initialize_repository(tmp_path)
     completed_hook = run_hook("git status", tmp_path)
@@ -157,20 +153,19 @@ def test_commit_with_clean_staged_python_file_is_allowed(tmp_path: Path) -> None
     completed_hook = run_hook("git commit -m add", tmp_path)
     assert completed_hook.returncode == 0
     assert completed_hook.stdout.strip() == ""
+    assert "Git commit proceeds to configured Git hooks." in completed_hook.stderr
 
 
-def test_commit_with_violating_staged_file_is_blocked(tmp_path: Path) -> None:
+def test_commit_with_staged_python_file_passes_through(tmp_path: Path) -> None:
     initialize_repository(tmp_path)
     stage_file(tmp_path, "totals.py", VIOLATING_MODULE_SOURCE)
     completed_hook = run_hook("git commit -m add", tmp_path)
     assert completed_hook.returncode == 0
-    denial = parse_denial(completed_hook.stdout)
-    assert denial["permissionDecision"] == "deny"
-    assert "totals.py" in denial["permissionDecisionReason"]
-    assert "Line" in denial["permissionDecisionReason"]
+    assert completed_hook.stdout.strip() == ""
+    assert "Git commit proceeds to configured Git hooks." in completed_hook.stderr
 
 
-def test_git_dash_c_commit_form_is_blocked(tmp_path: Path) -> None:
+def test_git_dash_c_commit_form_passes_through(tmp_path: Path) -> None:
     repository_root = tmp_path / "repo"
     repository_root.mkdir()
     initialize_repository(repository_root)
@@ -180,9 +175,8 @@ def test_git_dash_c_commit_form_is_blocked(tmp_path: Path) -> None:
     quoted_root = str(repository_root)
     completed_hook = run_hook(f'git -C "{quoted_root}" commit -m add', elsewhere)
     assert completed_hook.returncode == 0
-    denial = parse_denial(completed_hook.stdout)
-    assert denial["permissionDecision"] == "deny"
-    assert "totals.py" in denial["permissionDecisionReason"]
+    assert completed_hook.stdout.strip() == ""
+    assert "Git commit proceeds to configured Git hooks." in completed_hook.stderr
 
 
 def test_commit_with_no_staged_python_files_is_allowed(tmp_path: Path) -> None:
@@ -193,7 +187,7 @@ def test_commit_with_no_staged_python_files_is_allowed(tmp_path: Path) -> None:
     assert completed_hook.stdout.strip() == ""
 
 
-def test_worktree_commit_reads_worktree_paired_tests_not_sibling_checkout(
+def test_worktree_commit_passes_through(
     tmp_path: Path,
 ) -> None:
     main_checkout = tmp_path / "main_checkout"
@@ -213,3 +207,4 @@ def test_worktree_commit_reads_worktree_paired_tests_not_sibling_checkout(
     )
     assert completed_hook.returncode == 0
     assert completed_hook.stdout.strip() == ""
+    assert "Git commit proceeds to configured Git hooks." in completed_hook.stderr

package/hooks/blocking/test_precommit_code_rules_gate_native_owner.py

@@ -0,0 +1,168 @@
+"""Production-path tests for native staged-gate ownership.
+
+The tests run the Agent Bash dispatcher and a native Git pre-commit hook against
+the same isolated repository. The agent path passes the commit through. The
+native path runs the staged gate and controls the commit.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+HOOKS_ROOT = Path(__file__).resolve().parent.parent
+BLOCKING_ROOT = HOOKS_ROOT / "blocking"
+GIT_HOOKS_ROOT = HOOKS_ROOT / "git-hooks"
+PRE_COMMIT_SOURCE_PATH = GIT_HOOKS_ROOT / "pre_commit.py"
+GATE_UTILS_SOURCE_PATH = GIT_HOOKS_ROOT / "gate_utils.py"
+GIT_HOOKS_CONSTANTS_SOURCE_PATH = GIT_HOOKS_ROOT / "git_hooks_constants"
+DISPATCHER_SOURCE_PATH = BLOCKING_ROOT / "bash_pre_tool_use_dispatcher.py"
+GIT_COMMAND_TIMEOUT_SECONDS = 60
+CLEAN_MODULE_SOURCE = "def add_one(number: int) -> int:\n    return number + 1\n"
+
+
+def run_git(
+    repository_root: Path,
+    *git_arguments: str,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run one isolated Git command and return its captured process record."""
+    return subprocess.run(
+        ["git", *git_arguments],
+        cwd=str(repository_root),
+        check=check,
+        capture_output=True,
+        text=True,
+        timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+    )
+
+
+def initialize_repository(repository_root: Path) -> None:
+    """Create a repository with one committed base file and no active hook."""
+    run_git(repository_root, "init")
+    run_git(repository_root, "config", "user.name", "Hook Test")
+    run_git(repository_root, "config", "user.email", "hook-test@example.invalid")
+    run_git(repository_root, "config", "core.hooksPath", "absent_fixture_hooks")
+    (repository_root / "README.md").write_text("base\n", encoding="utf-8")
+    run_git(repository_root, "add", "README.md")
+    run_git(repository_root, "commit", "-m", "base")
+
+
+def write_gate_script(gate_path: Path, marker_path: Path, exit_code: int) -> None:
+    """Write a staged-gate fixture that records arguments and exits."""
+    gate_path.write_text(
+        "import pathlib\n"
+        "import sys\n"
+        f"pathlib.Path({str(marker_path)!r}).write_text("
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        f"sys.exit({exit_code})\n",
+        encoding="utf-8",
+    )
+
+
+def install_native_pre_commit(repository_root: Path, hooks_path: Path) -> None:
+    """Install the native pre-commit module and its self-contained imports."""
+    hooks_path.mkdir()
+    shutil.copyfile(PRE_COMMIT_SOURCE_PATH, hooks_path / "pre_commit.py")
+    shutil.copyfile(GATE_UTILS_SOURCE_PATH, hooks_path / "gate_utils.py")
+    shutil.copytree(
+        GIT_HOOKS_CONSTANTS_SOURCE_PATH,
+        hooks_path / "git_hooks_constants",
+    )
+    pre_commit_path = hooks_path / "pre-commit"
+    pre_commit_path.write_text(
+        "#!/usr/bin/env python3\n"
+        "import sys\n"
+        "from pathlib import Path\n"
+        "shim_directory = Path(__file__).resolve().parent\n"
+        "sys.path.insert(0, str(shim_directory))\n"
+        "import pre_commit\n"
+        "sys.exit(pre_commit.main())\n",
+        encoding="utf-8",
+    )
+    pre_commit_path.chmod(pre_commit_path.stat().st_mode | stat.S_IXUSR)
+    run_git(repository_root, "config", "core.hooksPath", str(hooks_path))
+
+
+def stage_module(repository_root: Path) -> None:
+    """Write and stage one Python module for the commit fixture."""
+    (repository_root / "widget.py").write_text(CLEAN_MODULE_SOURCE, encoding="utf-8")
+    run_git(repository_root, "add", "widget.py")
+
+
+def build_bash_payload(repository_root: Path) -> str:
+    """Build the Bash dispatcher payload for a commit in the fixture repository."""
+    commit_command = f'git -C "{repository_root}" commit -m add'
+    return json.dumps({"tool_name": "Bash", "tool_input": {"command": commit_command}})
+
+
+def run_agent_dispatcher(repository_root: Path) -> subprocess.CompletedProcess[str]:
+    """Run the production Bash dispatcher against the fixture commit command."""
+    return subprocess.run(
+        [sys.executable, str(DISPATCHER_SOURCE_PATH)],
+        cwd=str(repository_root),
+        input=build_bash_payload(repository_root),
+        capture_output=True,
+        text=True,
+        timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+    )
+
+
+def run_native_commit(repository_root: Path) -> subprocess.CompletedProcess[str]:
+    """Run the real Git commit that invokes the configured native hook."""
+    return run_git(
+        repository_root,
+        "commit",
+        "-m",
+        "add widget",
+        check=False,
+    )
+
+
+def test_agent_dispatcher_passes_commit_through_without_running_gate(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The Agent Bash path continues the commit without running the staged gate."""
+    initialize_repository(tmp_path)
+    stage_module(tmp_path)
+    gate_marker_path = tmp_path / "agent_gate_invocation.txt"
+    gate_path = tmp_path / "agent_gate.py"
+    write_gate_script(gate_path, gate_marker_path, exit_code=1)
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+
+    completed_dispatcher = run_agent_dispatcher(tmp_path)
+
+    assert completed_dispatcher.returncode == 0, completed_dispatcher.stderr
+    assert completed_dispatcher.stdout.strip() == ""
+    assert "Git commit proceeds to configured Git hooks." in completed_dispatcher.stderr
+    assert not gate_marker_path.exists()
+
+
+@pytest.mark.parametrize("gate_exit_code, expected_commit_exit_code", [(1, 1), (0, 0)])
+def test_installed_native_pre_commit_controls_staged_gate_decision(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    gate_exit_code: int,
+    expected_commit_exit_code: int,
+) -> None:
+    """The native Git hook runs the staged gate and returns its commit decision."""
+    initialize_repository(tmp_path)
+    native_hooks_path = tmp_path / "native_hooks"
+    install_native_pre_commit(tmp_path, native_hooks_path)
+    stage_module(tmp_path)
+    gate_marker_path = tmp_path / "native_gate_invocation.txt"
+    gate_path = tmp_path / "native_gate.py"
+    write_gate_script(gate_path, gate_marker_path, gate_exit_code)
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(gate_path))
+
+    completed_commit = run_native_commit(tmp_path)
+
+    assert completed_commit.returncode == expected_commit_exit_code
+    assert gate_marker_path.read_text(encoding="utf-8") == "--staged"

package/hooks/blocking/test_pytest_testpaths_orphan_blocker.py

@@ -6,7 +6,8 @@ import subprocess
 import sys
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+HOOK_DIRECTORY = Path(__file__).resolve().parent
+sys.path.insert(0, str(HOOK_DIRECTORY))
 
 from pytest_testpaths_orphan_blocker import (
     _explicit_testpaths,
@@ -15,7 +16,7 @@ from pytest_testpaths_orphan_blocker import (
     is_test_file,
 )
 
-HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "pytest_testpaths_orphan_blocker.py")
+HOOK_SCRIPT_PATH = HOOK_DIRECTORY / "pytest_testpaths_orphan_blocker.py"
 
 PYPROJECT_WITH_EXPLICIT_TESTPATHS = (
     "[tool.pytest.ini_options]\n"
@@ -51,21 +52,22 @@ def _write_package(package_root: Path, pyproject_text: str) -> None:
     (package_root / "pyproject.toml").write_text(pyproject_text, encoding="utf-8")
 
 
-class _RunHook:
-    """Helper to test the hook via subprocess, mirroring the sibling test style."""
-
-    def __call__(self, tool_name: str, tool_input: dict) -> subprocess.CompletedProcess:
-        payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
-        return subprocess.run(
-            [sys.executable, HOOK_SCRIPT_PATH],
-            input=payload,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-
-
-_run_hook = _RunHook()
+def _run_hook(
+    tool_name: str, tool_input: dict, home_directory: Path
+) -> subprocess.CompletedProcess:
+    """Run the hook in a subprocess with the supplied tool payload."""
+    payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
+    child_environment = os.environ.copy()
+    child_environment["HOME"] = str(home_directory)
+    child_environment["USERPROFILE"] = str(home_directory)
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=payload,
+        capture_output=True,
+        text=True,
+        check=True,
+        env=child_environment,
+    )
 
 
 def test_is_test_file_accepts_test_prefixed_python_file() -> None:
@@ -129,11 +131,13 @@ def test_hook_blocks_create_of_unregistered_test_file(tmp_path: Path) -> None:
             "file_path": str(unregistered_test_file),
             "content": "def test_x() -> None:\n    assert True\n",
         },
+        tmp_path,
     )
     decision = json.loads(completed.stdout)
     hook_output = decision["hookSpecificOutput"]
     assert hook_output["permissionDecision"] == "deny"
     assert "theme_assets/tests" in hook_output["permissionDecisionReason"]
+    assert (tmp_path / ".claude" / "logs" / "hook-blocks.log").is_file()
 
 
 def test_hook_allows_create_of_registered_test_file(tmp_path: Path) -> None:
@@ -146,6 +150,7 @@ def test_hook_allows_create_of_registered_test_file(tmp_path: Path) -> None:
             "file_path": str(registered_test_file),
             "content": "def test_x() -> None:\n    assert True\n",
         },
+        tmp_path,
     )
     assert completed.stdout.strip() == ""
 
@@ -163,6 +168,7 @@ def test_hook_ignores_edit_of_existing_test_file(tmp_path: Path) -> None:
             "old_string": "assert True",
             "new_string": "assert 1 == 1",
         },
+        tmp_path,
     )
     assert completed.stdout.strip() == ""
 
@@ -174,6 +180,7 @@ def test_hook_ignores_non_test_python_file(tmp_path: Path) -> None:
     completed = _run_hook(
         "Write",
         {"file_path": str(production_module), "content": "VALUE = 1\n"},
+        tmp_path,
     )
     assert completed.stdout.strip() == ""
 
@@ -242,6 +249,6 @@ def test_hook_does_not_crash_on_scalar_tool_ancestor(tmp_path: Path) -> None:
             "file_path": str(any_test_file),
             "content": "def test_x() -> None:\n    assert True\n",
         },
+        tmp_path,
     )
-    assert completed.returncode == 0
     assert completed.stdout.strip() == ""

package/hooks/blocking/test_sensitive_file_protector.py

@@ -14,20 +14,33 @@ it stays denied.
 from __future__ import annotations
 
 import json
+import shlex
 import subprocess
 import sys
+from functools import cache
 from pathlib import Path
 
 import pytest
 
 BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+HOOKS_DIRECTORY = BLOCKING_DIRECTORY.parent
+CLAUDE_DEV_ENV_DIRECTORY = BLOCKING_DIRECTORY.parent.parent
 HOOK_SCRIPT_PATH = BLOCKING_DIRECTORY / "sensitive_file_protector.py"
+DISPATCHER_SCRIPT_PATH = BLOCKING_DIRECTORY / "pre_tool_use_dispatcher.py"
+HOOKS_JSON_PATH = HOOKS_DIRECTORY / "hooks.json"
+DIRECT_HOOK_TIMEOUT_SECONDS = 10
 
-WRITE_TOOL_NAME = "Write"
-EDIT_TOOL_NAME = "Edit"
 READ_TOOL_NAME = "Read"
 
-DENY_DECISION = "deny"
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402, I001
+    DENY_DECISION,
+    EDIT_TOOL_NAME,
+    MULTI_EDIT_TOOL_NAME,
+    WRITE_TOOL_NAME,
+)
 
 PLACEHOLDER_TEMPLATE_BODY = "API_TOKEN=your-token-here\nDATABASE_HOST=localhost\n"
 ORDINARY_SOURCE_BODY = "def add(left: int, right: int) -> int:\n    return left + right\n"
@@ -65,11 +78,77 @@ ALL_UPPERCASE_DENIED_FILENAMES = (".ENV", "ID_RSA", "CREDENTIALS.JSON", "SERVER.
 ALL_ORDINARY_FILENAMES = ("main.py", "README.md", "settings.json")
 
 
-def _run_hook(tool_name: str, file_path: Path, content: str) -> subprocess.CompletedProcess:
+@cache
+def _registered_dispatcher_details(
+    hooks_json_path: Path = HOOKS_JSON_PATH,
+) -> tuple[list[str], int]:
+    hooks_configuration = json.loads(hooks_json_path.read_text(encoding="utf-8"))
+    pre_tool_use_registrations = hooks_configuration["hooks"]["PreToolUse"]
+    dispatcher_registrations = []
+    for each_registration in pre_tool_use_registrations:
+        for each_hook in each_registration["hooks"]:
+            command_parts = shlex.split(each_hook["command"])
+            if Path(command_parts[-1]).name != "pre_tool_use_dispatcher.py":
+                continue
+            dispatcher_registrations.append(
+                (each_registration, each_hook, command_parts)
+            )
+    assert len(dispatcher_registrations) == 1, (
+        "hooks.json must contain exactly one pre_tool_use_dispatcher.py registration; "
+        f"found {len(dispatcher_registrations)}"
+    )
+    each_registration, each_hook, command_parts = dispatcher_registrations[0]
+    assert each_registration["matcher"] == "Write|Edit|MultiEdit", (
+        "dispatcher registration must cover exactly Write, Edit, and MultiEdit; "
+        f"got matcher {each_registration['matcher']!r}"
+    )
+    assert command_parts[0] == "python3"
+    dispatcher_script_path = Path(
+        command_parts[-1].replace(
+            "${CLAUDE_PLUGIN_ROOT}", str(CLAUDE_DEV_ENV_DIRECTORY)
+        )
+    )
+    assert dispatcher_script_path.resolve() == DISPATCHER_SCRIPT_PATH.resolve()
+    registered_timeout_seconds = each_hook["timeout"]
+    assert isinstance(registered_timeout_seconds, int)
+    return (
+        [sys.executable, str(dispatcher_script_path)],
+        registered_timeout_seconds,
+    )
+
+
+def _build_file_tool_input(
+    tool_name: str, file_path: Path, replacement_content: str
+) -> dict[str, str | list[dict[str, str]]]:
+    file_path_text = str(file_path)
+    if tool_name == EDIT_TOOL_NAME:
+        return {
+            "file_path": file_path_text,
+            "old_string": "API_TOKEN=old-token\n",
+            "new_string": replacement_content,
+        }
+    if tool_name == MULTI_EDIT_TOOL_NAME:
+        return {
+            "file_path": file_path_text,
+            "edits": [
+                {
+                    "old_string": "API_TOKEN=old-token\n",
+                    "new_string": replacement_content,
+                }
+            ],
+        }
+    return {"file_path": file_path_text, "content": replacement_content}
+
+
+def _run_hook(
+    tool_name: str, file_path: Path, replacement_content: str
+) -> subprocess.CompletedProcess:
     payload = json.dumps(
         {
             "tool_name": tool_name,
-            "tool_input": {"file_path": str(file_path), "content": content},
+            "tool_input": _build_file_tool_input(
+                tool_name, file_path, replacement_content
+            ),
         }
     )
     return _run_hook_with_stdin(payload)
@@ -82,6 +161,22 @@ def _run_hook_with_stdin(stdin_text: str) -> subprocess.CompletedProcess:
         capture_output=True,
         text=True,
         check=False,
+        timeout=DIRECT_HOOK_TIMEOUT_SECONDS,
+    )
+
+
+def _run_dispatcher(
+    tool_name: str, tool_input: dict[str, str | list[dict[str, str]]]
+) -> subprocess.CompletedProcess[str]:
+    payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
+    dispatcher_command, dispatcher_timeout_seconds = _registered_dispatcher_details()
+    return subprocess.run(
+        dispatcher_command,
+        input=payload,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=dispatcher_timeout_seconds,
     )
 
 
@@ -153,6 +248,51 @@ def test_edit_to_a_secrets_file_is_denied(tmp_path: Path) -> None:
     assert _permission_decision(completed) == DENY_DECISION
 
 
+def test_multi_edit_to_a_secrets_file_is_denied(tmp_path: Path) -> None:
+    completed = _run_hook(
+        MULTI_EDIT_TOOL_NAME, tmp_path / ".env", PLACEHOLDER_TEMPLATE_BODY
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == DENY_DECISION
+
+
+def test_hooks_json_registers_exact_dispatcher_matcher_and_timeout() -> None:
+    dispatcher_command, dispatcher_timeout_seconds = _registered_dispatcher_details()
+    assert dispatcher_command[1] == str(DISPATCHER_SCRIPT_PATH)
+    assert dispatcher_timeout_seconds == 60
+
+
+@pytest.mark.parametrize(
+    ("tool_name", "target_filename", "expected_permission_decision"),
+    [
+        pytest.param(WRITE_TOOL_NAME, ".env", DENY_DECISION, id="write-secret-denied"),
+        pytest.param(EDIT_TOOL_NAME, ".env", DENY_DECISION, id="edit-secret-denied"),
+        pytest.param(
+            MULTI_EDIT_TOOL_NAME, ".env", DENY_DECISION, id="multi-edit-secret-denied"
+        ),
+        pytest.param(WRITE_TOOL_NAME, ".env.example", None, id="write-template-allowed"),
+        pytest.param(EDIT_TOOL_NAME, ".env.example", None, id="edit-template-allowed"),
+    ],
+)
+def test_dispatcher_applies_sensitive_filename_contract(
+    tmp_path: Path,
+    tool_name: str,
+    target_filename: str,
+    expected_permission_decision: str | None,
+) -> None:
+    completed = _run_dispatcher(
+        tool_name,
+        _build_file_tool_input(
+            tool_name, tmp_path / target_filename, PLACEHOLDER_TEMPLATE_BODY
+        ),
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == expected_permission_decision, (
+        f"{tool_name} to {target_filename} expected "
+        f"{expected_permission_decision!r}, got stdout {completed.stdout!r}"
+    )
+
+
 def test_read_tool_is_not_evaluated(tmp_path: Path) -> None:
     completed = _run_hook(READ_TOOL_NAME, tmp_path / ".env", PLACEHOLDER_TEMPLATE_BODY)
     assert completed.returncode == 0, completed.stderr