claude-dev-env 2.8.0 → 2.10.0

package/hooks/blocking/test_intent_only_ending_blocker.py

@@ -42,24 +42,40 @@ USER_DIRECTED_NEXT_STEPS_MESSAGE = (
 EMPTY_MESSAGE = ""
 
 
-def run_hook_with_message(assistant_message: str) -> subprocess.CompletedProcess:
+def run_hook_with_message(
+    assistant_message: str, *, is_prose_style_enabled: bool = True
+) -> subprocess.CompletedProcess:
     hook_input_payload = json.dumps({"last_assistant_message": assistant_message})
+    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=hook_input_payload,
         capture_output=True,
         text=True,
         check=False,
+        env=environment_by_key,
     )
 
 
-def run_hook_with_payload(hook_input_payload: dict) -> subprocess.CompletedProcess:
+def run_hook_with_payload(
+    hook_input_payload: dict, *, is_prose_style_enabled: bool = True
+) -> subprocess.CompletedProcess:
+    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=json.dumps(hook_input_payload),
         capture_output=True,
         text=True,
         check=False,
+        env=environment_by_key,
     )
 
 
@@ -76,6 +92,15 @@ def test_user_facing_notice_matches_config_messages_module():
     )
 
 
+def test_intent_scan_is_default_off() -> None:
+    completed_process = run_hook_with_message(
+        INTENT_ENDING_MESSAGE, is_prose_style_enabled=False
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
 def test_intent_ending_message_emits_block_with_short_user_notice():
     completed_process = run_hook_with_message(INTENT_ENDING_MESSAGE)
 

package/hooks/blocking/test_package_inventory_stale_blocker.py

@@ -367,9 +367,16 @@ def test_find_stale_inventory_returns_survey_for_omission(tmp_path: Path):
     assert survey.named_basenames == {"dialer_compose.py", "compose_dialer_cli.py"}
 
 
-def test_find_stale_inventory_skips_prose_only_directory():
-    audit_rubrics_directory = (
-        Path(__file__).resolve().parent.parent.parent / "audit-rubrics"
+def test_find_stale_inventory_skips_directory_below_minimum_named_entries(
+    tmp_path: Path,
+) -> None:
+    """Skip a package inventory that names fewer than the minimum on-disk siblings."""
+    package_directory = tmp_path / "prose_package"
+    package_directory.mkdir()
+    (package_directory / "CLAUDE.md").write_text(
+        "| File | Role |\n|---|---|\n| `only_one.py` | sole entry |\n",
+        encoding="utf-8",
     )
-    new_file_path = audit_rubrics_directory / "new_helper.py"
+    (package_directory / "only_one.py").write_text("FLAG = 1\n", encoding="utf-8")
+    new_file_path = package_directory / "new_helper.py"
     assert find_stale_inventory(str(new_file_path)) is None

package/hooks/blocking/test_plain_language_blocker.py

@@ -42,18 +42,31 @@ strip_non_prose_regions = hook_module.strip_non_prose_regions
 build_block_reason = hook_module.build_block_reason
 find_question_block_violations = hook_module.find_question_block_violations
 build_lean_block_reason = hook_module.build_lean_block_reason
-evaluate = hook_module.evaluate
+
+
+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 hook_module.evaluate(payload_by_key)
 
 from pre_tool_use_dispatcher import NativeHook, run_native_hook  # noqa: E402
 
 
-def _run_hook_with_payload(payload: dict) -> subprocess.CompletedProcess[str]:
+def _run_hook_with_payload(
+    payload: dict, *, is_prose_style_enabled: bool = True
+) -> subprocess.CompletedProcess[str]:
+    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, str(HOOK_SCRIPT_PATH)],
         input=json.dumps(payload),
         capture_output=True,
         text=True,
         check=False,
+        env=environment_by_key,
     )
 
 
@@ -64,10 +77,81 @@ def _decision_from(completed: subprocess.CompletedProcess[str]) -> str | None:
     return parsed.get("hookSpecificOutput", {}).get("permissionDecision")
 
 
+def _system_message_from(completed: subprocess.CompletedProcess[str]) -> str | None:
+    if not completed.stdout:
+        return None
+    parsed = json.loads(completed.stdout)
+    system_message = parsed.get("systemMessage")
+    return system_message if isinstance(system_message, str) else None
+
+
 def test_canonical_hook_script_exists_at_expected_path() -> None:
     assert HOOK_SCRIPT_PATH.is_file()
 
 
+def test_heavy_word_scan_is_default_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": "notes.md",
+            "content": "We initiate the worker pool at boot.",
+        },
+    }
+    assert hook_module.evaluate(payload) is None
+    completed = _run_hook_with_payload(payload, is_prose_style_enabled=False)
+    assert _decision_from(completed) is None
+
+
+def test_default_off_emits_privacy_safe_advisory_candidates(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    all_emitted: list[tuple[str, str, str]] = []
+
+    def _record_advisory(
+        matcher_id: str, surface: str, context_text: str, **_kwargs: object
+    ) -> dict[str, object]:
+        all_emitted.append((matcher_id, surface, context_text))
+        return {}
+
+    monkeypatch.setattr(hook_module, "emit_advisory_candidate", _record_advisory)
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": "notes.md",
+            "content": "We initiate the worker pool at boot.",
+        },
+    }
+    assert hook_module.evaluate(payload) is None
+    assert all_emitted
+    matcher_id, surface, context_text = all_emitted[0]
+    assert matcher_id == "plain_language_heavy_word"
+    assert surface == "Write"
+    assert "initiate" in context_text
+
+
+def test_heavy_word_scan_opt_in_allows_with_system_message_swaps() -> None:
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": "notes.md",
+            "content": "We initiate the worker pool at boot.",
+        },
+    }
+    assert evaluate(payload) is None
+    with patch.dict(os.environ, {"CLAUDE_PROSE_STYLE_ENFORCEMENT": "1"}):
+        deny_reason, advisory_message = hook_module.evaluate_with_advisory(payload)
+    assert deny_reason is None
+    assert advisory_message is not None
+    assert 'use "start" instead of "initiate"' in advisory_message
+    completed = _run_hook_with_payload(payload, is_prose_style_enabled=True)
+    assert _decision_from(completed) == "allow"
+    system_message = _system_message_from(completed)
+    assert system_message is not None
+    assert 'use "start" instead of "initiate"' in system_message
+
+
 def test_bare_prose_banned_term_is_detected() -> None:
     matched = find_banned_terms("We initiate the worker pool at boot.")
     assert any(each_term == "initiate" for each_term, _replacement in matched)
@@ -127,7 +211,7 @@ def test_block_reason_names_term_and_replacement() -> None:
     assert "start" in reason
 
 
-def test_ask_user_question_with_banned_term_is_denied() -> None:
+def test_ask_user_question_with_banned_term_is_advisory_allow() -> None:
     payload = {
         "tool_name": "AskUserQuestion",
         "tool_input": {
@@ -141,10 +225,13 @@ def test_ask_user_question_with_banned_term_is_denied() -> None:
         },
     }
     completed = _run_hook_with_payload(payload)
-    assert _decision_from(completed) == "deny"
+    assert _decision_from(completed) == "allow"
+    system_message = _system_message_from(completed)
+    assert system_message is not None
+    assert "utilize" in system_message
 
 
-def test_ask_user_question_banned_term_in_option_label_is_denied() -> None:
+def test_ask_user_question_banned_term_in_option_label_is_advisory_allow() -> None:
     payload = {
         "tool_name": "AskUserQuestion",
         "tool_input": {
@@ -158,7 +245,10 @@ def test_ask_user_question_banned_term_in_option_label_is_denied() -> None:
         },
     }
     completed = _run_hook_with_payload(payload)
-    assert _decision_from(completed) == "deny"
+    assert _decision_from(completed) == "allow"
+    system_message = _system_message_from(completed)
+    assert system_message is not None
+    assert "utilize" in system_message
 
 
 def test_clean_ask_user_question_passes_through() -> None:
@@ -178,7 +268,7 @@ def test_clean_ask_user_question_passes_through() -> None:
     assert _decision_from(completed) is None
 
 
-def test_write_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
+def test_write_markdown_with_banned_term_is_advisory_allow(tmp_path: Path) -> None:
     target = tmp_path / "notes.md"
     payload = {
         "tool_name": "Write",
@@ -188,7 +278,10 @@ def test_write_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
         },
     }
     completed = _run_hook_with_payload(payload)
-    assert _decision_from(completed) == "deny"
+    assert _decision_from(completed) == "allow"
+    system_message = _system_message_from(completed)
+    assert system_message is not None
+    assert "utilize" in system_message
 
 
 def test_write_markdown_at_ephemeral_path_is_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -230,7 +323,7 @@ def test_edit_markdown_clean_content_passes_through(tmp_path: Path) -> None:
     assert _decision_from(completed) is None
 
 
-def test_multiedit_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
+def test_multiedit_markdown_with_banned_term_is_advisory_allow(tmp_path: Path) -> None:
     target = tmp_path / "notes.md"
     payload = {
         "tool_name": "MultiEdit",
@@ -243,7 +336,10 @@ def test_multiedit_markdown_with_banned_term_is_denied(tmp_path: Path) -> None:
         },
     }
     completed = _run_hook_with_payload(payload)
-    assert _decision_from(completed) == "deny"
+    assert _decision_from(completed) == "allow"
+    system_message = _system_message_from(completed)
+    assert system_message is not None
+    assert "utilize" in system_message
 
 
 def test_other_tool_is_ignored() -> None:
@@ -270,19 +366,24 @@ def test_real_file_path_is_still_stripped() -> None:
 
 
 def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
-    """A deny routed through the dispatcher's native path logs one record.
+    """A lean-block deny routed through the dispatcher's native path logs once.
 
     On the Write|Edit|MultiEdit surface this hook runs only through
     pre_tool_use_dispatcher's native path, which calls evaluate() and
-    build_deny_payload() — never _emit_deny() or main(). The block must still
-    land in the hook-blocks log, so the log call lives on build_deny_payload,
-    the function the native path executes.
+    build_deny_payload() — never _emit_deny() or main(). Heavy words no longer
+    deny (OP-07D), so this probe uses AskUserQuestion lean-block chat detail.
+    The log call still lives on build_deny_payload.
     """
     deny_payload = {
-        "tool_name": "Edit",
+        "tool_name": "AskUserQuestion",
         "tool_input": {
-            "file_path": str(tmp_path / "notes.md"),
-            "new_string": "This guide explains how to utilize the new cache layer.",
+            "questions": [
+                {
+                    "question": "Which gate should run first?\n\nPlan the whole stack.",
+                    "header": "Gate",
+                    "options": [{"label": "Write", "description": "Runs on write."}],
+                }
+            ]
         },
     }
     native_hook = NativeHook(
@@ -291,7 +392,9 @@ def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
     )
 
     with patch.object(Path, "home", return_value=tmp_path):
-        hosted_result = run_native_hook(native_hook, deny_payload, is_blocking=True)
+        hosted_result = run_native_hook(
+            native_hook, deny_payload, is_blocking=True
+        )
 
     assert hosted_result.captured_stdout
     log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
@@ -527,7 +630,14 @@ def test_markdown_write_keeps_its_bullets_and_tables(tmp_path: Path) -> None:
         "tool_input": {"file_path": target_path, "content": bulleted_prose},
     }
 
-    assert evaluate(heavy_payload) is not None
+    assert evaluate(heavy_payload) is None
+    with patch.dict(os.environ, {"CLAUDE_PROSE_STYLE_ENFORCEMENT": "1"}):
+        _deny_reason, advisory_message = hook_module.evaluate_with_advisory(
+            heavy_payload
+        )
+    assert _deny_reason is None
+    assert advisory_message is not None
+    assert "utilize" in advisory_message
     assert evaluate(clean_payload) is None
 
 

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: