claude-dev-env 2.9.0 → 2.11.0

package/hooks/blocking/test_plain_language_blocker_allowlist.py

@@ -2,12 +2,19 @@
 
 import importlib.util
 import json
+import os
 from pathlib import Path
+
+import pytest
 from types import ModuleType
+from unittest.mock import patch
 
 BLOCKER_PATH = Path(__file__).parent / "plain_language_blocker.py"
 ALLOWLIST_RELATIVE_PATH = Path(".claude") / "plain-language-allow.json"
 ALWAYS_HEAVY_WORD = "utilize"
+_PROSE_STYLE_ENFORCEMENT_ENVIRONMENT = {
+    "CLAUDE_PROSE_STYLE_ENFORCEMENT": "1",
+}
 
 
 def _load_blocker() -> ModuleType:
@@ -22,6 +29,24 @@ def _load_blocker() -> ModuleType:
 
 _BLOCKER = _load_blocker()
 
+@pytest.fixture(autouse=True)
+def enable_prose_style_enforcement(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Opinionated heavy-word scan is default-off; these tests arm it."""
+    monkeypatch.setenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", "1")
+
+
+
+def _evaluate_advisory(
+    payload_by_key: dict[str, object],
+) -> tuple[str | None, str | None]:
+    """Return (deny_reason, advisory_message) with prose enforcement on.
+
+    Heavy words never deny (OP-07D); allowlist coverage asserts on the advisory
+    message and on ``find_banned_terms`` so the scanner still sees domain terms.
+    """
+    with patch.dict(os.environ, _PROSE_STYLE_ENFORCEMENT_ENVIRONMENT):
+        return _BLOCKER.evaluate_with_advisory(payload_by_key)
+
 
 def _init_repo(root: Path) -> Path:
     (root / ".git").mkdir(parents=True, exist_ok=True)
@@ -63,15 +88,17 @@ def test_allowlisted_word_passes_in_markdown_write(tmp_path: Path) -> None:
     project_with_allowlist = _init_repo(tmp_path / "domain")
     _write_allowlist(project_with_allowlist, ["submit"])
 
-    control_deny_reason = _BLOCKER.evaluate(
+    control_deny, control_advisory = _evaluate_advisory(
         _markdown_write_payload(project_without_allowlist, prose)
     )
-    allowlisted_deny_reason = _BLOCKER.evaluate(
+    allowlisted_deny, allowlisted_advisory = _evaluate_advisory(
         _markdown_write_payload(project_with_allowlist, prose)
     )
 
-    assert control_deny_reason is not None and "submit" in control_deny_reason
-    assert allowlisted_deny_reason is None
+    assert control_deny is None
+    assert control_advisory is not None and "submit" in control_advisory
+    assert allowlisted_deny is None
+    assert allowlisted_advisory is None
 
 
 def test_allowlisted_word_passes_in_ask_user_question(tmp_path: Path) -> None:
@@ -80,26 +107,29 @@ def test_allowlisted_word_passes_in_ask_user_question(tmp_path: Path) -> None:
     project_with_allowlist = _init_repo(tmp_path / "domain")
     _write_allowlist(project_with_allowlist, ["identify"])
 
-    control_deny_reason = _BLOCKER.evaluate(
+    control_deny, control_advisory = _evaluate_advisory(
         _ask_user_question_payload(project_without_allowlist, prose)
     )
-    allowlisted_deny_reason = _BLOCKER.evaluate(
+    allowlisted_deny, allowlisted_advisory = _evaluate_advisory(
         _ask_user_question_payload(project_with_allowlist, prose)
     )
 
-    assert control_deny_reason is not None and "identify" in control_deny_reason
-    assert allowlisted_deny_reason is None
+    assert control_deny is None
+    assert control_advisory is not None and "identify" in control_advisory
+    assert allowlisted_deny is None
+    assert allowlisted_advisory is None
 
 
-def test_non_allowlisted_heavy_word_still_blocked(tmp_path: Path) -> None:
+def test_non_allowlisted_heavy_word_still_flagged(tmp_path: Path) -> None:
     _init_repo(tmp_path)
     _write_allowlist(tmp_path, ["submit"])
 
-    deny_reason = _BLOCKER.evaluate(
+    deny_reason, advisory_message = _evaluate_advisory(
         _markdown_write_payload(tmp_path, f"Please {ALWAYS_HEAVY_WORD} the cache now.")
     )
 
-    assert deny_reason is not None and ALWAYS_HEAVY_WORD in deny_reason
+    assert deny_reason is None
+    assert advisory_message is not None and ALWAYS_HEAVY_WORD in advisory_message
 
 
 def test_allowlist_match_is_case_insensitive(tmp_path: Path) -> None:
@@ -108,26 +138,29 @@ def test_allowlist_match_is_case_insensitive(tmp_path: Path) -> None:
     project_with_allowlist = _init_repo(tmp_path / "domain")
     _write_allowlist(project_with_allowlist, ["Submit"])
 
-    control_deny_reason = _BLOCKER.evaluate(
+    control_deny, control_advisory = _evaluate_advisory(
         _markdown_write_payload(project_without_allowlist, prose)
     )
-    allowlisted_deny_reason = _BLOCKER.evaluate(
+    allowlisted_deny, allowlisted_advisory = _evaluate_advisory(
         _markdown_write_payload(project_with_allowlist, prose)
     )
 
-    assert control_deny_reason is not None and "submit" in control_deny_reason
-    assert allowlisted_deny_reason is None
+    assert control_deny is None
+    assert control_advisory is not None and "submit" in control_advisory
+    assert allowlisted_deny is None
+    assert allowlisted_advisory is None
 
 
 def test_malformed_allowlist_json_is_ignored(tmp_path: Path) -> None:
     _init_repo(tmp_path)
     _write_raw_allowlist(tmp_path, "{ this is not valid json ")
 
-    deny_reason = _BLOCKER.evaluate(
+    deny_reason, advisory_message = _evaluate_advisory(
         _markdown_write_payload(tmp_path, "Please submit the release notes.")
     )
 
-    assert deny_reason is not None and "submit" in deny_reason
+    assert deny_reason is None
+    assert advisory_message is not None and "submit" in advisory_message
 
 
 def test_allowlist_in_a_different_project_root_is_not_applied(tmp_path: Path) -> None:
@@ -135,43 +168,54 @@ def test_allowlist_in_a_different_project_root_is_not_applied(tmp_path: Path) ->
     project_without_allowlist = _init_repo(tmp_path / "project_b")
     _write_allowlist(project_with_allowlist, ["submit"])
 
-    deny_reason = _BLOCKER.evaluate(
+    deny_reason, advisory_message = _evaluate_advisory(
         _markdown_write_payload(project_without_allowlist, "Please submit the notes.")
     )
 
-    assert deny_reason is not None and "submit" in deny_reason
+    assert deny_reason is None
+    assert advisory_message is not None and "submit" in advisory_message
 
 
 def test_allowlist_above_the_repo_root_is_not_applied(tmp_path: Path) -> None:
     _write_allowlist(tmp_path, ["submit"])
     repository_root = _init_repo(tmp_path / "repo")
 
-    deny_reason = _BLOCKER.evaluate(
+    deny_reason, advisory_message = _evaluate_advisory(
         _markdown_write_payload(repository_root, "Please submit the notes.")
     )
 
-    assert deny_reason is not None and "submit" in deny_reason
+    assert deny_reason is None
+    assert advisory_message is not None and "submit" in advisory_message
 
 
 def test_allowlist_at_the_repo_root_is_applied(tmp_path: Path) -> None:
     repository_root = _init_repo(tmp_path / "repo")
     _write_allowlist(repository_root, ["submit"])
 
-    deny_reason = _BLOCKER.evaluate(
+    deny_reason, advisory_message = _evaluate_advisory(
         _markdown_write_payload(repository_root, "Please submit the notes.")
     )
 
     assert deny_reason is None
+    assert advisory_message is None
 
 
 def test_allowlist_without_a_repo_root_is_not_applied(tmp_path: Path) -> None:
+    """An allowlist only applies when the walk finds a ``.git`` repository root.
+
+    The upward walk can hit a personal home ``.git`` on some developer machines,
+    so this case stubs the finder to the no-repository outcome rather than
+    relying on the ambient filesystem.
+    """
     _write_allowlist(tmp_path, ["submit"])
 
-    deny_reason = _BLOCKER.evaluate(
-        _markdown_write_payload(tmp_path, "Please submit the notes.")
-    )
+    with patch.object(_BLOCKER, "_find_project_allowlist_file", return_value=None):
+        deny_reason, advisory_message = _evaluate_advisory(
+            _markdown_write_payload(tmp_path, "Please submit the notes.")
+        )
 
-    assert deny_reason is not None and "submit" in deny_reason
+    assert deny_reason is None
+    assert advisory_message is not None and "submit" in advisory_message
 
 
 def test_find_banned_terms_skips_allowlisted_terms() -> None:

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -14,6 +14,7 @@ fail-open malformed input.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -39,13 +40,27 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402, I
     HostedHookEntry,
 )
 from pre_tool_use_dispatcher import (  # noqa: E402, I001
+    DispatcherDecision,
     HostedHookResult,
+    _emit_deny_decision,
     aggregate_hosted_hook_results,
     run_hosted_hook,
+    unique_first_seen_strings,
 )
 
 _DISPATCHER_SCRIPT = str(_BLOCKING_DIR / "pre_tool_use_dispatcher.py")
 
+_PROSE_STYLE_ENV_VAR = "CLAUDE_PROSE_STYLE_ENFORCEMENT"
+_PROSE_STYLE_ENV_VALUE = "1"
+
+
+def _subprocess_environment() -> dict[str, str]:
+    """Return process env with opinionated prose gates enabled for golden tests."""
+    environment_by_key = os.environ.copy()
+    environment_by_key[_PROSE_STYLE_ENV_VAR] = _PROSE_STYLE_ENV_VALUE
+    return environment_by_key
+
+
 _TEMP_FILE_PATH = str(_HOOKS_ROOT.parent.parent.parent / "tmp" / "dispatcher_test_dummy.txt")
 _MARKDOWN_FILE_PATH = str(_HOOKS_ROOT.parent.parent.parent / "tmp" / "dispatcher_test_dummy.md")
 
@@ -70,6 +85,7 @@ def _run_hook_subprocess(
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_subprocess_environment(),
     )
 
 
@@ -89,6 +105,7 @@ def _run_dispatcher(payload_text: str) -> subprocess.CompletedProcess[str]:
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_subprocess_environment(),
     )
 
 
@@ -272,8 +289,8 @@ def test_clean_write_allows_on_multi_edit_tool() -> None:
     _assert_dispatcher_matches_individual_hooks(payload_text, MULTI_EDIT_TOOL_NAME)
 
 
-def test_plain_language_denial_on_write_of_markdown_file() -> None:
-    """Dispatcher denies when plain_language_blocker denies a Write of heavy prose."""
+def test_plain_language_heavy_prose_allows_on_write_of_markdown_file() -> None:
+    """Dispatcher matches individual hooks: heavy prose allows (OP-07D advisory)."""
     payload_text = _write_payload(
         _MARKDOWN_FILE_PATH,
         "# Guide\n\nPlease utilize this functionality to commence the process.\n",
@@ -281,8 +298,8 @@ def test_plain_language_denial_on_write_of_markdown_file() -> None:
     _assert_dispatcher_matches_individual_hooks(payload_text, WRITE_TOOL_NAME)
 
 
-def test_plain_language_denial_on_edit_of_markdown_file() -> None:
-    """Dispatcher denies when plain_language_blocker denies an Edit with heavy prose."""
+def test_plain_language_heavy_prose_allows_on_edit_of_markdown_file() -> None:
+    """Dispatcher matches individual hooks: heavy prose Edit allows (OP-07D)."""
     payload_text = _edit_payload(
         _MARKDOWN_FILE_PATH,
         "old line",
@@ -291,8 +308,8 @@ def test_plain_language_denial_on_edit_of_markdown_file() -> None:
     _assert_dispatcher_matches_individual_hooks(payload_text, EDIT_TOOL_NAME)
 
 
-def test_plain_language_denial_on_multi_edit_of_markdown_file() -> None:
-    """Dispatcher denies when plain_language_blocker denies a MultiEdit with heavy prose."""
+def test_plain_language_heavy_prose_allows_on_multi_edit_of_markdown_file() -> None:
+    """Dispatcher matches individual hooks: heavy prose MultiEdit allows (OP-07D)."""
     payload_text = _multi_edit_payload(
         _MARKDOWN_FILE_PATH,
         [{"old_string": "old", "new_string": "Please utilize this functionality to commence."}],
@@ -312,13 +329,11 @@ def test_dispatcher_docstring_points_at_roster_not_hardcoded_counts() -> None:
 def test_multi_edit_runs_only_group_b_hooks() -> None:
     """Dispatcher invokes only Group-B hooks on MultiEdit, not Group-A hooks.
 
-    A plain_language_blocker denial on a MultiEdit proves Group B runs.
     The write_existing_file_blocker (Group A only) must not run on MultiEdit,
     so a MultiEdit to any path that would trip a Group-A hook must still allow.
-    This test proves Group A does not run on MultiEdit by asserting:
-    1. Group-B (plain_language_blocker) fires on MultiEdit for a markdown file
-       with heavy prose.
-    2. The set of applicable entries for MultiEdit contains no Group-A entries.
+    Heavy prose no longer denies (OP-07D); this test proves Group A is absent
+    from MultiEdit and that plain_language_blocker stays in the MultiEdit set
+    and still runs (allow-with-advisory on heavy prose).
     """
     all_multi_edit_entries = _applicable_entries_for_tool(MULTI_EDIT_TOOL_NAME)
     all_write_only_entries = [
@@ -334,15 +349,20 @@ def test_multi_edit_runs_only_group_b_hooks() -> None:
             f"Group-A hook {each_group_a_entry.script_relative_path!r} "
             "appears in the MultiEdit applicable set — it must not"
         )
+    assert "blocking/plain_language_blocker.py" in all_multi_edit_script_paths, (
+        "plain_language_blocker (Group B) must stay in the MultiEdit applicable set"
+    )
     heavy_prose_payload = _multi_edit_payload(
         _MARKDOWN_FILE_PATH,
         [{"old_string": "old line", "new_string": "Utilize this to commence the process."}],
     )
     dispatcher_result = _run_dispatcher(heavy_prose_payload)
     dispatcher_is_deny, _reason = _parse_hook_decision(dispatcher_result)
-    assert dispatcher_is_deny, (
-        "Dispatcher should deny a MultiEdit with heavy prose (plain_language_blocker "
-        "is a Group-B hook and must run on MultiEdit)"
+    assert not dispatcher_is_deny, (
+        "Dispatcher should allow MultiEdit heavy prose (OP-07D advisory path)"
+    )
+    assert dispatcher_result.stdout.strip(), (
+        "plain_language_blocker should emit an allow advisory on MultiEdit heavy prose"
     )
 
 
@@ -431,16 +451,17 @@ def test_context_survives_alongside_deny_reason(
 def test_all_deny_reasons_present_when_multiple_hooks_deny() -> None:
     """When two or more hooks deny, all their reasons appear in the dispatcher output.
 
-    Uses a Write to a .md file carrying both a historical phrase ("previously")
-    and a heavy word ("utilize") so state_description_blocker (Group A) and
-    plain_language_blocker (Group B) both deny deterministically with no
-    real-filesystem dependency.
+    Uses a Write to an existing markdown path with a historical phrase
+    ("previously") so write_existing_file_blocker and state_description_blocker
+    both deny. Heavy words no longer hard-deny (OP-07D), so plain_language is
+    not a denier.
     """
+    existing_markdown_path = str(Path(__file__).resolve().parent / "CLAUDE.md")
     multi_deny_content = (
         "# Guide\n\n"
-        "Previously the system utilized a different mechanism.\n"
+        "Previously the system used a different mechanism.\n"
     )
-    payload_text = _write_payload(_MARKDOWN_FILE_PATH, multi_deny_content)
+    payload_text = _write_payload(existing_markdown_path, multi_deny_content)
     _assert_dispatcher_matches_individual_hooks(payload_text, WRITE_TOOL_NAME)
 
     dispatcher_result = _run_dispatcher(payload_text)
@@ -457,8 +478,8 @@ def test_all_deny_reasons_present_when_multiple_hooks_deny() -> None:
 
     assert len(all_expected_deny_reasons) >= 2, (
         f"Test payload must trip at least two hooks — got {len(all_expected_deny_reasons)}. "
-        "Check that 'previously' triggers state_description_blocker and 'utilized' "
-        "triggers plain_language_blocker on a .md Write."
+        "Check that an existing path triggers write_existing_file_blocker and "
+        "'previously' triggers state_description_blocker on a Write."
     )
     for each_reason in all_expected_deny_reasons:
         assert each_reason in dispatcher_reason, (
@@ -613,16 +634,68 @@ def test_aggregate_explicit_allow_is_overridden_by_a_deny() -> None:
     )
 
 
+def test_unique_first_seen_strings_keeps_order_and_drops_exact_duplicates() -> None:
+    assert unique_first_seen_strings(["a", "b", "a", "c", "b"]) == ["a", "b", "c"]
+    assert unique_first_seen_strings(["Same", "same"]) == ["Same", "same"]
+
+
+def test_emit_deny_collapses_identical_reasons_and_context(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Final JSON keeps each exact string once; distinct reasons stay; suppress stays."""
+    shared_text = "BLOCKED: same corrective text"
+    decision = DispatcherDecision(
+        should_deny=True,
+        should_allow=False,
+        all_deny_reasons=[shared_text, "BLOCKED: other reason", shared_text],
+        all_system_messages=[shared_text, shared_text, "other notice"],
+        all_additional_context=["ctx-a", "ctx-a", "ctx-b"],
+        should_suppress_output=True,
+    )
+    _emit_deny_decision(decision)
+    captured = capsys.readouterr().out
+    parsed = json.loads(captured)
+    reason = parsed["hookSpecificOutput"]["permissionDecisionReason"]
+    assert reason == f"{shared_text} | BLOCKED: other reason"
+    assert reason.count(shared_text) == 1
+    system_message = parsed["systemMessage"]
+    assert system_message == f"{shared_text}\nother notice"
+    assert parsed["hookSpecificOutput"]["additionalContext"] == "ctx-a\nctx-b"
+    assert parsed["suppressOutput"] is True
+    assert parsed["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_emit_deny_does_not_cross_collapse_reason_and_context(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A deny reason equal to a systemMessage string stays in both fields."""
+    shared_text = "identical across fields"
+    decision = DispatcherDecision(
+        should_deny=True,
+        should_allow=False,
+        all_deny_reasons=[shared_text],
+        all_system_messages=[shared_text],
+        all_additional_context=[shared_text],
+        should_suppress_output=False,
+    )
+    _emit_deny_decision(decision)
+    parsed = json.loads(capsys.readouterr().out)
+    assert parsed["hookSpecificOutput"]["permissionDecisionReason"] == shared_text
+    assert parsed["systemMessage"] == shared_text
+    assert parsed["hookSpecificOutput"]["additionalContext"] == shared_text
+
+
 def test_later_hook_deny_survives_early_hook_exit() -> None:
     """Dispatcher denies even when an earlier hook exits cleanly before a later hook denies.
 
-    plain_language_blocker (Group B, last in order) denies a markdown write with heavy
-    prose. Earlier hooks exit 0 (allow). The dispatcher must catch each hook's
-    SystemExit and continue, so the later denial reaches the aggregator.
+    state_description_blocker denies a markdown write with a historical phrase.
+    Earlier hooks exit 0 (allow). Heavy words no longer hard-deny (OP-07D). The
+    dispatcher must catch each hook's SystemExit and continue, so the later
+    denial reaches the aggregator.
     """
     payload_text = _write_payload(
         _MARKDOWN_FILE_PATH,
-        "# Doc\n\nThis section attempts to facilitate the utilization of this functionality.\n",
+        "# Doc\n\nPreviously this section used a different mechanism.\n",
     )
     _assert_dispatcher_matches_individual_hooks(payload_text, WRITE_TOOL_NAME)