claude-dev-env 2.9.0 → 2.10.0

package/hooks/blocking/plain_language_blocker.py

@@ -31,6 +31,9 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     ALL_CHAT_DETAIL_MARKERS,
@@ -44,6 +47,7 @@ from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     DOT_CLAUDE_DIRECTORY_NAME,
     FENCED_CODE_BLOCK_PATTERN,
     FILE_PATH_PATTERN,
+    HEAVY_WORD_SWAP_LIST_SEPARATOR,
     INLINE_CODE_PATTERN,
     INLINE_CODE_PLACEHOLDER,
     INLINE_CODE_SPAN_PATTERN,
@@ -65,6 +69,12 @@ from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     USER_FACING_LEAN_QUESTION_NOTICE,
     USER_FACING_PLAIN_LANGUAGE_NOTICE,
 )
+from hooks_constants.prose_matcher_precision_constants import (  # noqa: E402
+    ADVISORY_CONTEXT_SNIPPET_MAX_CHARS,
+    MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+    MAXIMUM_ADVISORY_EMITS_PER_CALL,
+)
+from observability.prose_matcher_advisory import emit_advisory_candidate  # noqa: E402
 
 
 def strip_non_prose_regions(text: str) -> str:
@@ -234,7 +244,12 @@ def _load_project_allowlist(
 
 
 def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
-    """Return a deny reason naming each flagged term and its plain replacement."""
+    """Return a legacy block-reason string naming each term and plain swap.
+
+    Heavy-word enforcement no longer hard-denies (OP-07D). Callers that still
+    need the named swap list for notices or tests use this helper. Lean-block
+    denials use ``build_lean_block_reason`` instead.
+    """
     swap_phrases = ", ".join(
         f'use "{each_replacement}" instead of "{each_term}"'
         for each_term, each_replacement in all_matches
@@ -246,6 +261,31 @@ def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
     )
 
 
+def build_advisory_system_message(all_matches: list[tuple[str, str]]) -> str:
+    """Return allow-path advisory text naming everyday swaps for heavy words.
+
+    ::
+
+        build_advisory_system_message([("initiate", "start")])
+            -> names use "start" instead of "initiate" (no permission deny)
+
+    Args:
+        all_matches: ``(heavy_term, everyday_swap)`` pairs from the word scan.
+
+    Returns:
+        A systemMessage string for PreToolUse allow with advisory guidance.
+    """
+    swap_phrases = HEAVY_WORD_SWAP_LIST_SEPARATOR.join(
+        f'use "{each_replacement}" instead of "{each_term}"'
+        for each_term, each_replacement in all_matches
+    )
+    return (
+        f"[PLAIN_LANGUAGE advisory] {swap_phrases}. "
+        "Reach for the everyday word the reader understands on the first pass. "
+        "This notice does not deny the write; lean-block structure denials still apply."
+    )
+
+
 def _normalize_line_endings(prose_text: str) -> str:
     """Return the prose with every line ending spelled as a bare line feed.
 
@@ -572,50 +612,125 @@ def _emit_deny(deny_reason: str, output_stream: TextIO) -> None:
     output_stream.flush()
 
 
+def build_allow_advisory_payload(system_message: str) -> dict[str, object]:
+    """Build an allow payload that still surfaces everyday-word guidance.
+
+    Args:
+        system_message: Advisory text naming heavy terms and plain swaps.
+
+    Returns:
+        A PreToolUse payload without permissionDecision deny.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        },
+        "systemMessage": system_message,
+        "suppressOutput": False,
+    }
+
+
+def _emit_allow_advisory(system_message: str, output_stream: TextIO) -> None:
+    output_stream.write(json.dumps(build_allow_advisory_payload(system_message)))
+    output_stream.flush()
+
+
+def _emit_plain_language_advisory_candidates(
+    surface: str,
+    all_matches: list[tuple[str, str]],
+    prose_text: str,
+) -> None:
+    """Record privacy-safe advisory hits when enforcement is off (fail open)."""
+    try:
+        for each_match in all_matches[:MAXIMUM_ADVISORY_EMITS_PER_CALL]:
+            each_term = each_match[0]
+            emit_advisory_candidate(
+                MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+                surface,
+                f"{each_term}:{prose_text[:ADVISORY_CONTEXT_SNIPPET_MAX_CHARS]}",
+            )
+    except (ImportError, OSError, TypeError, ValueError):
+        return
+
+
 def evaluate(payload_by_key: dict[str, object]) -> str | None:
-    """Decide whether a payload carries a question block or heavy words to block.
+    """Return a lean-block deny reason, or None when the payload is allowed.
 
-    An AskUserQuestion payload meets the lean-block check first, so a question
-    text or an option description carrying chat detail returns a LEAN_QUESTION
-    deny reason. Every guarded payload then meets the word scan, which returns a
-    PLAIN_LANGUAGE deny reason for the first heavy word it finds.
+    Heavy-word matches never produce a deny reason (OP-07D). When prose-style
+    enforcement is on, main still emits an allow advisory naming everyday swaps
+    for AskUserQuestion and ``.md`` writes. When enforcement is off, matches
+    only record privacy-safe advisory candidates (OP-07B).
 
     Args:
         payload_by_key: The PreToolUse payload with tool_name and tool_input.
 
     Returns:
-        The permissionDecisionReason text when the payload is denied, or None
-        when it is allowed.
+        The permissionDecisionReason text for a lean-block denial, or None when
+        the payload is allowed (with or without a heavy-word advisory).
+    """
+    deny_reason, _advisory_system_message = evaluate_with_advisory(payload_by_key)
+    return deny_reason
+
+
+def evaluate_with_advisory(
+    payload_by_key: dict[str, object],
+    all_allowlisted_terms: frozenset[str] | None = None,
+) -> tuple[str | None, str | None]:
+    """Return ``(deny_reason, advisory_system_message)`` for one PreToolUse payload.
+
+    ::
+
+        lean chat detail in AskUserQuestion  ->  (lean deny reason, None)
+        heavy word, enforcement ON           ->  (None, advisory systemMessage)
+        heavy word, enforcement OFF          ->  (None, None) + privacy JSONL
+        clean payload                        ->  (None, None)
+
+    Args:
+        payload_by_key: The PreToolUse payload with tool_name and tool_input.
+        all_allowlisted_terms: Optional project-vocabulary exemptions. When
+            omitted, the project allowlist file is loaded for the payload path.
+
+    Returns:
+        A pair of optional deny reason and optional allow-path advisory message.
     """
     raw_tool_name = payload_by_key.get("tool_name", "")
     raw_tool_input = payload_by_key.get("tool_input", {})
     if not isinstance(raw_tool_name, str) or not isinstance(raw_tool_input, dict):
-        return None
+        return None, None
 
     if raw_tool_name in ALL_WRITE_EDIT_TOOL_NAMES:
         target_file_path = raw_tool_input.get("file_path", "")
         if isinstance(target_file_path, str) and is_ephemeral_path(
             target_file_path, payload_by_key
         ):
-            return None
+            return None, None
 
     if raw_tool_name == ASK_USER_QUESTION_TOOL_NAME:
         all_block_violations = find_question_block_violations(raw_tool_input)
         if all_block_violations:
-            return build_lean_block_reason(all_block_violations)
+            return build_lean_block_reason(all_block_violations), None
 
     prose_text = _collect_prose_for_tool(raw_tool_name, raw_tool_input)
     if not prose_text:
-        return None
+        return None, None
 
-    all_allowlisted_terms = _load_project_allowlist(
-        raw_tool_name, raw_tool_input, payload_by_key
+    resolved_allowlisted_terms = (
+        all_allowlisted_terms
+        if all_allowlisted_terms is not None
+        else _load_project_allowlist(raw_tool_name, raw_tool_input, payload_by_key)
+    )
+    all_matches = find_banned_terms(
+        prose_text, all_allowlisted_terms=resolved_allowlisted_terms
     )
-    all_matches = find_banned_terms(prose_text, all_allowlisted_terms)
     if not all_matches:
-        return None
+        return None, None
 
-    return build_block_reason(all_matches)
+    if not prose_style_enforcement_enabled_in_environment():
+        _emit_plain_language_advisory_candidates(raw_tool_name, all_matches, prose_text)
+        return None, None
+
+    return None, build_advisory_system_message(all_matches)
 
 
 def main() -> None:
@@ -627,11 +742,15 @@ def main() -> None:
     if not isinstance(input_data, dict):
         sys.exit(0)
 
-    deny_reason = evaluate(input_data)
-    if deny_reason is None:
+    deny_reason, advisory_system_message = evaluate_with_advisory(input_data)
+    if deny_reason is not None:
+        _emit_deny(deny_reason, sys.stdout)
+        sys.exit(0)
+
+    if advisory_system_message is not None:
+        _emit_allow_advisory(advisory_system_message, sys.stdout)
         sys.exit(0)
 
-    _emit_deny(deny_reason, sys.stdout)
     sys.exit(0)
 
 

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -26,10 +26,16 @@ from pathlib import Path
 
 import _path_setup  # noqa: F401
 
+from plain_language_blocker import (
+    build_allow_advisory_payload as build_plain_language_allow_advisory_payload,
+)
 from plain_language_blocker import (
     build_deny_payload as build_plain_language_deny_payload,
 )
 from plain_language_blocker import evaluate as evaluate_plain_language
+from plain_language_blocker import (
+    evaluate_with_advisory as evaluate_plain_language_with_advisory,
+)
 from state_description_blocker import (
     build_deny_payload as build_state_description_deny_payload,
 )
@@ -40,32 +46,46 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (
     ALLOW_DECISION,
     BLOCKING_CRASH_DENY_REASON,
     BLOCKING_CRASH_EXIT_CODE,
+    CONTEXT_JOIN_SEPARATOR,
     DENY_DECISION,
     EXIT_CODE_TWO_DENY_REASON,
     HOOK_EVENT_NAME,
     PLAIN_LANGUAGE_BLOCKER_MODULE_NAME,
+    REASON_JOIN_SEPARATOR,
     STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
+    SYSTEM_MESSAGE_JOIN_SEPARATOR,
     HostedHookEntry,
 )
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 
 NativeEvaluator = Callable[[dict[str, object]], str | None]
 DenyPayloadBuilder = Callable[[str], dict[str, object]]
+AdvisoryEvaluator = Callable[
+    [dict[str, object]], tuple[str | None, str | None]
+]
+AllowAdvisoryPayloadBuilder = Callable[[str], dict[str, object]]
 
 
 @dataclass(frozen=True)
 class NativeHook:
-    """A nativized hook's evaluator paired with its full deny-payload builder.
+    """A nativized hook's evaluator paired with its full payload builders.
 
     Attributes:
         evaluate: The hook's evaluate function returning a deny-reason or None.
         build_deny_payload: The hook's builder that turns a deny-reason into the
             full deny payload the standalone hook writes (carrying systemMessage,
             additionalContext, and suppressOutput).
+        evaluate_with_advisory: Optional evaluator that returns
+            ``(deny_reason, advisory_system_message)`` so allow-path notices
+            match the standalone hook (plain_language OP-07D).
+        build_allow_advisory_payload: Optional builder for an allow payload that
+            carries the advisory systemMessage without denying.
     """
 
     evaluate: NativeEvaluator
     build_deny_payload: DenyPayloadBuilder
+    evaluate_with_advisory: AdvisoryEvaluator | None = None
+    build_allow_advisory_payload: AllowAdvisoryPayloadBuilder | None = None
 
 
 _native_hook_by_module_name: dict[str, NativeHook] = {
@@ -76,6 +96,8 @@ _native_hook_by_module_name: dict[str, NativeHook] = {
     PLAIN_LANGUAGE_BLOCKER_MODULE_NAME: NativeHook(
         evaluate=evaluate_plain_language,
         build_deny_payload=build_plain_language_deny_payload,
+        evaluate_with_advisory=evaluate_plain_language_with_advisory,
+        build_allow_advisory_payload=build_plain_language_allow_advisory_payload,
     ),
 }
 
@@ -180,19 +202,28 @@ def run_native_hook(
     Calls the evaluator directly with the payload dict, builds the full deny JSON
     via the hook's own deny-payload builder so the captured stdout matches the
     standalone hook's deny shape (carrying systemMessage, additionalContext, and
-    suppressOutput), and catches a non-SystemExit crash to log and classify it.
+    suppressOutput), emits an allow-with-systemMessage payload when the hook
+    returns an advisory without a deny, and catches a non-SystemExit crash to
+    log and classify it.
 
     Args:
-        native_hook: The hook's evaluator paired with its deny-payload builder.
+        native_hook: The hook's evaluator paired with its payload builders.
         payload_by_key: The parsed payload dict to pass to the evaluator.
         is_blocking: Whether a crash from this hook surfaces a blocking signal.
 
     Returns:
-        A HostedHookResult carrying the captured deny JSON (empty when allowed),
-        the crash flag, and the blocking classification.
+        A HostedHookResult carrying the captured deny or allow-advisory JSON
+        (empty when the payload is clean), the crash flag, and the blocking
+        classification.
     """
     try:
-        deny_reason = native_hook.evaluate(payload_by_key)
+        if native_hook.evaluate_with_advisory is not None:
+            deny_reason, advisory_system_message = native_hook.evaluate_with_advisory(
+                payload_by_key
+            )
+        else:
+            deny_reason = native_hook.evaluate(payload_by_key)
+            advisory_system_message = None
     except Exception as error:
         _log_hook_crash(native_hook.evaluate.__module__, error)
         return HostedHookResult(
@@ -202,9 +233,17 @@ def run_native_hook(
             is_blocking=is_blocking,
         )
 
-    captured_stdout = (
-        json.dumps(native_hook.build_deny_payload(deny_reason)) if deny_reason is not None else ""
-    )
+    if deny_reason is not None:
+        captured_stdout = json.dumps(native_hook.build_deny_payload(deny_reason))
+    elif (
+        advisory_system_message is not None
+        and native_hook.build_allow_advisory_payload is not None
+    ):
+        captured_stdout = json.dumps(
+            native_hook.build_allow_advisory_payload(advisory_system_message)
+        )
+    else:
+        captured_stdout = ""
     return HostedHookResult(
         exit_code=0,
         captured_stdout=captured_stdout,
@@ -394,40 +433,79 @@ def aggregate_hosted_hook_results(
     )
 
 
+def unique_first_seen_strings(all_values: list[str]) -> list[str]:
+    """Return values in first-seen order with exact-string duplicates dropped.
+
+    ::
+
+        unique_first_seen_strings(["a", "b", "a"])  ->  ["a", "b"]
+
+    Comparison is exact full-string equality only (no case fold, no trim).
+    Each field of the deny payload (reasons, systemMessage, additionalContext)
+    is collapsed separately so a deny reason identical to a context string never
+    cross-collapses.
+
+    Args:
+        all_values: Strings collected from hosted hooks in run order.
+
+    Returns:
+        A new list with the first occurrence of each exact string kept.
+    """
+    seen_values: set[str] = set()
+    unique_values: list[str] = []
+    for each_value in all_values:
+        if each_value in seen_values:
+            continue
+        seen_values.add(each_value)
+        unique_values.append(each_value)
+    return unique_values
+
+
 def _emit_deny_decision(decision: DispatcherDecision) -> None:
     """Write one deny JSON object to stdout carrying all deny reasons and context.
 
-    Carries every hook's systemMessage and additionalContext and the
-    suppressOutput flag so the dispatched deny matches the standalone hooks'
-    full deny shape.
+    Collapses exact-duplicate reasons, systemMessage lines, and additionalContext
+    lines at emit time (first-seen order) so the final payload is compact while
+    aggregate_hosted_hook_results still records every firing for logging.
 
     Args:
         decision: The aggregated dispatcher decision with deny reasons, context,
             and the suppressOutput flag.
     """
-    combined_reason = " | ".join(decision.all_deny_reasons)
+    all_unique_deny_reasons = unique_first_seen_strings(decision.all_deny_reasons)
+    all_unique_system_messages = unique_first_seen_strings(decision.all_system_messages)
+    all_unique_additional_context = unique_first_seen_strings(
+        decision.all_additional_context
+    )
+    combined_reason = REASON_JOIN_SEPARATOR.join(all_unique_deny_reasons)
     hook_specific: dict[str, object] = {
         "hookEventName": HOOK_EVENT_NAME,
         "permissionDecision": DENY_DECISION,
         "permissionDecisionReason": combined_reason,
     }
-    if decision.all_additional_context:
-        hook_specific["additionalContext"] = "\n".join(decision.all_additional_context)
+    if all_unique_additional_context:
+        hook_specific["additionalContext"] = CONTEXT_JOIN_SEPARATOR.join(
+            all_unique_additional_context
+        )
     deny_payload: dict[str, object] = {"hookSpecificOutput": hook_specific}
-    if decision.all_system_messages:
-        deny_payload["systemMessage"] = "\n".join(decision.all_system_messages)
+    if all_unique_system_messages:
+        deny_payload["systemMessage"] = CONTEXT_JOIN_SEPARATOR.join(
+            all_unique_system_messages
+        )
     if decision.should_suppress_output:
         deny_payload["suppressOutput"] = True
     sys.stdout.write(json.dumps(deny_payload) + "\n")
     sys.stdout.flush()
 
 
-def _emit_allow_decision() -> None:
+def _emit_allow_decision(decision: DispatcherDecision) -> None:
     """Write one explicit allow JSON object to stdout.
 
     Matches the shape a standalone hosted hook emits when it auto-approves the
     write, so a write a hosted hook allows explicitly is auto-approved under the
-    dispatcher rather than falling back to the default permission flow.
+    dispatcher rather than falling back to the default permission flow. When a
+    hook also carried an advisory systemMessage (plain-language heavy words),
+    that notice rides on the allow payload without denying.
     """
     allow_payload: dict[str, object] = {
         "hookSpecificOutput": {
@@ -435,6 +513,10 @@ def _emit_allow_decision() -> None:
             "permissionDecision": ALLOW_DECISION,
         }
     }
+    if decision.all_system_messages:
+        allow_payload["systemMessage"] = SYSTEM_MESSAGE_JOIN_SEPARATOR.join(
+            decision.all_system_messages
+        )
     sys.stdout.write(json.dumps(allow_payload) + "\n")
     sys.stdout.flush()
 
@@ -522,7 +604,7 @@ def dispatch(
         _emit_deny_decision(aggregated_decision)
         return
     if aggregated_decision.should_allow:
-        _emit_allow_decision()
+        _emit_allow_decision(aggregated_decision)
 
 
 def main() -> None:

package/hooks/blocking/state_description_blocker.py

@@ -20,6 +20,9 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from blocking.code_rules_shared import is_ephemeral_path  # noqa: E402
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
 from hooks_constants.state_description_blocker_constants import (  # noqa: E402
@@ -278,7 +281,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
 
     Applies the same tool-name gate, file-extension gate, content selection, and
     pattern scan the standalone hook applies. Returns the deny-reason text when a
-    historical phrase is found, or None to allow.
+    historical phrase is found, or None to allow. Opinionated prose enforcement
+    is default-off via ``prose_style_enforcement_enabled_in_environment()``.
 
     Args:
         payload_by_key: The PreToolUse payload with tool_name and tool_input.
@@ -287,6 +291,8 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
         The permissionDecisionReason text when the write is denied, or None when
         the write is allowed.
     """
+    if not prose_style_enforcement_enabled_in_environment():
+        return None
     raw_tool_name = payload_by_key.get("tool_name", "")
     tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
     if tool_name not in ("Write", "Edit"):

package/hooks/blocking/tdd_enforcer.py

@@ -17,6 +17,7 @@ try:
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
     from code_rules_shared import (
+        is_agent_home_tooling,
         is_ephemeral_script_path,
         is_under_session_scratchpad,
     )
@@ -40,6 +41,11 @@ def _is_session_scratchpad_write(file_path: str, input_data: dict) -> bool:
     return is_under_session_scratchpad(file_path, input_data)
 
 
+def _is_agent_home_tooling_write(file_path: str) -> bool:
+    """A coding agent's own home-directory tooling is outside the TDD gate."""
+    return is_agent_home_tooling(file_path)
+
+
 production_extensions = path_classification.production_extensions
 skip_extensions = path_classification.skip_extensions
 _is_inside_dotclaude_segment = path_classification._is_inside_dotclaude_segment
@@ -69,6 +75,8 @@ def _resolve_payload(input_data: dict) -> tuple[str, dict, str]:
 def _is_silently_skipped(file_path: str, extension: str, path: Path) -> bool:
     if _is_inside_dotclaude_segment(file_path) or is_ephemeral_script_path(file_path):
         return True
+    if _is_agent_home_tooling_write(file_path):
+        return True
     if extension in skip_extensions():
         return True
     if extension not in production_extensions():

package/hooks/blocking/test__path_setup.py

@@ -37,3 +37,31 @@ def test_importing_path_setup_puts_the_hooks_directory_on_sys_path() -> None:
     )
     assert completed.returncode == 0, completed.stderr
     assert completed.stdout.strip() == "ok"
+
+
+def test_importing_path_setup_puts_the_blocking_directory_on_sys_path() -> None:
+    """A module reached through the package finds its own directory on sys.path.
+
+    ``code_rules_shared`` imports both ``hooks_constants`` (a hooks-directory
+    package) and its blocking-directory siblings, so the bootstrap must place
+    both roots. Only the hooks directory is on PYTHONPATH here, so the blocking
+    entry can only come from the bootstrap itself.
+    """
+    driver = (
+        "import sys\n"
+        "from blocking import _path_setup\n"
+        "from pathlib import Path\n"
+        "blocking_dir = str(Path(_path_setup.__file__).resolve().parent)\n"
+        "assert blocking_dir in sys.path, blocking_dir\n"
+        "print('ok')\n"
+    )
+    subprocess_environment = {**os.environ, "PYTHONPATH": str(_HOOKS_DIR)}
+    completed = subprocess.run(
+        [sys.executable, "-c", driver],
+        check=False,
+        capture_output=True,
+        text=True,
+        env=subprocess_environment,
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert completed.stdout.strip() == "ok"

package/hooks/blocking/test_code_rules_enforcer_agent_home_tooling.py

@@ -0,0 +1,99 @@
+"""Agent-home tooling exemption tests for the classifier and the enforcer.
+
+A coding agent installs its own helper scripts under a dot-directory in the
+user's home — ``~/.grok/runs/`` sits beside the already-exempt
+``~/.claude/hooks/``. That tree is vendored tooling rather than project code,
+so the repository code rules do not govern it::
+
+    /home/example/.grok/runs/worktree-health/health.py  -> exempt
+    C:/dev/my-project/src/grokking.py               -> governed
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from blocking import _path_setup  # noqa: F401  (pins this checkout ahead of sibling worktrees)
+from blocking.code_rules_shared import is_agent_home_tooling, is_ephemeral_path
+
+_ENFORCER_SCRIPT = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+
+_VIOLATING_PRODUCTION_SOURCE = "def process_data(payload: str) -> None:\n    print(payload)\n"
+
+
+def _check_as(candidate_source: str, target_path: str) -> subprocess.CompletedProcess[str]:
+    """Run the enforcer's pre-check on a candidate judged as another path.
+
+    Args:
+        candidate_source: Python source written to the candidate file.
+        target_path: Destination path the candidate is judged as.
+
+    Returns:
+        The completed process carrying stdout, stderr, and the exit code.
+    """
+    with tempfile.TemporaryDirectory() as scratch:
+        candidate = Path(scratch) / "candidate.py"
+        candidate.write_text(candidate_source, encoding="utf-8")
+        return subprocess.run(
+            [sys.executable, str(_ENFORCER_SCRIPT), "--check", str(candidate), "--as", target_path],
+            input="",
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+
+def test_posix_agent_home_path_is_agent_tooling() -> None:
+    assert is_agent_home_tooling("/home/example/.grok/runs/worktree-health/health.py")
+
+
+def test_windows_agent_home_path_is_agent_tooling() -> None:
+    assert is_agent_home_tooling(r"C:\Users\example\.grok\runs\worktree-health\health.py")
+
+
+def test_any_depth_under_the_agent_home_is_agent_tooling() -> None:
+    assert is_agent_home_tooling("/home/example/.grok/hooks/force_worktree.py")
+
+
+def test_ordinary_project_code_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/src/service.py")
+
+
+def test_a_filename_spelled_like_the_agent_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/src/grokking.py")
+
+
+def test_a_directory_without_the_leading_dot_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("/dev/my-project/grok/runner.py")
+
+
+def test_an_empty_path_is_not_agent_tooling() -> None:
+    assert not is_agent_home_tooling("")
+
+
+def test_agent_home_path_is_exempt_from_the_repository_gates() -> None:
+    assert is_ephemeral_path("/home/example/.grok/runs/worktree-health/health.py")
+
+
+def test_project_code_is_not_exempt_from_the_repository_gates() -> None:
+    assert not is_ephemeral_path("/dev/my-project/src/service.py")
+
+
+def test_enforcer_allows_violating_source_under_the_agent_home() -> None:
+    target = os.path.join("/home/example", ".grok", "runs", "worktree-health", "health.py")
+
+    completed = _check_as(_VIOLATING_PRODUCTION_SOURCE, target)
+
+    assert completed.returncode == 0, completed.stdout + completed.stderr
+
+
+def test_enforcer_still_flags_the_same_source_in_a_project_path() -> None:
+    target = os.path.join("/dev/my-project", "src", "service.py")
+
+    completed = _check_as(_VIOLATING_PRODUCTION_SOURCE, target)
+
+    assert completed.returncode != 0