claude-dev-env 2.0.2 → 2.2.0

package/hooks/blocking/test_code_rules_shared.py

@@ -12,6 +12,9 @@ SHARED_MODULE_PATH = Path(__file__).parent / "code_rules_shared.py"
 FIXED_USER_ID = 4242
 WORKING_DIRECTORY = "/home/user/project"
 SESSION_ID = "session-abc-123"
+HARNESS_USER_DIRECTORY_WINDOWS = "claude"
+WINDOWS_MANGLED_WORKING_DIRECTORY = "c--Users-dev--claude-project"
+SESSION_ID_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_SESSION_ID"
 
 
 def _load_shared_module() -> ModuleType:
@@ -27,10 +30,6 @@ def _load_shared_module() -> ModuleType:
 _SHARED_MODULE = _load_shared_module()
 
 
-def _install_fixed_user_id(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(os, "getuid", lambda: FIXED_USER_ID, raising=False)
-
-
 def _point_temporary_directory_at(monkeypatch: pytest.MonkeyPatch, temporary_root: Path) -> None:
     monkeypatch.setattr(tempfile, "gettempdir", lambda: str(temporary_root))
 
@@ -48,6 +47,24 @@ def _build_scratchpad_directory(temporary_root: Path) -> Path:
     return scratchpad_directory
 
 
+def _build_windows_scratchpad_directory(temporary_root: Path) -> Path:
+    """Build the Windows-shaped scratchpad directory that carries no user id segment."""
+    scratchpad_directory = (
+        temporary_root
+        / HARNESS_USER_DIRECTORY_WINDOWS
+        / WINDOWS_MANGLED_WORKING_DIRECTORY
+        / SESSION_ID
+        / "scratchpad"
+    )
+    scratchpad_directory.mkdir(parents=True)
+    return scratchpad_directory
+
+
+def _simulate_windows_platform(monkeypatch: pytest.MonkeyPatch, temporary_root: Path) -> None:
+    monkeypatch.delattr(os, "getuid", raising=False)
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(temporary_root))
+
+
 def _session_payload() -> dict[str, str]:
     return {"cwd": WORKING_DIRECTORY, "session_id": SESSION_ID}
 
@@ -55,7 +72,6 @@ def _session_payload() -> dict[str, str]:
 def test_returns_true_for_file_inside_reconstructed_scratchpad(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     scratchpad_directory = _build_scratchpad_directory(tmp_path)
     throwaway_script = scratchpad_directory / "one_off_tool.py"
@@ -69,7 +85,6 @@ def test_returns_true_for_file_inside_reconstructed_scratchpad(
 def test_returns_false_for_file_outside_scratchpad(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     _build_scratchpad_directory(tmp_path)
     project_module = tmp_path / "elsewhere" / "orders.py"
@@ -82,7 +97,6 @@ def test_returns_false_for_file_outside_scratchpad(
 def test_resolves_symlink_into_scratchpad_to_true(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     scratchpad_directory = _build_scratchpad_directory(tmp_path)
     real_script = scratchpad_directory / "real_tool.py"
@@ -96,7 +110,6 @@ def test_resolves_symlink_into_scratchpad_to_true(
 def test_symlink_resolving_outside_scratchpad_is_false(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     scratchpad_directory = _build_scratchpad_directory(tmp_path)
     real_target_outside = tmp_path / "outside_target.py"
@@ -113,8 +126,8 @@ def test_symlink_resolving_outside_scratchpad_is_false(
 def test_missing_session_id_signal_returns_false(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
+    monkeypatch.delenv(SESSION_ID_ENVIRONMENT_VARIABLE, raising=False)
     scratchpad_directory = _build_scratchpad_directory(tmp_path)
     throwaway_script = scratchpad_directory / "one_off_tool.py"
     payload_without_session = {"cwd": WORKING_DIRECTORY}
@@ -125,10 +138,12 @@ def test_missing_session_id_signal_returns_false(
     )
 
 
-def test_missing_working_directory_signal_returns_false(
+def test_exempt_without_working_directory_signal(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
+    """The platform-safe predicate keys on the session id and the temp-directory path
+    shape, so a payload carrying the session id alone still exempts a real scratchpad
+    target even when it omits the working directory."""
     _point_temporary_directory_at(monkeypatch, tmp_path)
     scratchpad_directory = _build_scratchpad_directory(tmp_path)
     throwaway_script = scratchpad_directory / "one_off_tool.py"
@@ -136,27 +151,28 @@ def test_missing_working_directory_signal_returns_false(
 
     assert (
         _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), payload_without_cwd)
-        is False
+        is True
     )
 
 
-def test_absent_getuid_returns_false(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    _install_fixed_user_id(monkeypatch)
-    _point_temporary_directory_at(monkeypatch, tmp_path)
-    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+def test_exempt_on_windows_without_getuid(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """On Windows the os.getuid attribute is absent, and a real scratchpad target still
+    resolves as exempt through its temp-directory path shape and session id."""
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    scratchpad_directory = _build_windows_scratchpad_directory(tmp_path)
     throwaway_script = scratchpad_directory / "one_off_tool.py"
-    monkeypatch.delattr(os, "getuid", raising=False)
 
     assert (
         _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), _session_payload())
-        is False
+        is True
     )
 
 
 def test_nonexistent_scratchpad_directory_returns_false(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     mangled_working_directory = WORKING_DIRECTORY.replace("/", "-")
     unbuilt_target = (
@@ -174,8 +190,92 @@ def test_nonexistent_scratchpad_directory_returns_false(
 
 
 def test_empty_file_path_returns_false(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    _install_fixed_user_id(monkeypatch)
     _point_temporary_directory_at(monkeypatch, tmp_path)
     _build_scratchpad_directory(tmp_path)
 
     assert _SHARED_MODULE.is_under_session_scratchpad("", _session_payload()) is False
+
+
+def test_windows_shape_repository_file_is_not_exempt(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    _build_windows_scratchpad_directory(tmp_path)
+    repository_module = tmp_path / "repository" / "src" / "orders.py"
+    repository_module.parent.mkdir(parents=True)
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(repository_module), _session_payload())
+        is False
+    )
+
+
+def test_temp_path_outside_scratchpad_shape_is_not_exempt(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A path under the harness user directory but off the session/scratchpad shape
+    keeps full enforcement."""
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    _build_windows_scratchpad_directory(tmp_path)
+    off_shape_target = tmp_path / HARNESS_USER_DIRECTORY_WINDOWS / "unrelated" / "notes.py"
+    off_shape_target.parent.mkdir(parents=True)
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(off_shape_target), _session_payload())
+        is False
+    )
+
+
+def test_repository_path_containing_scratchpad_word_is_not_exempt(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A repository path outside the temp directory that merely carries a scratchpad
+    segment keeps full enforcement."""
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    _build_windows_scratchpad_directory(tmp_path)
+    repository_lookalike = tmp_path.parent / "project_repo" / "scratchpad" / "tool.py"
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(repository_lookalike), _session_payload())
+        is False
+    )
+
+
+def test_is_ephemeral_path_true_for_windows_scratchpad(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    scratchpad_directory = _build_windows_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "probe.py"
+
+    assert _SHARED_MODULE.is_ephemeral_path(str(throwaway_script), _session_payload()) is True
+
+
+def test_is_ephemeral_path_true_for_root_anchored_tmp(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
+
+    assert _SHARED_MODULE.is_ephemeral_path("/tmp/scratch.py") is True
+
+
+def test_is_ephemeral_path_false_for_repository_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
+    repository_file = tmp_path / "repository" / "orders.py"
+    repository_file.parent.mkdir(parents=True)
+
+    assert _SHARED_MODULE.is_ephemeral_path(str(repository_file), _session_payload()) is False
+
+
+def test_is_ephemeral_path_reads_session_id_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """With no payload, the session scratchpad match reads the session id from the
+    harness environment variable, so a caller that holds no payload still matches."""
+    _simulate_windows_platform(monkeypatch, tmp_path)
+    monkeypatch.setenv(SESSION_ID_ENVIRONMENT_VARIABLE, SESSION_ID)
+    scratchpad_directory = _build_windows_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "probe.py"
+
+    assert _SHARED_MODULE.is_ephemeral_path(str(throwaway_script)) is True

package/hooks/blocking/test_convergence_gate_blocker.py

@@ -132,3 +132,149 @@ def test_main_reads_cwd_from_top_level_payload(
         hook_module.main()
 
     assert captured_cwd == [worktree_path]
+
+
+def _capture_convergence_identity(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: pathlib.Path,
+    command: str,
+    cwd_owner_repo: tuple[str, str],
+) -> tuple[str, str, int]:
+    convergence_script = (
+        tmp_path / ".claude" / "skills" / "pr-converge" / "scripts" / "check_convergence.py"
+    )
+    convergence_script.parent.mkdir(parents=True)
+    convergence_script.write_text("")
+    monkeypatch.setattr(hook_module.Path, "home", classmethod(lambda _cls: tmp_path))
+    monkeypatch.setattr(hook_module, "_resolve_owner_repo", lambda _cwd: cwd_owner_repo)
+
+    captured_identity: list[tuple[str, str, int]] = []
+
+    def fake_check(
+        _script: str, owner: str, repo: str, pr_number: int, _cwd: str | None
+    ) -> subprocess.CompletedProcess[str]:
+        captured_identity.append((owner, repo, pr_number))
+        return subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
+
+    monkeypatch.setattr(hook_module, "_run_convergence_check", fake_check)
+
+    payload = {
+        "tool_name": "Bash",
+        "cwd": str(tmp_path / "worktree"),
+        "tool_input": {"command": command},
+    }
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+    with pytest.raises(SystemExit):
+        hook_module.main()
+    return captured_identity[0]
+
+
+def test_repo_flag_overrides_cwd_repo(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    identity = _capture_convergence_identity(
+        monkeypatch,
+        tmp_path,
+        "gh pr ready 161 --repo sample-owner/target-repo",
+        ("cwd-owner", "cwd-repo"),
+    )
+    assert identity == ("sample-owner", "target-repo", 161)
+
+
+def test_pr_url_yields_repo_and_number(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    identity = _capture_convergence_identity(
+        monkeypatch,
+        tmp_path,
+        "gh pr ready https://github.com/sample-owner/target-repo/pull/161",
+        ("cwd-owner", "cwd-repo"),
+    )
+    assert identity == ("sample-owner", "target-repo", 161)
+
+
+def test_bare_pr_ready_resolves_repo_from_cwd(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    identity = _capture_convergence_identity(
+        monkeypatch,
+        tmp_path,
+        "gh pr ready 418",
+        ("cwd-owner", "cwd-repo"),
+    )
+    assert identity == ("cwd-owner", "cwd-repo", 418)
+
+
+def test_parse_repo_flag_space_form() -> None:
+    assert hook_module._parse_repo_flag("gh pr ready 161 --repo sample-owner/target-repo") == (
+        "sample-owner",
+        "target-repo",
+    )
+
+
+def test_parse_repo_flag_equals_form() -> None:
+    assert hook_module._parse_repo_flag("gh pr ready 161 --repo=sample-owner/target-repo") == (
+        "sample-owner",
+        "target-repo",
+    )
+
+
+def test_parse_repo_flag_short_alias() -> None:
+    assert hook_module._parse_repo_flag("gh pr ready 161 -R sample-owner/target-repo") == (
+        "sample-owner",
+        "target-repo",
+    )
+
+
+def test_parse_repo_flag_absent_returns_none() -> None:
+    assert hook_module._parse_repo_flag("gh pr ready 418") is None
+
+
+def test_parse_pr_url_yields_owner_repo_number() -> None:
+    assert hook_module._parse_pr_url(
+        "gh pr ready https://github.com/sample-owner/target-repo/pull/161"
+    ) == ("sample-owner", "target-repo", 161)
+
+
+def test_parse_pr_url_absent_returns_none() -> None:
+    assert hook_module._parse_pr_url("gh pr ready 418") is None
+
+
+def test_ready_segment_clips_at_command_separator() -> None:
+    assert (
+        hook_module._ready_command_segment(
+            "gh pr ready 161 && gh pr comment 999 --repo other-owner/other-repo"
+        )
+        == "gh pr ready 161 "
+    )
+
+
+def test_chained_repo_flag_does_not_misbind_the_gate(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    identity = _capture_convergence_identity(
+        monkeypatch,
+        tmp_path,
+        "gh pr ready 161 && gh pr comment 999 --repo other-owner/other-repo --body-file note.md",
+        ("cwd-owner", "cwd-repo"),
+    )
+    assert identity == ("cwd-owner", "cwd-repo", 161)
+
+
+def test_chained_pr_url_does_not_misbind_the_gate(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    identity = _capture_convergence_identity(
+        monkeypatch,
+        tmp_path,
+        "gh pr ready 161 && echo https://github.com/other-owner/other-repo/pull/5",
+        ("cwd-owner", "cwd-repo"),
+    )
+    assert identity == ("cwd-owner", "cwd-repo", 161)
+
+
+def test_ready_segment_skips_a_leading_undo_invocation() -> None:
+    assert (
+        hook_module._ready_command_segment("gh pr ready --undo && gh pr ready 161")
+        == "gh pr ready 161"
+    )

package/hooks/blocking/test_plain_language_blocker.py

@@ -14,6 +14,8 @@ import sys
 from pathlib import Path
 from unittest.mock import patch
 
+import pytest
+
 HOOK_SCRIPT_PATH = Path(__file__).parent / "plain_language_blocker.py"
 _HOOKS_DIR = str(Path(__file__).resolve().parent)
 _HOOKS_ROOT = str(Path(__file__).resolve().parent.parent)
@@ -185,6 +187,19 @@ def test_write_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
     assert _decision_from(completed) == "deny"
 
 
+def test_write_markdown_at_ephemeral_path_is_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": "/tmp/notes.md",
+            "content": "This guide explains how to utilize the new cache layer.",
+        },
+    }
+    completed = _run_hook_with_payload(payload)
+    assert _decision_from(completed) is None
+
+
 def test_write_non_markdown_is_ignored(tmp_path: Path) -> None:
     target = tmp_path / "notes.txt"
     payload = {

package/hooks/blocking/test_state_description_blocker.py

@@ -7,6 +7,8 @@ import sys
 from pathlib import Path
 from unittest.mock import patch
 
+import pytest
+
 _BLOCKING_DIR = str(Path(__file__).resolve().parent)
 _HOOKS_ROOT = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIR not in sys.path:
@@ -207,6 +209,19 @@ def test_detects_now_uses_in_markdown():
     assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
 
 
+def test_markdown_at_ephemeral_path_is_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "/tmp/api.md",
+            "content": VIOLATION_MD_INSTEAD,
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
 def test_detects_edit_new_string():
     result = _run_hook(
         "Edit",

package/hooks/blocking/test_verified_commit_config_bootstrap.py

@@ -31,6 +31,24 @@ def test_register_binds_dotted_name_to_sibling_constants_file(
     assert detached_head_line == "HEAD"
 
 
+def test_register_binds_gate_output_constants_module(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import verified_commit_config_bootstrap as bootstrap\n"
+        "bootstrap.register_verified_commit_constants()\n"
+        "import config.verified_commit_gate_output_constants as loaded\n"
+        "print(loaded.__file__)\n"
+        "print(loaded.DENY_PERMISSION_DECISION)\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    resolved_file_line, deny_decision_line = completed_probe.stdout.splitlines()[:2]
+    assert resolved_file_line.replace("\\", "/").endswith(
+        "blocking/config/verified_commit_gate_output_constants.py"
+    )
+    assert deny_decision_line == "deny"
+
+
 def test_register_leaves_an_already_cached_module_untouched(
     run_under_config_shadow: RunUnderConfigShadow,
 ) -> None:

package/hooks/blocking/test_verified_commit_gate_additional_context.py

@@ -0,0 +1,134 @@
+"""The verified-commit gate's deny payload teaches the verify-skip policy.
+
+A blocked commit prints a PreToolUse ``hookSpecificOutput`` deny whose
+``additionalContext`` carries the ``# verify-skip`` usage rule, so the agent
+learns at the moment of the block when the marker is legitimate.
+"""
+
+import importlib.util
+import io
+import json
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+gate_spec = importlib.util.spec_from_file_location(
+    "verified_commit_gate",
+    _HOOK_DIR / "verified_commit_gate.py",
+)
+assert gate_spec is not None
+assert gate_spec.loader is not None
+gate_module = importlib.util.module_from_spec(gate_spec)
+gate_spec.loader.exec_module(gate_module)
+gate_main = gate_module.main
+
+PRODUCTION_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
+CHANGED_SOURCE = "def add(left: int, right: int) -> int:\n    return left - right\n"
+
+
+def _run_git(work_dir: pathlib.Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(work_dir), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _make_gated_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    origin_dir = tmp_path / "origin.git"
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    _run_git(work_dir, "init", "--initial-branch=main")
+    _run_git(work_dir, "config", "user.email", "tests@example.com")
+    _run_git(work_dir, "config", "user.name", "Gate Tests")
+    (work_dir / "app.py").write_text(PRODUCTION_SOURCE, encoding="utf-8")
+    _run_git(work_dir, "add", "-A")
+    _run_git(work_dir, "commit", "-m", "base")
+    _run_git(work_dir, "remote", "add", "origin", str(origin_dir))
+    _run_git(work_dir, "push", "-u", "origin", "main")
+    (work_dir / "app.py").write_text(CHANGED_SOURCE, encoding="utf-8")
+    return work_dir
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: pathlib.Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _run_gate_main(
+    monkeypatch: pytest.MonkeyPatch, command_text: str, work_dir: pathlib.Path
+) -> None:
+    payload_text = json.dumps(
+        {
+            "tool_name": "Bash",
+            "tool_input": {"command": command_text},
+            "cwd": str(work_dir),
+            "transcript_path": "",
+        }
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload_text))
+    gate_main()
+
+
+def test_deny_payload_carries_verify_skip_additional_context(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: pathlib.Path,
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    _run_gate_main(monkeypatch, "git commit -m x", work_dir)
+    deny_payload = json.loads(capsys.readouterr().out)
+    hook_specific_output = deny_payload["hookSpecificOutput"]
+    assert hook_specific_output["permissionDecision"] == "deny"
+    additional_context = hook_specific_output["additionalContext"]
+    assert "# verify-skip" in additional_context
+    assert "already passed clean" in additional_context
+    assert "fresh verification" in additional_context
+
+
+def test_marker_inside_a_quoted_message_still_denies(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: pathlib.Path,
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    quoted_marker_command = 'git commit -m "docs: explain the # verify-skip escape hatch"'
+    _run_gate_main(monkeypatch, quoted_marker_command, work_dir)
+    deny_payload = json.loads(capsys.readouterr().out)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_marker_as_a_trailing_comment_bypasses(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: pathlib.Path,
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    trailing_marker_command = 'git commit -m "wire up feature" # verify-skip'
+    _run_gate_main(monkeypatch, trailing_marker_command, work_dir)
+    assert capsys.readouterr().out == ""

package/hooks/blocking/tests/test_verified_commit_gate.py

@@ -0,0 +1,41 @@
+"""Entry-boundary behavior of the verified_commit_gate hook process.
+
+Runs the hook as a subprocess the way Claude Code does and pins the two
+silent paths: a tool the gate does not cover, and a gated command carrying
+the bypass marker.
+"""
+
+import json
+import pathlib
+import subprocess
+import sys
+
+_BLOCKING_DIRECTORY = pathlib.Path(__file__).resolve().parent.parent
+_GATE_SCRIPT_PATH = _BLOCKING_DIRECTORY / "verified_commit_gate.py"
+
+
+def _run_gate_process(tool_name: str, command_text: str) -> str:
+    payload_text = json.dumps(
+        {
+            "tool_name": tool_name,
+            "tool_input": {"command": command_text},
+            "cwd": str(_BLOCKING_DIRECTORY),
+            "transcript_path": "",
+        }
+    )
+    completed_process = subprocess.run(
+        [sys.executable, str(_GATE_SCRIPT_PATH)],
+        input=payload_text,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return completed_process.stdout
+
+
+def test_uncovered_tool_name_stays_silent() -> None:
+    assert _run_gate_process("Read", "git commit -m x") == ""
+
+
+def test_bypass_marker_stays_silent_at_the_process_boundary() -> None:
+    assert _run_gate_process("Bash", "git commit -m x # verify-skip") == ""