claude-dev-env 2.21.0 → 2.21.2

package/hooks/blocking/test_plain_language_blocker.py

@@ -0,0 +1,119 @@
+"""Production-path tests for the AskUserQuestion plain-language blocker."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+HOOK_PATH = Path(__file__).with_name("plain_language_blocker.py")
+
+
+def _run_hook(
+    payload: dict[str, object], *, enabled: bool
+) -> subprocess.CompletedProcess[str]:
+    environment = os.environ.copy()
+    if enabled:
+        environment["CLAUDE_PROSE_STYLE_ENFORCEMENT"] = "1"
+    else:
+        environment.pop("CLAUDE_PROSE_STYLE_ENFORCEMENT", None)
+    return subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        check=False,
+        env=environment,
+        text=True,
+    )
+
+
+def _decision(result: subprocess.CompletedProcess[str]) -> str | None:
+    if not result.stdout:
+        return None
+    parsed_payload = json.loads(result.stdout)
+    return parsed_payload.get("hookSpecificOutput", {}).get("permissionDecision")
+
+
+def test_default_off_allows_formal_question_word() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [{"question": "Should we utilize this path?"}]
+            },
+        },
+        enabled=False,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_enabled_blocks_formal_question_word() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [
+                    {
+                        "question": "Should we utilize this path?",
+                        "options": [{"description": "Initiate the migration."}],
+                    }
+                ]
+            },
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert _decision(result) == "deny"
+    assert "utilize -> use" in result.stdout
+    assert "initiate -> start" in result.stdout
+
+
+def test_exact_code_url_and_path_text_is_exempt() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [
+                    {
+                        "question": (
+                            "Use `utilize` in src/initiate.py or "
+                            "https://example.test/utilize."
+                        )
+                    }
+                ]
+            },
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_other_tools_are_ignored() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {"content": "Utilize the existing helper."},
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+@pytest.mark.parametrize("raw_input", ["", "[]", "not json"])
+def test_invalid_input_is_fail_open(raw_input: str) -> None:
+    result = subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=raw_input,
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""

package/hooks/blocking/test_send_user_file_open_locally_blocker.py

@@ -47,7 +47,10 @@ def test_allows_proactive_status() -> None:
 
 def test_corrective_message_points_to_native_windows_app() -> None:
     assert "native Windows app" in CORRECTIVE_MESSAGE
+    assert "Invoke-Item -LiteralPath" in CORRECTIVE_MESSAGE
     assert "Show-Asset.ps1" not in CORRECTIVE_MESSAGE
+    assert "Cursor.exe" in CORRECTIVE_MESSAGE
+    assert "EPIPE" in CORRECTIVE_MESSAGE
 
 
 def test_corrective_message_names_proactive_escape_hatch() -> None:

package/hooks/hooks.json

@@ -22,6 +22,16 @@
           }
         ]
       },
+      {
+        "matcher": "apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
+            "timeout": 60
+          }
+        ]
+      },
       {
         "matcher": "Bash|PowerShell",
         "hooks": [
@@ -80,6 +90,11 @@
       {
         "matcher": "AskUserQuestion",
         "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/ask_user_question_shape_blocker.py",

package/hooks/hooks_constants/AGENTS.md

@@ -21,6 +21,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
 | `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
 | `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
+| `cursor_cli_python_misfire_blocker_constants.py` | Detection patterns and deny message for Cursor launches that mistreat a Python code-rules-gate script |
 | `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
 | `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
 | `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
@@ -63,7 +64,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
 | `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
 | `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
-| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
+| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the `Invoke-Item` block message for the open-locally attach blocker |
 | `sensitive_file_protector_constants.py` | Sensitive filename patterns, committed-template suffixes that earn an exemption, and the deny decision and message template for `sensitive_file_protector` |
 | `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
 | `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -58,6 +58,10 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry("blocking/gh_body_arg_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/shell_substitution_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/piped_pytest_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
+    BashHostedHookEntry(
+        "blocking/cursor_cli_python_misfire_blocker.py",
+        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
     BashHostedHookEntry(
         "blocking/unscoped_search_blocker.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES
     ),

package/hooks/hooks_constants/cursor_cli_python_misfire_blocker_constants.py

@@ -0,0 +1,79 @@
+"""Constants for the Cursor-vs-Python gate misfire PreToolUse blocker.
+
+Blocks Shell commands that launch Cursor's CLI or GUI binary against a Python
+script with code-rules-gate flags. That path feeds unknown options into
+Cursor's main process ``resolveArgs``, where ``console.warn`` on a closed pipe
+raises an EPIPE error dialog and still opens the script as an editor path.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "ALL_SUPPORTED_TOOL_NAMES",
+    "BASH_TOOL_NAME",
+    "POWERSHELL_TOOL_NAME",
+    "TOOL_NAME_KEY",
+    "TOOL_INPUT_KEY",
+    "COMMAND_KEY",
+    "HOOK_SPECIFIC_OUTPUT_KEY",
+    "HOOK_EVENT_NAME_KEY",
+    "HOOK_EVENT_NAME",
+    "PERMISSION_DECISION_KEY",
+    "DENY_DECISION",
+    "PERMISSION_DECISION_REASON_KEY",
+    "CALLING_HOOK_NAME",
+    "CURSOR_LAUNCH_PATTERN",
+    "GATE_SCRIPT_PATTERN",
+    "GATE_FLAG_PATTERN",
+    "PYTHON_PATH_PATTERN",
+    "CORRECTIVE_MESSAGE",
+]
+
+BASH_TOOL_NAME = "Bash"
+POWERSHELL_TOOL_NAME = "PowerShell"
+ALL_SUPPORTED_TOOL_NAMES: frozenset[str] = frozenset(
+    {BASH_TOOL_NAME, POWERSHELL_TOOL_NAME}
+)
+
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+COMMAND_KEY = "command"
+
+HOOK_SPECIFIC_OUTPUT_KEY = "hookSpecificOutput"
+HOOK_EVENT_NAME_KEY = "hookEventName"
+HOOK_EVENT_NAME = "PreToolUse"
+PERMISSION_DECISION_KEY = "permissionDecision"
+DENY_DECISION = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+
+CALLING_HOOK_NAME = "cursor_cli_python_misfire_blocker.py"
+
+CURSOR_LAUNCH_PATTERN = re.compile(
+    r"(?i)"
+    r"(?:"
+    r"(?:^|[\s;&|])(?:cursor(?:\.cmd|\.exe)?)(?=\s|[\"']|$)"
+    r"|"
+    r"[\\/](?:cursor(?:\.cmd|\.exe)?)(?=\s|[\"']|$)"
+    r")"
+)
+GATE_SCRIPT_PATTERN = re.compile(r"(?i)code_rules_gate\.py\b")
+GATE_FLAG_PATTERN = re.compile(
+    r"(?i)(?:^|[\s,\"'])(?:--base|--staged|--repo-root|--only-under)"
+    r"(?:\s|=|$|[\"'])"
+)
+PYTHON_PATH_PATTERN = re.compile(r"(?i)\.py(?:\s|$|['\":])")
+
+CORRECTIVE_MESSAGE = (
+    "BLOCKED [cursor-python-misfire]: Cursor's CLI/GUI was invoked against a "
+    "Python script with code-rules-gate flags. Cursor treats those flags as "
+    "unknown options, warns on a closed pipe, and raises an EPIPE error dialog "
+    "while still opening the script as an editor path.\n\n"
+    "To run the gate:\n"
+    "  python <path-to>/code_rules_gate.py --base origin/main\n\n"
+    "To open a file on screen in its native Windows app:\n"
+    "  Invoke-Item -LiteralPath '<path>'\n\n"
+    "Do not pass --base, --staged, --repo-root, or --only-under to cursor / "
+    "Cursor.exe."
+)

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -0,0 +1,26 @@
+"""Configuration for the AskUserQuestion plain-language blocker."""
+
+from __future__ import annotations
+
+import re
+
+ALL_PLAIN_LANGUAGE_TERM_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"\butilize\b", re.IGNORECASE), "use"),
+    (re.compile(r"\binitiate\b", re.IGNORECASE), "start"),
+    (re.compile(r"\bsufficient\b", re.IGNORECASE), "enough"),
+    (re.compile(r"\bprior to\b", re.IGNORECASE), "before"),
+    (re.compile(r"\bin order to\b", re.IGNORECASE), "to"),
+)
+
+FENCED_CODE_PATTERN = re.compile(r"```[\s\S]*?```")
+INLINE_CODE_PATTERN = re.compile(r"`[^`\n]+`")
+URL_PATTERN = re.compile(r"https?://\S+", re.IGNORECASE)
+FILE_PATH_PATTERN = re.compile(
+    r"(?<!\w)(?:[A-Za-z]:[\\/]|\.\.?[\\/])?[\w.-]+(?:[\\/][\w.-]+)+"
+)
+
+PLAIN_LANGUAGE_BLOCK_PREFIX = "BLOCKED: [PLAIN_LANGUAGE] Use familiar words: "
+PLAIN_LANGUAGE_TERM_SEPARATOR = "; "
+PLAIN_LANGUAGE_NOTICE = (
+    "Plain-language check: use familiar words in the question and its options."
+)

package/hooks/hooks_constants/send_user_file_open_locally_blocker_constants.py

@@ -7,7 +7,11 @@ PROACTIVE_STATUS: str = "proactive"
 CORRECTIVE_MESSAGE: str = (
     "BLOCKED [open-locally]: SendUserFile attaches a file to the session, which "
     "does not let the user see it while they are at the terminal. Open the file on "
-    "screen with its native Windows app. Open every path the user named.\n"
+    "screen with its native Windows app:\n"
+    "  Invoke-Item -LiteralPath '<path>'\n"
+    "Open every path the user named. Do not launch Cursor.exe or cursor.cmd to open "
+    "a file — unknown flags on that path raise an EPIPE error dialog in Cursor's "
+    "main process.\n"
     "The one allowed attach is a phone push: when the user has stepped away and you "
     'want the file to reach their phone, call SendUserFile with status "proactive".'
 )

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -27,6 +27,7 @@ _EXPECTED_BASH_ORDER = (
     "blocking/gh_body_arg_blocker.py",
     "blocking/shell_substitution_blocker.py",
     "blocking/piped_pytest_blocker.py",
+    "blocking/cursor_cli_python_misfire_blocker.py",
     "blocking/unscoped_search_blocker.py",
     "blocking/nas_ssh_binary_enforcer.py",
     "blocking/volatile_path_in_post_blocker.py",
@@ -41,6 +42,7 @@ _EXPECTED_BASH_ORDER = (
 )
 
 _POWERSHELL_APPLICABLE = (
+    "blocking/cursor_cli_python_misfire_blocker.py",
     "blocking/unscoped_search_blocker.py",
     "blocking/pii_prevention_blocker.py",
 )

package/package.json

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

package/scripts/codex_compat_materializer.py

@@ -520,8 +520,9 @@ def render_codex_failure_blast_radius(rule_content: str) -> str:
 def _build_codex_instruction_projection(config: MaterializerConfig) -> PlannedFile | None:
     """Build the managed AGENTS.md projection when the canonical rule is present."""
     source_path = config.source_root / failure_blast_radius_rule_relative_path
-    if not source_path.is_file():
+    if not source_path.exists() and not _is_reparse_point(source_path):
         return None
+    source_path = _validated_source_file(config, failure_blast_radius_rule_relative_path, "failure blast-radius rule")
     rule_content = source_path.read_text(encoding="utf-8")
     projected_content = render_codex_failure_blast_radius(rule_content)
     return PlannedFile(
@@ -545,6 +546,24 @@ def _read_json_object(file_path: Path, description: str) -> dict[str, object]:
     return {each_key: each_record for each_key, each_record in parsed_json.items()}
 
 
+def _validated_source_file(
+    config: MaterializerConfig, relative_path: str, description: str
+) -> Path:
+    """Resolve one source file while rejecting reparse points and escapes."""
+    source_path = config.source_root.joinpath(*relative_path.split(path_separator))
+    current_path = config.source_root
+    for each_part in relative_path.split(path_separator):
+        current_path /= each_part
+        if current_path.exists() and _is_reparse_point(current_path):
+            raise MaterializerRunFatal(
+                f"{description} source reparse point is not allowed: {relative_path}"
+            )
+    resolved_path = _validate_containment(config.source_root, source_path)
+    if not resolved_path.is_file():
+        raise MaterializerError(f"{description} source file is missing: {relative_path}")
+    return resolved_path
+
+
 def _validated_agent_iterable(candidate: object) -> tuple[ClaudeAgent, ...]:
     """Validate the optional agent iterable used by the legacy call form."""
     if not isinstance(candidate, Iterable):
@@ -571,7 +590,11 @@ def _find_codex_hook_source(config: MaterializerConfig) -> Path | None:
         config.source_root / codex_hook_manifest_source_path,
         config.source_root / Path(codex_hook_manifest_source_path).name,
     )
-    return next((each_path for each_path in all_candidates if each_path.is_file()), None)
+    for each_path in all_candidates:
+        if each_path.exists() or _is_reparse_point(each_path):
+            relative_path = each_path.relative_to(config.source_root).as_posix()
+            return _validated_source_file(config, relative_path, "Codex hook manifest")
+    return None
 
 
 def _resolved_codex_enforcer_command(config: MaterializerConfig) -> str:
@@ -635,6 +658,41 @@ def _is_code_rules_enforcer_hook(all_hook_record: dict[str, object]) -> bool:
     )
 
 
+def _codex_enforcer_hooks(all_manifest: object) -> tuple[dict[str, object], ...]:
+    """Return enforcer records from the target apply-patch matcher."""
+    if not isinstance(all_manifest, dict):
+        return ()
+    all_events = all_manifest.get("hooks")
+    if not isinstance(all_events, dict):
+        return ()
+    all_pre_tool_use = all_events.get(codex_hook_event_name)
+    if not isinstance(all_pre_tool_use, list):
+        return ()
+    all_enforcer_hooks: list[dict[str, object]] = []
+    for each_entry in all_pre_tool_use:
+        if not isinstance(each_entry, dict) or each_entry.get("matcher") != codex_hook_matcher:
+            continue
+        for each_hook in _hook_records(each_entry.get("hooks", [])):
+            if _is_code_rules_enforcer_hook(each_hook):
+                all_enforcer_hooks.append(each_hook)
+    return tuple(all_enforcer_hooks)
+
+
+def _has_modified_codex_enforcer_hook(
+    current_bytes: bytes, planned_content: ManagedContent
+) -> bool:
+    """Report whether an existing enforcer record differs from the plan."""
+    try:
+        current_manifest = json.loads(current_bytes.decode("utf-8"))
+        planned_manifest = json.loads(content_to_bytes(planned_content).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return True
+    current_hooks = _codex_enforcer_hooks(current_manifest)
+    if not current_hooks:
+        return False
+    return current_hooks != _codex_enforcer_hooks(planned_manifest)
+
+
 def _merge_codex_hook_manifest(
     all_target_manifest: dict[str, object], all_focused_hook: dict[str, object]
 ) -> dict[str, object]:
@@ -710,11 +768,9 @@ def _build_codex_hook_dependency_projection(
     """Build the reviewed source files required by the target enforcer."""
     all_dependencies: list[PlannedFile] = []
     for each_relative_path in codex_hook_dependency_manifest:
-        source_path = config.source_root / each_relative_path
-        if not source_path.is_file():
-            raise MaterializerError(
-                f"source file is missing from the reviewed hook source list: {each_relative_path}"
-            )
+        source_path = _validated_source_file(
+            config, each_relative_path, "reviewed Codex hook dependency"
+        )
         try:
             dependency_content = source_path.read_bytes()
         except OSError as error:
@@ -1119,6 +1175,7 @@ def _record_target_state(config: MaterializerConfig, planned_file: PlannedFile,
 
         target absent                    -> ok:   publish
         on-disk bytes == planned bytes   -> ok:   unchanged, no write
+        _has_modified_codex_enforcer_hook -> flag: conflicted, preserved untouched
         on-disk hash == manifest hash    -> ok:   publish, the tool owns these bytes
         on-disk hash != manifest hash    -> flag: conflicted, preserved untouched
 
@@ -1140,6 +1197,9 @@ def _record_target_state(config: MaterializerConfig, planned_file: PlannedFile,
         _record_matching_target(report, planned_file.target_relative_path, previous_record)
         return target_path, current_bytes, False
     if planned_file.action == codex_hook_merge_action:
+        if _has_modified_codex_enforcer_hook(current_bytes, planned_file.content):
+            _record_target_conflict(report, planned_file.target_relative_path, previous_record)
+            return target_path, current_bytes, False
         return target_path, current_bytes, True
     if _is_pristine_managed(previous_record, current_bytes):
         return target_path, current_bytes, True