claude-dev-env 2.9.0 → 2.10.0

package/hooks/blocking/_path_setup.py

@@ -1,13 +1,17 @@
-"""Add the hooks directory to sys.path for sibling entry-point dispatchers.
+"""Add the hooks and blocking directories to sys.path for sibling imports.
 
 Importing this module inserts the hooks directory (this file's parent's parent)
-at the front of sys.path so a dispatcher that runs as a standalone script from
-blocking/ can import hooks_constants with every import kept at module top.
+and the blocking directory (its own parent) at the front of sys.path, so a
+module that runs as a standalone script from blocking/ can import both
+``hooks_constants`` and its blocking-directory siblings while every import stays
+at module top.
 """
 
 import sys
 from pathlib import Path
 
+_blocking_directory = str(Path(__file__).resolve().parent)
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
+for each_directory in (_blocking_directory, _hooks_directory):
+    if each_directory not in sys.path:
+        sys.path.insert(0, each_directory)

package/hooks/blocking/code_rules_docstrings.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
 from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
     _statement_is_docstring,
     _walk_skipping_nested_functions,
     _walk_skipping_type_checking_blocks,
@@ -2664,18 +2665,53 @@ def _runon_sentences(narrative_text: str) -> list[str]:
     return flagged_sentences
 
 
+def _docstring_owner_span(owner_node: ast.AST, anchor_lineno: int) -> range:
+    """Lines from the owner's anchor through the end of its docstring statement.
+
+    ::
+
+        def clean_helper() -> str:              <- anchor (def / class line)
+            '''run-on narrative across lines''' <- docstring end
+            return "ok"                         <- outside the span
+
+        An edit that only rewrites the docstring body intersects this span and
+        re-grades the finding. An edit to the return line does not.
+    """
+    body = getattr(owner_node, "body", None) or []
+    if not body:
+        return range(anchor_lineno, anchor_lineno + 1)
+    first_statement = body[0]
+    end_lineno = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+    return range(anchor_lineno, end_lineno + 1)
+
+
 def _documentable_docstring_targets(
     parsed_tree: ast.Module,
-) -> list[tuple[int, str, str]]:
-    documentable_targets: list[tuple[int, str, str]] = []
+) -> list[tuple[int, str, str, range]]:
+    documentable_targets: list[tuple[int, str, str, range]] = []
     module_docstring = ast.get_docstring(parsed_tree)
     if module_docstring and parsed_tree.body:
-        documentable_targets.append((parsed_tree.body[0].lineno, "module", module_docstring))
+        module_anchor = parsed_tree.body[0].lineno
+        documentable_targets.append(
+            (
+                module_anchor,
+                "module",
+                module_docstring,
+                _docstring_owner_span(parsed_tree, module_anchor),
+            )
+        )
     for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
         if isinstance(each_node, ast.ClassDef):
             class_docstring = ast.get_docstring(each_node)
             if class_docstring:
-                documentable_targets.append((each_node.lineno, each_node.name, class_docstring))
+                documentable_targets.append(
+                    (
+                        each_node.lineno,
+                        each_node.name,
+                        class_docstring,
+                        _docstring_owner_span(each_node, each_node.lineno),
+                    )
+                )
             continue
         if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
@@ -2686,34 +2722,58 @@ def _documentable_docstring_targets(
         function_docstring = _function_docstring_text(each_node)
         if function_docstring:
             documentable_targets.append(
-                (each_node.lineno, f"{each_node.name}()", function_docstring)
+                (
+                    each_node.lineno,
+                    f"{each_node.name}()",
+                    function_docstring,
+                    _docstring_owner_span(each_node, each_node.lineno),
+                )
             )
     return documentable_targets
 
 
-def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
+def check_docstring_runon_sentence(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
     """Flag a docstring narrative sentence that reads as a dense run-on wall.
 
     A readable docstring breaks its narrative into short sentences a general
     developer follows on the first read. The one mechanical mark of a wall is a
     single sentence that runs past the word limit while chaining clauses with an
     em-dash, a double-hyphen, or a semicolon. This check inspects the narrative prose of module,
-    class, and public-function docstrings — the text before the first structured
+    class, and public-function docstrings - the text before the first structured
     section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
-    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
+    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) - and
     reports a sentence that is both over the word limit and joined by one of those
     marks.
     Whether the prose paints a concrete, illustrative picture is judgment the
     plain-illustrative-docstrings audit lane carries; this gate catches only the
     run-on mark.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a run-on it just introduced while a pre-existing far-away
+    run-on on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per docstring whose narrative carries a run-on sentence, capped
-        at the module limit.
+        at the module limit and scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2721,25 +2781,37 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
         parsed_tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
-        parsed_tree
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) in _documentable_docstring_targets(parsed_tree):
         flagged_sentences = _runon_sentences(_docstring_narrative_text(each_docstring))
         if not flagged_sentences:
             continue
         run_on_word_count = _sentence_word_count(flagged_sentences[0])
-        issues.append(
+        message = (
             f"Line {each_line_number}: {each_label} docstring carries a {run_on_word_count}-word "
-            "run-on sentence — break the narrative into short, illustrative sentences a general "
+            "run-on sentence - break the narrative into short, illustrative sentences a general "
             "developer reads in one pass (plain-illustrative-docstrings)"
         )
-        if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
-            break
-    return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
 
 
-def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> list[str]:
+def check_docstring_prose_wall_without_illustration(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
     """Flag a summary that tells for many sentences and shows nothing.
 
     A reader trusts the opening to paint a scene. A run of short sentences with
@@ -2754,13 +2826,28 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
     Past the prose-line limit with no ``::`` listing and no ``>>>`` doctest, this
     fires. A narrative that shows a worked example, or one at the limit, passes.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a wall it just introduced while a pre-existing far-away wall
+    on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per summary that runs a wall of sentences with no worked
-        example, capped at the issue limit for the rule.
+        example, capped at the issue limit for the rule and scoped to the
+        changed lines unless *defer_scope_to_caller* is True or
+        *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2768,25 +2855,32 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
         parsed_tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
-        parsed_tree
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) in _documentable_docstring_targets(parsed_tree):
         prose_lines, has_illustration = _docstring_narrative_partition(each_docstring)
         if has_illustration:
             continue
         prose_line_count = len(prose_lines)
         if prose_line_count <= DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT:
             continue
-        issues.append(
+        message = (
             f"Line {each_line_number}: {each_label} summary runs {prose_line_count} "
             "narrative lines with no worked example - show, don't tell: swap the wall for a "
             "'::' listing (a sample input, an annotated outcome, ok/flag contrast rows) and "
             "keep the narrative to a few short lines (plain-illustrative-docstrings)"
         )
-        if len(issues) >= MAX_DOCSTRING_PROSE_WALL_ISSUES:
-            break
-    return issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
 
 
 def _raises_section_text(docstring_text: str) -> str:

package/hooks/blocking/code_rules_enforcer.py

@@ -18,6 +18,7 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 import json
 import sys
 from collections import Counter
+from collections.abc import Callable
 from pathlib import Path
 from typing import TextIO
 
@@ -285,7 +286,15 @@ def validate_content(
         all_issues.extend(check_logging_adjacent_string_literals(content, file_path))
         all_issues.extend(check_windows_api_none(content))
         all_issues.extend(check_naive_datetime_construction(content, file_path))
-        all_issues.extend(check_magic_values(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_magic_values,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_fstring_structural_literals(content, file_path))
         all_issues.extend(check_constants_outside_config(content, file_path))
         all_issues.extend(check_config_duplicate_path_anchor(content, file_path))
@@ -358,9 +367,21 @@ def validate_content(
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
-        all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
         all_issues.extend(
-            check_docstring_prose_wall_without_illustration(effective_content, file_path)
+            check_docstring_runon_sentence(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            check_docstring_prose_wall_without_illustration(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
         )
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
@@ -508,8 +529,24 @@ def validate_content(
         all_issues.extend(check_polarity_name_contradiction(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
-        all_issues.extend(check_join_separator_string_magic(content, file_path))
-        all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_join_separator_string_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            _fragment_or_deferred_check(
+                check_string_literal_magic,
+                old_content,
+                content,
+                file_path,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
@@ -723,6 +760,124 @@ def _without_line_prefix(violation_text: str) -> str:
     return violation_text
 
 
+def _issues_absent_from_prior_bodies(
+    all_candidate_issues: list[str],
+    all_prior_issues: list[str],
+) -> list[str]:
+    """Return candidates whose message bodies are not covered by prior issues.
+
+    Matching is line-number-agnostic with per-occurrence accounting: each prior
+    entry consumes exactly one candidate carrying the same body.
+
+    ::
+
+        prior:    ["Line 1: magic 'X'"]
+        candidates: ["Line 4: magic 'X'", "Line 9: magic 'Y'"]
+        -> ["Line 9: magic 'Y'"]
+
+    Args:
+        all_candidate_issues: Findings from the scan under review.
+        all_prior_issues: Findings that already account for a body.
+
+    Returns:
+        Candidates not consumed by a matching prior body.
+    """
+    remaining_prior_counts = Counter(
+        _without_line_prefix(each_issue) for each_issue in all_prior_issues
+    )
+    all_uncovered_issues: list[str] = []
+    for each_issue in all_candidate_issues:
+        message_body = _without_line_prefix(each_issue)
+        if remaining_prior_counts[message_body] > 0:
+            remaining_prior_counts[message_body] -= 1
+            continue
+        all_uncovered_issues.append(each_issue)
+    return all_uncovered_issues
+
+
+def _fragment_or_deferred_check(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+    defer_scope_to_caller: bool,
+) -> list[str]:
+    """Run a check with fragment baselining, or full-file when the gate owns scope.
+
+    The commit/push gate sets ``defer_scope_to_caller`` and passes HEAD as
+    ``old_content`` while scanning the current file (often the same blob on a
+    clean worktree). Fragment baselining would grandfather every finding there,
+    so the gate path runs the check on ``new_content`` alone and classifies by
+    added line afterward. PreToolUse Edit keeps baselining against the prior
+    fragment.
+
+    ::
+
+        defer=True, old==new with magic 9999
+            -> [Line 2: Magic value 9999 ...]  gate still sees it
+        defer=False, old and new both carry the same magic
+            -> []  grandfathered for wide Edit
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: Prior fragment or gate HEAD blob.
+        new_content: Proposed fragment or current full file.
+        file_path: Destination path used for path-based exemptions.
+        defer_scope_to_caller: True when the gate will scope by added line.
+
+    Returns:
+        Findings from the check, baselined against ``old_content`` only when
+        ``defer_scope_to_caller`` is False.
+    """
+    if defer_scope_to_caller:
+        return check_function(new_content, file_path)
+    return _issues_introduced_in_fragment(
+        check_function, old_content, new_content, file_path
+    )
+
+
+def _issues_introduced_in_fragment(
+    check_function: Callable[[str, str], list[str]],
+    old_content: str,
+    new_content: str,
+    file_path: str,
+) -> list[str]:
+    """Return fragment findings that are new relative to the pre-edit fragment.
+
+    Grades both the prior and proposed Edit fragments with the same check, then
+    subtracts findings whose message body already appears in the prior scan.
+    Per-occurrence accounting keeps a second identical new finding when only
+    one matching body existed before. Line numbers on kept findings come from
+    the proposed fragment so diagnostics point at the introduced location.
+
+    ::
+
+        old:  def f(): return os.environ['STRIPE_SECRET']
+        new:  def f(): return os.environ['STRIPE_SECRET']  # same body
+              -> []  grandfathered
+        old:  def f(): return 0
+        new:  def f(): return os.environ['STRIPE_SECRET']
+              -> [Line ...: string magic value 'STRIPE_SECRET' ...]
+
+    Args:
+        check_function: A ``(content, file_path) -> list[str]`` check.
+        old_content: The Edit's prior ``old_string`` fragment, or empty when
+            there is no prior region to baseline against.
+        new_content: The Edit's ``new_string`` fragment (or Write body).
+        file_path: Destination path used for path-based exemptions.
+
+    Returns:
+        Findings present in ``new_content`` that are absent from ``old_content``
+        under line-number-agnostic body matching. When ``old_content`` is empty,
+        every finding from ``new_content`` is returned.
+    """
+    all_new_issues = check_function(new_content, file_path)
+    if not old_content:
+        return all_new_issues
+    all_old_issues = check_function(old_content, file_path)
+    return _issues_absent_from_prior_bodies(all_new_issues, all_old_issues)
+
+
 def _forecast_full_file_violations(
     full_file_content_after_edit: str,
     file_path: str,
@@ -763,17 +918,7 @@ def _forecast_full_file_violations(
     all_full_file_issues = validate_content(
         full_file_content_after_edit, file_path, prior_full_file_content
     )
-    remaining_blocking_counts = Counter(
-        _without_line_prefix(each_issue) for each_issue in all_blocking_issues
-    )
-    forecast_issues: list[str] = []
-    for each_issue in all_full_file_issues:
-        message_body = _without_line_prefix(each_issue)
-        if remaining_blocking_counts[message_body] > 0:
-            remaining_blocking_counts[message_body] -= 1
-            continue
-        forecast_issues.append(each_issue)
-    return forecast_issues
+    return _issues_absent_from_prior_bodies(all_full_file_issues, all_blocking_issues)
 
 
 def _precheck_hint() -> str:

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()