claude-dev-env 2.9.0 → 2.10.0

package/hooks/blocking/config/test_prose_style_enforcement_constants.py

@@ -0,0 +1,45 @@
+"""Tests for the prose-style enforcement opt-in flag (default off)."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_CONSTANTS_PATH = Path(__file__).resolve().parent / "prose_style_enforcement_constants.py"
+
+
+def _load_constants_module(monkeypatch: pytest.MonkeyPatch, env_value: str | None):
+    module_name = "prose_style_enforcement_constants_under_test"
+    if env_value is None:
+        monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    else:
+        monkeypatch.setenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", env_value)
+    module_spec = importlib.util.spec_from_file_location(module_name, _CONSTANTS_PATH)
+    assert module_spec is not None and module_spec.loader is not None
+    module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(module)
+    return module
+
+
+def test_absent_env_is_default_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    module = _load_constants_module(monkeypatch, None)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False
+    assert module.prose_style_enforcement_enabled_in_environment() is False
+
+
+@pytest.mark.parametrize("enabled_value", ["1", "true", "yes", "on", " True "])
+def test_truthy_env_enables(
+    monkeypatch: pytest.MonkeyPatch, enabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, enabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is True
+
+
+@pytest.mark.parametrize("disabled_value", ["0", "false", "no", "off", ""])
+def test_falsy_env_stays_off(
+    monkeypatch: pytest.MonkeyPatch, disabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, disabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False

package/hooks/blocking/eli11_reply_enforcer.py

@@ -1,15 +1,13 @@
 #!/usr/bin/env python3
 """
-Stop hook that blocks a final reply breaking the short action-first reply shape.
-
-The `eli11-replies` rule asks every chat reply to lead with the action, keep
-findings to a few bullets, and stay short. This hook reads the final assistant
-message, strips code fences, inline code, blockquotes, table rows, and link
-targets, then judges what a reader actually sees: the word count against a hard
-cap, whether numbered steps lead a reply that tells the user to act, the number
-of bullet lines, and how many lines pack more than one idea's worth of words.
-A reply opening with "Long form:" opts out, so a user-requested full report
-still goes through.
+Stop hook that blocks egregious reply-shape failures (action-first, bullets).
+
+The `eli11-replies` and `opus5-communication-contract` rules ask every chat
+reply to lead with the action when the user must act, keep findings to a few
+bullets, and stay scannable. This hook reads the final assistant message,
+strips code fences, inline code, blockquotes, table rows, and link targets,
+then judges shape only: multi-line instructions need numbered steps first,
+bullet count stays bounded, and list lines stay one-idea short.
 """
 
 import json
@@ -30,13 +28,10 @@ from hooks_constants.eli11_reply_enforcer_constants import (  # noqa: E402
     IMPERATIVE_OBJECT_TOKEN_PATTERN,
     LINK_TARGET_PATTERN,
     LIST_MARKER_PREFIX_PATTERN,
-    LONG_FORM_ESCAPE_PREFIX,
     MARKDOWN_LEAD_MARKER_PATTERN,
     MAXIMUM_BULLET_LINE_COUNT,
-    MAXIMUM_OVERPACKED_LINE_COUNT,
-    MAXIMUM_REPLY_WORD_COUNT,
-    MAXIMUM_WORDS_PER_LINE,
-    MINIMUM_ENFORCED_WORD_COUNT,
+    MAXIMUM_OVERPACKED_LIST_LINE_COUNT,
+    MAXIMUM_WORDS_PER_LIST_LINE,
     NUMBERED_STEP_PATTERN,
     TABLE_ROW_PATTERN,
     TARGET_BULLET_LINE_COUNT,
@@ -69,18 +64,6 @@ def extract_reply_prose(assistant_message: str) -> str:
     return LINK_TARGET_PATTERN.sub("", prose_text)
 
 
-def count_reply_words(prose_text: str) -> int:
-    """Return the number of reader-visible words in the stripped prose.
-
-    Args:
-        prose_text: Prose already cleaned of code, quotes, tables, and links.
-
-    Returns:
-        The count of whitespace-separated tokens carrying a letter or digit.
-    """
-    return len(COUNTABLE_WORD_PATTERN.findall(prose_text))
-
-
 def collect_non_empty_lines(prose_text: str) -> list[str]:
     """Return every line of the stripped prose that carries visible text.
 
@@ -249,29 +232,13 @@ def count_words_in_line(prose_line: str) -> int:
     return len(COUNTABLE_WORD_PATTERN.findall(unmarked_line))
 
 
-def count_overpacked_lines(all_prose_lines: list[str]) -> int:
-    """Return how many lines carry more words than one idea needs.
-
-    Args:
-        all_prose_lines: The non-empty lines of reply prose.
-
-    Returns:
-        The count of lines over the per-line word cap.
-    """
-    return sum(
-        1
-        for each_line in all_prose_lines
-        if count_words_in_line(each_line) > MAXIMUM_WORDS_PER_LINE
-    )
-
-
 def strip_markdown_lead_markers(prose_line: str) -> str:
     """Return a line with its opening blockquote, heading, and bold markers off.
 
     ::
 
-        in:  "> **Long form:** the report follows"
-        out: "Long form:** the report follows"
+        in:  "> **Bold lead:** the report follows"
+        out: "Bold lead:** the report follows"
 
     Args:
         prose_line: One line of raw reply text.
@@ -282,34 +249,37 @@ def strip_markdown_lead_markers(prose_line: str) -> str:
     return MARKDOWN_LEAD_MARKER_PATTERN.sub("", prose_line.strip(), count=1)
 
 
-def opens_with_long_form_escape(assistant_message: str) -> bool:
-    """Return True when the reply opts out through the Long form prefix.
+def is_list_item_line(prose_line: str) -> bool:
+    """Return True when a line is a bullet or numbered list item.
+
+    Args:
+        prose_line: One non-empty line of reply prose.
+
+    Returns:
+        True when the line opens with a bullet or numbered-step marker.
+    """
+    if BULLET_LINE_PATTERN.match(prose_line):
+        return True
+    return NUMBERED_STEP_PATTERN.match(prose_line) is not None
 
-    ::
 
-        ok:   "**Long form:** the report follows" -> True
-        flag: "The report follows"                -> False
+def count_overpacked_list_lines(all_prose_lines: list[str]) -> int:
+    """Return how many list lines carry more words than one idea needs.
 
-    A bold, blockquote, or heading wrapper around the prefix still opts out.
+    Plain paragraphs are not counted so a requested full report can use long
+    prose lines without a word ceiling.
 
     Args:
-        assistant_message: The raw final assistant message.
+        all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
-        True when the first line with content starts with the escape prefix.
+        The count of bullet/numbered lines over the per-list-line word cap.
     """
-    for each_line in assistant_message.splitlines():
-        if not each_line.strip():
-            continue
-        unwrapped_line = strip_markdown_lead_markers(each_line)
-        return unwrapped_line.lower().startswith(LONG_FORM_ESCAPE_PREFIX)
-    return False
-
-
-def describe_word_cap_violation(reply_word_count: int) -> str:
-    """Return the violation text naming the reply length and the cap."""
-    return (
-        f"{reply_word_count} words, over the {MAXIMUM_REPLY_WORD_COUNT}-word cap"
+    return sum(
+        1
+        for each_line in all_prose_lines
+        if is_list_item_line(each_line)
+        and count_words_in_line(each_line) > MAXIMUM_WORDS_PER_LIST_LINE
     )
 
 
@@ -317,70 +287,68 @@ def describe_bullet_cap_violation(bullet_line_count: int) -> str:
     """Return the violation text naming the bullet count and the target."""
     return (
         f"{bullet_line_count} bullets, over the {MAXIMUM_BULLET_LINE_COUNT}-bullet "
-        f"cap - cut findings to {TARGET_BULLET_LINE_COUNT} bullets"
+        f"cap - put findings in at most {TARGET_BULLET_LINE_COUNT} bullets"
     )
 
 
-def describe_overpacked_line_violation(overpacked_line_count: int) -> str:
-    """Return the violation text naming how many lines pack too much in."""
+def describe_overpacked_list_line_violation(overpacked_line_count: int) -> str:
+    """Return the violation text for overpacked list lines."""
     return (
-        f"{overpacked_line_count} lines carry too many words - one idea per line, "
-        f"at most {MAXIMUM_WORDS_PER_LINE} words each"
+        f"{overpacked_line_count} list lines carry too many words - one idea per "
+        f"bullet or step, at most {MAXIMUM_WORDS_PER_LIST_LINE} words each"
     )
 
 
 def describe_action_first_violation() -> str:
     """Return the violation text for instructions buried under prose."""
     return (
-        "the reply tells the user to act but leads with prose - put the steps "
-        "first, as a numbered list"
+        "the reply tells the user to act but leads with prose - open with "
+        "numbered steps, one short line each"
     )
 
 
-def is_action_first_violation(
-    reply_word_count: int, all_prose_lines: list[str]
-) -> bool:
-    """Return True when instructions sit below the lead of a long reply.
+def is_action_first_violation(all_prose_lines: list[str]) -> bool:
+    """Return True when multi-line instructions lack leading numbered steps.
+
+    ::
+
+        ok:   single-line "Run the migration." -> False
+        ok:   numbered steps first, then prose -> False
+        flag: prose then "Install the package." -> True
 
     Args:
-        reply_word_count: The reader-visible word count of the reply.
         all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
-        True when the reply is long, carries instruction lines, and shows no
-        numbered step among its lead lines.
+        True when the reply has more than one line, carries instruction
+        lines, and shows no numbered step among its lead lines.
     """
-    if reply_word_count < MINIMUM_ENFORCED_WORD_COUNT:
+    if len(all_prose_lines) <= 1:
         return False
     if not has_imperative_instruction_line(all_prose_lines):
         return False
     return not has_leading_numbered_step(all_prose_lines)
 
 
-def collect_shape_violations(
-    reply_word_count: int, all_prose_lines: list[str]
-) -> list[str]:
+def collect_shape_violations(all_prose_lines: list[str]) -> list[str]:
     """Return the violation texts for every reply-shape rule the reply breaks.
 
     Args:
-        reply_word_count: The reader-visible word count of the reply.
         all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
         One violation text per broken rule, empty when the reply is in shape.
     """
     all_violations: list[str] = []
-    if reply_word_count > MAXIMUM_REPLY_WORD_COUNT:
-        all_violations.append(describe_word_cap_violation(reply_word_count))
-    if is_action_first_violation(reply_word_count, all_prose_lines):
+    if is_action_first_violation(all_prose_lines):
         all_violations.append(describe_action_first_violation())
     bullet_line_count = count_bullet_lines(all_prose_lines)
     if bullet_line_count > MAXIMUM_BULLET_LINE_COUNT:
         all_violations.append(describe_bullet_cap_violation(bullet_line_count))
-    overpacked_line_count = count_overpacked_lines(all_prose_lines)
-    if overpacked_line_count > MAXIMUM_OVERPACKED_LINE_COUNT:
+    overpacked_list_line_count = count_overpacked_list_lines(all_prose_lines)
+    if overpacked_list_line_count > MAXIMUM_OVERPACKED_LIST_LINE_COUNT:
         all_violations.append(
-            describe_overpacked_line_violation(overpacked_line_count)
+            describe_overpacked_list_line_violation(overpacked_list_line_count)
         )
     return all_violations
 
@@ -390,11 +358,9 @@ def find_reply_shape_violations(assistant_message: str) -> list[str]:
 
     ::
 
-        ok:   a 40-word outcome sentence -> []
-        flag: a 260-word wall            -> ["260 words, over the 120-word cap"]
-
-    A reply opening with the escape prefix, and a reply under the enforced word
-    floor, are both returned as in shape.
+        ok:   a short outcome sentence              -> []
+        ok:   a long requested audit with few bullets -> []
+        flag: prose then buried "Install the package." -> [action-first]
 
     Args:
         assistant_message: The raw final assistant message.
@@ -402,19 +368,12 @@ def find_reply_shape_violations(assistant_message: str) -> list[str]:
     Returns:
         One violation text per broken rule, empty when the reply is in shape.
     """
-    if opens_with_long_form_escape(assistant_message):
-        return []
     prose_text = extract_reply_prose(assistant_message)
-    reply_word_count = count_reply_words(prose_text)
-    if reply_word_count < MINIMUM_ENFORCED_WORD_COUNT:
-        return []
-    return collect_shape_violations(
-        reply_word_count, collect_non_empty_lines(prose_text)
-    )
+    return collect_shape_violations(collect_non_empty_lines(prose_text))
 
 
 def build_block_reason(all_violations: list[str]) -> str:
-    """Return the corrective message naming each violation and the escape hatch.
+    """Return the corrective message naming each violation and the rewrite path.
 
     Args:
         all_violations: The violation texts the reply earned.
@@ -424,16 +383,14 @@ def build_block_reason(all_violations: list[str]) -> str:
     """
     formatted_violation_list = VIOLATION_SEPARATOR.join(all_violations)
     return (
-        f"ELI11 REPLY SHAPE: Your reply breaks the short action-first shape "
+        f"ELI11 REPLY SHAPE: Rewrite the reply into a short action-first shape "
         f"({formatted_violation_list}).\n\n"
-        f"Rewrite it short. When the user must act, open with numbered "
-        f"click-by-click steps, one short line each. When nothing is needed, open "
-        f"with the outcome in one sentence. Keep findings to at most "
-        f"{TARGET_BULLET_LINE_COUNT} short bullets and stay under "
-        f"{MAXIMUM_REPLY_WORD_COUNT} words. Code fences, blockquotes, tables, and "
-        f"links are already exempt from the count.\n\n"
-        f"When the user asked for a full report, start the reply with "
-        f'"Long form:" to opt out of this check.\n\n'
+        f"When the user must act, open with numbered click-by-click steps, one "
+        f"short line each. When nothing is needed, open with the outcome in one "
+        f"sentence. Keep findings to at most {TARGET_BULLET_LINE_COUNT} short "
+        f"bullets. A requested full report may run long; keep list lines short "
+        f"and lead with the outcome. Code fences, blockquotes, tables, and "
+        f"links are already exempt from shape counting.\n\n"
         f"You MUST re-output the complete, revised response with the correction "
         f"applied."
     )

package/hooks/blocking/hedging_language_blocker.py

@@ -1,9 +1,19 @@
 #!/usr/bin/env python3
-"""
-Stop hook that blocks Claude responses containing hedging language.
+"""Stop hook for bare hedging words that mark unverified claims.
+
+Words like "likely" or "probably" stand in for evidence. When prose-style
+enforcement is on, a hedge word blocks the response unless the same sentence
+carries an explicit uncertainty label (unverified, I don't know, no source for
+this claim). A label in another sentence does not exempt a bare hedge.
+
+::
 
-Words like "likely", "probably", "presumably" signal unverified claims.
-When detected, Claude is forced to re-check and respond with verified facts.
+    pass:  This claim is unverified; the deploy is probably blocked.
+    flag:  This claim is unverified. The deploy is probably blocked.
+
+When enforcement is off, surviving bare hedges emit privacy-safe advisory
+candidates (OP-07B). See rules/hedging-claims.md and
+docs/references/prose-style-enforcement.md.
 """
 
 import json
@@ -16,9 +26,25 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
+from hooks_constants.hedging_uncertainty_constants import (  # noqa: E402
+    ALL_EXPLICIT_UNCERTAINTY_LABEL_PATTERNS,
+    BLOCK_REASON_PREFIX,
+    HEDGING_TERM_LIST_SEPARATOR,
+    POSITIVE_CORRECTIVE_GUIDANCE,
+    SENTENCE_BOUNDARY_PATTERN,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_NOTICE  # noqa: E402
+from hooks_constants.prose_matcher_precision_constants import (  # noqa: E402
+    ADVISORY_CONTEXT_SNIPPET_MAX_CHARS,
+    MATCHER_ID_HEDGING_WORD,
+    MAXIMUM_ADVISORY_EMITS_PER_CALL,
+)
 from hooks_constants.text_stripping import strip_code_and_quotes  # noqa: E402
+from observability.prose_matcher_advisory import emit_advisory_candidate  # noqa: E402
 
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
@@ -59,18 +85,65 @@ ALL_HEDGING_PATTERNS = [
     re.compile(pattern, re.IGNORECASE) for pattern in HEDGING_WORDS + HEDGING_PHRASES
 ]
 
-def find_hedging_words(text: str) -> list[str]:
-    """Return all hedging words/phrases found in the text."""
-    prose_text = strip_code_and_quotes(text)
-    matched_terms = []
 
-    for pattern in ALL_HEDGING_PATTERNS:
-        all_matches = pattern.findall(prose_text)
-        for each_match in all_matches:
+def _sentence_carries_explicit_uncertainty(sentence: str) -> bool:
+    """Return True when the sentence labels the claim as unknown or unverified."""
+    for each_label_pattern in ALL_EXPLICIT_UNCERTAINTY_LABEL_PATTERNS:
+        if each_label_pattern.search(sentence):
+            return True
+    return False
+
+
+def _hedging_terms_in_prose_slice(prose_slice: str) -> list[str]:
+    """Return unique hedge terms found in one prose slice (sentence or full text)."""
+    matched_terms: list[str] = []
+    for each_pattern in ALL_HEDGING_PATTERNS:
+        for each_match in each_pattern.findall(prose_slice):
             normalized_term = each_match.strip().lower()
             if normalized_term not in matched_terms:
                 matched_terms.append(normalized_term)
+    return matched_terms
+
+
+def find_hedging_words(text: str) -> list[str]:
+    """Return all hedging words/phrases in the stripped prose (any sentence)."""
+    prose_text = strip_code_and_quotes(text)
+    return _hedging_terms_in_prose_slice(prose_text)
+
+
+def find_blocking_hedging_terms(text: str) -> list[str]:
+    """Return hedge terms that lack an explicit uncertainty label in-sentence.
+
+    ::
+
+        find_blocking_hedging_terms("Unverified: the port is probably down.")
+            -> []
+        find_blocking_hedging_terms("Unverified. The port is probably down.")
+            -> ["probably"]
 
+    Args:
+        text: Full assistant message, including code and quotes.
+
+    Returns:
+        Unique bare hedge terms that still warrant a block or advisory emit.
+    """
+    prose_text = strip_code_and_quotes(text)
+    if not prose_text.strip():
+        return []
+
+    all_sentences = SENTENCE_BOUNDARY_PATTERN.split(prose_text)
+    if len(all_sentences) <= 1:
+        all_sentences = [prose_text]
+
+    matched_terms: list[str] = []
+    for each_sentence in all_sentences:
+        if not each_sentence.strip():
+            continue
+        if _sentence_carries_explicit_uncertainty(each_sentence):
+            continue
+        for each_term in _hedging_terms_in_prose_slice(each_sentence):
+            if each_term not in matched_terms:
+                matched_terms.append(each_term)
     return matched_terms
 
 
@@ -88,12 +161,26 @@ def main() -> None:
     if not assistant_message:
         sys.exit(0)
 
-    found_hedging_terms = find_hedging_words(assistant_message)
+    found_hedging_terms = find_blocking_hedging_terms(assistant_message)
 
     if not found_hedging_terms:
         sys.exit(0)
 
-    formatted_term_list = ", ".join(f'"{term}"' for term in found_hedging_terms)
+    if not prose_style_enforcement_enabled_in_environment():
+        try:
+            for each_term in found_hedging_terms[:MAXIMUM_ADVISORY_EMITS_PER_CALL]:
+                emit_advisory_candidate(
+                    MATCHER_ID_HEDGING_WORD,
+                    "Stop",
+                    f"{each_term}:{assistant_message[:ADVISORY_CONTEXT_SNIPPET_MAX_CHARS]}",
+                )
+        except (ImportError, OSError, TypeError, ValueError):
+            pass
+        sys.exit(0)
+
+    formatted_term_list = HEDGING_TERM_LIST_SEPARATOR.join(
+        f'"{term}"' for term in found_hedging_terms
+    )
 
     resolved_skill_path: str | None = None
     for each_skill_path in RESEARCH_MODE_SKILL_SEARCH_PATHS:
@@ -110,13 +197,9 @@ def main() -> None:
         )
 
     block_reason = (
-        f"ANTI-HALLUCINATION GUARDRAIL: Your response contains hedging language: "
-        f"{formatted_term_list}. "
-        f"These words signal unverified claims. You MUST rewrite your response "
-        f"{skill_reference}\n\n"
-        f"Do NOT simply remove the hedging word and keep the unverified claim. "
-        f"Do more research to VERIFY it with a source, or prompt the user via AskUserQuestion with some potential options + context if you are unable to find anything online.\n\n"
-        f"You MUST re-output the complete, revised response with the corrections applied."
+        f"{BLOCK_REASON_PREFIX}{formatted_term_list}. "
+        f"Rewrite {skill_reference}\n\n"
+        f"{POSITIVE_CORRECTIVE_GUIDANCE}"
     )
     block_response = {
         "decision": "block",

package/hooks/blocking/hook_prose_detector_consistency.py

@@ -39,6 +39,9 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.hook_prose_detector_consistency_constants import (  # noqa: E402
     CONSTANTS_MODULE_SUFFIX,
@@ -118,6 +121,9 @@ def main() -> None:
     except json.JSONDecodeError:
         sys.exit(0)
 
+    if not prose_style_enforcement_enabled_in_environment():
+        sys.exit(0)
+
     tool_name = hook_input.get("tool_name", "")
     if tool_name not in (WRITE_TOOL_NAME, EDIT_TOOL_NAME):
         sys.exit(0)

package/hooks/blocking/intent_only_ending_blocker.py

@@ -18,6 +18,9 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_INTENT_ENDING_NOTICE  # noqa: E402
 from hooks_constants.text_stripping import strip_code_and_quotes  # noqa: E402
@@ -110,6 +113,9 @@ def main() -> None:
     if hook_input.get("stop_hook_active", False):
         sys.exit(0)
 
+    if not prose_style_enforcement_enabled_in_environment():
+        sys.exit(0)
+
     assistant_message = hook_input.get("last_assistant_message", "")
 
     if not assistant_message: