claude-dev-env 2.8.0 → 2.10.0

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)
 

package/hooks/blocking/test_pre_tool_use_dispatcher_native.py

@@ -13,14 +13,22 @@ equivalence holds across both outcomes.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
+from unittest.mock import patch
+
+import pytest
 
 _HOOKS_DIR = str(Path(__file__).resolve().parent.parent)
 if _HOOKS_DIR not in sys.path:
     sys.path.insert(0, _HOOKS_DIR)
 
+_PROSE_STYLE_ENFORCEMENT_ENVIRONMENT = {
+    "CLAUDE_PROSE_STYLE_ENFORCEMENT": "1",
+}
+
 from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: E402, I001
     DENY_DECISION,
     EDIT_TOOL_NAME,
@@ -43,6 +51,19 @@ _STATE_DESCRIPTION_DENY_CONTENT = "# Guide\n\nPreviously the system used port 80
 _PLAIN_LANGUAGE_ALLOW_CONTENT = "# Guide\n\nStart the build to make the report.\n"
 _PLAIN_LANGUAGE_DENY_CONTENT = "# Guide\n\nUtilize this to commence the process.\n"
 
+_PROSE_STYLE_ENV_VAR = "CLAUDE_PROSE_STYLE_ENFORCEMENT"
+_PROSE_STYLE_ENV_VALUE = "1"
+
+@pytest.fixture(autouse=True)
+def enable_prose_style_enforcement(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Opinionated prose gates are default-off; native-equivalence tests arm them."""
+    monkeypatch.setenv(_PROSE_STYLE_ENV_VAR, _PROSE_STYLE_ENV_VALUE)
+
+def _subprocess_environment() -> dict[str, str]:
+    """Return process env with opinionated prose gates enabled."""
+    environment_by_key = os.environ.copy()
+    environment_by_key[_PROSE_STYLE_ENV_VAR] = _PROSE_STYLE_ENV_VALUE
+    return environment_by_key
 
 def _write_payload_dictionary(file_path: str, content: str) -> dict[str, object]:
     """Build a Write tool payload dict.
@@ -59,7 +80,6 @@ def _write_payload_dictionary(file_path: str, content: str) -> dict[str, object]
         "tool_input": {"file_path": file_path, "content": content},
     }
 
-
 def _edit_payload_dictionary(file_path: str, new_string: str) -> dict[str, object]:
     """Build an Edit tool payload dict.
 
@@ -79,7 +99,6 @@ def _edit_payload_dictionary(file_path: str, new_string: str) -> dict[str, objec
         },
     }
 
-
 def _multi_edit_payload_dictionary(file_path: str, new_string: str) -> dict[str, object]:
     """Build a MultiEdit tool payload dict.
 
@@ -99,6 +118,14 @@ def _multi_edit_payload_dictionary(file_path: str, new_string: str) -> dict[str,
     }
 
 
+def _evaluate_with_prose_style_opt_in(
+    evaluate_callable: object, payload_dictionary: dict[str, object]
+) -> str | None:
+    """Call a native evaluate with opinionated prose enforcement enabled."""
+    with patch.dict(os.environ, _PROSE_STYLE_ENFORCEMENT_ENVIRONMENT):
+        return evaluate_callable(payload_dictionary)  # type: ignore[operator]
+
+
 def _run_script_subprocess(script_path: str, payload_dictionary: dict[str, object]) -> str:
     """Run a hook script as a subprocess and return its stripped stdout.
 
@@ -116,10 +143,10 @@ def _run_script_subprocess(script_path: str, payload_dictionary: dict[str, objec
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_subprocess_environment(),
     )
     return completed_process.stdout.strip()
 
-
 def _deny_reason_from_script_stdout(stdout_text: str) -> str | None:
     """Parse a script's stdout into its deny-reason text, or None for allow.
 
@@ -139,7 +166,6 @@ def _deny_reason_from_script_stdout(stdout_text: str) -> str | None:
     reason_text = hook_specific.get("permissionDecisionReason", "")
     return reason_text if isinstance(reason_text, str) else None
 
-
 def _deny_reason_from_dispatcher(payload_dictionary: dict[str, object]) -> str | None:
     """Run the dispatcher as a subprocess and return its deny-reason text.
 
@@ -157,10 +183,10 @@ def _deny_reason_from_dispatcher(payload_dictionary: dict[str, object]) -> str |
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_subprocess_environment(),
     )
     return _deny_reason_from_script_stdout(completed_process.stdout.strip())
 
-
 def _deny_payload_from_dispatcher(payload_dictionary: dict[str, object]) -> dict[str, object]:
     """Run the dispatcher as a subprocess and return its parsed deny payload.
 
@@ -177,145 +203,157 @@ def _deny_payload_from_dispatcher(payload_dictionary: dict[str, object]) -> dict
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_subprocess_environment(),
     )
     parsed_payload = json.loads(completed_process.stdout.strip())
     assert isinstance(parsed_payload, dict)
     return parsed_payload
 
-
 def test_state_description_native_allows_match_script() -> None:
     """state_description_blocker native allow matches the script's allow."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _STATE_DESCRIPTION_ALLOW_CONTENT)
-    native_reason = state_description_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_STATE_DESCRIPTION_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is None
     assert script_reason is None
 
-
 def test_state_description_native_deny_matches_script_reason() -> None:
     """state_description_blocker native deny reason matches the script's reason."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _STATE_DESCRIPTION_DENY_CONTENT)
-    native_reason = state_description_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_STATE_DESCRIPTION_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is not None
     assert native_reason == script_reason
 
-
 def test_state_description_native_edit_deny_matches_script_reason() -> None:
     """state_description_blocker native and script agree on an Edit denial."""
     payload_dictionary = _edit_payload_dictionary(
         _MARKDOWN_PATH, "Previously this used the old client.\n"
     )
-    native_reason = state_description_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_STATE_DESCRIPTION_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is not None
     assert native_reason == script_reason
 
-
 def test_state_description_native_non_target_tool_allows_match_script() -> None:
     """state_description_blocker native allows MultiEdit, matching the script."""
     payload_dictionary = _multi_edit_payload_dictionary(
         _MARKDOWN_PATH, _STATE_DESCRIPTION_DENY_CONTENT
     )
-    native_reason = state_description_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_STATE_DESCRIPTION_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is None
     assert script_reason is None
 
-
 def test_plain_language_native_allows_match_script() -> None:
     """plain_language_blocker native allow matches the script's allow."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _PLAIN_LANGUAGE_ALLOW_CONTENT)
-    native_reason = plain_language_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(plain_language_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_PLAIN_LANGUAGE_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is None
     assert script_reason is None
 
 
-def test_plain_language_native_deny_matches_script_reason() -> None:
-    """plain_language_blocker native deny reason matches the script's reason."""
+def test_plain_language_native_heavy_word_advisory_matches_script() -> None:
+    """plain_language_blocker native and script agree: no deny, allow advisory."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _PLAIN_LANGUAGE_DENY_CONTENT)
-    native_reason = plain_language_blocker.evaluate(payload_dictionary)
+    with patch.dict(os.environ, _PROSE_STYLE_ENFORCEMENT_ENVIRONMENT):
+        native_deny, native_advisory = plain_language_blocker.evaluate_with_advisory(
+            payload_dictionary
+        )
     script_stdout = _run_script_subprocess(_PLAIN_LANGUAGE_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
-    assert native_reason is not None
-    assert native_reason == script_reason
+    assert native_deny is None
+    assert script_reason is None
+    assert native_advisory is not None
+    assert "utilize" in native_advisory.lower() or "commence" in native_advisory.lower()
+    script_payload = json.loads(script_stdout)
+    assert script_payload["hookSpecificOutput"]["permissionDecision"] == "allow"
+    assert native_advisory in script_payload["systemMessage"]
 
 
-def test_plain_language_native_multi_edit_deny_matches_script_reason() -> None:
-    """plain_language_blocker native and script agree on a MultiEdit denial."""
+def test_plain_language_native_multi_edit_heavy_word_advisory_matches_script() -> None:
+    """plain_language_blocker native and script agree on MultiEdit heavy-word allow."""
     payload_dictionary = _multi_edit_payload_dictionary(
         _MARKDOWN_PATH, "Utilize this to commence the process.\n"
     )
-    native_reason = plain_language_blocker.evaluate(payload_dictionary)
+    with patch.dict(os.environ, _PROSE_STYLE_ENFORCEMENT_ENVIRONMENT):
+        native_deny, native_advisory = plain_language_blocker.evaluate_with_advisory(
+            payload_dictionary
+        )
     script_stdout = _run_script_subprocess(_PLAIN_LANGUAGE_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
-    assert native_reason is not None
-    assert native_reason == script_reason
-
+    assert native_deny is None
+    assert script_reason is None
+    assert native_advisory is not None
+    script_payload = json.loads(script_stdout)
+    assert script_payload["hookSpecificOutput"]["permissionDecision"] == "allow"
+    assert native_advisory in script_payload["systemMessage"]
 
 def test_plain_language_native_non_markdown_allows_match_script() -> None:
     """plain_language_blocker native allows a non-markdown Write, matching the script."""
     payload_dictionary = _write_payload_dictionary(_PYTHON_PATH, _PLAIN_LANGUAGE_DENY_CONTENT)
-    native_reason = plain_language_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(plain_language_blocker.evaluate, payload_dictionary)
     script_stdout = _run_script_subprocess(_PLAIN_LANGUAGE_SCRIPT, payload_dictionary)
     script_reason = _deny_reason_from_script_stdout(script_stdout)
     assert native_reason is None
     assert script_reason is None
 
-
 def test_dispatcher_native_path_denies_state_description() -> None:
     """The dispatcher's native path denies a state_description_blocker violation."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _STATE_DESCRIPTION_DENY_CONTENT)
-    native_reason = state_description_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     dispatcher_reason = _deny_reason_from_dispatcher(payload_dictionary)
     assert native_reason is not None
     assert dispatcher_reason is not None
     assert native_reason in dispatcher_reason
 
 
-def test_dispatcher_native_path_denies_plain_language() -> None:
-    """The dispatcher's native path denies a plain_language_blocker violation."""
+def test_dispatcher_native_path_allows_plain_language_heavy_word() -> None:
+    """The dispatcher's native path allows heavy words and does not deny."""
     payload_dictionary = _multi_edit_payload_dictionary(
         _MARKDOWN_PATH, "Utilize this to commence the process.\n"
     )
-    native_reason = plain_language_blocker.evaluate(payload_dictionary)
+    native_reason = _evaluate_with_prose_style_opt_in(
+        plain_language_blocker.evaluate, payload_dictionary
+    )
     dispatcher_reason = _deny_reason_from_dispatcher(payload_dictionary)
-    assert native_reason is not None
-    assert dispatcher_reason is not None
-    assert native_reason in dispatcher_reason
+    assert native_reason is None
+    assert dispatcher_reason is None
 
 
-def test_dispatcher_native_plain_language_carries_system_message() -> None:
-    """The dispatcher's plain-language deny carries the standalone systemMessage."""
+def test_dispatcher_native_plain_language_carries_advisory_system_message() -> None:
+    """The dispatcher's plain-language allow carries the advisory systemMessage."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _PLAIN_LANGUAGE_DENY_CONTENT)
-    deny_reason = plain_language_blocker.evaluate(payload_dictionary)
-    assert deny_reason is not None
-    standalone_payload = plain_language_blocker.build_deny_payload(deny_reason)
-    expected_system_message = standalone_payload["systemMessage"]
-    assert isinstance(expected_system_message, str)
+    with patch.dict(os.environ, _PROSE_STYLE_ENFORCEMENT_ENVIRONMENT):
+        deny_reason, advisory_message = plain_language_blocker.evaluate_with_advisory(
+            payload_dictionary
+        )
+    assert deny_reason is None
+    assert advisory_message is not None
     dispatcher_payload = _deny_payload_from_dispatcher(payload_dictionary)
+    assert dispatcher_payload["hookSpecificOutput"]["permissionDecision"] == "allow"
     dispatcher_system_message = dispatcher_payload.get("systemMessage")
     assert isinstance(dispatcher_system_message, str)
-    assert expected_system_message in dispatcher_system_message
+    assert advisory_message in dispatcher_system_message
 
 
-def test_dispatcher_native_plain_language_carries_suppress_output() -> None:
-    """The dispatcher's plain-language deny carries the standalone suppressOutput flag."""
+def test_dispatcher_native_plain_language_allow_does_not_suppress_output() -> None:
+    """The dispatcher's plain-language advisory allow leaves suppressOutput off."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _PLAIN_LANGUAGE_DENY_CONTENT)
     dispatcher_payload = _deny_payload_from_dispatcher(payload_dictionary)
-    assert dispatcher_payload.get("suppressOutput") is True
-
+    assert dispatcher_payload.get("suppressOutput") is not True
+    assert dispatcher_payload["hookSpecificOutput"]["permissionDecision"] == "allow"
 
 def test_dispatcher_native_state_description_carries_additional_context() -> None:
     """The dispatcher's state-description deny carries the standalone additionalContext."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _STATE_DESCRIPTION_DENY_CONTENT)
-    deny_reason = state_description_blocker.evaluate(payload_dictionary)
+    deny_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     assert deny_reason is not None
     standalone_payload = state_description_blocker.build_deny_payload(deny_reason)
     standalone_hook_specific = standalone_payload["hookSpecificOutput"]
@@ -326,11 +364,10 @@ def test_dispatcher_native_state_description_carries_additional_context() -> Non
     assert isinstance(dispatcher_hook_specific, dict)
     assert dispatcher_hook_specific.get("additionalContext") == expected_additional_context
 
-
 def test_dispatcher_native_state_description_carries_system_message() -> None:
     """The dispatcher's state-description deny carries the standalone systemMessage."""
     payload_dictionary = _write_payload_dictionary(_MARKDOWN_PATH, _STATE_DESCRIPTION_DENY_CONTENT)
-    deny_reason = state_description_blocker.evaluate(payload_dictionary)
+    deny_reason = _evaluate_with_prose_style_opt_in(state_description_blocker.evaluate, payload_dictionary)
     assert deny_reason is not None
     standalone_payload = state_description_blocker.build_deny_payload(deny_reason)
     expected_system_message = standalone_payload["systemMessage"]

package/hooks/blocking/test_state_description_blocker.py

@@ -19,8 +19,8 @@ if _HOOKS_ROOT not in sys.path:
 from pre_tool_use_dispatcher import NativeHook, run_native_hook  # noqa: E402
 from state_description_blocker import (  # noqa: E402
     build_deny_payload,
-    evaluate,
 )
+from state_description_blocker import evaluate as _evaluate_without_opt_in  # noqa: E402
 
 HOOK_SCRIPT_PATH = os.path.join(
     os.path.dirname(__file__), "state_description_blocker.py"
@@ -39,23 +39,66 @@ VIOLATION_MD_PREVIOUSLY = "# Config\n\nPreviously set via env var."
 VIOLATION_MD_NOW_USES = "# Auth\n\nNow uses OAuth2."
 
 
+def evaluate(payload_by_key: dict[str, object]) -> str | None:
+    """Call evaluate with opinionated prose enforcement enabled."""
+    with patch.dict(os.environ, {"CLAUDE_PROSE_STYLE_ENFORCEMENT": "1"}):
+        return _evaluate_without_opt_in(payload_by_key)
+
+
 class _RunHook:
     """Helper to test the hook via subprocess."""
 
-    def __call__(self, tool_name: str, tool_input: dict) -> subprocess.CompletedProcess:
+    def __call__(
+        self,
+        tool_name: str,
+        tool_input: dict,
+        *,
+        is_prose_style_enabled: bool = True,
+    ) -> subprocess.CompletedProcess:
         payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
+        environment_by_key = os.environ.copy()
+        if is_prose_style_enabled:
+            environment_by_key["CLAUDE_PROSE_STYLE_ENFORCEMENT"] = "1"
+        else:
+            environment_by_key.pop("CLAUDE_PROSE_STYLE_ENFORCEMENT", None)
         return subprocess.run(
             [sys.executable, HOOK_SCRIPT_PATH],
             input=payload,
             capture_output=True,
             text=True,
             check=False,
+            env=environment_by_key,
         )
 
 
 _run_hook = _RunHook()
 
 
+def test_historical_phrase_scan_is_default_off(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    result = _run_hook(
+        "Write",
+        {
+            "file_path": "src/main.py",
+            "content": VIOLATION_INSTEAD_OF_COMMENT,
+        },
+        is_prose_style_enabled=False,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+    assert _evaluate_without_opt_in(
+        {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": "src/main.py",
+                "content": VIOLATION_INSTEAD_OF_COMMENT,
+            },
+        }
+    ) is None
+
+
 def test_block_clean_python_comment_passes():
     result = _run_hook(
         "Write",