claude-dev-env 1.81.0 → 1.83.0

package/hooks/blocking/test_reviewer_spawn_gate.py

@@ -0,0 +1,230 @@
+"""Unit tests for reviewer_spawn_gate PreToolUse hook."""
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+from contextlib import redirect_stderr, redirect_stdout
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "reviewer_spawn_gate",
+    _HOOK_DIR / "reviewer_spawn_gate.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+_matches_copilot_trigger = hook_module._matches_copilot_trigger
+_matches_bugbot_trigger = hook_module._matches_bugbot_trigger
+_reviewer_trigger = hook_module._reviewer_trigger
+
+_SENTINEL_MARKER = hook_module.GATE_SENTINEL_MARKER
+_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME = hook_module.AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME
+
+_COPILOT_TRIGGER_COMMAND = (
+    f"{_SENTINEL_MARKER} gh api repos/o/r/pulls/1/requested_reviewers "
+    f'-f "reviewers[]=copilot-pull-request-reviewer[bot]"'
+)
+_BUGBOT_TRIGGER_COMMAND = f'{_SENTINEL_MARKER} python post_fix_reply.py --body "bugbot run"'
+
+
+def _write_fake_availability_script(tmp_path: pathlib.Path, exit_code: int) -> pathlib.Path:
+    fake_script_path = tmp_path / "fake_reviewer_availability.py"
+    fake_script_path.write_text(f"import sys\nsys.exit({exit_code})\n", encoding="utf-8")
+    return fake_script_path
+
+
+def _run_hook_with_stdin_text(stdin_text: str) -> tuple[str, str, int]:
+    captured_stdout = io.StringIO()
+    captured_stderr = io.StringIO()
+    exit_code = 0
+    sys.stdin = io.StringIO(stdin_text)
+    try:
+        with redirect_stdout(captured_stdout), redirect_stderr(captured_stderr):
+            try:
+                hook_module.main()
+            except SystemExit as exit_signal:
+                exit_code = exit_signal.code if isinstance(exit_signal.code, int) else 0
+    finally:
+        sys.stdin = sys.__stdin__
+    return captured_stdout.getvalue(), captured_stderr.getvalue(), exit_code
+
+
+def _run_hook(hook_input: dict) -> tuple[str, int]:
+    stdout_text, _stderr_text, exit_code = _run_hook_with_stdin_text(json.dumps(hook_input))
+    return stdout_text, exit_code
+
+
+def test_matches_copilot_trigger_true_for_request_reviewers_command() -> None:
+    assert _matches_copilot_trigger(_COPILOT_TRIGGER_COMMAND)
+
+
+def test_matches_copilot_trigger_false_for_unrelated_command() -> None:
+    assert not _matches_copilot_trigger("gh pr list")
+
+
+def test_matches_bugbot_trigger_true_for_rerun_comment_command() -> None:
+    assert _matches_bugbot_trigger(_BUGBOT_TRIGGER_COMMAND)
+
+
+def test_matches_bugbot_trigger_false_for_unrelated_command() -> None:
+    assert not _matches_bugbot_trigger("python post_fix_reply.py --body 'looks good'")
+
+
+def test_reviewer_trigger_returns_none_for_unrecognized_command() -> None:
+    assert _reviewer_trigger("gh pr list") is None
+
+
+def test_main_allows_copilot_shaped_command_with_no_sentinel_marker(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=3)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Bash",
+            "tool_input": {
+                "command": (
+                    "gh api repos/o/r/pulls/1/requested_reviewers "
+                    '-f "reviewers[]=copilot-pull-request-reviewer[bot]"'
+                )
+            },
+        }
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_allows_copilot_trigger_when_available(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=0)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_denies_copilot_trigger_when_down(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=3)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    response_payload = json.loads(stdout_text)
+    decision_block = response_payload["hookSpecificOutput"]
+    assert decision_block["permissionDecision"] == "deny"
+    assert "GitHub Copilot" in decision_block["permissionDecisionReason"]
+
+
+def test_main_allows_copilot_trigger_on_unexpected_exit_code(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=2)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_allows_copilot_trigger_when_availability_script_crashes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = tmp_path / "fake_reviewer_availability.py"
+    fake_script_path.write_text(
+        "import module_that_does_not_exist_anywhere\n", encoding="utf-8"
+    )
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_allows_bugbot_trigger_when_available(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=0)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _BUGBOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_denies_bugbot_trigger_when_opted_out(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=3)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _BUGBOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    response_payload = json.loads(stdout_text)
+    decision_block = response_payload["hookSpecificOutput"]
+    assert decision_block["permissionDecision"] == "deny"
+    assert "Cursor Bugbot" in decision_block["permissionDecisionReason"]
+
+
+def test_main_allows_marker_command_with_no_recognized_trigger(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_script_path = _write_fake_availability_script(tmp_path, exit_code=3)
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(fake_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": f"{_SENTINEL_MARKER} gh pr list"}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_allows_when_availability_script_missing(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    missing_script_path = tmp_path / "does_not_exist.py"
+    monkeypatch.setenv(_AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, str(missing_script_path))
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Bash", "tool_input": {"command": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_allows_non_bash_tool() -> None:
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Write", "tool_input": {"content": _COPILOT_TRIGGER_COMMAND}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_with_empty_stdin_exits_silently() -> None:
+    stdout_text, stderr_text, exit_code = _run_hook_with_stdin_text("")
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""
+
+
+def test_main_with_invalid_json_stdin_exits_silently() -> None:
+    stdout_text, stderr_text, exit_code = _run_hook_with_stdin_text("{broken")
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""

package/hooks/blocking/test_stale_comment_reference_blocker.py

@@ -0,0 +1,236 @@
+"""Tests for the stale_comment_reference_blocker hook."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+_BLOCKING_DIR = str(Path(__file__).resolve().parent)
+_HOOKS_ROOT = str(Path(__file__).resolve().parent.parent)
+if _BLOCKING_DIR not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIR)
+if _HOOKS_ROOT not in sys.path:
+    sys.path.insert(0, _HOOKS_ROOT)
+
+from stale_comment_reference_blocker import (  # noqa: E402
+    build_deny_payload,
+    evaluate,
+)
+
+from hooks_constants.hook_block_logger import _HOOK_BLOCKS_LOG_RELATIVE_PATH  # noqa: E402
+
+HOOK_SCRIPT_PATH = str(Path(__file__).resolve().parent / "stale_comment_reference_blocker.py")
+
+PATCHED_SLEEP_LINE = (
+    "    with patch('theme_exports.core.exporter.asyncio.sleep', new_callable=AsyncMock):\n"
+)
+PATCHED_POLL_LINE = "    with patch('theme_exports.core.exporter.wait_for_overlay_clear', new_callable=AsyncMock):\n"
+KEPT_COMMENT_LINE = "    # Mock asyncio\n"
+
+
+def _run_hook(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,
+    )
+
+
+def _write_module(tmp_path: Path, source_text: str) -> Path:
+    written_module_path = tmp_path / "sample_module.py"
+    written_module_path.write_text(source_text, encoding="utf-8")
+    return written_module_path
+
+
+def test_blocks_edit_that_orphans_the_comment_above(tmp_path: Path) -> None:
+    """Rewriting the patched target under an unchanged comment naming it
+    is denied.
+    """
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n" + KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+    )
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": PATCHED_SLEEP_LINE.rstrip("\n"),
+            "new_string": PATCHED_POLL_LINE.rstrip("\n"),
+        },
+    )
+    assert outcome.returncode == 0
+    decision = json.loads(outcome.stdout)
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "asyncio" in decision["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_blocks_edit_that_deletes_the_line_the_comment_names(tmp_path: Path) -> None:
+    """Deleting the patched line under an unchanged comment naming it is
+    denied the same as rewriting it would be.
+    """
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n" + KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+    )
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": PATCHED_SLEEP_LINE,
+            "new_string": "",
+        },
+    )
+    assert outcome.returncode == 0
+    decision = json.loads(outcome.stdout)
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "asyncio" in decision["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_allows_edit_that_updates_the_comment_together(tmp_path: Path) -> None:
+    """An edit rewriting the comment and the line together passes."""
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n" + KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+    )
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+            "new_string": "    # Mock the overlay poll\n" + PATCHED_POLL_LINE,
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_edit_that_keeps_the_named_identifier(tmp_path: Path) -> None:
+    """A rewrite that still carries the identifier the comment names passes."""
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n" + KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+    )
+    retained_line = "    with patch('theme_exports.core.exporter.asyncio.sleep'):\n"
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": PATCHED_SLEEP_LINE.rstrip("\n"),
+            "new_string": retained_line.rstrip("\n"),
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_prose_comment_with_no_orphaned_identifier(tmp_path: Path) -> None:
+    """A prose comment whose tokens never name anything in the edited line
+    passes.
+    """
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n"
+        "    # Overlay settle pause\n"
+        "    runner.pause_for_overlay_settle()\n",
+    )
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": "    runner.pause_for_overlay_settle()",
+            "new_string": "    runner.confirm_editor_ready()",
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_non_python_file(tmp_path: Path) -> None:
+    """A non-Python target passes untouched."""
+    plain_text_target = tmp_path / "notes.txt"
+    plain_text_target.write_text("# Mock asyncio\nasyncio row\n", encoding="utf-8")
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(plain_text_target),
+            "old_string": "asyncio row",
+            "new_string": "other row",
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_write_tool() -> None:
+    """A non-Edit invocation passes untouched."""
+    outcome = _run_hook(
+        "Write",
+        {
+            "file_path": "src/sample_module.py",
+            "content": KEPT_COMMENT_LINE + PATCHED_POLL_LINE,
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_missing_file(tmp_path: Path) -> None:
+    """An Edit aimed at a path with no readable target passes."""
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(tmp_path / "absent_module.py"),
+            "old_string": "one",
+            "new_string": "two",
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_allows_old_string_not_found(tmp_path: Path) -> None:
+    """An Edit whose old_string never occurs in the target passes."""
+    written_module_path = _write_module(tmp_path, "value_count = 1\n")
+    outcome = _run_hook(
+        "Edit",
+        {
+            "file_path": str(written_module_path),
+            "old_string": "never present",
+            "new_string": "still never present",
+        },
+    )
+    assert outcome.returncode == 0
+    assert outcome.stdout == ""
+
+
+def test_deny_payload_logs_the_block(tmp_path: Path) -> None:
+    """One record lands in the block journal for each denial built through
+    evaluate plus build_deny_payload.
+    """
+    written_module_path = _write_module(
+        tmp_path,
+        "def launch_export() -> None:\n" + KEPT_COMMENT_LINE + PATCHED_SLEEP_LINE,
+    )
+    deny_reason = evaluate(
+        {
+            "tool_name": "Edit",
+            "tool_input": {
+                "file_path": str(written_module_path),
+                "old_string": PATCHED_SLEEP_LINE.rstrip("\n"),
+                "new_string": PATCHED_POLL_LINE.rstrip("\n"),
+            },
+        }
+    )
+    assert deny_reason is not None
+    with patch.object(Path, "home", return_value=tmp_path):
+        deny_payload = build_deny_payload(deny_reason)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    block_log_path = tmp_path / _HOOK_BLOCKS_LOG_RELATIVE_PATH
+    all_log_records = block_log_path.read_text(encoding="utf-8").strip().splitlines()
+    assert len(all_log_records) == 1
+    parsed_log_line = json.loads(all_log_records[0])
+    assert parsed_log_line["hook"] == "stale_comment_reference_blocker.py"

package/hooks/blocking/test_state_description_blocker.py

@@ -633,6 +633,141 @@ def test_handles_non_string_tool_name():
     assert result.stdout == ""
 
 
+def test_detects_used_to_in_python_module_docstring() -> None:
+    """A module docstring carrying a transitional phrase counts as
+    documentation and is denied.
+    """
+    written_source = (
+        '"""Both paths used to pad with a flat sleep on every export."""\n'
+        "\n"
+        "RETRY_BUDGET = 5\n"
+    )
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "tests/test_exports.py",
+            "content": written_source,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "used to" in output["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_detects_previously_in_python_function_docstring() -> None:
+    """A function docstring carrying a transitional phrase is denied.
+    """
+    written_source = (
+        "def load_configuration() -> None:\n"
+        '    """Previously configured via an environment variable."""\n'
+        "    raise ValueError\n"
+    )
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "src/configuration.py",
+            "content": written_source,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "previously" in output["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_ignores_transitional_phrase_in_regular_python_string() -> None:
+    """A plain string literal counts as data rather than documentation and
+    passes.
+    """
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "src/messages.py",
+            "content": 'PADDING_NOTE = "used to pad with a flat sleep"\n',
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_ignores_quoted_mention_inside_python_docstring() -> None:
+    """A docstring quoting a phrase as a mention in double quotes passes.
+    """
+    written_source = (
+        '"""Blocks docstrings carrying phrases like "used to" in their prose."""\n'
+        "\n"
+        "RETRY_BUDGET = 3\n"
+    )
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "src/scanner.py",
+            "content": written_source,
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_detects_docstring_at_start_of_unparseable_edit_fragment() -> None:
+    """An Edit fragment opening with a docstring is scanned even when
+    parsing fails.
+    """
+    fragment = '"""The runner used to sleep between exports."""\n    continue\n'
+    result = _run_hook(
+        "Edit",
+        {
+            "file_path": "src/exports.py",
+            "old_string": "placeholder",
+            "new_string": fragment,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "used to" in output["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_detects_docstring_after_def_header_in_unparseable_fragment() -> None:
+    """A triple-quoted block directly under a def header counts as a
+    docstring in a fragment.
+    """
+    fragment = (
+        "    def render_summary(self) -> None:\n"
+        '        """No longer writes the summary sheet."""\n'
+    )
+    result = _run_hook(
+        "Edit",
+        {
+            "file_path": "src/reporting.py",
+            "old_string": "placeholder",
+            "new_string": fragment,
+        },
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "no longer" in output["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_ignores_assigned_triple_quoted_string_in_unparseable_fragment() -> None:
+    """A triple-quoted block assigned to a name counts as data rather than
+    a docstring in a fragment.
+    """
+    fragment = 'FIXTURE_TEXT = """used to pad with a flat sleep"""\n    continue\n'
+    result = _run_hook(
+        "Edit",
+        {
+            "file_path": "src/fixtures.py",
+            "old_string": "placeholder",
+            "new_string": fragment,
+        },
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
 def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
     """A deny routed through the dispatcher's native path logs one record.
 

package/hooks/hooks.json

@@ -55,6 +55,16 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_body_arg_blocker.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/conventional_pr_title_gate.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/reviewer_spawn_gate.py",
+            "timeout": 20
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/block_main_commit.py",

package/hooks/hooks_constants/CLAUDE.md

@@ -18,6 +18,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `code_verifier_spawn_preflight_gate_constants.py` | Subagent type, merge-tree command flags, timeouts, and deny-message text for the code-verifier spawn pre-flight gate |
 | `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
+| `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
 | `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
 | `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
 | `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
@@ -52,11 +53,13 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
 | `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
 | `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
+| `reviewer_spawn_gate_constants.py` | Bash tool name, the sentinel marker, the Copilot and Bugbot trigger markers, the availability-script relative path and override env-var name, and the deny-message template for the reviewer-spawn gate |
 | `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
 | `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
 | `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
 | `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
-| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects |
+| `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
+| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
 | `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
 | `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
 | `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |