claude-dev-env 8.38.3 → 8.40.0

package/_shared/pr-loop/scripts/check_convergence.py

@@ -29,10 +29,10 @@ The frozen process env is only a fallback when that disk read fails (logged once
 A probe error does not waive the gate; the live GitHub checks still run.
 
 The Codex gate is conditional-required: it demands
-``codex_clean_at == current_head`` only when the Codex account picker
-(``scripts/codex_account_choice.py choose``) answers the ``normal`` tier, so
+``codex_clean_at == current_head`` only when the account broker
+(``scripts/account_broker.py choose --product codex``) answers the ``normal`` tier, so
 one signed-in account has room for a review. A ``luna`` or ``wait`` answer, an
-unreadable picker, the codex token, or ``codex_down`` never blocks ready.
+unreadable broker, the codex token, or ``codex_down`` never blocks ready.
 """
 
 from __future__ import annotations
@@ -64,11 +64,12 @@ from check_convergence_thread_gates import (
     _count_unresolved_bot_threads,
 )
 from pr_converge_scripts_constants.convergence_gate_constants import (
-    ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS,
+    ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS,
+    ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES,
     BUGBOT_DOWN_BYPASS_NOTE,
     CLAUDE_JOB_DIR_ENV_VAR_NAME,
     CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS,
-    CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+    CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
     CODEX_BYPASS_DETAIL,
     CODEX_CLEAN_AT_STATE_KEY,
     CODEX_CLEAN_DETAIL_TEMPLATE,
@@ -344,16 +345,16 @@ def _evaluate_codex_clean(
 
     ::
 
-        clean stamp on head                  -> pass  (picker never runs)
+        clean stamp on head                  -> pass  (broker never runs)
         no stamp, tier luna, wait, or None   -> skip  (never blocks)
         no stamp, tier normal                -> fail
 
-    A stamp on the current HEAD settles the gate on its own, so the picker
-    stays behind it: the picker starts one Codex app server per account, and
+    A stamp on the current HEAD settles the gate on its own, so the broker
+    stays behind it: the broker starts one Codex app server per account, and
     the common already-clean tick has no reason to pay for them.
 
     Args:
-        read_codex_tier: Returns the picker's tier, or None when the picker cannot say.
+        read_codex_tier: Returns the broker's tier, or None when the broker cannot say.
         codex_clean_at: HEAD SHA where Codex last reported clean, or None.
         head_sha: Current PR HEAD commit SHA.
 
@@ -367,20 +368,22 @@ def _evaluate_codex_clean(
     return False, CODEX_MISSING_CLEAN_DETAIL_TEMPLATE % _short_sha(head_sha)
 
 
-def _codex_account_picker_path() -> Path:
-    """Return the installed Codex account picker beside this shared tree."""
+def _codex_account_broker_path() -> Path:
+    """Return the installed account broker beside this shared tree."""
     shared_root = Path(__file__).resolve().parents[SHARED_PACKAGE_ROOT_PARENT_INDEX]
-    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS)
+    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS)
 
 
 def _read_codex_tier() -> str | None:
-    """Ask the Codex account picker which tier a review runs on, or None when it cannot say."""
+    """Ask the account broker which tier a review runs on, or None when it cannot say."""
     try:
         completed = subprocess.run(
             [
                 sys.executable,
-                str(_codex_account_picker_path()),
-                CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+                str(_codex_account_broker_path()),
+                CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
+                "--product",
+                "codex",
             ],
             capture_output=True,
             text=True,
@@ -390,9 +393,12 @@ def _read_codex_tier() -> str | None:
         answer = json.loads(completed.stdout)
     except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
         return None
-    if completed.returncode != 0 or not isinstance(answer, dict):
+    if completed.returncode not in ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES or not isinstance(answer, dict):
         return None
-    tier = answer.get(CODEX_TIER_KEY)
+    decision = answer.get("decision")
+    if not isinstance(decision, dict):
+        return None
+    tier = decision.get(CODEX_TIER_KEY)
     return tier if isinstance(tier, str) else None
 
 

package/_shared/pr-loop/scripts/pr_converge_scripts_constants/convergence_gate_constants.py

@@ -69,11 +69,12 @@ CODEX_CLEAN_AT_STATE_KEY: str = "codex_clean_at"
 CODEX_DOWN_STATE_KEY: str = "codex_down"
 MINIMUM_ABBREVIATED_SHA_LENGTH: int = 7
 SHARED_PACKAGE_ROOT_PARENT_INDEX: int = 3
-ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS: tuple[str, ...] = (
+ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS: tuple[str, ...] = (
     "scripts",
-    "codex_account_choice.py",
+    "account_broker.py",
 )
-CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND: str = "choose"
+CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND: str = "choose"
 CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS: float = 150.0
 CODEX_TIER_KEY: str = "tier"
+ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES: tuple[int, ...] = (0, 3)
 CODEX_TIER_NORMAL: str = "normal"

package/_shared/pr-loop/scripts/test_check_convergence_codex.py

@@ -1,7 +1,7 @@
 """Fixture-driven tests for the conditional Codex convergence gate.
 
 Covers: required-and-clean, required-and-dirty, skipped-by-tier,
-skipped-by-token, skipped-by-down, and the read of the Codex account picker's
+skipped-by-token, skipped-by-down, and the read of the account broker's
 ``choose`` answer. The required tier comes from ``CODEX_TIER_NORMAL``.
 """
 
@@ -117,15 +117,15 @@ def should_pass_when_codex_required_and_clean(
     assert "All pre-conditions met" in captured
 
 
-def should_pass_without_running_the_picker_when_the_clean_stamp_is_on_head(
+def test_should_pass_without_running_the_broker_when_the_clean_stamp_is_on_head(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    def _picker_that_must_not_run() -> str | None:
+    def _broker_that_must_not_run() -> str | None:
         raise AssertionError(
-            "the Codex account picker must not run when codex_clean_at is on HEAD"
+            "the account broker must not run when codex_clean_at is on HEAD"
         )
 
-    monkeypatch.setattr(check_convergence, "_read_codex_tier", _picker_that_must_not_run)
+    monkeypatch.setattr(check_convergence, "_read_codex_tier", _broker_that_must_not_run)
 
     is_passed, detail = check_convergence._evaluate_codex_clean(
         read_codex_tier=check_convergence._read_codex_tier,
@@ -228,7 +228,7 @@ def should_fail_when_codex_required_and_dirty(
 
 
 @pytest.mark.parametrize("tier_without_room", ALL_TIERS_WITHOUT_ROOM_FOR_REVIEW)
-def should_skip_when_the_picker_names_no_account_with_room_for_review(
+def test_should_skip_when_the_broker_names_no_account_with_room_for_review(
     tier_without_room: str, tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     fixture_path = _write_fixture(
@@ -513,47 +513,86 @@ def should_accept_codex_clean_at_flag_in_parsed_arguments() -> None:
     assert arguments.codex_clean_at == HEAD_SHA
 
 
-def _install_fake_picker(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, picker_source: str
+def _install_fake_broker(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, broker_source: str
 ) -> None:
-    picker_path = tmp_path / "codex_account_choice.py"
-    picker_path.write_text(picker_source, encoding="utf-8")
-    monkeypatch.setattr(check_convergence, "_codex_account_picker_path", lambda: picker_path)
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(broker_source, encoding="utf-8")
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
 
 
-def should_read_the_tier_the_picker_chooses(
+def test_should_read_normal_tier_from_broker_decision(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'reason': 'room'}, 'accounts': []}))\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
+
+
+def test_should_read_wait_tier_from_broker_exit_three(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'wait', 'reason': 'no room'}, 'accounts': []}))\n"
+        "sys.exit(3)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == "wait"
+
+    passed, detail = check_convergence._evaluate_codex_clean(
+        read_codex_tier=check_convergence._read_codex_tier,
+        codex_clean_at=None,
+        head_sha=HEAD_SHA,
+    )
+    assert passed
+    assert "skipped" in detail
+
+
+def test_should_read_the_tier_the_broker_chooses(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fake_broker(
         tmp_path,
         monkeypatch,
         "import json, sys\n"
-        "assert sys.argv[1:] == ['choose']\n"
-        "print(json.dumps({'tier': 'normal', 'account': 'codex-2'}))\n",
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'account': 'codex-2'}, 'accounts': []}))\n",
     )
 
     assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
 
 
 @pytest.mark.parametrize(
-    "picker_source",
+    "broker_source",
     [
-        "import sys\nprint('{\"tier\": \"normal\"}')\nsys.exit(1)\n",
+        "import sys\nprint('{\"decision\": {\"tier\": \"normal\"}}')\nsys.exit(1)\n",
         "print('not json')\n",
         "print('[\"normal\"]')\n",
-        "print('{\"tier\": 1}')\n",
+        "print('{\"decision\": {\"tier\": 1}}')\n",
     ],
 )
-def should_read_no_tier_when_the_picker_fails_or_answers_out_of_shape(
-    picker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_should_read_no_tier_when_the_broker_fails_or_answers_out_of_shape(
+    broker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(tmp_path, monkeypatch, picker_source)
+    _install_fake_broker(tmp_path, monkeypatch, broker_source)
 
     assert check_convergence._read_codex_tier() is None
 
 
-def should_locate_the_packaged_codex_account_picker() -> None:
-    picker_path = check_convergence._codex_account_picker_path()
+def test_should_locate_the_packaged_codex_account_broker() -> None:
+    broker_path = check_convergence._codex_account_broker_path()
 
-    assert picker_path.name == "codex_account_choice.py"
-    assert picker_path.is_file()
+    assert broker_path.name == "account_broker.py"
+    assert broker_path.is_file()

package/docs/codex-accounts.md

@@ -1,15 +1,16 @@
 # Codex accounts
 
-The codex_account_choice picker spreads agent work across the Codex accounts
-on one machine. Each account signs in under its own Codex home, and every home
+The account broker assigns agent work across the Codex accounts.
+Each account signs in under its own Codex home, and every home
 shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
-A job asks the picker which account to use.
+A job asks the broker which account to use.
 
 ## Pieces
 
 | File | What it does |
 |---|---|
-| `scripts/codex_account_choice.py` | `choose` names the account and tier a job runs on, `check` tells a running job whether its account is still above a floor, `sync` links the shared setup into every account's home, `setup` and `install` write one launcher per account |
+| `scripts/account_broker.py` | `choose --product codex` names the account and tier a job runs on; `check --product codex` reports whether any account has room |
+| `scripts/codex_account_choice.py` | `sync` links the shared setup into every account's home; `setup` and `install` write one launcher per account |
 | `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
 | `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
 
@@ -21,8 +22,8 @@ The account roster names the accounts and their order. It comes from the
 in `account-launchers.json` under the profiles root. When neither exists, the
 accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`.
 
-`choose`, `sync` and `check` all work on that list, in that order. `check`
-accepts only a name on it. Each account's home is `~/.codex-profiles/<name>`, or
+The broker's `choose` and `check` commands and the setup commands use that list.
+Each account's home is `~/.codex-profiles/<name>`, or
 `<name>` under `CODEX_PROFILES_ROOT` when set. `~/.codex` holds the shared setup
 and is never an account. A name uses letters, digits, hyphens or underscores.
 `main`, `wait` and the Windows device names are refused.
@@ -83,50 +84,45 @@ folder under the profiles root stays, with its `auth.json`, so typing the name
 again restores it. A blank first line empties the roster and moves every launcher
 aside.
 
-`check <name>` reads a saved name the same way:
-
-```
-python packages/claude-dev-env/scripts/codex_account_choice.py check alpha --floor 1
-```
-
 ## Which account a job uses
 
 Room is the smaller of an account's two windows: the 5-hour window and the week.
 
 | Condition | Answer |
 |---|---|
-| First account in order with more than 10% left | `normal` on that account |
-| No account over 10%, one or more over 1% | `luna` on the account with the most room, `stop_below_percent` 1 |
+| One or more accounts with more than 10% left | `normal` on the account with the most room |
+| No account over 10%, one or more over 1% | `luna` on the account with the most room |
 | An account that reports a 5-hour window, with under 20% of that window left | never takes `luna` |
-| No account over 1% | `wait`, naming the account whose blocking windows reset first |
-| Account not signed in, or its meter unread | skipped, with the reason in `accounts` |
+| No account over 1% | `wait`, naming the next reset when known |
+| A meter is unread | The account has `meters: null` in `accounts` |
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py choose
-{"tier": "normal", "account": "codex-1", "codex_home": "...\\codex-1", "percent_left": 62.0,
- "stop_below_percent": null, "reason": "codex-1 has 62% left", "accounts": [...]}
+python packages/claude-dev-env/scripts/account_broker.py choose --product codex
+{"decision": {"action": "run", "account": "codex-1", "home": "...\\codex-1",
+ "resets_at": null, "reason": "codex-1 has 62% left", "tier": "normal"},
+ "accounts": [{"name": "codex-1", "home": "...\\codex-1", "is_main": false,
+ "meters": {"session_percent_left": 62.0, "session_resets_at": null,
+ "weekly_percent_left": 70.0, "weekly_resets_at": null}}]}
 ```
 
-A job runs Codex with `CODEX_HOME` set to `codex_home`. On `luna`, the job runs
+A job runs Codex with `CODEX_HOME` set to `decision.home`. On `luna`, the job runs
 Luna and polls `check` between steps:
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py check codex-2 --floor 1
+python packages/claude-dev-env/scripts/account_broker.py check --product codex
 ```
 
-`check` exits 0 while the account has more than the floor left, and 3 once it has
-not or its meter is unread. The job stops on 3.
+`check` exits 3 while every account is below its floor, and 0 when an account
+has room. The job stops on 3. `choose` also exits 3 for `wait` and still prints
+the JSON answer.
 
 ## Shared callers
 
-Two scripts under `_shared` run `choose` by path. Each finds the picker at
-`scripts/codex_account_choice.py` in the directory that holds `_shared`. Once
-installed, that is `~/.claude/scripts/codex_account_choice.py`.
+Two scripts under `_shared` run `choose --product codex` by path. Each finds the
+broker at `scripts/account_broker.py` in the directory that holds `_shared`.
+Once installed, that is `~/.claude/scripts/account_broker.py`.
 
 | Caller | What it does with the answer |
 |---|---|
-| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed picker skips the Codex gate |
-| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `codex_home` |
-
-Pass `--codex-path` when `codex` is off PATH. Without it the picker also tries
-the desktop install path under the user home.
+| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed broker skips the Codex gate |
+| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `decision.home` |

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.38.3",
+    "version": "8.40.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {