claude-dev-env 2.8.0 → 2.10.0

package/hooks/blocking/code_rules_shared.py

@@ -3,19 +3,12 @@
 import ast
 import difflib
 import os
-import sys
 import tempfile
 from collections.abc import Collection, Iterator
 from pathlib import Path
 
-_blocking_directory = str(Path(__file__).resolve().parent)
-_hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _blocking_directory not in sys.path:
-    sys.path.insert(0, _blocking_directory)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
-
-from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+from hooks_constants.code_rules_enforcer_constants import (
+    ALL_AGENT_HOME_TOOLING_PATTERNS,
     ALL_DIFF_CHANGED_OPCODE_TAGS,
     ALL_EPHEMERAL_EXEMPT_DISABLE_TRUTHY_VALUES,
     ALL_HOOK_INFRASTRUCTURE_PATTERNS,
@@ -30,14 +23,14 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
-from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+from hooks_constants.harness_scratchpad_constants import (
     CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME,
     HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
     HOOK_PAYLOAD_SESSION_ID_KEY,
 )
-from hooks_constants.unused_module_import_constants import (  # noqa: E402
+from hooks_constants.unused_module_import_constants import (
     TYPE_CHECKING_IDENTIFIER,
 )
 
@@ -56,6 +49,27 @@ def is_hook_infrastructure(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_HOOK_INFRASTRUCTURE_PATTERNS)
 
 
+def is_agent_home_tooling(file_path: str) -> bool:
+    """Check whether a path sits under a coding agent's home-directory tooling.
+
+    A coding agent installs helper scripts under a dot-directory in the home
+    tree, such as ``~/.grok/runs/``. That tree is vendored tooling rather than
+    project code, so the repository code rules do not govern it. The leading dot
+    is load-bearing: a project directory named ``grok/`` stays governed.
+
+    Args:
+        file_path: The candidate path to classify.
+
+    Returns:
+        True when the path sits under a recognized agent home directory.
+    """
+    path_lower = "/" + file_path.lower().replace("\\", "/").lstrip("/")
+    return any(
+        each_pattern.replace("\\", "/") in path_lower
+        for each_pattern in ALL_AGENT_HOME_TOOLING_PATTERNS
+    )
+
+
 def is_test_file(file_path: str) -> bool:
     """Check if file is a test file."""
     path_lower = file_path.lower()
@@ -405,17 +419,18 @@ def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
 
 
 def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
-    """Return True when file_path is a throwaway scratch path exempt from repo gates.
-
-    Combines the two throwaway-path families a repo gate skips: the root-anchored
-    ephemeral scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``) and the
-    harness session scratchpad. The session scratchpad match reads the session id
-    from the payload when one is supplied, and from the harness environment
-    variable otherwise, so a caller that holds no payload still gets the match.
-    The run_all_validators PreToolUse gate calls this predicate to skip a scratch
-    target before it validates. The code-rules and TDD gates call the two path
-    predicates ``is_ephemeral_script_path`` and ``is_under_session_scratchpad``
-    directly.
+    """Return True when file_path is exempt from the repository gates.
+
+    Combines the path families a repo gate skips: the root-anchored ephemeral
+    scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``), the harness
+    session scratchpad, and a coding agent's own home-directory tooling such as
+    ``~/.grok/runs/``. The session scratchpad match reads the session id from the
+    payload when one is supplied, and from the harness environment variable
+    otherwise, so a caller that holds no payload still gets the match. The
+    run_all_validators PreToolUse gate calls this predicate to skip an exempt
+    target before it validates. The code-rules and TDD gates call the underlying
+    predicates ``is_ephemeral_script_path``, ``is_agent_home_tooling``, and
+    ``is_under_session_scratchpad`` directly.
 
     Args:
         file_path: The candidate path to classify.
@@ -423,10 +438,12 @@ def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
             read the session id from the environment alone.
 
     Returns:
-        True when the path is ephemeral scratch or under the session scratchpad.
+        True when the path is scratch, agent tooling, or the session scratchpad.
     """
     if is_ephemeral_script_path(file_path):
         return True
+    if is_agent_home_tooling(file_path):
+        return True
     return is_under_session_scratchpad(file_path, hook_payload or {})
 
 

package/hooks/blocking/config/CLAUDE.md

@@ -1,16 +1,14 @@
 # hooks/blocking/config
 
-A Python package that holds shared constants for the verified-commit gate family. Three modules in `blocking/` import from here:
-
-- `verification_verdict_store.py`
-- `verified_commit_gate.py`
-- `verifier_verdict_minter.py`
+A Python package that holds shared constants for blocking hooks. Verified-commit gate modules and opinionated prose-style gates import from here.
 
 ## Key files
 
 | File | Contents |
 |---|---|
 | `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
+| `code_review_enforcement_constants.py` | Stamp and effort tunables for the code-review enforcement gates |
+| `prose_style_enforcement_constants.py` | `CLAUDE_PROSE_STYLE_ENFORCEMENT` opt-in (default off) for opinionated prose gates |
 | `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
 | `verified_commit_context_constants.py` | `VERIFY_SKIP_ADDITIONAL_CONTEXT`, the ``# verify-skip`` usage rule the gate attaches to a deny payload's `additionalContext` |
 | `verified_commit_gate_output_constants.py` | `PRE_TOOL_USE_HOOK_EVENT_NAME` and `DENY_PERMISSION_DECISION` (the deny payload's event name and decision string), `GATE_HOOK_MODULE_NAME` (the gate's own module name for block logging), and `REGEX_ALTERNATION_SEPARATOR` (the `\|` join for the directory-change verb alternation in `gated_invocations.py`) |

package/hooks/blocking/config/prose_style_enforcement_constants.py

@@ -0,0 +1,38 @@
+"""Single source of truth for opinionated prose-style gate opt-in.
+
+::
+
+    CLAUDE_PROSE_STYLE_ENFORCEMENT=1  ->  PROSE_STYLE_ENFORCEMENT_ENABLED True
+    (unset)                           ->  PROSE_STYLE_ENFORCEMENT_ENABLED False
+
+Structural AskUserQuestion lean-block validation stays always on. The flag
+arms only opinionated prose gates (heavy-word swaps, hedging, historical
+state phrasing, intent-only endings, hook prose-detector consistency).
+"""
+
+from __future__ import annotations
+
+import os
+
+PROSE_STYLE_ENFORCEMENT_ENV_VAR = "CLAUDE_PROSE_STYLE_ENFORCEMENT"
+ALL_ENFORCEMENT_ENABLED_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
+
+
+def prose_style_enforcement_enabled_in_environment() -> bool:
+    """Read whether this machine turns opinionated prose gates on.
+
+    ::
+
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=1      -> True
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=" On " -> True
+        CLAUDE_PROSE_STYLE_ENFORCEMENT=0      -> False
+        (variable unset)                      -> False
+
+    Returns:
+        True when the variable holds an enabled value, False otherwise.
+    """
+    raw_environment_setting = os.environ.get(PROSE_STYLE_ENFORCEMENT_ENV_VAR, "")
+    return raw_environment_setting.strip().lower() in ALL_ENFORCEMENT_ENABLED_ENV_VALUES
+
+
+PROSE_STYLE_ENFORCEMENT_ENABLED = prose_style_enforcement_enabled_in_environment()

package/hooks/blocking/config/test_prose_style_enforcement_constants.py

@@ -0,0 +1,45 @@
+"""Tests for the prose-style enforcement opt-in flag (default off)."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_CONSTANTS_PATH = Path(__file__).resolve().parent / "prose_style_enforcement_constants.py"
+
+
+def _load_constants_module(monkeypatch: pytest.MonkeyPatch, env_value: str | None):
+    module_name = "prose_style_enforcement_constants_under_test"
+    if env_value is None:
+        monkeypatch.delenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", raising=False)
+    else:
+        monkeypatch.setenv("CLAUDE_PROSE_STYLE_ENFORCEMENT", env_value)
+    module_spec = importlib.util.spec_from_file_location(module_name, _CONSTANTS_PATH)
+    assert module_spec is not None and module_spec.loader is not None
+    module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(module)
+    return module
+
+
+def test_absent_env_is_default_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    module = _load_constants_module(monkeypatch, None)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False
+    assert module.prose_style_enforcement_enabled_in_environment() is False
+
+
+@pytest.mark.parametrize("enabled_value", ["1", "true", "yes", "on", " True "])
+def test_truthy_env_enables(
+    monkeypatch: pytest.MonkeyPatch, enabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, enabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is True
+
+
+@pytest.mark.parametrize("disabled_value", ["0", "false", "no", "off", ""])
+def test_falsy_env_stays_off(
+    monkeypatch: pytest.MonkeyPatch, disabled_value: str
+) -> None:
+    module = _load_constants_module(monkeypatch, disabled_value)
+    assert module.PROSE_STYLE_ENFORCEMENT_ENABLED is False

package/hooks/blocking/eli11_reply_enforcer.py

@@ -1,15 +1,13 @@
 #!/usr/bin/env python3
 """
-Stop hook that blocks a final reply breaking the short action-first reply shape.
-
-The `eli11-replies` rule asks every chat reply to lead with the action, keep
-findings to a few bullets, and stay short. This hook reads the final assistant
-message, strips code fences, inline code, blockquotes, table rows, and link
-targets, then judges what a reader actually sees: the word count against a hard
-cap, whether numbered steps lead a reply that tells the user to act, the number
-of bullet lines, and how many lines pack more than one idea's worth of words.
-A reply opening with "Long form:" opts out, so a user-requested full report
-still goes through.
+Stop hook that blocks egregious reply-shape failures (action-first, bullets).
+
+The `eli11-replies` and `opus5-communication-contract` rules ask every chat
+reply to lead with the action when the user must act, keep findings to a few
+bullets, and stay scannable. This hook reads the final assistant message,
+strips code fences, inline code, blockquotes, table rows, and link targets,
+then judges shape only: multi-line instructions need numbered steps first,
+bullet count stays bounded, and list lines stay one-idea short.
 """
 
 import json
@@ -30,13 +28,10 @@ from hooks_constants.eli11_reply_enforcer_constants import (  # noqa: E402
     IMPERATIVE_OBJECT_TOKEN_PATTERN,
     LINK_TARGET_PATTERN,
     LIST_MARKER_PREFIX_PATTERN,
-    LONG_FORM_ESCAPE_PREFIX,
     MARKDOWN_LEAD_MARKER_PATTERN,
     MAXIMUM_BULLET_LINE_COUNT,
-    MAXIMUM_OVERPACKED_LINE_COUNT,
-    MAXIMUM_REPLY_WORD_COUNT,
-    MAXIMUM_WORDS_PER_LINE,
-    MINIMUM_ENFORCED_WORD_COUNT,
+    MAXIMUM_OVERPACKED_LIST_LINE_COUNT,
+    MAXIMUM_WORDS_PER_LIST_LINE,
     NUMBERED_STEP_PATTERN,
     TABLE_ROW_PATTERN,
     TARGET_BULLET_LINE_COUNT,
@@ -69,18 +64,6 @@ def extract_reply_prose(assistant_message: str) -> str:
     return LINK_TARGET_PATTERN.sub("", prose_text)
 
 
-def count_reply_words(prose_text: str) -> int:
-    """Return the number of reader-visible words in the stripped prose.
-
-    Args:
-        prose_text: Prose already cleaned of code, quotes, tables, and links.
-
-    Returns:
-        The count of whitespace-separated tokens carrying a letter or digit.
-    """
-    return len(COUNTABLE_WORD_PATTERN.findall(prose_text))
-
-
 def collect_non_empty_lines(prose_text: str) -> list[str]:
     """Return every line of the stripped prose that carries visible text.
 
@@ -249,29 +232,13 @@ def count_words_in_line(prose_line: str) -> int:
     return len(COUNTABLE_WORD_PATTERN.findall(unmarked_line))
 
 
-def count_overpacked_lines(all_prose_lines: list[str]) -> int:
-    """Return how many lines carry more words than one idea needs.
-
-    Args:
-        all_prose_lines: The non-empty lines of reply prose.
-
-    Returns:
-        The count of lines over the per-line word cap.
-    """
-    return sum(
-        1
-        for each_line in all_prose_lines
-        if count_words_in_line(each_line) > MAXIMUM_WORDS_PER_LINE
-    )
-
-
 def strip_markdown_lead_markers(prose_line: str) -> str:
     """Return a line with its opening blockquote, heading, and bold markers off.
 
     ::
 
-        in:  "> **Long form:** the report follows"
-        out: "Long form:** the report follows"
+        in:  "> **Bold lead:** the report follows"
+        out: "Bold lead:** the report follows"
 
     Args:
         prose_line: One line of raw reply text.
@@ -282,34 +249,37 @@ def strip_markdown_lead_markers(prose_line: str) -> str:
     return MARKDOWN_LEAD_MARKER_PATTERN.sub("", prose_line.strip(), count=1)
 
 
-def opens_with_long_form_escape(assistant_message: str) -> bool:
-    """Return True when the reply opts out through the Long form prefix.
+def is_list_item_line(prose_line: str) -> bool:
+    """Return True when a line is a bullet or numbered list item.
+
+    Args:
+        prose_line: One non-empty line of reply prose.
+
+    Returns:
+        True when the line opens with a bullet or numbered-step marker.
+    """
+    if BULLET_LINE_PATTERN.match(prose_line):
+        return True
+    return NUMBERED_STEP_PATTERN.match(prose_line) is not None
 
-    ::
 
-        ok:   "**Long form:** the report follows" -> True
-        flag: "The report follows"                -> False
+def count_overpacked_list_lines(all_prose_lines: list[str]) -> int:
+    """Return how many list lines carry more words than one idea needs.
 
-    A bold, blockquote, or heading wrapper around the prefix still opts out.
+    Plain paragraphs are not counted so a requested full report can use long
+    prose lines without a word ceiling.
 
     Args:
-        assistant_message: The raw final assistant message.
+        all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
-        True when the first line with content starts with the escape prefix.
+        The count of bullet/numbered lines over the per-list-line word cap.
     """
-    for each_line in assistant_message.splitlines():
-        if not each_line.strip():
-            continue
-        unwrapped_line = strip_markdown_lead_markers(each_line)
-        return unwrapped_line.lower().startswith(LONG_FORM_ESCAPE_PREFIX)
-    return False
-
-
-def describe_word_cap_violation(reply_word_count: int) -> str:
-    """Return the violation text naming the reply length and the cap."""
-    return (
-        f"{reply_word_count} words, over the {MAXIMUM_REPLY_WORD_COUNT}-word cap"
+    return sum(
+        1
+        for each_line in all_prose_lines
+        if is_list_item_line(each_line)
+        and count_words_in_line(each_line) > MAXIMUM_WORDS_PER_LIST_LINE
     )
 
 
@@ -317,70 +287,68 @@ def describe_bullet_cap_violation(bullet_line_count: int) -> str:
     """Return the violation text naming the bullet count and the target."""
     return (
         f"{bullet_line_count} bullets, over the {MAXIMUM_BULLET_LINE_COUNT}-bullet "
-        f"cap - cut findings to {TARGET_BULLET_LINE_COUNT} bullets"
+        f"cap - put findings in at most {TARGET_BULLET_LINE_COUNT} bullets"
     )
 
 
-def describe_overpacked_line_violation(overpacked_line_count: int) -> str:
-    """Return the violation text naming how many lines pack too much in."""
+def describe_overpacked_list_line_violation(overpacked_line_count: int) -> str:
+    """Return the violation text for overpacked list lines."""
     return (
-        f"{overpacked_line_count} lines carry too many words - one idea per line, "
-        f"at most {MAXIMUM_WORDS_PER_LINE} words each"
+        f"{overpacked_line_count} list lines carry too many words - one idea per "
+        f"bullet or step, at most {MAXIMUM_WORDS_PER_LIST_LINE} words each"
     )
 
 
 def describe_action_first_violation() -> str:
     """Return the violation text for instructions buried under prose."""
     return (
-        "the reply tells the user to act but leads with prose - put the steps "
-        "first, as a numbered list"
+        "the reply tells the user to act but leads with prose - open with "
+        "numbered steps, one short line each"
     )
 
 
-def is_action_first_violation(
-    reply_word_count: int, all_prose_lines: list[str]
-) -> bool:
-    """Return True when instructions sit below the lead of a long reply.
+def is_action_first_violation(all_prose_lines: list[str]) -> bool:
+    """Return True when multi-line instructions lack leading numbered steps.
+
+    ::
+
+        ok:   single-line "Run the migration." -> False
+        ok:   numbered steps first, then prose -> False
+        flag: prose then "Install the package." -> True
 
     Args:
-        reply_word_count: The reader-visible word count of the reply.
         all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
-        True when the reply is long, carries instruction lines, and shows no
-        numbered step among its lead lines.
+        True when the reply has more than one line, carries instruction
+        lines, and shows no numbered step among its lead lines.
     """
-    if reply_word_count < MINIMUM_ENFORCED_WORD_COUNT:
+    if len(all_prose_lines) <= 1:
         return False
     if not has_imperative_instruction_line(all_prose_lines):
         return False
     return not has_leading_numbered_step(all_prose_lines)
 
 
-def collect_shape_violations(
-    reply_word_count: int, all_prose_lines: list[str]
-) -> list[str]:
+def collect_shape_violations(all_prose_lines: list[str]) -> list[str]:
     """Return the violation texts for every reply-shape rule the reply breaks.
 
     Args:
-        reply_word_count: The reader-visible word count of the reply.
         all_prose_lines: The non-empty lines of reply prose.
 
     Returns:
         One violation text per broken rule, empty when the reply is in shape.
     """
     all_violations: list[str] = []
-    if reply_word_count > MAXIMUM_REPLY_WORD_COUNT:
-        all_violations.append(describe_word_cap_violation(reply_word_count))
-    if is_action_first_violation(reply_word_count, all_prose_lines):
+    if is_action_first_violation(all_prose_lines):
         all_violations.append(describe_action_first_violation())
     bullet_line_count = count_bullet_lines(all_prose_lines)
     if bullet_line_count > MAXIMUM_BULLET_LINE_COUNT:
         all_violations.append(describe_bullet_cap_violation(bullet_line_count))
-    overpacked_line_count = count_overpacked_lines(all_prose_lines)
-    if overpacked_line_count > MAXIMUM_OVERPACKED_LINE_COUNT:
+    overpacked_list_line_count = count_overpacked_list_lines(all_prose_lines)
+    if overpacked_list_line_count > MAXIMUM_OVERPACKED_LIST_LINE_COUNT:
         all_violations.append(
-            describe_overpacked_line_violation(overpacked_line_count)
+            describe_overpacked_list_line_violation(overpacked_list_line_count)
         )
     return all_violations
 
@@ -390,11 +358,9 @@ def find_reply_shape_violations(assistant_message: str) -> list[str]:
 
     ::
 
-        ok:   a 40-word outcome sentence -> []
-        flag: a 260-word wall            -> ["260 words, over the 120-word cap"]
-
-    A reply opening with the escape prefix, and a reply under the enforced word
-    floor, are both returned as in shape.
+        ok:   a short outcome sentence              -> []
+        ok:   a long requested audit with few bullets -> []
+        flag: prose then buried "Install the package." -> [action-first]
 
     Args:
         assistant_message: The raw final assistant message.
@@ -402,19 +368,12 @@ def find_reply_shape_violations(assistant_message: str) -> list[str]:
     Returns:
         One violation text per broken rule, empty when the reply is in shape.
     """
-    if opens_with_long_form_escape(assistant_message):
-        return []
     prose_text = extract_reply_prose(assistant_message)
-    reply_word_count = count_reply_words(prose_text)
-    if reply_word_count < MINIMUM_ENFORCED_WORD_COUNT:
-        return []
-    return collect_shape_violations(
-        reply_word_count, collect_non_empty_lines(prose_text)
-    )
+    return collect_shape_violations(collect_non_empty_lines(prose_text))
 
 
 def build_block_reason(all_violations: list[str]) -> str:
-    """Return the corrective message naming each violation and the escape hatch.
+    """Return the corrective message naming each violation and the rewrite path.
 
     Args:
         all_violations: The violation texts the reply earned.
@@ -424,16 +383,14 @@ def build_block_reason(all_violations: list[str]) -> str:
     """
     formatted_violation_list = VIOLATION_SEPARATOR.join(all_violations)
     return (
-        f"ELI11 REPLY SHAPE: Your reply breaks the short action-first shape "
+        f"ELI11 REPLY SHAPE: Rewrite the reply into a short action-first shape "
         f"({formatted_violation_list}).\n\n"
-        f"Rewrite it short. When the user must act, open with numbered "
-        f"click-by-click steps, one short line each. When nothing is needed, open "
-        f"with the outcome in one sentence. Keep findings to at most "
-        f"{TARGET_BULLET_LINE_COUNT} short bullets and stay under "
-        f"{MAXIMUM_REPLY_WORD_COUNT} words. Code fences, blockquotes, tables, and "
-        f"links are already exempt from the count.\n\n"
-        f"When the user asked for a full report, start the reply with "
-        f'"Long form:" to opt out of this check.\n\n'
+        f"When the user must act, open with numbered click-by-click steps, one "
+        f"short line each. When nothing is needed, open with the outcome in one "
+        f"sentence. Keep findings to at most {TARGET_BULLET_LINE_COUNT} short "
+        f"bullets. A requested full report may run long; keep list lines short "
+        f"and lead with the outcome. Code fences, blockquotes, tables, and "
+        f"links are already exempt from shape counting.\n\n"
         f"You MUST re-output the complete, revised response with the correction "
         f"applied."
     )