claude-dev-env 2.17.0 → 2.19.0

package/hooks/hooks_constants/AGENTS.md

@@ -11,6 +11,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `ask_user_question_shape.py` | Pure AskUserQuestion lean-block shape analyzer: grades question and option-description prose against shared chat-detail markers and sentence/word caps with no hook I/O |
 | `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
 | `bash_pre_tool_use_dispatcher_constants.py` | Permission outcomes, tool-name sets, and the ordered hosted-hook roster for the Bash PreToolUse dispatcher (also covers PowerShell-shared gates) |
+| `pre_tool_use_dispatcher_constants.py` | Shared Write, Edit, and MultiEdit tool-name set and the ordered hosted-hook roster for the Write/Edit/MultiEdit PreToolUse dispatcher |
 | `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
 | `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
 | `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
@@ -24,6 +25,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
 | `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
 | `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
+| `destructive_command_environment_constants.py` | Environment keys and shared truthy values used by destructive-command hooks |
 | `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
 | `docstring_rule_gate_count_blocker_constants.py` | Target rule basename, spelled-out-number lookup, count-clause and `check_*` validator patterns, and block-message text for the docstring-rule gate-count staleness blocker |
 | `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
@@ -62,7 +64,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `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 |
-| `sensitive_file_protector_constants.py` | Sensitive filename patterns, the committed-template suffixes that earn an exemption, the write/edit tool names, and the deny decision and message template for `sensitive_file_protector` |
+| `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 |
 | `session_start_injector.py` | Pure SessionStart context injector: normalize `source` (`startup`/`resume`/`clear`/`compact`), honor enable/timeout, return structured injection results for starter hooks |

package/hooks/hooks_constants/atomic_file_writer_constants.py

@@ -0,0 +1,4 @@
+"""Constants for atomic hook-state text replacement."""
+
+TEXT_WRITE_MODE = "w"
+ATOMIC_WRITE_TEMPORARY_SUFFIX = ".tmp"

package/hooks/hooks_constants/banned_identifiers_constants.py

@@ -38,6 +38,7 @@ ALL_BANNED_NOUN_WORDS: frozenset[str] = frozenset(
         "temp",
     }
 )
+BANNED_NOUN_COMPATIBILITY_COMMENT: str = "# pragma: no-banned-noun"
 CAMEL_CASE_WORD_PATTERN: re.Pattern[str] = re.compile(
     r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+"
 )

package/hooks/hooks_constants/destructive_command_environment_constants.py

@@ -0,0 +1,18 @@
+"""Environment keys and values used by destructive-command hooks."""
+
+from __future__ import annotations
+
+ALL_KNOWN_TEMPORARY_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
+    {
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "CLAUDE_JOB_DIR",
+    }
+)
+ALL_TRUTHY_ENV_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})
+DESTRUCTIVE_DENY_MODE_ENV_VAR: str = "CLAUDE_DESTRUCTIVE_DENY_MODE"
+EPHEMERAL_AUTO_ALLOW_DISABLE_ENV_VAR: str = (
+    "CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW"
+)
+GH_REDIRECT_ACTIVE_ENV_VAR: str = "CLAUDE_GH_REDIRECT_ACTIVE"

package/hooks/hooks_constants/destructive_command_segment_constants.py

@@ -1,4 +1,4 @@
-"""Segment-splitting, command-name, and deny-mode constants for the destructive command blocker."""
+"""Segment-splitting and command-name constants for the destructive command blocker."""
 
 ALL_SHELL_CONTROL_OPERATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|&", "|", "&", "\n", "\r"})
 ALL_COMMAND_LAUNCHER_WRAPPER_COMMANDS: frozenset[str] = frozenset(
@@ -183,13 +183,3 @@ ALL_LAUNCHER_OPTIONS_TAKING_SEPARATE_VALUE: frozenset[str] = frozenset(
     }
 )
 ALL_SUBSHELL_GROUPING_CHARACTERS: str = "({"
-ALL_KNOWN_TEMPORARY_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
-    {
-        "TEMP",
-        "TMP",
-        "TMPDIR",
-        "CLAUDE_JOB_DIR",
-    }
-)
-DESTRUCTIVE_DENY_MODE_ENV_VAR: str = "CLAUDE_DESTRUCTIVE_DENY_MODE"
-ALL_TRUTHY_ENV_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})

package/hooks/hooks_constants/hardcoded_user_path_constants.py

@@ -4,9 +4,15 @@ import re
 
 HARDCODED_USER_PATH_PATTERN: re.Pattern[str] = re.compile(
     r"(?:"
-    r"[A-Za-z]:[\\/](?i:users)[\\/](?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
-    r"|(?<![A-Za-z:])/Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|/home/[^/]+(?=/|$))"
+    r"[A-Za-z]:[\\/]+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
+    r"|\\{2,}(?:[^\\/\r\n]+[\\/]+)+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
+    r"|(?<!:)//(?:[^\\/\r\n]+/)+(?i:users)/(?!(?i:Public|Shared|All Users)(?:/|$))[^/]+(?=/|$)"
+    r"|(?i:file):///Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:Users)/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
+    r"|(?i:file):///home/[^/]+(?=/|$)"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:home)/[^/]+(?=/|$)"
+    r"|(?<![A-Za-z0-9._:/\-\]])/Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
+    r"|(?<![A-Za-z0-9._:/\-\]])/home/[^/]+(?=/|$))"
 )
 MAX_HARDCODED_USER_PATH_ISSUES: int = 25
 HARDCODED_USER_PATH_GUIDANCE: str = "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -82,7 +82,7 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
     ),
     HostedHookEntry(
         script_relative_path="blocking/sensitive_file_protector.py",
-        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
     ),
     HostedHookEntry(
         script_relative_path="blocking/pii_prevention_blocker.py",

package/hooks/hooks_constants/sensitive_file_protector_constants.py

@@ -1,7 +1,7 @@
 """Constants for the ``sensitive_file_protector`` PreToolUse hook.
 
-The hook denies a Write or Edit whose target basename names a live secret or a
-lock file, and steps aside for a placeholders-only committed template.
+The hook denies a Write, Edit, or MultiEdit whose target basename names a live
+secret or a lock file, and steps aside for a placeholders-only committed template.
 """
 
 from __future__ import annotations
@@ -28,8 +28,6 @@ ALL_SENSITIVE_PATTERNS = (
 
 ALL_TEMPLATE_SUFFIXES = (".example", ".sample", ".template")
 
-ALL_WRITE_EDIT_TOOLS = ("Write", "Edit")
-
 HOOK_SCRIPT_NAME = "sensitive_file_protector.py"
 
 HOOK_EVENT_NAME = "PreToolUse"

package/hooks/json_file_reader.py

@@ -0,0 +1,22 @@
+"""Safe JSON-object reads for hook-state files."""
+
+import json
+from pathlib import Path
+
+
+def read_json_object(file_path: Path, encoding: str) -> dict[str, object] | None:
+    """Return one decoded JSON object.
+
+    Args:
+        file_path: The JSON file path.
+        encoding: The text encoding.
+
+    Returns:
+        The decoded object, or ``None`` for missing, unreadable, or malformed data.
+    """
+    try:
+        raw_text = file_path.read_text(encoding=encoding)
+        parsed_payload = json.loads(raw_text)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return parsed_payload if isinstance(parsed_payload, dict) else None

package/hooks/pending_sidecars.py

@@ -0,0 +1,33 @@
+"""Pending-sidecar discovery and cleanup for hook state."""
+
+from pathlib import Path
+
+
+def pending_sidecar_paths(
+    main_file: Path, pending_marker: str, pending_suffix: str
+) -> tuple[Path, ...]:
+    """Return pending sidecars for one main state file.
+
+    Args:
+        main_file: The primary state file.
+        pending_marker: The marker before the unique sidecar token.
+        pending_suffix: The sidecar filename suffix.
+
+    Returns:
+        The matching pending sidecar paths.
+    """
+    pending_pattern = f"{main_file.name}{pending_marker}*{pending_suffix}"
+    return tuple(main_file.parent.glob(pending_pattern))
+
+
+def remove_pending_sidecars(all_pending_files: tuple[Path, ...]) -> None:
+    """Remove a captured pending-sidecar set.
+
+    Args:
+        all_pending_files: The exact sidecars already merged or consumed.
+    """
+    for each_pending_file in all_pending_files:
+        try:
+            each_pending_file.unlink(missing_ok=True)
+        except OSError:
+            continue

package/hooks/test_atomic_file_writer.py

@@ -0,0 +1,73 @@
+"""Behavior tests for atomic hook-state text replacement."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+import atomic_file_writer
+from atomic_file_writer import write_text_atomically
+
+
+def test_write_text_atomically_creates_parent_and_replaces_complete_text(
+    tmp_path: Path,
+) -> None:
+    target_path = tmp_path / "state" / "cache.json"
+
+    write_text_atomically(
+        target_path,
+        '{"complete": true}',
+        encoding="utf-8",
+        temporary_prefix=".cache-",
+        temporary_suffix=".tmp",
+        should_reap_orphans=False,
+    )
+
+    assert target_path.read_text(encoding="utf-8") == '{"complete": true}'
+
+
+def test_write_text_atomically_preserves_target_and_cleans_temp_after_replace_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    target_path = tmp_path / "cache.json"
+    target_path.write_text("stable", encoding="utf-8")
+
+    def _raise_replace_error(source_path: object, destination_path: object) -> None:
+        del source_path, destination_path
+        raise OSError("replace failed")
+
+    monkeypatch.setattr(atomic_file_writer.os, "replace", _raise_replace_error)
+
+    with pytest.raises(OSError, match="replace failed"):
+        write_text_atomically(
+            target_path,
+            "replacement",
+            encoding="utf-8",
+            temporary_prefix=".cache-",
+            temporary_suffix=".tmp",
+            should_reap_orphans=False,
+        )
+
+    assert target_path.read_text(encoding="utf-8") == "stable"
+    assert list(tmp_path.glob(".cache-*.tmp")) == []
+
+
+def test_write_text_atomically_reaps_orphans(tmp_path: Path) -> None:
+    target_path = tmp_path / "cache.json"
+    orphan_path = tmp_path / ".cache-orphan.tmp"
+    orphan_path.write_text("orphan", encoding="utf-8")
+
+    write_text_atomically(
+        target_path,
+        "replacement",
+        encoding="utf-8",
+        temporary_prefix=".cache-",
+        temporary_suffix=".tmp",
+        should_reap_orphans=True,
+    )
+
+    assert not orphan_path.exists()

package/hooks/test_json_file_reader.py

@@ -0,0 +1,24 @@
+"""Behavior tests for safe JSON-object reads."""
+
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from json_file_reader import read_json_object
+
+
+def test_read_json_object_returns_decoded_mapping(tmp_path: Path) -> None:
+    file_path = tmp_path / "state.json"
+    file_path.write_text('{"status": "ready"}', encoding="utf-8")
+
+    assert read_json_object(file_path, "utf-8") == {"status": "ready"}
+
+
+def test_read_json_object_returns_none_for_invalid_bytes(tmp_path: Path) -> None:
+    file_path = tmp_path / "state.json"
+    file_path.write_bytes(b"\xff")
+
+    assert read_json_object(file_path, "utf-8") is None

package/hooks/test_pending_sidecars.py

@@ -0,0 +1,25 @@
+"""Behavior tests for pending-sidecar discovery and cleanup."""
+
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from pending_sidecars import pending_sidecar_paths, remove_pending_sidecars
+
+
+def test_pending_sidecar_paths_and_remove_pending_sidecars(tmp_path: Path) -> None:
+    main_file = tmp_path / "state.json"
+    first_pending = tmp_path / "state.json.pending-first.json"
+    second_pending = tmp_path / "state.json.pending-second.json"
+    unrelated_file = tmp_path / "other.json"
+    for each_file in (first_pending, second_pending, unrelated_file):
+        each_file.write_text("state", encoding="utf-8")
+
+    all_pending_files = pending_sidecar_paths(main_file, ".pending-", ".json")
+    remove_pending_sidecars(all_pending_files)
+
+    assert sorted(all_pending_files) == sorted((first_pending, second_pending))
+    assert unrelated_file.is_file()

package/package.json

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