claude-dev-env 8.106.2 → 8.106.4

package/docs/CODE_RULES.md

@@ -62,7 +62,7 @@ Open [details](code-rules/design-and-structure.md) when adding a class or parame
 
 ## 7.5 SOLID PRINCIPLES
 
-Apply SRP throughout. Apply OCP, LSP, ISP, and DIP when two concrete implementations share a contract. Keep cohesive classes together.
+Keep a function whole while it reads top to bottom. Split it when the new piece has a second caller or makes the caller easier to read, or when it reaches the 60-line cap the lint and the write-time hook enforce. Apply OCP, LSP, ISP, and DIP when two concrete implementations share a contract. Keep cohesive classes together.
 
 Open [details](code-rules/design-and-structure.md) when extracting a responsibility.
 

package/hooks/blocking/reply_length_gate.py

@@ -83,6 +83,7 @@ import os
 import re
 import shlex
 import sys
+from collections.abc import Callable, Iterable
 from pathlib import Path
 
 hooks_root_directory = str(Path(__file__).resolve().parent.parent)
@@ -155,6 +156,8 @@ from hooks_constants.reply_length_gate_constants import (
     EM_DASH_MESSAGE,
     EM_DASH_PATTERN,
     FENCED_BLOCK_PATTERN,
+    FINDING_SEPARATOR,
+    FIX_EVERY_ITEM_INSTRUCTION,
     ADDITIONAL_CONTEXT_KEY,
     HOOK_EVENT_NAME,
     INLINE_CODE_PATTERN,
@@ -207,27 +210,92 @@ def sentence_word_lists(reply_text: str) -> list[list[str]]:
     return [each_word_list for each_word_list in all_word_lists if each_word_list]
 
 
+def joined_violations(all_violations: Iterable[str | None]) -> str | None:
+    """Join every violation found into one deny reason, one violation per line.
+
+    ::
+
+        []                         -> None
+        ["Too long."]              -> "Too long."
+        ["Too long.", "Em dash."]  -> "Too long." and "Em dash." on two lines
+
+    None entries are skipped. A joined reason can join again at an outer
+    level and stays one violation per line, so ``numbered_violations``
+    numbers the whole reason once.
+    """
+    all_found = [each_violation for each_violation in all_violations if each_violation]
+    return FINDING_SEPARATOR.join(all_found) if all_found else None
+
+
+def numbered_violations(violation: str) -> str:
+    """Number each line of a joined deny reason that holds several violations.
+
+    ::
+
+        "Too long."             -> "Too long."
+        "Too long.\nEm dash."   -> "1. Too long." and "2. Em dash." on two lines
+    """
+    all_lines = violation.split(FINDING_SEPARATOR)
+    if len(all_lines) == 1:
+        return violation
+    return FINDING_SEPARATOR.join(
+        f"{each_position}. {each_line}" for each_position, each_line in enumerate(all_lines, start=1)
+    )
+
+
+def collected_violations(all_checks: Iterable[Callable[[], str | None]]) -> str | None:
+    """Run every check in order and join each violation it reports.
+
+    A check that raises ends the run. With nothing found yet the error
+    propagates, which lets the call through as an early-return gate did.
+    After a finding, the findings so far stand, as the first one did when
+    the gate never ran the later checks.
+    """
+    all_violations: list[str | None] = []
+    for each_check in all_checks:
+        is_stopped, violation = _checked_violation(each_check, any(all_violations))
+        if is_stopped:
+            break
+        all_violations.append(violation)
+    return joined_violations(all_violations)
+
+
+def _checked_violation(check: Callable[[], str | None], has_finding: bool) -> tuple[bool, str | None]:
+    try:
+        return False, check()
+    except Exception:
+        if has_finding:
+            return True, None
+        raise
+
+
 def length_violation(reply_text: str) -> str | None:
-    """Return the deny reason for an over-long reply, or None when it fits."""
+    """Return the deny reason for an over-long reply and each over-long sentence, or None when it fits."""
     all_sentences = sentence_word_lists(reply_text)
-    if len(all_sentences) > MAXIMUM_SENTENCE_COUNT:
-        return TOO_MANY_SENTENCES_MESSAGE.format(
-            sentence_count=len(all_sentences), sentence_limit=MAXIMUM_SENTENCE_COUNT
-        )
-    return long_sentence_violation(reply_text)
+    return joined_violations(
+        [
+            TOO_MANY_SENTENCES_MESSAGE.format(
+                sentence_count=len(all_sentences), sentence_limit=MAXIMUM_SENTENCE_COUNT
+            )
+            if len(all_sentences) > MAXIMUM_SENTENCE_COUNT
+            else None,
+            long_sentence_violation(reply_text),
+        ]
+    )
 
 
 def long_sentence_violation(prose_text: str) -> str | None:
-    """Return the deny reason for the first sentence over the word limit, or None."""
-    for each_sentence in sentence_word_lists(prose_text):
-        if len(each_sentence) > MAXIMUM_WORDS_PER_SENTENCE:
-            sentence_preview = WORD_SEPARATOR.join(each_sentence[:SENTENCE_PREVIEW_WORD_COUNT])
-            return LONG_SENTENCE_MESSAGE.format(
-                word_count=len(each_sentence),
-                word_limit=MAXIMUM_WORDS_PER_SENTENCE,
-                sentence_preview=sentence_preview + SENTENCE_PREVIEW_SUFFIX,
-            )
-    return None
+    """Return the deny reason for each sentence over the word limit, or None."""
+    return joined_violations(
+        LONG_SENTENCE_MESSAGE.format(
+            word_count=len(each_sentence),
+            word_limit=MAXIMUM_WORDS_PER_SENTENCE,
+            sentence_preview=WORD_SEPARATOR.join(each_sentence[:SENTENCE_PREVIEW_WORD_COUNT])
+            + SENTENCE_PREVIEW_SUFFIX,
+        )
+        for each_sentence in sentence_word_lists(prose_text)
+        if len(each_sentence) > MAXIMUM_WORDS_PER_SENTENCE
+    )
 
 
 def mid_sentence_colon_violation(reply_text: str) -> str | None:
@@ -254,13 +322,13 @@ def prose_sentences(reply_text: str) -> list[str]:
 
 
 def unsourced_cause_violation(reply_text: str) -> str | None:
-    """Return the deny reason for the first causal sentence that cites no evidence itself, or None."""
-    for each_sentence in prose_sentences(reply_text):
-        is_causal = CAUSAL_CLAIM_PATTERN.search(INLINE_CODE_PATTERN.sub(" ", each_sentence))
-        has_evidence = any(each_pattern.search(each_sentence) for each_pattern in ALL_EVIDENCE_PATTERNS)
-        if is_causal and not has_evidence:
-            return UNSOURCED_CAUSE_MESSAGE.format(sentence=each_sentence.strip())
-    return None
+    """Return the deny reason for each causal sentence that cites no evidence itself, or None."""
+    return joined_violations(
+        UNSOURCED_CAUSE_MESSAGE.format(sentence=each_sentence.strip())
+        for each_sentence in prose_sentences(reply_text)
+        if CAUSAL_CLAIM_PATTERN.search(INLINE_CODE_PATTERN.sub(" ", each_sentence))
+        and not any(each_pattern.search(each_sentence) for each_pattern in ALL_EVIDENCE_PATTERNS)
+    )
 
 
 def prose_outside_links(reply_text: str) -> str:
@@ -272,11 +340,11 @@ def prose_outside_links(reply_text: str) -> str:
 
 
 def unlinked_pull_request_violation(reply_text: str) -> str | None:
-    """Return the deny reason for a pull request number outside a link, or None."""
-    unlinked_match = UNLINKED_PULL_REQUEST_PATTERN.search(prose_outside_links(reply_text))
-    if unlinked_match is None:
-        return None
-    return UNLINKED_PULL_REQUEST_MESSAGE.format(reference=unlinked_match.group(0))
+    """Return the deny reason for each pull request number outside a link, or None."""
+    return joined_violations(
+        UNLINKED_PULL_REQUEST_MESSAGE.format(reference=each_match.group(0))
+        for each_match in UNLINKED_PULL_REQUEST_PATTERN.finditer(prose_outside_links(reply_text))
+    )
 
 
 def banned_words_config_path() -> Path:
@@ -303,20 +371,25 @@ def configured_banned_words() -> tuple[str, ...]:
 
 
 def banned_word_violation(reply_text: str, all_banned_words: tuple[str, ...]) -> str | None:
-    """Return the deny reason for the first banned word in the prose, or None."""
+    """Return the deny reason for each banned word in the prose, or None."""
     prose_text = countable_text(reply_text)
-    for each_banned_word in all_banned_words:
-        word_pattern = BANNED_WORD_PART_SEPARATOR.join(
-            re.escape(each_part) for each_part in each_banned_word.split()
+    return joined_violations(
+        BANNED_WORD_MESSAGE.format(banned_word=each_banned_word)
+        for each_banned_word in all_banned_words
+        if re.search(
+            BANNED_WORD_PATTERN_TEMPLATE.format(
+                word_pattern=BANNED_WORD_PART_SEPARATOR.join(
+                    re.escape(each_part) for each_part in each_banned_word.split()
+                )
+            ),
+            prose_text,
+            re.IGNORECASE,
         )
-        whole_word_pattern = BANNED_WORD_PATTERN_TEMPLATE.format(word_pattern=word_pattern)
-        if re.search(whole_word_pattern, prose_text, re.IGNORECASE):
-            return BANNED_WORD_MESSAGE.format(banned_word=each_banned_word)
-    return None
+    )
 
 
 def unvalidated_claim_violation(reply_text: str) -> str | None:
-    """Return the deny reason quoting the first sentence that guesses or admits a skipped check, or None.
+    """Return the deny reason quoting each sentence that guesses or admits a skipped check, or None.
 
     A duration counts as a guess unless its sentence cites the run, job, check,
     or pull request that measured it::
@@ -324,6 +397,7 @@ def unvalidated_claim_violation(reply_text: str) -> str | None:
         flag: It should take about 40 minutes.
         ok:   The last queue build took 39 minutes, run 18239174012.
     """
+    all_claims: list[str] = []
     for each_sentence in prose_sentences(reply_text):
         prose_text = countable_text(each_sentence).replace(CURLY_APOSTROPHE, STRAIGHT_APOSTROPHE)
         is_guess = UNVALIDATED_CLAIM_PATTERN.search(prose_text) is not None
@@ -332,12 +406,12 @@ def unvalidated_claim_violation(reply_text: str) -> str | None:
             and CITED_NUMBER_PATTERN.search(each_sentence) is None
         )
         if is_guess or is_uncited_duration:
-            return UNVALIDATED_CLAIM_MESSAGE.format(claim=each_sentence)
-    return None
+            all_claims.append(UNVALIDATED_CLAIM_MESSAGE.format(claim=each_sentence))
+    return joined_violations(all_claims)
 
 
 def unseen_citation_violation(reply_text: str, transcript_path: object) -> str | None:
-    """Return the deny reason for the first cited run, job, check, or pull request no tool result shows.
+    """Return the deny reason for each cited run, job, check, or pull request no tool result shows.
 
     Returns None when the text cites nothing or the transcript cannot be read.
     """
@@ -347,11 +421,17 @@ def unseen_citation_violation(reply_text: str, transcript_path: object) -> str |
     result_text = successful_result_text(transcript_path)
     if result_text is None:
         return None
-    for each_match in all_citations:
-        cited_number = next(each_group for each_group in each_match.groups() if each_group)
-        if re.search(CITED_NUMBER_IN_RESULT_TEMPLATE.format(number=cited_number), result_text) is None:
-            return UNSEEN_CITATION_MESSAGE.format(citation=each_match.group(0))
-    return None
+    return joined_violations(
+        UNSEEN_CITATION_MESSAGE.format(citation=each_match.group(0))
+        for each_match in all_citations
+        if re.search(
+            CITED_NUMBER_IN_RESULT_TEMPLATE.format(
+                number=next(each_group for each_group in each_match.groups() if each_group)
+            ),
+            result_text,
+        )
+        is None
+    )
 
 
 def all_card_texts(
@@ -382,25 +462,25 @@ def card_length_violation(all_card_input: dict[str, object]) -> str | None:
 
 
 def card_shape_violation(all_card_input: dict[str, object]) -> str | None:
-    """Return the deny reason for a listed or over-long card context or card sentence, or None."""
+    """Return the deny reason for each listed or over-long card context and card sentence, or None."""
     context_text = all_card_input.get(DECISION_CARD_CONTEXT_KEY)
+    all_violations: list[str | None] = []
     if isinstance(context_text, str):
         if CARD_LIST_ITEM_PATTERN.search(FENCED_BLOCK_PATTERN.sub(" ", context_text)) is not None:
-            return CARD_CONTEXT_LIST_MESSAGE
+            all_violations.append(CARD_CONTEXT_LIST_MESSAGE)
         context_sentence_count = len(sentence_word_lists(context_text))
         if context_sentence_count > MAXIMUM_CARD_CONTEXT_SENTENCE_COUNT:
-            return CARD_CONTEXT_TOO_LONG_MESSAGE.format(
-                sentence_count=context_sentence_count,
-                sentence_limit=MAXIMUM_CARD_CONTEXT_SENTENCE_COUNT,
+            all_violations.append(
+                CARD_CONTEXT_TOO_LONG_MESSAGE.format(
+                    sentence_count=context_sentence_count,
+                    sentence_limit=MAXIMUM_CARD_CONTEXT_SENTENCE_COUNT,
+                )
             )
     all_length_checked_texts = all_card_texts(
         all_card_input, ALL_DECISION_CARD_LENGTH_KEYS, ALL_DECISION_OPTION_LENGTH_KEYS
     )
-    for each_text in all_length_checked_texts:
-        violation = long_sentence_violation(each_text)
-        if violation is not None:
-            return violation
-    return None
+    all_violations.extend(long_sentence_violation(each_text) for each_text in all_length_checked_texts)
+    return joined_violations(all_violations)
 
 
 def all_question_card_texts(all_card_input: dict[str, object]) -> list[str]:
@@ -429,37 +509,41 @@ def active_mode_rules() -> VisualReplyRules | None:
 
 
 def card_violation(card_text: str, mode_rules: VisualReplyRules | None) -> str | None:
-    """Return the deny reason for a decision card's prose, or None."""
-    return (
-        banned_word_violation(card_text, configured_banned_words())
-        or unvalidated_claim_violation(card_text)
-    ) or (
-        None if mode_rules is None else abbreviation_violation(prose_outside_links(card_text), mode_rules)
+    """Return the deny reason for each problem in a decision card's prose, or None."""
+    return collected_violations(
+        [
+            lambda: banned_word_violation(card_text, configured_banned_words()),
+            lambda: unvalidated_claim_violation(card_text),
+            lambda: None
+            if mode_rules is None
+            else abbreviation_violation(prose_outside_links(card_text), mode_rules),
+        ]
     )
 
 
 def reply_violation(
     reply_text: str, transcript_path: object, mode_rules: VisualReplyRules | None
 ) -> str | None:
-    """Return the deny reason for a reply's text, or None."""
-    violation = (
-        length_violation(reply_text)
-        or mid_sentence_colon_violation(reply_text)
-        or em_dash_violation(reply_text)
-        or unlinked_pull_request_violation(reply_text)
-        or unsourced_cause_violation(reply_text)
-        or banned_word_violation(reply_text, configured_banned_words())
-        or unvalidated_claim_violation(reply_text)
-        or unseen_citation_violation(reply_text, transcript_path)
-    )
-    if violation is not None or mode_rules is None:
-        return violation
-    prose_text = prose_outside_links(reply_text)
-    return (
-        abbreviation_violation(prose_text, mode_rules)
-        or second_reply_violation(transcript_path, mode_rules)
-        or visual_violation(len(sentence_word_lists(reply_text)), transcript_path, mode_rules)
-    )
+    """Return the deny reason for each problem in a reply's text, or None."""
+    all_checks: list[Callable[[], str | None]] = [
+        lambda: length_violation(reply_text),
+        lambda: mid_sentence_colon_violation(reply_text),
+        lambda: em_dash_violation(reply_text),
+        lambda: unlinked_pull_request_violation(reply_text),
+        lambda: unsourced_cause_violation(reply_text),
+        lambda: banned_word_violation(reply_text, configured_banned_words()),
+        lambda: unvalidated_claim_violation(reply_text),
+        lambda: unseen_citation_violation(reply_text, transcript_path),
+    ]
+    if mode_rules is not None:
+        all_checks.extend(
+            [
+                lambda: abbreviation_violation(prose_outside_links(reply_text), mode_rules),
+                lambda: second_reply_violation(transcript_path, mode_rules),
+                lambda: visual_violation(len(sentence_word_lists(reply_text)), transcript_path, mode_rules),
+            ]
+        )
+    return collected_violations(all_checks)
 
 
 def tool_violation(
@@ -467,26 +551,30 @@ def tool_violation(
 ) -> tuple[str, str] | None:
     """Return the deny reason and the checked text for one call, or None when it passes."""
     mode_rules = active_mode_rules()
-    if isinstance(tool_name, str) and mode_rules is not None:
-        anchor_violation = widget_anchor_violation(tool_name, all_tool_input)
-        if anchor_violation is not None:
-            return anchor_violation, str(all_tool_input)
+    anchor_violation = (
+        widget_anchor_violation(tool_name, all_tool_input)
+        if isinstance(tool_name, str) and mode_rules is not None
+        else None
+    )
+    if anchor_violation is None:
+        return _text_violation(tool_name, all_tool_input, transcript_path, mode_rules)
+    try:
+        checked = _text_violation(tool_name, all_tool_input, transcript_path, mode_rules)
+    except Exception:
+        checked = None
+    if checked is None:
+        return anchor_violation, str(all_tool_input)
+    return FINDING_SEPARATOR.join([anchor_violation, checked[0]]), checked[1]
+
+
+def _text_violation(
+    tool_name: object,
+    all_tool_input: dict[str, object],
+    transcript_path: object,
+    mode_rules: VisualReplyRules | None,
+) -> tuple[str, str] | None:
     if tool_name in (DECISION_CARD_TOOL_NAME, QUESTION_CARD_TOOL_NAME):
-        if tool_name == DECISION_CARD_TOOL_NAME:
-            all_texts = all_card_texts(
-                all_tool_input, ALL_DECISION_CARD_PROSE_KEYS, ALL_DECISION_OPTION_PROSE_KEYS
-            )
-            shape_violation = card_length_violation(all_tool_input)
-        else:
-            all_texts = all_question_card_texts(all_tool_input)
-            shape_violation = None
-        card_text = CARD_TEXT_SEPARATOR.join(all_texts)
-        violation = (
-            shape_violation
-            or card_violation(card_text, mode_rules)
-            or unseen_citation_violation(card_text, transcript_path)
-        )
-        return None if violation is None else (violation, card_text)
+        return _card_text_violation(tool_name, all_tool_input, transcript_path, mode_rules)
     if tool_name not in ALL_CHECKED_TOOL_NAMES:
         return None
     reply_text = all_tool_input.get(TEXT_KEY)
@@ -496,6 +584,29 @@ def tool_violation(
     return None if violation is None else (violation, reply_text)
 
 
+def _card_text_violation(
+    tool_name: object,
+    all_tool_input: dict[str, object],
+    transcript_path: object,
+    mode_rules: VisualReplyRules | None,
+) -> tuple[str, str] | None:
+    if tool_name == DECISION_CARD_TOOL_NAME:
+        all_texts = all_card_texts(all_tool_input, ALL_DECISION_CARD_PROSE_KEYS, ALL_DECISION_OPTION_PROSE_KEYS)
+        shape_violation = card_length_violation(all_tool_input)
+    else:
+        all_texts = all_question_card_texts(all_tool_input)
+        shape_violation = None
+    card_text = CARD_TEXT_SEPARATOR.join(all_texts)
+    violation = collected_violations(
+        [
+            lambda: shape_violation,
+            lambda: card_violation(card_text, mode_rules),
+            lambda: unseen_citation_violation(card_text, transcript_path),
+        ]
+    )
+    return None if violation is None else (violation, card_text)
+
+
 def github_comment_texts(tool_name: object, all_tool_input: dict[str, object]) -> list[str]:
     """Return the GitHub comment texts one call would post, or an empty list.
 
@@ -569,15 +680,21 @@ def comment_length_violation(comment_text: str) -> str | None:
 
 
 def github_comment_violation(tool_name: object, all_tool_input: dict[str, object]) -> tuple[str, str] | None:
-    """Return the deny reason and text for an over-long GitHub comment, or None.
+    """Return the deny reason and text for every over-long GitHub comment, or None.
 
     Fenced code blocks and collapsed ``<details>`` blocks carry no words.
     """
-    for each_comment_text in github_comment_texts(tool_name, all_tool_input):
-        violation = comment_length_violation(each_comment_text)
-        if violation is not None:
-            return violation, each_comment_text
-    return None
+    all_over_long = [
+        (violation, each_comment_text)
+        for each_comment_text in github_comment_texts(tool_name, all_tool_input)
+        if (violation := comment_length_violation(each_comment_text)) is not None
+    ]
+    if not all_over_long:
+        return None
+    return (
+        FINDING_SEPARATOR.join(each_violation for each_violation, _ in all_over_long),
+        CARD_TEXT_SEPARATOR.join(each_text for _, each_text in all_over_long),
+    )
 
 
 def write_flowchart_advice(tool_name: object, all_tool_input: dict[str, object]) -> None:
@@ -607,7 +724,13 @@ def main() -> int:
         write_flowchart_advice(tool_name, tool_input)
         return ALLOW_EXIT_CODE
     violation, reply_text = checked
-    block_reason = violation + RETRY_INSTRUCTION
+    numbered_violation = numbered_violations(violation)
+    instruction = RETRY_INSTRUCTION + FIX_EVERY_ITEM_INSTRUCTION
+    block_reason = (
+        numbered_violation + FINDING_SEPARATOR + instruction.lstrip()
+        if FINDING_SEPARATOR in numbered_violation
+        else numbered_violation + instruction
+    )
     log_hook_block(
         Path(__file__).name,
         HOOK_EVENT_NAME,

package/hooks/blocking/test_reply_length_gate.py

@@ -1076,3 +1076,80 @@ def test_should_report_an_over_long_comment_text_with_the_comment_instruction()
 def test_should_pass_a_comment_text_whose_long_part_sits_in_a_details_block() -> None:
     comment_text = "Fixed.\n<details><summary>Log</summary>\n" + LONG_GITHUB_COMMENT + "\n</details>"
     assert reply_length_gate.comment_length_violation(comment_text) is None
+
+
+def test_joined_violations_should_put_each_violation_on_its_own_line() -> None:
+    assert reply_length_gate.joined_violations(["Too long.", None, "Em dash.\nNo link."]) == (
+        "Too long.\nEm dash.\nNo link."
+    )
+
+
+def test_numbered_violations_should_number_each_line_once() -> None:
+    assert reply_length_gate.numbered_violations("Too long.\nEm dash.\nNo link.") == (
+        "1. Too long.\n2. Em dash.\n3. No link."
+    )
+    assert reply_length_gate.numbered_violations("Too long.") == "Too long."
+
+
+def test_joined_violations_should_keep_one_violation_unchanged() -> None:
+    assert reply_length_gate.joined_violations([None, "Too long."]) == "Too long."
+
+
+def test_collected_violations_should_keep_findings_made_before_a_check_raises() -> None:
+    def broken_check() -> str | None:
+        raise TypeError("malformed input")
+
+    assert reply_length_gate.collected_violations([lambda: "Too long.", broken_check]) == "Too long."
+
+
+def test_collected_violations_should_keep_findings_when_a_later_check_raises_any_error() -> None:
+    def broken_check() -> str | None:
+        raise RuntimeError("transcript unreadable")
+
+    assert reply_length_gate.collected_violations([lambda: "Too long.", broken_check]) == "Too long."
+
+
+def test_collected_violations_should_raise_when_a_check_breaks_before_any_finding() -> None:
+    def broken_check() -> str | None:
+        raise TypeError("malformed input")
+
+    with pytest.raises(TypeError):
+        reply_length_gate.collected_violations([lambda: None, broken_check])
+
+
+def test_should_name_every_broken_rule_in_one_refusal(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, error_text = run_gate(
+        monkeypatch,
+        capsys,
+        POST_TOOL_NAME,
+        {"text": f"See PR 7452 and PR 7460.\n{SIXTEEN_WORD_SENTENCE}\nIt failed — again."},
+    )
+
+    assert exit_code == reply_length_gate.BLOCK_EXIT_CODE
+    assert "PR 7452" in error_text
+    assert "PR 7460" in error_text
+    assert "16 words" in error_text
+    assert reply_length_gate.EM_DASH_MESSAGE in error_text
+    assert error_text.endswith(reply_length_gate.FIX_EVERY_ITEM_INSTRUCTION)
+
+
+def test_should_number_nested_violations_once_in_one_refusal(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, error_text = run_gate(
+        monkeypatch,
+        capsys,
+        POST_TOOL_NAME,
+        {"text": f"One.\nTwo.\nThree.\n{SIXTEEN_WORD_SENTENCE}\n{SIXTEEN_WORD_SENTENCE}\nIt failed — again."},
+    )
+
+    assert exit_code == reply_length_gate.BLOCK_EXIT_CODE
+    all_numbered_lines = [each_line for each_line in error_text.splitlines() if each_line[:1].isdigit()]
+    assert [each_line.split(". ", 1)[0] for each_line in all_numbered_lines] == ["1", "2", "3", "4"]
+    assert not any(each_line.split(". ", 1)[1][:1].isdigit() for each_line in all_numbered_lines)
+    assert "Reply too long: 6 sentences" in all_numbered_lines[0]
+    assert all_numbered_lines[1].count("16 words") == 1
+    assert all_numbered_lines[2].count("16 words") == 1
+    assert reply_length_gate.EM_DASH_MESSAGE in all_numbered_lines[3]

package/hooks/features/conduct-gates.md

@@ -4,11 +4,11 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 ## Checks
 
-- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on.
+- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. One refusal names every broken rule and every offending sentence, numbered, and ends with "Fix every item above in your next write." With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on.
 - `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with. Its `windows_path_violation` blocks a path the terminal would render without one of its backslashes.
 - `blocking/open_tasks_stop_gate.py` holds the end of a turn once when the prompt that started it asks for work, the turn ran a work tool, and the turn made no tracker call: TaskCreate, TaskUpdate, TodoWrite, the Codex `update_plan`, or the desktop `mcp__ccd_turn__update_plan`. A work tool is any tool but a tracker call, the session title tool, `AskUserQuestion`, a hearthbot decision card, Codex `request_user_input`, `ToolSearch`, `TaskList`, or `TaskGet`. It never reads the reply text. `open_task_asks.is_ask` decides whether a prompt asks for work: a question-only prompt, an acknowledgement such as `thanks!`, an empty prompt, a prompt of only `<system-reminder>` blocks, and an envelope such as `<agent-message>` or `<task-notification>` do not. `blocking/open_tasks_transcript.py` replays the transcript for it: the turn's prompt, its tool calls, and the task list. `session_task_items` merges the task store with the transcript items whose subject the store does not hold, for the session title gate.
 - `session/tracking_nudge.py` adds one `additionalContext` note to a prompt that asks for work. The note asks for a task list item. When the title shows the red flag or the check mark, it also asks for the hourglass before other work. It never blocks.
-- The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies the first claim about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
+- The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies every claim, numbered in one refusal, about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
 - `blocking/chat_reply_gate.py` runs the `reply_length_gate.py` reply checks on a plain chat reply, which is no tool call. On `UserPromptSubmit` it adds the reply rules as `additionalContext`. On `MessageDisplay` it holds each streamed batch until the message ends. A message that passes shows whole. A message that fails shows as a draft from `claude -p` on Haiku that passes the same checks, and the original shows when two drafts fail. The draft changes only the text on screen, so the next `UserPromptSubmit` tells the agent the text the user saw, and `SessionEnd` deletes the stored draft. The [reply arena harness](https://github.com/jl-cmd-projects/claude-dev-env/tree/160349b90f627ea542fc6bc7b2b7f86dcbf98b73/tests/reply_arena) ran the comparison that chose this display path.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
 - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
@@ -63,7 +63,7 @@ Preconditions:
 - **Final reply.** Input is a closing reply that says "My guess is one to two hours." or cites a run no tool result shows. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_final_reply_gate.py -q`. The adjacent test observes a `block` decision that quotes the sentence or the citation; a reply that cites a run a tool result shows passes. A reply with a plain-text `D:\Reports\.claude\report.html` is blocked; the same path in backticks or a fenced block passes.
 - **Open tasks.** Input is a transcript whose last prompt asks for work and whose turn ran a Bash call and no tracker call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_open_tasks_stop_gate.py -q`. The adjacent test observes one `block` decision; the same turn with a TaskCreate, TaskUpdate, TodoWrite, or desktop plan call passes. A question, an acknowledgement, a `<task-notification>` envelope, a tool-free turn, and a held stop pass. The same file covers Codex and Cursor payloads.
 - **Ask nudge.** Input is a `UserPromptSubmit` payload with a work prompt, a question, and a `<task-notification>` envelope, after a transcript whose title shows the red flag. Run `python -m pytest packages/claude-dev-env/hooks/session/test_tracking_nudge.py -q`. The adjacent test observes a task list note and a title note for the work prompt, and empty stdout for the other two.
-- **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Fact with no source: ...`. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
+- **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Facts with no source: 1. ...`, numbering every failing claim. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
 - **Chat reply.** Input is a `MessageDisplay` event whose message holds four sentences, the same message split over two batches, and a `UserPromptSubmit` event. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_chat_reply_gate.py -q`. The adjacent test observes the drafter's text in `displayContent`, an empty first batch, no output for three sentences, the original after two failed drafts, the shown draft in the next `additionalContext`, and the stored draft deleted at session end.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.

package/hooks/features/lifecycle-cleanup.md

@@ -4,7 +4,7 @@ This family runs nested checkout hooks, refreshes a worktree base, and clears st
 
 ## Checks
 
-- `lifecycle/nested_project_hooks.py` runs hook registrations from checkouts nested one level below a session directory.
+- `lifecycle/nested_project_hooks.py` runs hook registrations from checkouts nested one level below a session directory. When several nested hooks refuse a tool call, the one refusal it returns carries every refusing hook's reason.
 - `lifecycle/enter_worktree_origin_prefetch.py` fetches the default branch before a fresh worktree is created.
 - `lifecycle/session_end_cleanup.py` removes old context cache files, temporary files, and transcript backups at session end.
 - `session/plugin_data_dir_cleanup.py` removes empty plugin data directories at session start.
@@ -34,7 +34,7 @@ Preconditions:
 
 ## Gotchas
 
-- The nested checkout runner forwards child denials and asks. It drops child allow decisions so a child cannot widen permission.
+- The nested checkout runner forwards child denials and asks, a denial ahead of an ask. It drops child allow decisions so a child cannot widen permission.
 - Worktree prefetch applies to fresh creation and exits zero after a failed fetch.
 - Session-end cleanup has no adjacent behavior test. Its direct probe calls `purge_old_entries` with an isolated directory.
 - The session edit tracker survives a compact or resume. Cleanup targets the current session only.

package/hooks/hooks.json

@@ -182,7 +182,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "You check one chat message before it posts. The hook input JSON is: $ARGUMENTS\n\nRead the message prose in tool_input: the text, body, question, context, reason, and option fields. Find each claim the message states as fact about how code, a file, a tool, a service, a run, or a process behaves, what state it is in, or why something happened.\n\nA claim passes when the message carries evidence that shows it: inline code that quotes output, an exit code, a count, a log line, or a code line; a file:line reference; or a URL or markdown link to the run, file, pull request, or page. A pull request or commit link covers what that change does, what it blocks or lets through, and the state of its checks, also in the later sentences about that same change. The evidence may sit in another sentence of the same message when it covers that claim. A link to one thing does not cover a claim about something else.\n\nThese pass with no evidence: the author's own actions, done, in progress, or planned, with or without \"I\", including what the action is aimed at, such as \"I'm finding where the check failed\"; a change the author made; a question; an instruction or request; a restatement of what the user said; and an option's consequence on a decision card.\n\nWhen every claim passes, return {\"ok\": true}. Otherwise return {\"ok\": false, \"reason\": \"Fact with no source: <the first failing claim>. Put the file:line, the quoted output, or the link that shows it in the message, run the check first, or leave the claim out.\"}",
+            "prompt": "You check one chat message before it posts. The hook input JSON is: $ARGUMENTS\n\nRead the message prose in tool_input: the text, body, question, context, reason, and option fields. Find each claim the message states as fact about how code, a file, a tool, a service, a run, or a process behaves, what state it is in, or why something happened.\n\nA claim passes when the message carries evidence that shows it: inline code that quotes output, an exit code, a count, a log line, or a code line; a file:line reference; or a URL or markdown link to the run, file, pull request, or page. A pull request or commit link covers what that change does, what it blocks or lets through, and the state of its checks, also in the later sentences about that same change. The evidence may sit in another sentence of the same message when it covers that claim. A link to one thing does not cover a claim about something else.\n\nThese pass with no evidence: the author's own actions, done, in progress, or planned, with or without \"I\", including what the action is aimed at, such as \"I'm finding where the check failed\"; a change the author made; a question; an instruction or request; a restatement of what the user said; and an option's consequence on a decision card.\n\nWhen every claim passes, return {\"ok\": true}. Otherwise return {\"ok\": false, \"reason\": \"Facts with no source: 1. <first failing claim> 2. <second failing claim> ... For each, put the file:line, the quoted output, or the link that shows it in the message, run the check first, or leave the claim out. Fix every item above in your next write.\"} List every failing claim, numbered in message order, never only the first.",
             "timeout": 30,
             "continueOnBlock": true,
             "statusMessage": "claude-dev-env: checking each claim for its source"

package/hooks/hooks_constants/hook_specific_output_keys.py

@@ -6,10 +6,12 @@ __all__ = [
     "HOOK_SPECIFIC_OUTPUT_KEY",
     "HOOK_EVENT_NAME_KEY",
     "PERMISSION_DECISION_KEY",
+    "PERMISSION_DECISION_REASON_KEY",
     "UPDATED_INPUT_KEY",
 ]
 
 HOOK_SPECIFIC_OUTPUT_KEY: str = "hookSpecificOutput"
 HOOK_EVENT_NAME_KEY: str = "hookEventName"
 PERMISSION_DECISION_KEY: str = "permissionDecision"
+PERMISSION_DECISION_REASON_KEY: str = "permissionDecisionReason"
 UPDATED_INPUT_KEY: str = "updatedInput"

package/hooks/hooks_constants/nested_project_hooks_constants.py

@@ -31,6 +31,8 @@ ALL_SHELL_PROGRAM_NAMES: tuple[str, ...] = ("bash", "sh")
 SHELL_COMMAND_FLAG: str = "-c"
 
 BLOCKING_EXIT_CODE: int = 2
-ALL_FORWARDED_PERMISSION_DECISIONS: frozenset[str] = frozenset({"deny", "ask"})
+DENY_PERMISSION_DECISION: str = "deny"
+ASK_PERMISSION_DECISION: str = "ask"
+ALL_FORWARDED_PERMISSION_DECISIONS: tuple[str, ...] = (DENY_PERMISSION_DECISION, ASK_PERMISSION_DECISION)
 ADDITIONAL_CONTEXT_KEY: str = "additionalContext"
 CONTEXT_SECTION_SEPARATOR: str = "\n\n"

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -44,6 +44,8 @@ SENTENCE_PREVIEW_WORD_COUNT = 6
 WORD_SEPARATOR = " "
 SENTENCE_PREVIEW_SUFFIX = "..."
 RETRY_INSTRUCTION = " Cut the text and resend the call."
+FIX_EVERY_ITEM_INSTRUCTION = " Fix every item above in your next write."
+FINDING_SEPARATOR = "\n"
 TOO_MANY_SENTENCES_MESSAGE = "Reply too long: {sentence_count} sentences, limit {sentence_limit}."
 CARD_CONTEXT_TOO_LONG_MESSAGE = (
     "Card context too long: {sentence_count} sentences, limit {sentence_limit}."

package/hooks/hooks_constants/test_hook_specific_output_keys.py

@@ -13,5 +13,6 @@ def test_keys_match_the_harness_hook_specific_output_field_names() -> None:
         "HOOK_SPECIFIC_OUTPUT_KEY": "hookSpecificOutput",
         "HOOK_EVENT_NAME_KEY": "hookEventName",
         "PERMISSION_DECISION_KEY": "permissionDecision",
+        "PERMISSION_DECISION_REASON_KEY": "permissionDecisionReason",
         "UPDATED_INPUT_KEY": "updatedInput",
     }

package/hooks/hooks_constants/visual_reply_rules_constants.py

@@ -66,6 +66,7 @@ RESULT_TEXT_SEPARATOR = "\n"
 
 ABBREVIATION_MESSAGE = 'Abbreviation "{abbreviation}" in the text. {reminder}'
 TRACKER_NUMBER_MESSAGE = 'Tracker number "{reference}" in the text. {reminder}'
+VIOLATION_LINE_SEPARATOR = "\n"
 NO_VISUAL_MESSAGE = "This reply has {sentence_count} sentences and no visual this turn. {reminder}"
 SECOND_REPLY_MESSAGE = "A reply already went out this turn. {reminder}"
 NOT_FLOWCHART_MESSAGE = "This widget is not a flowchart. {reminder}"

package/hooks/lifecycle/nested_project_hooks.py

@@ -13,7 +13,8 @@ hooks, and tool guards then never run. This hook runs them::
 
 Each child hook receives the same stdin payload, runs inside its checkout, and
 keeps its own matcher and timeout. A child ``exit 2`` blocks the tool call and a
-child ``deny`` or ``ask`` decision passes through; a child ``allow`` is dropped,
+child ``deny``, else a child ``ask``, passes through, a ``deny`` carrying every
+refusing child's reason; a child ``allow`` is dropped,
 so no child widens permissions for the session. The ``additionalContext`` of
 every child, at SessionStart, UserPromptSubmit, and PreToolUse, joins into one
 ``additionalContext``.
@@ -48,6 +49,7 @@ from hooks_constants.nested_project_hooks_constants import (
     COMMAND_KEY,
     CONTEXT_SECTION_SEPARATOR,
     DEFAULT_HOOK_TIMEOUT_SECONDS,
+    DENY_PERMISSION_DECISION,
     HOOK_EVENT_NAME_KEY,
     HOOK_TYPE_KEY,
     HOOKS_KEY,
@@ -67,6 +69,7 @@ from hooks_constants.hook_specific_output_keys import (
     HOOK_EVENT_NAME_KEY as HOOK_EVENT_NAME_OUTPUT_KEY,
     HOOK_SPECIFIC_OUTPUT_KEY,
     PERMISSION_DECISION_KEY,
+    PERMISSION_DECISION_REASON_KEY,
 )
 from hooks_constants.subprocess_window import hidden_window_creation_flags
 
@@ -276,41 +279,78 @@ def _permission_decision(all_output_fields: dict[str, object]) -> object:
     return specific_output.get(PERMISSION_DECISION_KEY)
 
 
+def _deny_reason(all_output_fields: dict[str, object]) -> str:
+    if _permission_decision(all_output_fields) != DENY_PERMISSION_DECISION:
+        return ""
+    specific_output = all_output_fields.get(HOOK_SPECIFIC_OUTPUT_KEY)
+    reason = (
+        specific_output.get(PERMISSION_DECISION_REASON_KEY)
+        if isinstance(specific_output, dict)
+        else None
+    )
+    return reason.strip() if isinstance(reason, str) else ""
+
+
+def _joined_reasons(all_reasons: Iterable[str]) -> str:
+    return CONTEXT_SECTION_SEPARATOR.join(dict.fromkeys(_non_empty_sections(all_reasons)))
+
+
 def pre_tool_use_verdict(
     all_results: list[subprocess.CompletedProcess[str]],
 ) -> HookVerdict:
     """Fold nested PreToolUse results into the one verdict Claude Code reads.
 
+    Claude Code shows one reason per refused call, so every refusing child's
+    reason travels in that one reason::
+
+        alpha exits 2 "no tests", beta denies "no link"  -> exit 2, both reasons
+        alpha denies "no link", beta denies "too long"   -> deny, both reasons
+        alpha asks, beta denies "no link"                -> deny, "no link"
+
     Args:
         all_results: The completed nested hooks, in run order.
 
     Returns:
-        A blocking exit carrying the child's stderr when any child exits 2,
-        else the first child ``deny`` or ``ask`` output carrying one copy
-        of each distinct child ``additionalContext``, else a pass carrying
-        that context, else an empty pass.
+        A blocking exit when any child exits 2, its stderr holding every
+        exit-2 child's stderr and every child ``deny`` reason; else the first
+        child ``deny`` output, its reason holding every child ``deny``
+        reason, or with no ``deny`` the first child ``ask`` output, either
+        carrying one copy of each distinct child ``additionalContext``; else
+        a pass carrying that context, else an empty pass.
     """
-    for each_result in all_results:
-        if each_result.returncode == BLOCKING_EXIT_CODE:
-            return HookVerdict(BLOCKING_EXIT_CODE, "", each_result.stderr)
     all_parsed_outputs = [
         _parsed_hook_output(each_result.stdout)
         for each_result in all_results
         if each_result.returncode == 0
     ]
     all_parsed_outputs = [each_output for each_output in all_parsed_outputs if each_output is not None]
+    all_deny_reasons = [_deny_reason(each_output) for each_output in all_parsed_outputs]
+    all_blocking_stderr = [
+        each_result.stderr.strip()
+        for each_result in all_results
+        if each_result.returncode == BLOCKING_EXIT_CODE
+    ]
+    if all_blocking_stderr:
+        return HookVerdict(
+            BLOCKING_EXIT_CODE, "", _joined_reasons([*all_blocking_stderr, *all_deny_reasons])
+        )
     all_context_sections = _non_empty_sections(
         _json_additional_context(each_parsed_output) for each_parsed_output in all_parsed_outputs
     )
     all_distinct_context_sections = list(dict.fromkeys(all_context_sections))
     joined_context = CONTEXT_SECTION_SEPARATOR.join(all_distinct_context_sections)
-    for each_parsed_output in all_parsed_outputs:
-        if _permission_decision(each_parsed_output) in ALL_FORWARDED_PERMISSION_DECISIONS:
+    for each_decision in ALL_FORWARDED_PERMISSION_DECISIONS:
+        for each_parsed_output in all_parsed_outputs:
+            if _permission_decision(each_parsed_output) != each_decision:
+                continue
             decision_output = dict(each_parsed_output)
+            decision_specific_output = dict(decision_output[HOOK_SPECIFIC_OUTPUT_KEY])
             if joined_context:
-                decision_specific_output = dict(decision_output[HOOK_SPECIFIC_OUTPUT_KEY])
                 decision_specific_output[ADDITIONAL_CONTEXT_KEY] = joined_context
-                decision_output[HOOK_SPECIFIC_OUTPUT_KEY] = decision_specific_output
+            joined_deny_reasons = _joined_reasons(all_deny_reasons)
+            if each_decision == DENY_PERMISSION_DECISION and joined_deny_reasons:
+                decision_specific_output[PERMISSION_DECISION_REASON_KEY] = joined_deny_reasons
+            decision_output[HOOK_SPECIFIC_OUTPUT_KEY] = decision_specific_output
             return HookVerdict(0, json.dumps(decision_output), "")
     if not joined_context:
         return HookVerdict(0, "", "")

package/hooks/lifecycle/test_nested_project_hooks.py

@@ -189,6 +189,87 @@ def test_should_pass_a_child_deny_decision_through(tmp_path: pathlib.Path) -> No
     assert json.loads(completed_process.stdout) == deny_output
 
 
+def _deny_output(reason: str) -> dict[str, object]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+
+
+def test_should_carry_every_child_deny_reason_in_one_refusal(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {
+            "PreToolUse": [
+                _command_group("Bash", f"echo '{json.dumps(_deny_output('no link'))}'"),
+                _command_group("Bash", f"echo '{json.dumps(_deny_output('too long'))}'"),
+            ]
+        },
+    )
+    _make_checkout(
+        tmp_path,
+        "beta",
+        {"PreToolUse": [_command_group("Bash", f"echo '{json.dumps(_deny_output('no link'))}'")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+    assert json.loads(completed_process.stdout) == _deny_output("no link\n\ntoo long")
+
+
+def test_should_carry_child_deny_reasons_into_a_blocking_exit(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Bash", f"echo '{json.dumps(_deny_output('no link'))}'")]},
+    )
+    _make_checkout(
+        tmp_path,
+        "beta",
+        {"PreToolUse": [_command_group("Bash", "echo no tests ran >&2; exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == BLOCKING_EXIT_CODE
+    assert completed_process.stderr == "no tests ran\n\nno link"
+
+
+def test_should_forward_a_later_child_deny_ahead_of_an_earlier_ask(
+    tmp_path: pathlib.Path,
+) -> None:
+    ask_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason": "publishing needs a person",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Bash", f"echo '{json.dumps(ask_output)}'")]},
+    )
+    _make_checkout(
+        tmp_path,
+        "beta",
+        {"PreToolUse": [_command_group("Bash", f"echo '{json.dumps(_deny_output('no link'))}'")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert json.loads(completed_process.stdout) == _deny_output("no link")
+
+
 def test_should_not_forward_a_child_allow_decision(tmp_path: pathlib.Path) -> None:
     allow_output = {
         "hookSpecificOutput": {

package/hooks/test_visual_reply_rules.py

@@ -72,6 +72,18 @@ def test_abbreviation_violation_flags_a_lowercase_abbreviation_and_a_tracker_num
     assert 'Tracker number "card 12"' in str(abbreviation_violation("See card 12.", SHIPPED_RULES))
 
 
+def test_abbreviation_violation_names_every_abbreviation_and_tracker_number_on_its_own_line() -> None:
+    assert SHIPPED_RULES is not None
+    violation = str(abbreviation_violation("The UI and the API, e.g. card 12 and card 13.", SHIPPED_RULES))
+    all_lines = violation.splitlines()
+    assert len(all_lines) == 5
+    assert 'Abbreviation "UI"' in all_lines[0]
+    assert 'Abbreviation "API"' in all_lines[1]
+    assert 'Abbreviation "e.g."' in all_lines[2]
+    assert 'Tracker number "card 12"' in all_lines[3]
+    assert 'Tracker number "card 13"' in all_lines[4]
+
+
 def test_widget_anchor_violation_reads_only_widget_calls() -> None:
     anchor_input = {"widget_code": '<a href="https://example.com">page</a>'}
     assert widget_anchor_violation("mcp__hearthbot__post_widget", anchor_input) is not None

package/hooks/visual_reply_rules.py

@@ -19,6 +19,7 @@ from pathlib import Path
 from json_file_reader import read_json_object
 from hooks_constants.visual_reply_rules_constants import (
     ABBREVIATION_MESSAGE,
+    VIOLATION_LINE_SEPARATOR,
     ABBREVIATIONS_RULE_KEY,
     ALL_REPLY_TOOL_NAME_SUFFIXES,
     ALL_VISUAL_TOOL_NAME_SUFFIXES,
@@ -140,19 +141,35 @@ def mode_enabled(claude_home: Path) -> bool:
 
 
 def abbreviation_violation(prose_text: str, rules: VisualReplyRules) -> str | None:
-    """Return the deny reason for the first abbreviation in prose with links and code removed."""
+    """Return the deny reason naming each abbreviation and tracker number in prose with links and code removed.
+
+    Each one gets its own line, so one refusal names them all.
+    """
     reminder = rules.reminder(ABBREVIATIONS_RULE_KEY)
-    for each_match in CAPITALIZED_ABBREVIATION_PATTERN.finditer(prose_text):
-        if each_match.group(0) not in rules.all_allowed_capitalized_words:
-            return ABBREVIATION_MESSAGE.format(abbreviation=each_match.group(0), reminder=reminder)
-    for each_abbreviation in rules.all_lowercase_abbreviations:
-        pattern = LOWERCASE_ABBREVIATION_TEMPLATE.format(abbreviation=re.escape(each_abbreviation))
-        if re.search(pattern, prose_text, re.IGNORECASE):
-            return ABBREVIATION_MESSAGE.format(abbreviation=each_abbreviation, reminder=reminder)
-    tracker_match = TRACKER_NUMBER_PATTERN.search(prose_text)
-    if tracker_match is not None:
-        return TRACKER_NUMBER_MESSAGE.format(reference=tracker_match.group(0), reminder=reminder)
-    return None
+    all_abbreviations = [
+        each_match.group(0)
+        for each_match in CAPITALIZED_ABBREVIATION_PATTERN.finditer(prose_text)
+        if each_match.group(0) not in rules.all_allowed_capitalized_words
+    ] + [
+        each_abbreviation
+        for each_abbreviation in rules.all_lowercase_abbreviations
+        if re.search(
+            LOWERCASE_ABBREVIATION_TEMPLATE.format(abbreviation=re.escape(each_abbreviation)),
+            prose_text,
+            re.IGNORECASE,
+        )
+    ]
+    all_violations = [
+        *(
+            ABBREVIATION_MESSAGE.format(abbreviation=each_abbreviation, reminder=reminder)
+            for each_abbreviation in dict.fromkeys(all_abbreviations)
+        ),
+        *(
+            TRACKER_NUMBER_MESSAGE.format(reference=each_match.group(0), reminder=reminder)
+            for each_match in TRACKER_NUMBER_PATTERN.finditer(prose_text)
+        ),
+    ]
+    return VIOLATION_LINE_SEPARATOR.join(all_violations) if all_violations else None
 
 
 def widget_anchor_violation(tool_name: str, all_tool_input: dict[str, object]) -> str | None:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.106.2",
+    "version": "8.106.4",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/policy_lint/config/check_catalog_constants.py

@@ -61,6 +61,9 @@ ALL_CHECK_CATALOG_ENTRIES: tuple[CheckCatalogEntry, ...] = (
         "paired-test-missing-function",
     ),
     CheckCatalogEntry("but exercises nowhere", "paired-test-omitted-function"),
+    CheckCatalogEntry(") - consider splitting", "file-length"),
+    CheckCatalogEntry(" lines (max ", "function-line-cap"),
+    CheckCatalogEntry(" has nesting depth ", "nesting-depth"),
 )
 
 SEVERITY_BREAKING: str = "breaking"
@@ -68,5 +71,8 @@ SEVERITY_SMELL: str = "smell"
 SEVERITY_BY_CHECK_ID: dict[str, str] = {
     "code-rules/paired-test-missing-function": SEVERITY_SMELL,
     "code-rules/paired-test-omitted-function": SEVERITY_SMELL,
+    "validators/file-length": SEVERITY_SMELL,
+    "validators/function-line-cap": SEVERITY_SMELL,
+    "validators/nesting-depth": SEVERITY_SMELL,
     "test-pairing": SEVERITY_SMELL,
 }

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -18,6 +18,7 @@ from policy_lint.config.check_catalog_constants import (
 from policy_lint.model import Diagnostic, Severity
 
 _BUNDLING_RULE_ID = "code-rules"
+_VALIDATORS_RULE_ID = "validators"
 _HOOKS_DIRECTORY = Path(__file__).resolve().parents[2] / "hooks"
 _TEST_FILE_PREFIX = "test_"
 _PYTHON_GLOB = "*.py"
@@ -82,6 +83,9 @@ ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
         " already covers another public function in that module",
         "paired-test-omitted-function",
     ),
+    ("src/app.py:1: File is 412 lines (max 400) - consider splitting", "file-length"),
+    ("src/app.py:4: Function 'run' is 37 lines (max 30)", "function-line-cap"),
+    ("src/app.py:9: Function 'run' has nesting depth 3 (max 2)", "nesting-depth"),
 )
 
 
@@ -169,6 +173,23 @@ def test_a_paired_test_check_reports_as_a_warning(check_name: str) -> None:
     assert severity_for_check_id(f"{_BUNDLING_RULE_ID}/{check_name}") is Severity.WARNING
 
 
+@pytest.mark.parametrize(
+    ("sample_message", "check_name"),
+    tuple(
+        each_sample
+        for each_sample in ALL_MESSAGE_SAMPLES
+        if each_sample[1] in ("file-length", "function-line-cap", "nesting-depth")
+    ),
+)
+def test_a_validator_smell_reports_as_a_warning(
+    sample_message: str, check_name: str
+) -> None:
+    check_id = check_id_for_message(_VALIDATORS_RULE_ID, sample_message)
+
+    assert check_id == f"{_VALIDATORS_RULE_ID}/{check_name}"
+    assert severity_for_check_id(check_id) is Severity.WARNING
+
+
 def test_an_unclassified_check_reports_as_an_error() -> None:
     unclassified_check_id = f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"