claude-dev-env 8.39.0 → 8.40.0

package/hooks/blocking/reply_length_gate.py

@@ -9,6 +9,15 @@ It also denies a pull request number the reader cannot open::
     flag: Both land in PR 5256.
     flag: It merged in #4347.
     ok:   Both land in [PR 5256](https://github.com/owner/repo/pull/5256).
+
+It denies a banned word or phrase, matched whole and case-insensitive::
+
+    flag: The cause is likely the cache.
+    ok:   The cache log shows the miss at 12:04.
+
+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.
 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.
@@ -20,6 +29,8 @@ later pass, so this gate denies it and the model resends a shorter one.
 
 from __future__ import annotations
 
+import os
+import re
 import sys
 from pathlib import Path
 
@@ -27,12 +38,22 @@ 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 json_file_reader import read_json_object
 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,
+    ALL_DEFAULT_BANNED_WORDS,
     ALLOW_EXIT_CODE,
+    BANNED_WORD_MESSAGE,
+    BANNED_WORD_PART_SEPARATOR,
+    BANNED_WORD_PATTERN_TEMPLATE,
+    BANNED_WORDS_FILE_NAME,
+    BANNED_WORDS_JSON_KEY,
+    BANNED_WORDS_PATH_ENV_VAR,
     BLOCK_EXIT_CODE,
+    CLAUDE_HOME_DIRECTORY_NAME,
+    CONFIG_FILE_ENCODING,
     FENCED_BLOCK_PATTERN,
     HOOK_EVENT_NAME,
     INLINE_CODE_PATTERN,
@@ -106,6 +127,42 @@ def unlinked_pull_request_violation(reply_text: str) -> str | None:
     return UNLINKED_PULL_REQUEST_MESSAGE.format(reference=unlinked_match.group(0))
 
 
+def banned_words_config_path() -> Path:
+    """Return the banned-words file named by the environment, or the one in the Claude home."""
+    path_override = os.environ.get(BANNED_WORDS_PATH_ENV_VAR)
+    if path_override:
+        return Path(path_override)
+    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME / BANNED_WORDS_FILE_NAME
+
+
+def configured_banned_words() -> tuple[str, ...]:
+    """Return the configured banned words, or the defaults when no valid list is configured."""
+    config_document = read_json_object(banned_words_config_path(), CONFIG_FILE_ENCODING)
+    if config_document is None:
+        return ALL_DEFAULT_BANNED_WORDS
+    all_configured_words = config_document.get(BANNED_WORDS_JSON_KEY)
+    if not isinstance(all_configured_words, list):
+        return ALL_DEFAULT_BANNED_WORDS
+    return tuple(
+        each_word.strip()
+        for each_word in all_configured_words
+        if isinstance(each_word, str) and each_word.strip()
+    )
+
+
+def banned_word_violation(reply_text: str, all_banned_words: tuple[str, ...]) -> str | None:
+    """Return the deny reason for the first banned word in the prose, or None."""
+    prose_text = countable_text(reply_text)
+    for each_banned_word in all_banned_words:
+        word_pattern = BANNED_WORD_PART_SEPARATOR.join(
+            re.escape(each_part) for each_part in each_banned_word.split()
+        )
+        whole_word_pattern = BANNED_WORD_PATTERN_TEMPLATE.format(word_pattern=word_pattern)
+        if re.search(whole_word_pattern, prose_text, re.IGNORECASE):
+            return BANNED_WORD_MESSAGE.format(banned_word=each_banned_word)
+    return None
+
+
 def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None:
@@ -119,7 +176,11 @@ def main() -> int:
     reply_text = tool_input.get(TEXT_KEY)
     if not isinstance(reply_text, str):
         return ALLOW_EXIT_CODE
-    violation = length_violation(reply_text) or unlinked_pull_request_violation(reply_text)
+    violation = (
+        length_violation(reply_text)
+        or unlinked_pull_request_violation(reply_text)
+        or banned_word_violation(reply_text, configured_banned_words())
+    )
     if violation is None:
         return ALLOW_EXIT_CODE
     block_reason = violation + RETRY_INSTRUCTION

package/hooks/blocking/test_reply_length_gate.py

@@ -235,3 +235,90 @@ def test_should_allow_a_bare_pull_request_url(
         {"text": "Pull request: https://github.com/owner/repo/pull/5256"},
     )
     assert exit_code == 0
+
+
+def test_should_deny_a_reply_that_says_likely_and_name_the_word(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "The back-test flagged the garland star. It likely flags the call button."},
+    )
+    assert exit_code == 2
+    assert 'Banned word "likely"' in stderr_text
+
+
+def test_should_allow_the_same_reply_without_the_banned_word(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "The back-test flagged the garland star. It flags the call button in 7 themes."},
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    ["Really fast.", "A real-world case.", "In   reality it passed.", "ACTUALLY done."],
+)
+def test_should_deny_default_banned_words_in_any_case_and_spacing(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, POST_TOOL_NAME, {"text": reply_text})
+    assert exit_code == 2
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    [
+        "I realized the cache missed.",
+        "Run `actual_count` again.",
+        "See https://example.com/likely.",
+    ],
+)
+def test_should_allow_banned_words_inside_longer_words_code_and_urls(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text})
+    assert exit_code == 0
+
+
+def test_should_replace_the_defaults_with_the_configured_list(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    config_path = tmp_path / ".claude" / "reply-banned-words.json"
+    config_path.parent.mkdir()
+    config_path.write_text(json.dumps({"banned_words": ["synergy"]}), encoding="utf-8")
+    likely_exit_code, _ = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "It likely passed."}
+    )
+    synergy_exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "Synergy shipped."}
+    )
+    assert (likely_exit_code, synergy_exit_code) == (0, 2)
+    assert 'Banned word "synergy"' in stderr_text
+
+
+def test_should_read_the_list_from_the_path_the_environment_names(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    config_path = tmp_path / "words.json"
+    config_path.write_text(json.dumps({"banned_words": ["basically"]}), encoding="utf-8")
+    monkeypatch.setenv("CLAUDE_REPLY_BANNED_WORDS_PATH", str(config_path))
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "Basically done."})
+    assert exit_code == 2
+
+
+def test_should_keep_the_defaults_when_the_config_file_is_malformed(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    config_path = tmp_path / ".claude" / "reply-banned-words.json"
+    config_path.parent.mkdir()
+    config_path.write_text("{not json", encoding="utf-8")
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "It likely passed."})
+    assert exit_code == 2

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -28,6 +28,32 @@ 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}."
 UNLINKED_PULL_REQUEST_MESSAGE = 'Pull request "{reference}" has no link. Write it as [PR N](https://github.com/<owner>/<repo>/pull/N).'
+ALL_DEFAULT_BANNED_WORDS = (
+    "real",
+    "really",
+    "in reality",
+    "genuine",
+    "genuinely",
+    "actual",
+    "actually",
+    "likely",
+    "unlikely",
+    "probably",
+    "seems",
+    "seem",
+    "seemingly",
+    "suspect",
+    "guess",
+    "my theory",
+)
+BANNED_WORD_PART_SEPARATOR = r"\s+"
+BANNED_WORD_PATTERN_TEMPLATE = r"(?<![A-Za-z0-9]){word_pattern}(?![A-Za-z0-9])"
+BANNED_WORDS_JSON_KEY = "banned_words"
+BANNED_WORDS_FILE_NAME = "reply-banned-words.json"
+BANNED_WORDS_PATH_ENV_VAR = "CLAUDE_REPLY_BANNED_WORDS_PATH"
+CLAUDE_HOME_DIRECTORY_NAME = ".claude"
+CONFIG_FILE_ENCODING = "utf-8"
+BANNED_WORD_MESSAGE = 'Banned word "{banned_word}". Delete it and name the evidence: the log line, the check, the file and line.'
 LONG_SENTENCE_MESSAGE = (
     'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
 )

package/hooks/hooks_constants/test_reply_length_gate_constants.py

@@ -13,3 +13,9 @@ def test_gate_checks_the_two_chat_tools_that_post_to_the_user() -> None:
 
 def test_gate_exit_codes_match_the_hook_contract() -> None:
     assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)
+
+
+def test_default_banned_words_hold_the_hedges_and_intensifiers() -> None:
+    assert {"likely", "probably", "seems", "real", "actually", "genuine"} <= set(
+        constants.ALL_DEFAULT_BANNED_WORDS
+    )

package/package.json

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