claude-dev-env 2.8.0 → 2.10.0

package/hooks/blocking/hedging_language_blocker.py

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

package/hooks/blocking/hook_prose_detector_consistency.py

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

package/hooks/blocking/intent_only_ending_blocker.py

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

package/hooks/blocking/plain_language_blocker.py

@@ -31,6 +31,9 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     ALL_CHAT_DETAIL_MARKERS,
@@ -44,6 +47,7 @@ from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     DOT_CLAUDE_DIRECTORY_NAME,
     FENCED_CODE_BLOCK_PATTERN,
     FILE_PATH_PATTERN,
+    HEAVY_WORD_SWAP_LIST_SEPARATOR,
     INLINE_CODE_PATTERN,
     INLINE_CODE_PLACEHOLDER,
     INLINE_CODE_SPAN_PATTERN,
@@ -65,6 +69,12 @@ from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     USER_FACING_LEAN_QUESTION_NOTICE,
     USER_FACING_PLAIN_LANGUAGE_NOTICE,
 )
+from hooks_constants.prose_matcher_precision_constants import (  # noqa: E402
+    ADVISORY_CONTEXT_SNIPPET_MAX_CHARS,
+    MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+    MAXIMUM_ADVISORY_EMITS_PER_CALL,
+)
+from observability.prose_matcher_advisory import emit_advisory_candidate  # noqa: E402
 
 
 def strip_non_prose_regions(text: str) -> str:
@@ -234,7 +244,12 @@ def _load_project_allowlist(
 
 
 def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
-    """Return a deny reason naming each flagged term and its plain replacement."""
+    """Return a legacy block-reason string naming each term and plain swap.
+
+    Heavy-word enforcement no longer hard-denies (OP-07D). Callers that still
+    need the named swap list for notices or tests use this helper. Lean-block
+    denials use ``build_lean_block_reason`` instead.
+    """
     swap_phrases = ", ".join(
         f'use "{each_replacement}" instead of "{each_term}"'
         for each_term, each_replacement in all_matches
@@ -246,6 +261,31 @@ def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
     )
 
 
+def build_advisory_system_message(all_matches: list[tuple[str, str]]) -> str:
+    """Return allow-path advisory text naming everyday swaps for heavy words.
+
+    ::
+
+        build_advisory_system_message([("initiate", "start")])
+            -> names use "start" instead of "initiate" (no permission deny)
+
+    Args:
+        all_matches: ``(heavy_term, everyday_swap)`` pairs from the word scan.
+
+    Returns:
+        A systemMessage string for PreToolUse allow with advisory guidance.
+    """
+    swap_phrases = HEAVY_WORD_SWAP_LIST_SEPARATOR.join(
+        f'use "{each_replacement}" instead of "{each_term}"'
+        for each_term, each_replacement in all_matches
+    )
+    return (
+        f"[PLAIN_LANGUAGE advisory] {swap_phrases}. "
+        "Reach for the everyday word the reader understands on the first pass. "
+        "This notice does not deny the write; lean-block structure denials still apply."
+    )
+
+
 def _normalize_line_endings(prose_text: str) -> str:
     """Return the prose with every line ending spelled as a bare line feed.
 
@@ -572,50 +612,125 @@ def _emit_deny(deny_reason: str, output_stream: TextIO) -> None:
     output_stream.flush()
 
 
+def build_allow_advisory_payload(system_message: str) -> dict[str, object]:
+    """Build an allow payload that still surfaces everyday-word guidance.
+
+    Args:
+        system_message: Advisory text naming heavy terms and plain swaps.
+
+    Returns:
+        A PreToolUse payload without permissionDecision deny.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        },
+        "systemMessage": system_message,
+        "suppressOutput": False,
+    }
+
+
+def _emit_allow_advisory(system_message: str, output_stream: TextIO) -> None:
+    output_stream.write(json.dumps(build_allow_advisory_payload(system_message)))
+    output_stream.flush()
+
+
+def _emit_plain_language_advisory_candidates(
+    surface: str,
+    all_matches: list[tuple[str, str]],
+    prose_text: str,
+) -> None:
+    """Record privacy-safe advisory hits when enforcement is off (fail open)."""
+    try:
+        for each_match in all_matches[:MAXIMUM_ADVISORY_EMITS_PER_CALL]:
+            each_term = each_match[0]
+            emit_advisory_candidate(
+                MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+                surface,
+                f"{each_term}:{prose_text[:ADVISORY_CONTEXT_SNIPPET_MAX_CHARS]}",
+            )
+    except (ImportError, OSError, TypeError, ValueError):
+        return
+
+
 def evaluate(payload_by_key: dict[str, object]) -> str | None:
-    """Decide whether a payload carries a question block or heavy words to block.
+    """Return a lean-block deny reason, or None when the payload is allowed.
 
-    An AskUserQuestion payload meets the lean-block check first, so a question
-    text or an option description carrying chat detail returns a LEAN_QUESTION
-    deny reason. Every guarded payload then meets the word scan, which returns a
-    PLAIN_LANGUAGE deny reason for the first heavy word it finds.
+    Heavy-word matches never produce a deny reason (OP-07D). When prose-style
+    enforcement is on, main still emits an allow advisory naming everyday swaps
+    for AskUserQuestion and ``.md`` writes. When enforcement is off, matches
+    only record privacy-safe advisory candidates (OP-07B).
 
     Args:
         payload_by_key: The PreToolUse payload with tool_name and tool_input.
 
     Returns:
-        The permissionDecisionReason text when the payload is denied, or None
-        when it is allowed.
+        The permissionDecisionReason text for a lean-block denial, or None when
+        the payload is allowed (with or without a heavy-word advisory).
+    """
+    deny_reason, _advisory_system_message = evaluate_with_advisory(payload_by_key)
+    return deny_reason
+
+
+def evaluate_with_advisory(
+    payload_by_key: dict[str, object],
+    all_allowlisted_terms: frozenset[str] | None = None,
+) -> tuple[str | None, str | None]:
+    """Return ``(deny_reason, advisory_system_message)`` for one PreToolUse payload.
+
+    ::
+
+        lean chat detail in AskUserQuestion  ->  (lean deny reason, None)
+        heavy word, enforcement ON           ->  (None, advisory systemMessage)
+        heavy word, enforcement OFF          ->  (None, None) + privacy JSONL
+        clean payload                        ->  (None, None)
+
+    Args:
+        payload_by_key: The PreToolUse payload with tool_name and tool_input.
+        all_allowlisted_terms: Optional project-vocabulary exemptions. When
+            omitted, the project allowlist file is loaded for the payload path.
+
+    Returns:
+        A pair of optional deny reason and optional allow-path advisory message.
     """
     raw_tool_name = payload_by_key.get("tool_name", "")
     raw_tool_input = payload_by_key.get("tool_input", {})
     if not isinstance(raw_tool_name, str) or not isinstance(raw_tool_input, dict):
-        return None
+        return None, None
 
     if raw_tool_name in ALL_WRITE_EDIT_TOOL_NAMES:
         target_file_path = raw_tool_input.get("file_path", "")
         if isinstance(target_file_path, str) and is_ephemeral_path(
             target_file_path, payload_by_key
         ):
-            return None
+            return None, None
 
     if raw_tool_name == ASK_USER_QUESTION_TOOL_NAME:
         all_block_violations = find_question_block_violations(raw_tool_input)
         if all_block_violations:
-            return build_lean_block_reason(all_block_violations)
+            return build_lean_block_reason(all_block_violations), None
 
     prose_text = _collect_prose_for_tool(raw_tool_name, raw_tool_input)
     if not prose_text:
-        return None
+        return None, None
 
-    all_allowlisted_terms = _load_project_allowlist(
-        raw_tool_name, raw_tool_input, payload_by_key
+    resolved_allowlisted_terms = (
+        all_allowlisted_terms
+        if all_allowlisted_terms is not None
+        else _load_project_allowlist(raw_tool_name, raw_tool_input, payload_by_key)
+    )
+    all_matches = find_banned_terms(
+        prose_text, all_allowlisted_terms=resolved_allowlisted_terms
     )
-    all_matches = find_banned_terms(prose_text, all_allowlisted_terms)
     if not all_matches:
-        return None
+        return None, None
 
-    return build_block_reason(all_matches)
+    if not prose_style_enforcement_enabled_in_environment():
+        _emit_plain_language_advisory_candidates(raw_tool_name, all_matches, prose_text)
+        return None, None
+
+    return None, build_advisory_system_message(all_matches)
 
 
 def main() -> None:
@@ -627,11 +742,15 @@ def main() -> None:
     if not isinstance(input_data, dict):
         sys.exit(0)
 
-    deny_reason = evaluate(input_data)
-    if deny_reason is None:
+    deny_reason, advisory_system_message = evaluate_with_advisory(input_data)
+    if deny_reason is not None:
+        _emit_deny(deny_reason, sys.stdout)
+        sys.exit(0)
+
+    if advisory_system_message is not None:
+        _emit_allow_advisory(advisory_system_message, sys.stdout)
         sys.exit(0)
 
-    _emit_deny(deny_reason, sys.stdout)
     sys.exit(0)
 
 

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -26,10 +26,16 @@ from pathlib import Path
 
 import _path_setup  # noqa: F401
 
+from plain_language_blocker import (
+    build_allow_advisory_payload as build_plain_language_allow_advisory_payload,
+)
 from plain_language_blocker import (
     build_deny_payload as build_plain_language_deny_payload,
 )
 from plain_language_blocker import evaluate as evaluate_plain_language
+from plain_language_blocker import (
+    evaluate_with_advisory as evaluate_plain_language_with_advisory,
+)
 from state_description_blocker import (
     build_deny_payload as build_state_description_deny_payload,
 )
@@ -40,32 +46,46 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (
     ALLOW_DECISION,
     BLOCKING_CRASH_DENY_REASON,
     BLOCKING_CRASH_EXIT_CODE,
+    CONTEXT_JOIN_SEPARATOR,
     DENY_DECISION,
     EXIT_CODE_TWO_DENY_REASON,
     HOOK_EVENT_NAME,
     PLAIN_LANGUAGE_BLOCKER_MODULE_NAME,
+    REASON_JOIN_SEPARATOR,
     STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
+    SYSTEM_MESSAGE_JOIN_SEPARATOR,
     HostedHookEntry,
 )
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 
 NativeEvaluator = Callable[[dict[str, object]], str | None]
 DenyPayloadBuilder = Callable[[str], dict[str, object]]
+AdvisoryEvaluator = Callable[
+    [dict[str, object]], tuple[str | None, str | None]
+]
+AllowAdvisoryPayloadBuilder = Callable[[str], dict[str, object]]
 
 
 @dataclass(frozen=True)
 class NativeHook:
-    """A nativized hook's evaluator paired with its full deny-payload builder.
+    """A nativized hook's evaluator paired with its full payload builders.
 
     Attributes:
         evaluate: The hook's evaluate function returning a deny-reason or None.
         build_deny_payload: The hook's builder that turns a deny-reason into the
             full deny payload the standalone hook writes (carrying systemMessage,
             additionalContext, and suppressOutput).
+        evaluate_with_advisory: Optional evaluator that returns
+            ``(deny_reason, advisory_system_message)`` so allow-path notices
+            match the standalone hook (plain_language OP-07D).
+        build_allow_advisory_payload: Optional builder for an allow payload that
+            carries the advisory systemMessage without denying.
     """
 
     evaluate: NativeEvaluator
     build_deny_payload: DenyPayloadBuilder
+    evaluate_with_advisory: AdvisoryEvaluator | None = None
+    build_allow_advisory_payload: AllowAdvisoryPayloadBuilder | None = None
 
 
 _native_hook_by_module_name: dict[str, NativeHook] = {
@@ -76,6 +96,8 @@ _native_hook_by_module_name: dict[str, NativeHook] = {
     PLAIN_LANGUAGE_BLOCKER_MODULE_NAME: NativeHook(
         evaluate=evaluate_plain_language,
         build_deny_payload=build_plain_language_deny_payload,
+        evaluate_with_advisory=evaluate_plain_language_with_advisory,
+        build_allow_advisory_payload=build_plain_language_allow_advisory_payload,
     ),
 }
 
@@ -180,19 +202,28 @@ def run_native_hook(
     Calls the evaluator directly with the payload dict, builds the full deny JSON
     via the hook's own deny-payload builder so the captured stdout matches the
     standalone hook's deny shape (carrying systemMessage, additionalContext, and
-    suppressOutput), and catches a non-SystemExit crash to log and classify it.
+    suppressOutput), emits an allow-with-systemMessage payload when the hook
+    returns an advisory without a deny, and catches a non-SystemExit crash to
+    log and classify it.
 
     Args:
-        native_hook: The hook's evaluator paired with its deny-payload builder.
+        native_hook: The hook's evaluator paired with its payload builders.
         payload_by_key: The parsed payload dict to pass to the evaluator.
         is_blocking: Whether a crash from this hook surfaces a blocking signal.
 
     Returns:
-        A HostedHookResult carrying the captured deny JSON (empty when allowed),
-        the crash flag, and the blocking classification.
+        A HostedHookResult carrying the captured deny or allow-advisory JSON
+        (empty when the payload is clean), the crash flag, and the blocking
+        classification.
     """
     try:
-        deny_reason = native_hook.evaluate(payload_by_key)
+        if native_hook.evaluate_with_advisory is not None:
+            deny_reason, advisory_system_message = native_hook.evaluate_with_advisory(
+                payload_by_key
+            )
+        else:
+            deny_reason = native_hook.evaluate(payload_by_key)
+            advisory_system_message = None
     except Exception as error:
         _log_hook_crash(native_hook.evaluate.__module__, error)
         return HostedHookResult(
@@ -202,9 +233,17 @@ def run_native_hook(
             is_blocking=is_blocking,
         )
 
-    captured_stdout = (
-        json.dumps(native_hook.build_deny_payload(deny_reason)) if deny_reason is not None else ""
-    )
+    if deny_reason is not None:
+        captured_stdout = json.dumps(native_hook.build_deny_payload(deny_reason))
+    elif (
+        advisory_system_message is not None
+        and native_hook.build_allow_advisory_payload is not None
+    ):
+        captured_stdout = json.dumps(
+            native_hook.build_allow_advisory_payload(advisory_system_message)
+        )
+    else:
+        captured_stdout = ""
     return HostedHookResult(
         exit_code=0,
         captured_stdout=captured_stdout,
@@ -394,40 +433,79 @@ def aggregate_hosted_hook_results(
     )
 
 
+def unique_first_seen_strings(all_values: list[str]) -> list[str]:
+    """Return values in first-seen order with exact-string duplicates dropped.
+
+    ::
+
+        unique_first_seen_strings(["a", "b", "a"])  ->  ["a", "b"]
+
+    Comparison is exact full-string equality only (no case fold, no trim).
+    Each field of the deny payload (reasons, systemMessage, additionalContext)
+    is collapsed separately so a deny reason identical to a context string never
+    cross-collapses.
+
+    Args:
+        all_values: Strings collected from hosted hooks in run order.
+
+    Returns:
+        A new list with the first occurrence of each exact string kept.
+    """
+    seen_values: set[str] = set()
+    unique_values: list[str] = []
+    for each_value in all_values:
+        if each_value in seen_values:
+            continue
+        seen_values.add(each_value)
+        unique_values.append(each_value)
+    return unique_values
+
+
 def _emit_deny_decision(decision: DispatcherDecision) -> None:
     """Write one deny JSON object to stdout carrying all deny reasons and context.
 
-    Carries every hook's systemMessage and additionalContext and the
-    suppressOutput flag so the dispatched deny matches the standalone hooks'
-    full deny shape.
+    Collapses exact-duplicate reasons, systemMessage lines, and additionalContext
+    lines at emit time (first-seen order) so the final payload is compact while
+    aggregate_hosted_hook_results still records every firing for logging.
 
     Args:
         decision: The aggregated dispatcher decision with deny reasons, context,
             and the suppressOutput flag.
     """
-    combined_reason = " | ".join(decision.all_deny_reasons)
+    all_unique_deny_reasons = unique_first_seen_strings(decision.all_deny_reasons)
+    all_unique_system_messages = unique_first_seen_strings(decision.all_system_messages)
+    all_unique_additional_context = unique_first_seen_strings(
+        decision.all_additional_context
+    )
+    combined_reason = REASON_JOIN_SEPARATOR.join(all_unique_deny_reasons)
     hook_specific: dict[str, object] = {
         "hookEventName": HOOK_EVENT_NAME,
         "permissionDecision": DENY_DECISION,
         "permissionDecisionReason": combined_reason,
     }
-    if decision.all_additional_context:
-        hook_specific["additionalContext"] = "\n".join(decision.all_additional_context)
+    if all_unique_additional_context:
+        hook_specific["additionalContext"] = CONTEXT_JOIN_SEPARATOR.join(
+            all_unique_additional_context
+        )
     deny_payload: dict[str, object] = {"hookSpecificOutput": hook_specific}
-    if decision.all_system_messages:
-        deny_payload["systemMessage"] = "\n".join(decision.all_system_messages)
+    if all_unique_system_messages:
+        deny_payload["systemMessage"] = CONTEXT_JOIN_SEPARATOR.join(
+            all_unique_system_messages
+        )
     if decision.should_suppress_output:
         deny_payload["suppressOutput"] = True
     sys.stdout.write(json.dumps(deny_payload) + "\n")
     sys.stdout.flush()
 
 
-def _emit_allow_decision() -> None:
+def _emit_allow_decision(decision: DispatcherDecision) -> None:
     """Write one explicit allow JSON object to stdout.
 
     Matches the shape a standalone hosted hook emits when it auto-approves the
     write, so a write a hosted hook allows explicitly is auto-approved under the
-    dispatcher rather than falling back to the default permission flow.
+    dispatcher rather than falling back to the default permission flow. When a
+    hook also carried an advisory systemMessage (plain-language heavy words),
+    that notice rides on the allow payload without denying.
     """
     allow_payload: dict[str, object] = {
         "hookSpecificOutput": {
@@ -435,6 +513,10 @@ def _emit_allow_decision() -> None:
             "permissionDecision": ALLOW_DECISION,
         }
     }
+    if decision.all_system_messages:
+        allow_payload["systemMessage"] = SYSTEM_MESSAGE_JOIN_SEPARATOR.join(
+            decision.all_system_messages
+        )
     sys.stdout.write(json.dumps(allow_payload) + "\n")
     sys.stdout.flush()
 
@@ -522,7 +604,7 @@ def dispatch(
         _emit_deny_decision(aggregated_decision)
         return
     if aggregated_decision.should_allow:
-        _emit_allow_decision()
+        _emit_allow_decision(aggregated_decision)
 
 
 def main() -> None: