claude-dev-env 8.81.0 → 8.82.0

package/hooks/blocking/final_reply_gate.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Stop hook that checks the closing chat reply for an unvalidated claim.
+
+The reply length gate checks the chat tools. This gate checks the reply the
+session ends its turn with, which reaches the user with no tool call::
+
+    flag: My guess is one to two hours.
+    flag: I didn't confirm this one.
+    flag: Run 18239174012 passed.        (no tool result shows the run)
+    ok:   Run 18239174012 took 39 minutes. (a tool result shows the run)
+
+It applies the banned words, the unvalidated claim pattern, and the cited
+run, job, check, and pull request numbers from ``reply_length_gate.py``. The
+citation check is skipped when the transcript cannot be read. A block sends
+the reason back so the model rewrites the reply. Claude Code ends the turn
+after eight blocks in a row.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from reply_length_gate import (
+    banned_word_violation,
+    configured_banned_words,
+    unseen_citation_violation,
+    unvalidated_claim_violation,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.final_reply_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    DECISION_KEY,
+    HOOK_EVENT_NAME,
+    LAST_ASSISTANT_MESSAGE_KEY,
+    REASON_KEY,
+    REWRITE_INSTRUCTION,
+    TRANSCRIPT_PATH_KEY,
+)
+
+
+def final_reply_violation(reply_text: str, transcript_path: object) -> str | None:
+    """Return the block reason for the closing reply, or None when it passes."""
+    return (
+        banned_word_violation(reply_text, configured_banned_words())
+        or unvalidated_claim_violation(reply_text)
+        or unseen_citation_violation(reply_text, transcript_path)
+    )
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    reply_text = hook_input.get(LAST_ASSISTANT_MESSAGE_KEY)
+    if not isinstance(reply_text, str):
+        return ALLOW_EXIT_CODE
+    violation = final_reply_violation(reply_text, hook_input.get(TRANSCRIPT_PATH_KEY))
+    if violation is None:
+        return ALLOW_EXIT_CODE
+    block_reason = violation + REWRITE_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name, HOOK_EVENT_NAME, block_reason, offending_input_preview=reply_text
+    )
+    sys.stdout.write(json.dumps({DECISION_KEY: BLOCK_DECISION, REASON_KEY: block_reason}))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/reply_length_gate.py

@@ -33,9 +33,23 @@ The gate uses the ``banned_words`` list in ``~/.claude/reply-banned-words.json``
 or in the file that CLAUDE_REPLY_BANNED_WORDS_PATH names. Without a valid
 list there, it uses ALL_DEFAULT_BANNED_WORDS.
 
-The banned-word check also reads the prose of a decision card: its question,
-its context, and each option's label and consequence.
-A decision card gets no length check.
+It denies a sentence that guesses, estimates, hedges a duration, or admits
+a check did not run::
+
+    flag: My guess is one to two hours.
+    flag: I didn't confirm this one.
+    ok:   The last build took 39 minutes.
+
+It denies an Actions run, a pull request link, or a 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. With no readable transcript, this check
+is skipped.
+
+The banned-word, unvalidated claim, and citation checks also read the prose of a
+decision card: its question, its context, and each option's label and
+consequence. They read an AskUserQuestion card the same way: each
+question, its header, and each option's label and description.
+A card gets no length check.
 
 Each non-empty line counts as its own sentence, so a list counts one
 sentence per item. URLs, markdown link targets, inline code spans, and
@@ -74,6 +88,7 @@ from visual_reply_rules import (
     load_rules,
     mode_enabled,
     second_reply_violation,
+    successful_result_text,
     visual_violation,
     widget_anchor_violation,
     widget_flowchart_advice,
@@ -90,6 +105,8 @@ from hooks_constants.reply_length_gate_constants import (
     ALL_DECISION_OPTION_PROSE_KEYS,
     ALL_DEFAULT_BANNED_WORDS,
     ALL_EVIDENCE_PATTERNS,
+    ALL_QUESTION_CARD_PROSE_KEYS,
+    ALL_QUESTION_OPTION_PROSE_KEYS,
     ALLOW_EXIT_CODE,
     BANNED_WORD_MESSAGE,
     BANNED_WORD_PART_SEPARATOR,
@@ -100,10 +117,14 @@ from hooks_constants.reply_length_gate_constants import (
     BLOCK_EXIT_CODE,
     CAUSAL_CLAIM_PATTERN,
     CARD_TEXT_SEPARATOR,
+    CITED_NUMBER_IN_RESULT_TEMPLATE,
+    CITED_NUMBER_PATTERN,
     CLAUDE_HOME_DIRECTORY_NAME,
     CONFIG_FILE_ENCODING,
+    CURLY_APOSTROPHE,
     DECISION_CARD_OPTIONS_KEY,
     DECISION_CARD_TOOL_NAME,
+    DURATION_CLAIM_PATTERN,
     EM_DASH_MESSAGE,
     EM_DASH_PATTERN,
     FENCED_BLOCK_PATTERN,
@@ -118,10 +139,13 @@ from hooks_constants.reply_length_gate_constants import (
     MAXIMUM_WORDS_PER_SENTENCE,
     MID_SENTENCE_COLON_MESSAGE,
     MID_SENTENCE_COLON_PATTERN,
+    QUESTION_CARD_QUESTIONS_KEY,
+    QUESTION_CARD_TOOL_NAME,
     RETRY_INSTRUCTION,
     SENTENCE_END_PATTERN,
     SENTENCE_PREVIEW_SUFFIX,
     SENTENCE_PREVIEW_WORD_COUNT,
+    STRAIGHT_APOSTROPHE,
     TEXT_KEY,
     TOO_MANY_SENTENCES_MESSAGE,
     TOOL_INPUT_KEY,
@@ -129,7 +153,10 @@ from hooks_constants.reply_length_gate_constants import (
     TRANSCRIPT_PATH_KEY,
     UNLINKED_PULL_REQUEST_MESSAGE,
     UNLINKED_PULL_REQUEST_PATTERN,
+    UNSEEN_CITATION_MESSAGE,
     UNSOURCED_CAUSE_MESSAGE,
+    UNVALIDATED_CLAIM_MESSAGE,
+    UNVALIDATED_CLAIM_PATTERN,
     URL_PATTERN,
     WORD_PATTERN,
     WORD_SEPARATOR,
@@ -146,12 +173,9 @@ def countable_text(reply_text: str) -> str:
 
 def sentence_word_lists(reply_text: str) -> list[list[str]]:
     """Split the text into sentences, one per line or terminal mark, as word lists."""
-    all_sentence_texts = [
-        each_sentence
-        for each_line in LINE_BREAK_PATTERN.split(countable_text(reply_text))
-        for each_sentence in SENTENCE_END_PATTERN.split(each_line)
+    all_word_lists = [
+        WORD_PATTERN.findall(each_sentence) for each_sentence in prose_sentences(countable_text(reply_text))
     ]
-    all_word_lists = [WORD_PATTERN.findall(each_sentence) for each_sentence in all_sentence_texts]
     return [each_word_list for each_word_list in all_word_lists if each_word_list]
 
 
@@ -187,14 +211,18 @@ def em_dash_violation(reply_text: str) -> str | None:
     return EM_DASH_MESSAGE
 
 
-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."""
-    all_sentences = [
-        each_sentence
+def prose_sentences(reply_text: str) -> list[str]:
+    """Split the text outside fenced blocks into sentences, one per line or terminal mark."""
+    return [
+        each_sentence.strip()
         for each_line in LINE_BREAK_PATTERN.split(FENCED_BLOCK_PATTERN.sub(" ", reply_text))
         for each_sentence in SENTENCE_END_PATTERN.split(each_line)
     ]
-    for each_sentence in all_sentences:
+
+
+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:
@@ -254,6 +282,45 @@ def banned_word_violation(reply_text: str, all_banned_words: tuple[str, ...]) ->
     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.
+
+    A duration counts as a guess unless its sentence cites the run, job, check,
+    or pull request that measured it::
+
+        flag: It should take about 40 minutes.
+        ok:   The last queue build took 39 minutes, run 18239174012.
+    """
+    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
+        is_uncited_duration = (
+            DURATION_CLAIM_PATTERN.search(prose_text) is not 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
+
+
+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.
+
+    Returns None when the text cites nothing or the transcript cannot be read.
+    """
+    all_citations = list(CITED_NUMBER_PATTERN.finditer(FENCED_BLOCK_PATTERN.sub(" ", reply_text)))
+    if not all_citations:
+        return None
+    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
+
+
 def all_card_texts(all_card_input: dict[str, object]) -> list[str]:
     """Collect the prose fields of a decision card: question, context, and each option's text."""
     all_options = all_card_input.get(DECISION_CARD_OPTIONS_KEY)
@@ -271,6 +338,24 @@ def all_card_texts(all_card_input: dict[str, object]) -> list[str]:
     ]
 
 
+def all_question_card_texts(all_card_input: dict[str, object]) -> list[str]:
+    """Collect the prose fields of a question card: each question, its header, and each option's text."""
+    all_questions = all_card_input.get(QUESTION_CARD_QUESTIONS_KEY)
+    all_question_fields: list[object] = []
+    for each_question in all_questions if isinstance(all_questions, list) else []:
+        if not isinstance(each_question, dict):
+            continue
+        all_question_fields.extend(each_question.get(each_key) for each_key in ALL_QUESTION_CARD_PROSE_KEYS)
+        all_options = each_question.get(DECISION_CARD_OPTIONS_KEY)
+        all_question_fields.extend(
+            each_option.get(each_key)
+            for each_option in (all_options if isinstance(all_options, list) else [])
+            if isinstance(each_option, dict)
+            for each_key in ALL_QUESTION_OPTION_PROSE_KEYS
+        )
+    return [each_field for each_field in all_question_fields if isinstance(each_field, str)]
+
+
 def active_mode_rules() -> VisualReplyRules | None:
     """Return the visual reply rules when the mode is on and the rule file parses."""
     if not mode_enabled(Path.home() / CLAUDE_HOME_DIRECTORY_NAME):
@@ -280,7 +365,10 @@ 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 (
+    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)
     )
 
@@ -296,6 +384,8 @@ def reply_violation(
         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
@@ -316,9 +406,16 @@ def tool_violation(
         anchor_violation = widget_anchor_violation(tool_name, all_tool_input)
         if anchor_violation is not None:
             return anchor_violation, str(all_tool_input)
-    if tool_name == DECISION_CARD_TOOL_NAME:
-        card_text = CARD_TEXT_SEPARATOR.join(all_card_texts(all_tool_input))
-        violation = card_violation(card_text, mode_rules)
+    if tool_name in (DECISION_CARD_TOOL_NAME, QUESTION_CARD_TOOL_NAME):
+        all_texts = (
+            all_card_texts(all_tool_input)
+            if tool_name == DECISION_CARD_TOOL_NAME
+            else all_question_card_texts(all_tool_input)
+        )
+        card_text = CARD_TEXT_SEPARATOR.join(all_texts)
+        violation = card_violation(card_text, mode_rules) or unseen_citation_violation(
+            card_text, transcript_path
+        )
         return None if violation is None else (violation, card_text)
     if tool_name not in ALL_CHECKED_TOOL_NAMES:
         return None

package/hooks/blocking/test_final_reply_gate.py

@@ -0,0 +1,94 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import final_reply_gate
+
+GUESSED_REPLY = "My guess is one to two hours if those builds pass first time."
+UNCONFIRMED_REPLY = "Merge queue: I didn\u2019t confirm this one."
+MEASURED_REPLY = "The last queue build took 39 minutes, run 18239174012."
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    reply_text: str,
+    transcript_path: Path | None = None,
+) -> tuple[int, str]:
+    hook_input: dict[str, object] = {
+        "hook_event_name": "Stop",
+        "stop_hook_active": False,
+        "last_assistant_message": reply_text,
+    }
+    if transcript_path is not None:
+        hook_input["transcript_path"] = str(transcript_path)
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = final_reply_gate.main()
+    return exit_code, capsys.readouterr().out
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    monkeypatch.delenv("CLAUDE_REPLY_BANNED_WORDS_PATH", raising=False)
+
+
+def write_tool_result_transcript(transcript_path: Path, result_text: str) -> Path:
+    tool_result = {"type": "tool_result", "tool_use_id": "t1", "content": result_text}
+    transcript_path.write_text(
+        json.dumps({"type": "user", "message": {"content": [tool_result]}}), encoding="utf-8"
+    )
+    return transcript_path
+
+
+@pytest.mark.parametrize(
+    ("reply_text", "quoted_text"),
+    [
+        (GUESSED_REPLY, 'Banned word "guess"'),
+        (UNCONFIRMED_REPLY, 'No tool validated this: "Merge queue: I didn\u2019t confirm this one."'),
+        ("It should take about 40 minutes.", "It should take about 40 minutes."),
+    ],
+)
+def test_should_block_a_closing_reply_that_guesses(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    reply_text: str,
+    quoted_text: str,
+) -> None:
+    exit_code, stdout_text = run_gate(monkeypatch, capsys, reply_text)
+    decision = json.loads(stdout_text)
+    assert exit_code == 0
+    assert decision["decision"] == "block"
+    assert quoted_text in decision["reason"]
+    assert decision["reason"].endswith("Rewrite the reply without it.")
+
+
+def test_should_block_a_run_no_tool_result_shows(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_tool_result_transcript(tmp_path / "s.jsonl", "run 18239170000 ok")
+    _, stdout_text = run_gate(monkeypatch, capsys, MEASURED_REPLY, transcript_path)
+    assert 'cites "run 18239174012"' in json.loads(stdout_text)["reason"]
+
+
+def test_should_allow_a_run_a_tool_result_shows(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_tool_result_transcript(tmp_path / "s.jsonl", "run 18239174012 took 39m")
+    assert run_gate(monkeypatch, capsys, MEASURED_REPLY, transcript_path) == (0, "")
+
+
+def test_should_allow_a_closing_reply_with_no_message(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b'{"hook_event_name": "Stop"}')))
+    assert (final_reply_gate.main(), capsys.readouterr().out) == (0, "")
+
+
+def test_should_return_none_for_a_measured_reply_without_a_transcript() -> None:
+    assert final_reply_gate.final_reply_violation(MEASURED_REPLY, None) is None

package/hooks/blocking/test_reply_length_gate.py

@@ -726,3 +726,211 @@ def test_should_allow_a_reply_with_no_causal_claim(
         monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "The runner restarted. Also, so far so good."}
     )
     assert exit_code == 0
+
+
+UPDATE_TOOL_NAME = "mcp__hearthbot__update_message"
+QUESTION_CARD_TOOL_NAME = "AskUserQuestion"
+RUN_LINK_REPLY = (
+    "The last build passed in [run 18239174012]"
+    "(https://github.com/owner/repo/actions/runs/18239174012)."
+)
+
+
+def write_tool_result_transcript(transcript_path: Path, result_text: str, is_error: bool = False) -> Path:
+    all_entries = [
+        {"type": "user", "message": {"content": "how close are we"}},
+        {
+            "type": "assistant",
+            "message": {"content": [{"type": "tool_use", "id": "t1", "name": "Bash", "input": {}}]},
+        },
+        {
+            "type": "user",
+            "message": {
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": "t1",
+                        "is_error": is_error,
+                        "content": [{"type": "text", "text": result_text}],
+                    }
+                ]
+            },
+        },
+    ]
+    transcript_path.write_text(
+        "\n".join(json.dumps(each_entry) for each_entry in all_entries), encoding="utf-8"
+    )
+    return transcript_path
+
+
+@pytest.mark.parametrize("tool_name", [REPLY_TOOL_NAME, POST_TOOL_NAME, UPDATE_TOOL_NAME])
+def test_should_deny_an_estimate_and_quote_it(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tool_name: str
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, tool_name, {"text": "My estimate is one to two hours."}
+    )
+    assert exit_code == 2
+    assert 'No tool validated this: "My estimate is one to two hours."' in stderr_text
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    [
+        "I didn\u2019t confirm this one.",
+        "I have not checked the queue.",
+        "I assumed the build passed.",
+        "Run 18239174012 is unverified.",
+        "About 20 minutes left.",
+        "It will take two hours.",
+        "ETA is 3-4 hours.",
+        "Estimate from the last check is two builds.",
+        "I did not run the suite.",
+        "The tests have not yet been run.",
+        "The job takes 39 minutes.",
+        "The migration takes seventy minutes.",
+        "I was not able to verify the fix.",
+        "The fix has not been validated.",
+        "The fix was not verified in production.",
+        "The suite takes about 90 seconds.",
+    ],
+)
+def test_should_deny_each_unvalidated_claim_shape(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text})
+    assert exit_code == 2
+    assert "No tool validated this" in stderr_text
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    [
+        "Two builds are left in the queue.",
+        "I will check the queue again within 15 minutes.",
+        "The last queue build took 39 minutes.",
+        "The gate now refuses `guess` and `assumed`.",
+        "The job takes 39 minutes, see run 18239174012.",
+        "The hook cannot run on Windows.",
+        "The crash is not a test problem.",
+        "That is not the check that failed.",
+        "The migration did not run out of memory.",
+        "We did not run into any errors.",
+        "This is not something to check before the release.",
+        "The result is not what we tested for.",
+        "The migration did not run on the replica.",
+        "The old parser did not validate the header length.",
+        "The job has not run yet.",
+        "The config file is not checked in.",
+        "The release branch is not checked out.",
+    ],
+)
+def test_should_allow_a_reply_with_no_unvalidated_claim(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    assert run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text}) == (0, "")
+
+
+def test_should_deny_a_run_no_tool_result_shows(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_tool_result_transcript(tmp_path / "s.jsonl", "run 18239170000 ok")
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": RUN_LINK_REPLY}, transcript_path
+    )
+    assert exit_code == 2
+    assert 'cites "run 18239174012"' in stderr_text
+
+
+def test_should_deny_a_run_only_an_error_result_shows(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_tool_result_transcript(
+        tmp_path / "s.jsonl", "run 18239174012 ok", is_error=True
+    )
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": RUN_LINK_REPLY}, transcript_path
+    )
+    assert exit_code == 2
+    assert "no tool result in this session shows it" in stderr_text
+
+
+def test_should_allow_a_run_a_tool_result_shows(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_tool_result_transcript(tmp_path / "s.jsonl", "run 18239174012 took 39m")
+    assert run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": RUN_LINK_REPLY}, transcript_path
+    ) == (0, "")
+
+
+def test_should_deny_a_question_card_that_admits_a_skipped_check(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    card = {
+        "questions": [
+            {
+                "question": "Ship the gate now?",
+                "header": "Ship",
+                "options": [
+                    {"label": "Ship", "description": "I did not test the Stop hook."},
+                    {"label": "Wait", "description": "Run the suite first."},
+                ],
+            }
+        ]
+    }
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, QUESTION_CARD_TOOL_NAME, card)
+    assert exit_code == 2
+    assert "I did not test the Stop hook." in stderr_text
+
+
+def test_should_allow_a_question_card_with_no_unvalidated_claim(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    card = {
+        "questions": [
+            {
+                "question": "Which gate design?",
+                "header": "Design",
+                "options": [{"label": "Fold in", "description": "One gate checks every reply."}],
+            }
+        ]
+    }
+    assert run_gate(monkeypatch, capsys, QUESTION_CARD_TOOL_NAME, card) == (0, "")
+
+
+def test_should_collect_each_question_card_prose_field() -> None:
+    card = {
+        "questions": [
+            {"question": "Q?", "header": "H", "options": [{"label": "L", "description": "D"}, "x"]},
+            "not a question",
+        ]
+    }
+    assert reply_length_gate.all_question_card_texts(card) == ["Q?", "H", "L", "D"]
+
+
+def test_should_quote_the_hedged_sentence() -> None:
+    assert reply_length_gate.unvalidated_claim_violation("Done. It should take a few minutes.") == (
+        'No tool validated this: "It should take a few minutes.". Run the check yourself or through'
+        " a subagent, then state what the run, log line, output, or file and line shows, or leave"
+        " the claim out."
+    )
+
+
+def test_should_skip_the_citation_check_without_a_transcript() -> None:
+    assert reply_length_gate.unseen_citation_violation(RUN_LINK_REPLY, None) is None
+
+
+def test_should_leave_the_transcript_unread_when_the_text_cites_nothing(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_read_paths: list[object] = []
+    monkeypatch.setattr(reply_length_gate, "successful_result_text", all_read_paths.append)
+    transcript_path = write_tool_result_transcript(tmp_path / "s.jsonl", "nothing cited")
+    assert reply_length_gate.unseen_citation_violation("Two builds left.", transcript_path) is None
+    assert all_read_paths == []
+
+
+def test_should_split_prose_sentences_outside_fenced_blocks() -> None:
+    reply_text = "First one. Second one?\n```\nskipped. code\n```\nThird"
+    assert reply_length_gate.prose_sentences(reply_text) == ["First one.", "Second one?", "", "Third"]

package/hooks/features/conduct-gates.md

@@ -4,8 +4,9 @@ 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. 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.
-- 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, claims labeled as unchecked, 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/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/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.
+- 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.
 - `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.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
@@ -18,7 +19,8 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 ## When it fires
 
-- `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__ask_decision|mcp__hearthbot__post_widget`, timeout `10` seconds in `hooks.json`.
+- `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision|AskUserQuestion|mcp__hearthbot__post_widget`, timeout `10` seconds in `hooks.json`.
+- `blocking/final_reply_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
 - The claim judge runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision`, timeout `30` seconds in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
 - `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
@@ -37,6 +39,7 @@ Preconditions:
 - Run each command from the repository root with Python and pytest available. The tests create transcript and payload fixtures.
 
 - **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
+- **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.
 - **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.
 - **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.
@@ -53,6 +56,7 @@ Preconditions:
 - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
+- The final reply gate blocks the stop and returns its reason to the model, which rewrites the reply. Claude Code ends the turn anyway after eight blocks in a row. The cited number checks in both gates skip when the transcript cannot be read.
 - The edit marker gate scans replacement cards as well as the message text.
 - The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.

package/hooks/hooks.json

@@ -133,7 +133,7 @@
         ]
       },
       {
-        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__ask_decision|mcp__hearthbot__post_widget",
+        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision|AskUserQuestion|mcp__hearthbot__post_widget",
         "hooks": [
           {
             "type": "command",
@@ -147,7 +147,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; a claim labeled as not yet checked; 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, or say you have not checked it.\"}",
+            "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.\"}",
             "timeout": 30,
             "continueOnBlock": true,
             "statusMessage": "claude-dev-env: checking each claim for its source"
@@ -347,6 +347,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/final_reply_gate.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/hooks/hooks_constants/final_reply_gate_constants.py

@@ -0,0 +1,10 @@
+"""Constants for the final reply gate Stop hook."""
+
+HOOK_EVENT_NAME = "Stop"
+LAST_ASSISTANT_MESSAGE_KEY = "last_assistant_message"
+TRANSCRIPT_PATH_KEY = "transcript_path"
+DECISION_KEY = "decision"
+BLOCK_DECISION = "block"
+REASON_KEY = "reason"
+ALLOW_EXIT_CODE = 0
+REWRITE_INSTRUCTION = " Rewrite the reply without it."

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -4,12 +4,18 @@ import re
 
 MAXIMUM_SENTENCE_COUNT = 3
 MAXIMUM_WORDS_PER_SENTENCE = 15
-ALL_CHECKED_TOOL_NAMES = frozenset({"mcp__hearthbot__reply", "mcp__hearthbot__post_message"})
+ALL_CHECKED_TOOL_NAMES = frozenset(
+    {"mcp__hearthbot__reply", "mcp__hearthbot__post_message", "mcp__hearthbot__update_message"}
+)
 DECISION_CARD_TOOL_NAME = "mcp__hearthbot__ask_decision"
 CARD_TEXT_SEPARATOR = "\n"
 ALL_DECISION_CARD_PROSE_KEYS = ("question", "context")
 DECISION_CARD_OPTIONS_KEY = "options"
 ALL_DECISION_OPTION_PROSE_KEYS = ("label", "consequence")
+QUESTION_CARD_TOOL_NAME = "AskUserQuestion"
+QUESTION_CARD_QUESTIONS_KEY = "questions"
+ALL_QUESTION_CARD_PROSE_KEYS = ("question", "header")
+ALL_QUESTION_OPTION_PROSE_KEYS = ("label", "description")
 TOOL_NAME_KEY = "tool_name"
 TOOL_INPUT_KEY = "tool_input"
 TEXT_KEY = "text"
@@ -88,5 +94,54 @@ BANNED_WORD_MESSAGE = 'Banned word "{banned_word}". Delete it and name the evide
 LONG_SENTENCE_MESSAGE = (
     'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
 )
+CURLY_APOSTROPHE = "\u2019"
+STRAIGHT_APOSTROPHE = "'"
+QUANTITY_PATTERN = (
+    r"(?:\d+(?:\.\d+)?|an?|one|two|three|four|five|six|seven|eight|nine|ten"
+    r"|eleven|twelve|(?:thir|four|fif|six|seven|eigh|nine)teen"
+    r"|twenty|thirty|forty(?:-five)?|fifty|sixty|seventy|eighty|ninety"
+    r"|(?:an?\s+|one\s+)?hundred|half an?|a couple(?: of)?|a few|several)"
+)
+DURATION_UNIT_PATTERN = r"(?:hours?|hrs?|minutes?|mins?|seconds?|secs?|days?|weeks?)"
+NEGATION_PATTERN = (
+    r"(?:(?:did|have|has|could|was|were|is|are)(?:\s+not|n't)|can(?:not|'t)|not\s+yet|never)"
+)
+FIRST_PERSON_PATTERN = r"(?:i|we)"
+CHECK_VERB_PATTERN = r"(?:confirm|verif(?:y|ied)|validate|check|test)(?:ed)?"
+CHECKED_PARTICIPLE_PATTERN = r"(?:confirmed|verified|validated|tested|checked(?!\s+(?:in|out)\b))"
+PASSIVE_NEGATION_PATTERN = (
+    r"(?:(?:has|have)(?:\s+not|n't)(?:\s+yet)?\s+been"
+    r"|(?:was|were|is|are)(?:\s+not|n't)(?:\s+yet)?(?:\s+been)?"
+    r"|can(?:not|'t)\s+be)"
+)
+FILLER_WORDS_PATTERN = r"(?:(?!(?:a|an|the|what|which|something|anything)\b)\w+\s+){0,2}"
+UNVALIDATED_CLAIM_PATTERN = re.compile(
+    r"\b(?:guess(?:es|ed|ing)?|estimat(?:e|es|ed|ing)|eta|ballpark"
+    r"|assum(?:e|es|ed|ing)|i think|i expect"
+    r"|un(?:confirmed|verified|validated|checked|tested))\b"
+    rf"|\b{FIRST_PERSON_PATTERN}\s+{NEGATION_PATTERN}\s+{FILLER_WORDS_PATTERN}{CHECK_VERB_PATTERN}\b"
+    rf"|\b{FIRST_PERSON_PATTERN}\s+{NEGATION_PATTERN}\s+{FILLER_WORDS_PATTERN}run\b(?!\s+(?:into|out)\b)"
+    rf"|\b{PASSIVE_NEGATION_PATTERN}\s+(?:{CHECKED_PARTICIPLE_PATTERN}|run)\b",
+    re.IGNORECASE,
+)
+DURATION_CLAIM_PATTERN = re.compile(
+    rf"\btakes?\s+(?:about\s+)?{QUANTITY_PATTERN}\s+{DURATION_UNIT_PATTERN}\b"
+    rf"|\b{QUANTITY_PATTERN}\s+(?:more\s+)?{DURATION_UNIT_PATTERN}\s+(?:left|remaining|to go)\b"
+    rf"|\b(?:about|around|approximately|roughly|another)\s+{QUANTITY_PATTERN}\s+{DURATION_UNIT_PATTERN}\b"
+    rf"|\b{QUANTITY_PATTERN}\s*(?:to|-|or)\s*{QUANTITY_PATTERN}\s+{DURATION_UNIT_PATTERN}\b",
+    re.IGNORECASE,
+)
+UNVALIDATED_CLAIM_MESSAGE = (
+    'No tool validated this: "{claim}". Run the check yourself or through a subagent,'
+    " then state what the run, log line, output, or file and line shows, or leave the claim out."
+)
+CITED_NUMBER_PATTERN = re.compile(
+    r"/actions/runs/(\d+)|/pull/(\d+)|\b(?:run|job|check)\s+#?(\d{5,})\b", re.IGNORECASE
+)
+CITED_NUMBER_IN_RESULT_TEMPLATE = r"(?<!\d){number}(?!\d)"
+UNSEEN_CITATION_MESSAGE = (
+    'The text cites "{citation}", and no tool result in this session shows it.'
+    " Read it yourself or through a subagent first."
+)
 
 ADDITIONAL_CONTEXT_KEY = "additionalContext"

package/hooks/hooks_constants/test_reply_length_gate_constants.py

@@ -5,9 +5,9 @@ def test_gate_limits_replies_to_three_sentences_of_fifteen_words() -> None:
     assert (constants.MAXIMUM_SENTENCE_COUNT, constants.MAXIMUM_WORDS_PER_SENTENCE) == (3, 15)
 
 
-def test_gate_checks_the_two_chat_tools_that_post_to_the_user() -> None:
+def test_gate_checks_the_three_chat_tools_that_post_to_the_user() -> None:
     assert constants.ALL_CHECKED_TOOL_NAMES == frozenset(
-        {"mcp__hearthbot__reply", "mcp__hearthbot__post_message"}
+        {"mcp__hearthbot__reply", "mcp__hearthbot__post_message", "mcp__hearthbot__update_message"}
     )
 
 

package/hooks/hooks_constants/visual_reply_rules_constants.py

@@ -61,6 +61,8 @@ BLOCK_ID_KEY = "id"
 TOOL_USE_ID_KEY = "tool_use_id"
 IS_ERROR_KEY = "is_error"
 IS_META_KEY = "isMeta"
+BLOCK_TEXT_KEY = "text"
+RESULT_TEXT_SEPARATOR = "\n"
 
 ABBREVIATION_MESSAGE = 'Abbreviation "{abbreviation}" in the text. {reminder}'
 TRACKER_NUMBER_MESSAGE = 'Tracker number "{reference}" in the text. {reminder}'

package/hooks/test_visual_reply_rules.py

@@ -15,6 +15,7 @@ from visual_reply_rules import (
     mode_enabled,
     replies_sent_this_turn,
     second_reply_violation,
+    successful_result_text,
     visual_shown_this_turn,
     visual_violation,
     widget_anchor_violation,
@@ -207,3 +208,23 @@ def test_widget_flowchart_advice_should_stay_quiet_when_the_rule_list_has_no_flo
     assert rules is not None
     card_input = {"widget_code": "<div class='card'>Merged</div>"}
     assert widget_flowchart_advice("mcp__hearthbot__post_widget", card_input, rules) is None
+
+
+def test_successful_result_text_joins_only_results_without_an_error(tmp_path: Path) -> None:
+    all_entries = [
+        {"type": "user", "message": {"content": "run 111 from the prompt"}},
+        {"type": "user", "message": {"content": [{"type": "tool_result", "content": "run 222 ok"}]}},
+        {
+            "type": "user",
+            "message": {
+                "content": [
+                    {"type": "tool_result", "content": [{"type": "text", "text": "run 333 ok"}]},
+                    {"type": "tool_result", "is_error": True, "content": "run 444 failed"},
+                ]
+            },
+        },
+    ]
+    transcript_path = tmp_path / "s.jsonl"
+    transcript_path.write_text("\n".join(json.dumps(each) for each in all_entries), encoding="utf-8")
+    assert successful_result_text(str(transcript_path)) == "run 222 ok\nrun 333 ok"
+    assert successful_result_text(str(tmp_path / "missing.jsonl")) is None

package/hooks/visual_reply_rules.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import json
 import re
-from collections.abc import Iterable
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -26,6 +26,7 @@ from hooks_constants.visual_reply_rules_constants import (
     ASSISTANT_ENTRY_TYPE,
     BLOCK_ID_KEY,
     BLOCK_NAME_KEY,
+    BLOCK_TEXT_KEY,
     BLOCK_TYPE_KEY,
     CAPITALIZED_ABBREVIATION_PATTERN,
     CONTENT_KEY,
@@ -45,6 +46,7 @@ from hooks_constants.visual_reply_rules_constants import (
     RULE_KEY_FIELD,
     RULE_LABEL_FIELD,
     RULE_REMINDER_FIELD,
+    RESULT_TEXT_SEPARATOR,
     RULES_FILE_ENCODING,
     RULES_FILE_PATH,
     RULES_LIST_KEY,
@@ -248,14 +250,44 @@ def _read_transcript_lines(transcript_path: object) -> list[str] | None:
         return None
 
 
-def _result_ids(all_entries: list[dict[str, object]], is_error: bool) -> set[object]:
-    return {
-        each_block.get(TOOL_USE_ID_KEY)
+def _result_blocks(all_entries: Iterable[dict[str, object]], is_error: bool) -> Iterator[dict[str, object]]:
+    return (
+        each_block
         for each_entry in all_entries
         for each_block in _content_blocks(each_entry, USER_ENTRY_TYPE)
         if each_block.get(BLOCK_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE
         and bool(each_block.get(IS_ERROR_KEY)) is is_error
-    }
+    )
+
+
+def _result_ids(all_entries: list[dict[str, object]], is_error: bool) -> set[object]:
+    return {each_block.get(TOOL_USE_ID_KEY) for each_block in _result_blocks(all_entries, is_error)}
+
+
+def _result_texts(result_content: object) -> list[str]:
+    if isinstance(result_content, str):
+        return [result_content]
+    return [
+        each_block[BLOCK_TEXT_KEY]
+        for each_block in (result_content if isinstance(result_content, list) else [])
+        if isinstance(each_block, dict) and isinstance(each_block.get(BLOCK_TEXT_KEY), str)
+    ]
+
+
+def successful_result_text(transcript_path: object) -> str | None:
+    """Join the text of every tool result in the session that came back without an error.
+
+    A subagent's report is the result of its Agent call, so it counts. Returns None
+    when the transcript cannot be read.
+    """
+    all_lines = _read_transcript_lines(transcript_path)
+    if all_lines is None:
+        return None
+    return RESULT_TEXT_SEPARATOR.join(
+        each_text
+        for each_block in _result_blocks(_parsed_entries(all_lines), is_error=False)
+        for each_text in _result_texts(each_block.get(CONTENT_KEY))
+    )
 
 
 def visual_shown_this_turn(all_transcript_lines: Iterable[str]) -> bool:

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -136,6 +136,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/artifact_dark_mode_gate.py        -> exempt
         hooks/blocking/merge_over_review_offer_gate.py   -> exempt
+        hooks/blocking/final_reply_gate.py               -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons

package/scripts/policy_lint/config/constants.py

@@ -75,6 +75,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/artifact_dark_mode_gate.py",
     "blocking/haiku_spawn_slim_gate.py",
     "blocking/merge_over_review_offer_gate.py",
+    "blocking/final_reply_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/tests/test_adapter_configuration.py

@@ -66,6 +66,14 @@ def test_new_merge_offer_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_final_reply_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/final_reply_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/step_note_gate.py"],