claude-dev-env 8.21.0 → 8.23.0

package/hooks/blocking/reply_length_gate.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that caps the length of a chat reply before it posts.
+
+The gate reads the ``text`` field of the chat tools that post to the user.
+It denies the call when the text holds more than MAXIMUM_SENTENCE_COUNT
+sentences, or a sentence longer than MAXIMUM_WORDS_PER_SENTENCE words.
+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
+fenced blocks carry no words.
+
+A length limit is a smell elsewhere in this package, recorded and fixed in a
+later pass. A posted reply reaches the user the moment it sends and has no
+later pass, so this gate denies it and the model resends a shorter one.
+"""
+
+from __future__ import annotations
+
+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 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.reply_length_gate_constants import (
+    ALL_CHECKED_TOOL_NAMES,
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    FENCED_BLOCK_PATTERN,
+    HOOK_EVENT_NAME,
+    INLINE_CODE_PATTERN,
+    LINE_BREAK_PATTERN,
+    LINK_TARGET_PATTERN,
+    LONG_SENTENCE_MESSAGE,
+    MAXIMUM_SENTENCE_COUNT,
+    MAXIMUM_WORDS_PER_SENTENCE,
+    RETRY_INSTRUCTION,
+    SENTENCE_END_PATTERN,
+    SENTENCE_PREVIEW_SUFFIX,
+    SENTENCE_PREVIEW_WORD_COUNT,
+    TEXT_KEY,
+    TOO_MANY_SENTENCES_MESSAGE,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    URL_PATTERN,
+    WORD_PATTERN,
+    WORD_SEPARATOR,
+)
+
+
+def countable_text(reply_text: str) -> str:
+    """Remove the spans that carry no words: fenced blocks, code, link targets, URLs."""
+    without_fences = FENCED_BLOCK_PATTERN.sub(" ", reply_text)
+    without_code = INLINE_CODE_PATTERN.sub(" ", without_fences)
+    without_link_targets = LINK_TARGET_PATTERN.sub("]", without_code)
+    return URL_PATTERN.sub(" ", without_link_targets)
+
+
+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 all_sentence_texts]
+    return [each_word_list for each_word_list in all_word_lists if each_word_list]
+
+
+def length_violation(reply_text: str) -> str | None:
+    """Return the deny reason for an over-long reply, 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
+        )
+    for each_sentence in all_sentences:
+        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
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if tool_name not in ALL_CHECKED_TOOL_NAMES:
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict):
+        return ALLOW_EXIT_CODE
+    reply_text = tool_input.get(TEXT_KEY)
+    if not isinstance(reply_text, str):
+        return ALLOW_EXIT_CODE
+    violation = length_violation(reply_text)
+    if violation is None:
+        return ALLOW_EXIT_CODE
+    block_reason = violation + RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=str(tool_name),
+        offending_input_preview=reply_text,
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_edit_marker_gate.py

@@ -0,0 +1,110 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import edit_marker_gate
+
+UPDATE_TOOL_NAME = "mcp__chat__update_message"
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = edit_marker_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@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))
+
+
+def test_should_allow_a_clean_replacement_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, UPDATE_TOOL_NAME, {"message_id": "m1", "text": "The fix is filed."}
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_deny_strikethrough_and_ask_for_the_clean_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        UPDATE_TOOL_NAME,
+        {"text": "~~Please pass this on.~~ The thread files it."},
+    )
+    assert exit_code == 2
+    assert "strikethrough" in stderr_text
+    assert "clean new text" in stderr_text
+
+
+@pytest.mark.parametrize(
+    "edited_text",
+    [
+        "Please pass this on. [Edit: nothing needed from you here.]",
+        "Done. [edit: the thread filed it]",
+        "Done. [ Edit : filed]",
+    ],
+)
+def test_should_deny_an_edit_note_in_any_case(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    edited_text: str,
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, UPDATE_TOOL_NAME, {"text": edited_text})
+    assert exit_code == 2
+    assert "[Edit:" in stderr_text
+
+
+def test_should_deny_a_marker_inside_a_replacement_card(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    card = {"blocks": [{"type": "section", "text": "~~Old plan~~ New plan."}]}
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, UPDATE_TOOL_NAME, {"text": "New plan.", "card": card}
+    )
+    assert exit_code == 2
+
+
+def test_should_allow_markers_on_tools_that_edit_no_message(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, "mcp__chat__reply", {"text": "~~old~~ [Edit: new]"}
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_single_tilde_pair_and_the_word_edit(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        UPDATE_TOOL_NAME,
+        {"text": "Edit the file at ~/notes, about ~5 lines."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_input_without_a_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"not json")))
+    assert edit_marker_gate.main() == 0

package/hooks/blocking/test_reply_length_gate.py

@@ -0,0 +1,193 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import reply_length_gate
+
+REPLY_TOOL_NAME = "mcp__hearthbot__reply"
+POST_TOOL_NAME = "mcp__hearthbot__post_message"
+SIXTEEN_WORD_SENTENCE = (
+    "One two three four five six seven eight nine ten eleven twelve thirteen "
+    "fourteen fifteen sixteen."
+)
+FIFTEEN_WORD_SENTENCE = (
+    "One two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen."
+)
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = reply_length_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@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))
+
+
+def test_should_allow_three_short_sentences(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "The fix is in. Tests pass on CI. It ships with the next release."},
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_allow_a_fifteen_word_sentence(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": FIFTEEN_WORD_SENTENCE})
+    assert exit_code == 0
+
+
+def test_should_deny_four_sentences_and_name_the_count(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "One. Two. Three. Four."},
+    )
+    assert exit_code == 2
+    assert "4 sentences" in stderr_text
+    assert "3" in stderr_text
+
+
+def test_should_deny_a_sixteen_word_sentence_and_name_it(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": SIXTEEN_WORD_SENTENCE}
+    )
+    assert exit_code == 2
+    assert "16 words" in stderr_text
+    assert "15" in stderr_text
+    assert "One two three" in stderr_text
+
+
+def test_should_check_the_project_chat_post_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, POST_TOOL_NAME, {"text": "One. Two. Three. Four."})
+    assert exit_code == 2
+
+
+def test_should_count_each_line_of_a_list_as_a_sentence(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Done:\n- first item\n- second item\n- third item"},
+    )
+    assert exit_code == 2
+    assert "4 sentences" in stderr_text
+
+
+def test_should_not_count_urls_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    long_url = "https://example.com/" + "/".join(["segment"] * 20)
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": f"The draft is up at {long_url} for review."},
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_link_targets_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {
+            "text": "Read [the pull request](https://example.com/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p) now."
+        },
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_backticked_spans_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {
+            "text": "Run `one two three four five six seven eight nine ten eleven twelve thirteen` now."
+        },
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_fenced_blocks(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fenced_block = "```\nOne.\nTwo.\nThree.\nFour.\n" + SIXTEEN_WORD_SENTENCE + "\n```"
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": f"Paste this block.\n{fenced_block}"},
+    )
+    assert exit_code == 0
+
+
+def test_should_not_split_on_decimal_points(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Version 4.5 shipped. Speed rose 2.5 times. Nothing else moved."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_other_tools(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, "mcp__other__reply", {"text": "One. Two. Three. Four."}
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_call_without_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"card": {"blocks": []}})
+    assert exit_code == 0
+
+
+def test_should_allow_empty_stdin(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"")))
+    assert reply_length_gate.main() == 0

package/hooks/hooks.json

@@ -52,6 +52,26 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/reply_length_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*__update_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/edit_marker_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [
@@ -109,6 +129,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/working_style_prompt.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/advisor_rules_prompt.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/orchestrator_auto_starter.py",

package/hooks/hooks_constants/advisor_rules_prompt_constants.py

@@ -0,0 +1,43 @@
+"""Advisor consult guidance for the SessionStart advisor_rules_prompt hook.
+
+Each sentence in ``ALL_ADVISOR_RULE_SENTENCES`` is copied word for word from
+``docs/references/advisor-tool.md``, which stays the one source. A
+synchronization test fails when a sentence drifts from that document.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ADVISOR_DISABLE_ENV_VAR",
+    "ADVISOR_MODEL_SETTINGS_KEY",
+    "ADVISOR_RULES_HEADER",
+    "ADVISOR_RULES_PROMPT",
+    "ALL_ADVISOR_RULE_SENTENCES",
+    "ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES",
+    "CLAUDE_CONFIG_DIR_ENV_VAR",
+    "DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME",
+    "USER_SETTINGS_FILE_NAME",
+]
+
+ADVISOR_MODEL_SETTINGS_KEY = "advisorModel"
+ADVISOR_DISABLE_ENV_VAR = "CLAUDE_CODE_DISABLE_ADVISOR_TOOL"
+ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"
+USER_SETTINGS_FILE_NAME = "settings.json"
+
+ADVISOR_RULES_HEADER = (
+    "ADVISOR, when `advisor` is in your tool list. Use your own judgment on when a"
+    " consult helps. Starting points from ~/.claude/docs/references/advisor-tool.md:"
+)
+
+ALL_ADVISOR_RULE_SENTENCES = (
+    "Call for design, architecture, and risk questions where you will not touch a file.",
+    "On tasks longer than a few steps, aim for an early approach consult and a completion review.",
+    "This cadence guides planning and leaves the task free to follow its evidence.",
+    "Short reactive tasks may use the single consult that best fits the live decision.",
+    "Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.",
+    "Give the advice serious weight.",
+)
+
+ADVISOR_RULES_PROMPT = " ".join((ADVISOR_RULES_HEADER, *ALL_ADVISOR_RULE_SENTENCES))

package/hooks/hooks_constants/edit_marker_gate_constants.py

@@ -0,0 +1,18 @@
+"""Constants for the edit marker gate PreToolUse hook."""
+
+import re
+
+MESSAGE_EDIT_TOOL_SUFFIX = "update_message"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+STRIKETHROUGH_PATTERN = re.compile(r"~~[^~]+~~")
+EDIT_NOTE_PATTERN = re.compile(r"\[\s*edit\s*:", re.IGNORECASE)
+STRIKETHROUGH_MESSAGE = "Edited message holds strikethrough (~~text~~)."
+EDIT_NOTE_MESSAGE = 'Edited message holds an "[Edit:" note.'
+RETRY_INSTRUCTION = (
+    " An edit replaces the whole message. Resend the clean new text,"
+    " with nothing kept from the old version."
+)

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -0,0 +1,28 @@
+"""Constants for the reply length gate PreToolUse hook."""
+
+import re
+
+MAXIMUM_SENTENCE_COUNT = 3
+MAXIMUM_WORDS_PER_SENTENCE = 15
+ALL_CHECKED_TOOL_NAMES = frozenset({"mcp__hearthbot__reply", "mcp__hearthbot__post_message"})
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+TEXT_KEY = "text"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+FENCED_BLOCK_PATTERN = re.compile(r"```.*?(?:```|\Z)", re.DOTALL)
+INLINE_CODE_PATTERN = re.compile(r"`[^`\n]*`")
+LINK_TARGET_PATTERN = re.compile(r"\]\([^)\s]*\)")
+URL_PATTERN = re.compile(r"(?:https?://|www\.)\S+")
+LINE_BREAK_PATTERN = re.compile(r"\n+")
+SENTENCE_END_PATTERN = re.compile(r"(?<=[.!?])\s+")
+WORD_PATTERN = re.compile(r"[A-Za-z0-9]+(?:['.,-][A-Za-z0-9]+)*")
+SENTENCE_PREVIEW_WORD_COUNT = 6
+WORD_SEPARATOR = " "
+SENTENCE_PREVIEW_SUFFIX = "..."
+RETRY_INSTRUCTION = " Cut the text and resend the call."
+TOO_MANY_SENTENCES_MESSAGE = "Reply too long: {sentence_count} sentences, limit {sentence_limit}."
+LONG_SENTENCE_MESSAGE = (
+    'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
+)

package/hooks/hooks_constants/test_edit_marker_gate_constants.py

@@ -0,0 +1,9 @@
+from hooks_constants import edit_marker_gate_constants as constants
+
+
+def test_gate_checks_every_message_edit_tool() -> None:
+    assert constants.MESSAGE_EDIT_TOOL_SUFFIX == "update_message"
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)

package/hooks/hooks_constants/test_reply_length_gate_constants.py

@@ -0,0 +1,15 @@
+from hooks_constants import reply_length_gate_constants as constants
+
+
+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:
+    assert constants.ALL_CHECKED_TOOL_NAMES == frozenset(
+        {"mcp__hearthbot__reply", "mcp__hearthbot__post_message"}
+    )
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)

package/hooks/session/advisor_rules_prompt.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""SessionStart hook: inject open advisor consult guidance when the advisor is on.
+
+The built-in advisor tool brings its own guidance on when to call it. This hook
+adds the team-advisor starting points, such as a consult on a design question,
+and leaves each call to the session's judgment. It emits them only when the user settings carry an
+``advisorModel`` value and ``CLAUDE_CODE_DISABLE_ADVISOR_TOOL`` is not set, so a
+session without the advisor is never told to call it.
+The hook writes nothing and runs no tools itself.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.advisor_rules_prompt_constants import (
+    ADVISOR_DISABLE_ENV_VAR,
+    ADVISOR_MODEL_SETTINGS_KEY,
+    ADVISOR_RULES_PROMPT,
+    ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
+    USER_SETTINGS_FILE_NAME,
+)
+
+
+def user_settings_path() -> Path:
+    """Return the user settings file under the active Claude config directory."""
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
+    if configured_directory:
+        return Path(configured_directory) / USER_SETTINGS_FILE_NAME
+    return Path.home() / DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME / USER_SETTINGS_FILE_NAME
+
+
+def is_advisor_disabled_by_environment() -> bool:
+    """Return True when the environment turns the advisor tool off."""
+    raw_value = os.environ.get(ADVISOR_DISABLE_ENV_VAR, "").strip().lower()
+    return raw_value in ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES
+
+
+def is_advisor_configured(settings_path: Path) -> bool:
+    """Return True when the settings file names a non-empty advisor model."""
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(settings, dict):
+        return False
+    advisor_model = settings.get(ADVISOR_MODEL_SETTINGS_KEY)
+    return isinstance(advisor_model, str) and advisor_model.strip() != ""
+
+
+def main() -> None:
+    """Emit the advisor guidance as SessionStart additionalContext when the advisor is on."""
+    if is_advisor_disabled_by_environment():
+        return
+    if not is_advisor_configured(user_settings_path()):
+        return
+    session_start_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": ADVISOR_RULES_PROMPT,
+        }
+    }
+    sys.stdout.write(json.dumps(session_start_output) + "\n")
+
+
+if __name__ == "__main__":
+    main()