claude-dev-env 2.7.0 → 2.8.0

package/hooks/blocking/plain_language_blocker.py

@@ -1,13 +1,24 @@
 #!/usr/bin/env python3
-"""PreToolUse hook that blocks heavy words in AskUserQuestion prose and .md writes.
-
-Reaches for the everyday word over the formal one: `use` over `utilize`,
-`start` over `initiate`, `enough` over `sufficient`. Two surfaces are guarded --
-AskUserQuestion (its question and option prose) and Write/Edit/MultiEdit targeting a .md
-file. Code fences, inline code, blockquotes, URLs, and file paths are stripped
-before matching so exact identifiers and paths are never flagged.
-
-See the plain-language rule for the full guidance this hook enforces.
+"""PreToolUse hook guarding AskUserQuestion prose and .md writes.
+
+Two checks run. The word check reaches for the everyday word over the formal
+one: `use` over `utilize`, `start` over `initiate`, `enough` over `sufficient`.
+It reads both guarded surfaces -- AskUserQuestion (its question and option
+prose) and Write/Edit/MultiEdit targeting a .md file -- with code fences,
+inline code, blockquotes, URLs, and file paths stripped first, so exact
+identifiers and paths are never flagged.
+
+The lean-block check reads the AskUserQuestion surface alone. AskUserQuestion
+renders as one plain text block, so the question text and each option
+description stay short and unformatted: a fenced block, a heading, a table row,
+a bullet or numbered list marker, a second paragraph, or prose past the
+sentence and word caps all belong in chat text before the call. Structure is
+read at block level on the raw text, with line endings folded to one spelling
+first; an inline code span naming a path, a flag, or a command weighs one word
+against the length caps.
+
+See the plain-language and ask-user-question-required rules for the full
+guidance this hook enforces.
 """
 
 import json
@@ -22,20 +33,36 @@ if _hooks_dir not in sys.path:
 from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
+    ALL_CHAT_DETAIL_MARKERS,
+    ALL_LINE_ENDING_REPLACEMENTS,
     ALL_SOFTWARE_TERMS,
     ALL_TERM_PATTERNS,
     ALL_WRITE_EDIT_TOOL_NAMES,
     ASK_USER_QUESTION_TOOL_NAME,
     BLOCKQUOTE_LINE_PATTERN,
+    COUNTABLE_WORD_PATTERN,
     DOT_CLAUDE_DIRECTORY_NAME,
     FENCED_CODE_BLOCK_PATTERN,
     FILE_PATH_PATTERN,
     INLINE_CODE_PATTERN,
+    INLINE_CODE_PLACEHOLDER,
+    INLINE_CODE_SPAN_PATTERN,
+    LEAN_QUESTION_BLOCK_GUIDANCE,
+    LEAN_QUESTION_BLOCK_PREFIX,
+    LEAN_QUESTION_VIOLATION_SEPARATOR,
     MARKDOWN_EXTENSION,
+    MAXIMUM_OPTION_DESCRIPTION_SENTENCE_COUNT,
+    MAXIMUM_OPTION_DESCRIPTION_WORD_COUNT,
+    MAXIMUM_QUESTION_SENTENCE_COUNT,
+    MAXIMUM_QUESTION_WORD_COUNT,
+    OPTION_DESCRIPTION_SURFACE_NAME,
     PROJECT_ALLOWLIST_FILENAME,
     PROJECT_ROOT_WALK_LIMIT,
+    QUESTION_SURFACE_NAME,
     REPOSITORY_MARKER_NAME,
+    SENTENCE_BOUNDARY_PATTERN,
     URL_PATTERN,
+    USER_FACING_LEAN_QUESTION_NOTICE,
     USER_FACING_PLAIN_LANGUAGE_NOTICE,
 )
 
@@ -219,6 +246,229 @@ def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
     )
 
 
+def _normalize_line_endings(prose_text: str) -> str:
+    """Return the prose with every line ending spelled as a bare line feed.
+
+    ::
+
+        in:  "Which gate?\\r\\n\\r\\nThe write gate reads it."
+        out: "Which gate?\\n\\nThe write gate reads it."
+
+    The structure markers read line boundaries, so a payload carrying carriage
+    returns is normalized once here rather than at each pattern.
+
+    Args:
+        prose_text: One question text or one option description.
+
+    Returns:
+        The prose with carriage returns folded into line feeds.
+    """
+    normalized_text = prose_text
+    for each_line_ending, each_replacement in ALL_LINE_ENDING_REPLACEMENTS:
+        normalized_text = normalized_text.replace(each_line_ending, each_replacement)
+    return normalized_text
+
+
+def _mask_inline_code(prose_text: str) -> str:
+    """Return the prose with each inline code span collapsed to a single word.
+
+    ::
+
+        in:  "Does `git diff --cached` list it?"
+        out: "Does code list it?"
+
+    A span names a path, a flag, or a command the reader needs verbatim, so it
+    weighs one word against the length caps. Only the length counts read the
+    masked prose: the structure markers read the raw text, so a one-line closed
+    fence still reads as a fence rather than as a span.
+
+    Args:
+        prose_text: One question text or one option description.
+
+    Returns:
+        The prose with every single-line inline code span replaced.
+    """
+    return INLINE_CODE_SPAN_PATTERN.sub(INLINE_CODE_PLACEHOLDER, prose_text)
+
+
+def _count_prose_sentences(prose_text: str) -> int:
+    """Return how many sentences one piece of question-block prose carries.
+
+    ::
+
+        in:  "Which gate runs first? Both read the same lines."
+        out: 2
+
+    A sentence closes on `.`, `!`, or `?` followed by a capitalized word or the
+    end of the text, so an abbreviation mid-sentence closes nothing.
+
+    Args:
+        prose_text: One question text or one option description.
+
+    Returns:
+        The count of sentence closings the prose carries.
+    """
+    return len(SENTENCE_BOUNDARY_PATTERN.findall(prose_text))
+
+
+def _count_prose_words(prose_text: str) -> int:
+    """Return how many reader-visible words one piece of prose carries.
+
+    Args:
+        prose_text: One question text or one option description.
+
+    Returns:
+        The count of whitespace-separated tokens carrying a letter or digit.
+    """
+    return len(COUNTABLE_WORD_PATTERN.findall(prose_text))
+
+
+def _find_chat_detail_markers(prose_text: str) -> list[str]:
+    """Return the name of each chat-detail marker the prose carries.
+
+    ::
+
+        ok:   "Which gate should run first?"        -> []
+        flag: "Which gate?\\n- write\\n- commit"      -> ["a bullet or numbered
+              list marker"]
+
+    Args:
+        prose_text: One question text or one option description.
+
+    Returns:
+        One marker name per marker found, in the order the markers are tried.
+    """
+    return [
+        each_marker_name
+        for each_pattern, each_marker_name in ALL_CHAT_DETAIL_MARKERS
+        if each_pattern.search(prose_text)
+    ]
+
+
+def _find_lean_block_violations(
+    prose_text: str,
+    surface_name: str,
+    maximum_sentence_count: int,
+    maximum_word_count: int,
+) -> list[str]:
+    """Return every lean-block rule one piece of question-block prose breaks.
+
+    Args:
+        prose_text: One question text or one option description.
+        surface_name: How the violation text names this piece of prose.
+        maximum_sentence_count: The sentence cap this piece answers to.
+        maximum_word_count: The word cap this piece answers to.
+
+    Returns:
+        One violation text per broken rule, empty when the prose is lean.
+
+    The structure markers read the line-ending-normalized prose; the sentence
+    and word counts read that prose with its inline code spans masked.
+    """
+    normalized_text = _normalize_line_endings(prose_text)
+    masked_text = _mask_inline_code(normalized_text)
+    all_violations = [
+        f"{surface_name} carries {each_marker_name}"
+        for each_marker_name in _find_chat_detail_markers(normalized_text)
+    ]
+    sentence_count = _count_prose_sentences(masked_text)
+    if sentence_count > maximum_sentence_count:
+        all_violations.append(
+            f"{surface_name} runs {sentence_count} sentences, over the "
+            f"{maximum_sentence_count}-sentence cap"
+        )
+    word_count = _count_prose_words(masked_text)
+    if word_count > maximum_word_count:
+        all_violations.append(
+            f"{surface_name} runs {word_count} words, over the "
+            f"{maximum_word_count}-word cap"
+        )
+    return all_violations
+
+
+def _violations_for_one_question(question_by_key: dict) -> list[str]:
+    """Return the lean-block violations one question entry carries.
+
+    Args:
+        question_by_key: One entry of the AskUserQuestion questions list.
+
+    Returns:
+        One violation text per broken rule across the question text and every
+        option description the entry carries.
+    """
+    all_violations: list[str] = []
+    question_text = question_by_key.get("question", "")
+    if isinstance(question_text, str):
+        all_violations.extend(
+            _find_lean_block_violations(
+                question_text,
+                QUESTION_SURFACE_NAME,
+                MAXIMUM_QUESTION_SENTENCE_COUNT,
+                MAXIMUM_QUESTION_WORD_COUNT,
+            )
+        )
+    all_options = question_by_key.get("options", [])
+    if not isinstance(all_options, list):
+        return all_violations
+    for each_option in all_options:
+        if not isinstance(each_option, dict):
+            continue
+        option_description = each_option.get("description", "")
+        if not isinstance(option_description, str):
+            continue
+        all_violations.extend(
+            _find_lean_block_violations(
+                option_description,
+                OPTION_DESCRIPTION_SURFACE_NAME,
+                MAXIMUM_OPTION_DESCRIPTION_SENTENCE_COUNT,
+                MAXIMUM_OPTION_DESCRIPTION_WORD_COUNT,
+            )
+        )
+    return all_violations
+
+
+def find_question_block_violations(tool_input: dict) -> list[str]:
+    """Return every lean-block violation an AskUserQuestion payload carries.
+
+    ::
+
+        ok:   "Which gate should run first?" + "Runs on every write." -> []
+        flag: a question with a three-bullet plan under it
+              -> ["the question carries a bullet or numbered list marker"]
+
+    Each violation text appears once, so two options breaking the same cap read
+    as one line.
+
+    Args:
+        tool_input: The AskUserQuestion tool input carrying the questions list.
+
+    Returns:
+        One violation text per broken rule, in first-seen order, empty when the
+        whole question block is lean.
+    """
+    all_questions = tool_input.get("questions", [])
+    if not isinstance(all_questions, list):
+        return []
+    all_violations: list[str] = []
+    for each_question in all_questions:
+        if isinstance(each_question, dict):
+            all_violations.extend(_violations_for_one_question(each_question))
+    return list(dict.fromkeys(all_violations))
+
+
+def build_lean_block_reason(all_violations: list[str]) -> str:
+    """Return a deny reason naming each chat detail and where the detail belongs.
+
+    Args:
+        all_violations: The violation texts the question block earned.
+
+    Returns:
+        The full deny reason the model rewrites its question block against.
+    """
+    violation_list = LEAN_QUESTION_VIOLATION_SEPARATOR.join(all_violations)
+    return f"{LEAN_QUESTION_BLOCK_PREFIX}{violation_list}. {LEAN_QUESTION_BLOCK_GUIDANCE}"
+
+
 def _collect_ask_user_question_prose(tool_input: dict) -> str:
     all_questions = tool_input.get("questions", [])
     if not isinstance(all_questions, list):
@@ -273,6 +523,21 @@ def _collect_prose_for_tool(tool_name: str, tool_input: dict) -> str:
     return ""
 
 
+def _notice_for_deny_reason(deny_reason: str) -> str:
+    """Return the short notice matching the check that produced a deny reason.
+
+    Args:
+        deny_reason: The permissionDecisionReason text for the denial.
+
+    Returns:
+        The lean-block notice for a question-block denial, the word-swap notice
+        otherwise.
+    """
+    if deny_reason.startswith(LEAN_QUESTION_BLOCK_PREFIX):
+        return USER_FACING_LEAN_QUESTION_NOTICE
+    return USER_FACING_PLAIN_LANGUAGE_NOTICE
+
+
 def build_deny_payload(deny_reason: str) -> dict[str, object]:
     """Build the full deny payload the hook writes for a deny-reason string.
 
@@ -297,7 +562,7 @@ def build_deny_payload(deny_reason: str) -> dict[str, object]:
             "permissionDecision": "deny",
             "permissionDecisionReason": deny_reason,
         },
-        "systemMessage": USER_FACING_PLAIN_LANGUAGE_NOTICE,
+        "systemMessage": _notice_for_deny_reason(deny_reason),
         "suppressOutput": True,
     }
 
@@ -308,17 +573,19 @@ def _emit_deny(deny_reason: str, output_stream: TextIO) -> None:
 
 
 def evaluate(payload_by_key: dict[str, object]) -> str | None:
-    """Decide whether a payload's prose carries heavy words to block.
+    """Decide whether a payload carries a question block or heavy words to block.
 
-    Collects the prose for the payload's tool, scans it for banned terms, and
-    returns the deny-reason text when any heavy word is found, or None to allow.
+    An AskUserQuestion payload meets the lean-block check first, so a question
+    text or an option description carrying chat detail returns a LEAN_QUESTION
+    deny reason. Every guarded payload then meets the word scan, which returns a
+    PLAIN_LANGUAGE deny reason for the first heavy word it finds.
 
     Args:
         payload_by_key: The PreToolUse payload with tool_name and tool_input.
 
     Returns:
-        The permissionDecisionReason text when the prose is denied, or None when
-        the prose is allowed.
+        The permissionDecisionReason text when the payload is denied, or None
+        when it is allowed.
     """
     raw_tool_name = payload_by_key.get("tool_name", "")
     raw_tool_input = payload_by_key.get("tool_input", {})
@@ -332,6 +599,11 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
         ):
             return None
 
+    if raw_tool_name == ASK_USER_QUESTION_TOOL_NAME:
+        all_block_violations = find_question_block_violations(raw_tool_input)
+        if all_block_violations:
+            return build_lean_block_reason(all_block_violations)
+
     prose_text = _collect_prose_for_tool(raw_tool_name, raw_tool_input)
     if not prose_text:
         return None