claude-dev-env 1.30.1 → 1.32.0

package/hooks/blocking/test_windows_rmtree_blocker.py

@@ -0,0 +1,148 @@
+"""Unit tests for windows_rmtree_blocker PreToolUse hook."""
+
+import importlib.util
+import json
+import io
+import pathlib
+import sys
+from contextlib import redirect_stdout
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "windows_rmtree_blocker",
+    _HOOK_DIR / "windows_rmtree_blocker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+payload_contains_unsafe_rmtree = hook_module.payload_contains_unsafe_rmtree
+extract_payload_text = hook_module.extract_payload_text
+
+
+def test_detects_basic_ignore_errors_call() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil.rmtree(target_path, ignore_errors=True)"
+    )
+
+
+def test_detects_call_with_path_first_then_ignore_errors() -> None:
+    assert payload_contains_unsafe_rmtree(
+        'shutil.rmtree(r"C:\\temp\\foo", ignore_errors=True)'
+    )
+
+
+def test_detects_oneliner_python_dash_c_form() -> None:
+    bash_command = (
+        'python -c "import shutil; '
+        "shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\""
+    )
+    assert payload_contains_unsafe_rmtree(bash_command)
+
+
+def test_detects_call_with_extra_whitespace() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil .rmtree (path,    ignore_errors  =  True)"
+    )
+
+
+def test_detects_call_split_across_lines() -> None:
+    multiline_code = "shutil.rmtree(\n    target_path,\n    ignore_errors=True,\n)"
+    assert payload_contains_unsafe_rmtree(multiline_code)
+
+
+def test_allows_rmtree_with_onexc_handler() -> None:
+    safe_code = "shutil.rmtree(target_path, onexc=_strip_read_only_and_retry)"
+    assert not payload_contains_unsafe_rmtree(safe_code)
+
+
+def test_allows_rmtree_with_onerror_handler() -> None:
+    safe_code = "shutil.rmtree(target_path, onerror=_strip_read_only_and_retry)"
+    assert not payload_contains_unsafe_rmtree(safe_code)
+
+
+def test_allows_bare_rmtree_call() -> None:
+    bare_call = "shutil.rmtree(target_path)"
+    assert not payload_contains_unsafe_rmtree(bare_call)
+
+
+def test_allows_ignore_errors_false() -> None:
+    assert not payload_contains_unsafe_rmtree(
+        "shutil.rmtree(target_path, ignore_errors=False)"
+    )
+
+
+def test_extract_payload_handles_write_content() -> None:
+    extracted = extract_payload_text("Write", {"content": "abc"})
+    assert extracted == "abc"
+
+
+def test_extract_payload_handles_edit_new_string() -> None:
+    extracted = extract_payload_text("Edit", {"new_string": "abc"})
+    assert extracted == "abc"
+
+
+def test_extract_payload_handles_bash_command() -> None:
+    extracted = extract_payload_text("Bash", {"command": "ls"})
+    assert extracted == "ls"
+
+
+def test_extract_payload_returns_empty_for_unknown_tool() -> None:
+    extracted = extract_payload_text("OtherTool", {"content": "abc"})
+    assert extracted == ""
+
+
+def _run_hook(hook_input: dict) -> tuple[str, int]:
+    captured = io.StringIO()
+    sys.stdin = io.StringIO(json.dumps(hook_input))
+    try:
+        with redirect_stdout(captured):
+            try:
+                hook_module.main()
+            except SystemExit as exit_signal:
+                exit_code = exit_signal.code or 0
+    finally:
+        sys.stdin = sys.__stdin__
+    return captured.getvalue(), exit_code
+
+
+def test_main_blocks_unsafe_bash_command() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Bash",
+            "tool_input": {
+                "command": (
+                    'python -c "import shutil; '
+                    "shutil.rmtree(r'/tmp/x', ignore_errors=True)\""
+                )
+            },
+        }
+    )
+    assert exit_code == 0
+    response_payload = json.loads(stdout_text)
+    decision_block = response_payload["hookSpecificOutput"]
+    assert decision_block["permissionDecision"] == "deny"
+    assert "windows-rmtree" in decision_block["permissionDecisionReason"]
+
+
+def test_main_passes_through_safe_write() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {"content": "shutil.rmtree(path, onexc=handler)"},
+        }
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_passes_through_unrelated_tool() -> None:
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Read", "tool_input": {"file_path": "/tmp/x"}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""

package/hooks/blocking/windows_rmtree_blocker.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block shutil.rmtree(..., ignore_errors=True).
+
+shutil.rmtree on Windows raises PermissionError when it encounters a file carrying
+the ReadOnly attribute (FILE_ATTRIBUTE_READONLY). With ignore_errors=True the failure
+is silently swallowed and the tree stays on disk — cleanup looks successful but
+pruned nothing. Linux never hits this because unlink on Linux only needs write on
+the parent directory, not on the file itself. Tests run inside pytest's tmp_path
+do not exercise the regression path because tmp dirs do not carry the attribute.
+
+This hook scans Write/Edit content and Bash commands for the dangerous pattern and
+blocks it with a corrective message pointing to the force_rmtree replacement.
+"""
+
+import json
+import re
+import sys
+
+_WRITE_EDIT_TOOL_NAMES = {"Write", "Edit"}
+_BASH_TOOL_NAME = "Bash"
+
+_RMTREE_IGNORE_ERRORS_PATTERN = re.compile(
+    r"shutil\s*\.\s*rmtree\s*\([^)]*\bignore_errors\s*=\s*True\b",
+    re.DOTALL,
+)
+
+_CORRECTIVE_MESSAGE = (
+    "BLOCKED [windows-rmtree]: shutil.rmtree(..., ignore_errors=True) silently "
+    "fails on Windows when a file carries the ReadOnly attribute "
+    "(FILE_ATTRIBUTE_READONLY). The PermissionError is swallowed and the tree "
+    "stays on disk -- cleanup looks successful but removes nothing. Linux is "
+    "unaffected because unlink only needs write on the parent directory.\n\n"
+    "Use a Windows-safe handler that strips the attribute and retries the "
+    "syscall:\n\n"
+    "    import os\n"
+    "    import shutil\n"
+    "    import stat\n"
+    "    import sys\n\n"
+    "    def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):\n"
+    "        try:\n"
+    "            os.chmod(target_path, stat.S_IWRITE)\n"
+    "            removal_function(target_path)\n"
+    "        except OSError:\n"
+    "            pass\n\n"
+    "    def force_rmtree(target_path: str) -> None:\n"
+    "        handler_kw = (\n"
+    '            {"onexc": _strip_read_only_and_retry}\n'
+    "            if sys.version_info >= (3, 12)\n"
+    '            else {"onerror": _strip_read_only_and_retry}\n'
+    "        )\n"
+    "        try:\n"
+    "            shutil.rmtree(target_path, **handler_kw)\n"
+    "        except OSError:\n"
+    "            pass\n\n"
+    "Two things to know about the handler:\n"
+    "  - *_exc_info collapses the signature difference. onerror passes "
+    "(type, value, traceback); onexc (Python 3.12+) passes a single exception.\n"
+    "  - removal_function is whichever syscall rmtree was attempting "
+    "(os.unlink for files, os.rmdir for dirs). Re-call it after chmod to finish "
+    "the work that originally failed.\n\n"
+    "See ~/.claude/rules/windows-filesystem-safe.md for full guidance."
+)
+
+
+def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
+    if not payload_text:
+        return False
+    return bool(_RMTREE_IGNORE_ERRORS_PATTERN.search(payload_text))
+
+
+def extract_payload_text(tool_name: str, tool_input: dict) -> str:
+    if tool_name in _WRITE_EDIT_TOOL_NAMES:
+        return tool_input.get("content", "") or tool_input.get("new_string", "") or ""
+    if tool_name == _BASH_TOOL_NAME:
+        return tool_input.get("command", "") or ""
+    return ""
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+
+    payload_text = extract_payload_text(tool_name, tool_input)
+
+    if not payload_contains_unsafe_rmtree(payload_text):
+        sys.exit(0)
+
+    deny_response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _CORRECTIVE_MESSAGE,
+        }
+    }
+    print(json.dumps(deny_response))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/config/hook_log_extractor_constants.py

@@ -0,0 +1,234 @@
+"""Constants for the hook-log extractor and init scripts.
+
+Centralizes all named values used by ``hook_log_extractor.py`` and
+``hook_log_init.py`` so that production modules carry zero magic values.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+COMMAND_EXCERPT_MAX_CHARACTERS: int = 300
+STDOUT_EXCERPT_MAX_CHARACTERS: int = 500
+STDERR_EXCERPT_MAX_CHARACTERS: int = 500
+
+INSERT_BATCH_SIZE: int = 500
+CONNECT_TIMEOUT_SECONDS: int = 5
+
+def _resolve_claude_home_directory() -> Path:
+    """Return the root of the local ``~/.claude`` tree, honoring ``CLAUDE_HOME``.
+
+    An unset, empty, or whitespace-only ``CLAUDE_HOME`` falls back to
+    ``~/.claude`` so state and transcript paths do not silently resolve
+    to the process working directory.
+    """
+    claude_home_override = os.environ.get("CLAUDE_HOME", "").strip()
+    if claude_home_override:
+        return Path(claude_home_override).expanduser()
+    return Path.home() / ".claude"
+
+
+OFFSET_STATE_FILE: str = str(
+    _resolve_claude_home_directory()
+    / "logs"
+    / "hooks"
+    / ".state"
+    / "offsets.json"
+)
+OFFLINE_WARNING_LOG: str = str(
+    _resolve_claude_home_directory() / "logs" / "hook-extractor.log"
+)
+PROJECTS_TRANSCRIPT_ROOT: str = str(_resolve_claude_home_directory() / "projects")
+
+NEON_DATABASE_URL_ENVIRONMENT_VARIABLE: str = "NEON_HOOK_LOGS_DATABASE_URL"
+
+ATTACHMENT_TYPE_PREFIX: str = "hook_"
+TOP_LEVEL_ATTACHMENT_TYPE: str = "attachment"
+
+ATTACHMENT_TYPE_HOOK_SUCCESS: str = "hook_success"
+ATTACHMENT_TYPE_HOOK_BLOCKING_ERROR: str = "hook_blocking_error"
+ATTACHMENT_TYPE_HOOK_SYSTEM_MESSAGE: str = "hook_system_message"
+ATTACHMENT_TYPE_HOOK_ADDITIONAL_CONTEXT: str = "hook_additional_context"
+
+OUTCOME_SUCCESS: str = "success"
+OUTCOME_BLOCKED: str = "blocked"
+OUTCOME_NON_BLOCKING_ERROR: str = "non_blocking_error"
+OUTCOME_SYSTEM_MESSAGE: str = "system_message"
+OUTCOME_ADDED_CONTEXT: str = "added_context"
+OUTCOME_INIT_PROBE: str = "init_probe"
+
+OUTCOME_BY_ATTACHMENT_TYPE: dict[str, str] = {
+    ATTACHMENT_TYPE_HOOK_SUCCESS: OUTCOME_SUCCESS,
+    ATTACHMENT_TYPE_HOOK_BLOCKING_ERROR: OUTCOME_BLOCKED,
+    "hook_non_blocking_error": OUTCOME_NON_BLOCKING_ERROR,
+    ATTACHMENT_TYPE_HOOK_SYSTEM_MESSAGE: OUTCOME_SYSTEM_MESSAGE,
+    ATTACHMENT_TYPE_HOOK_ADDITIONAL_CONTEXT: OUTCOME_ADDED_CONTEXT,
+}
+
+HOOK_CATEGORY_UNCATEGORIZED: str = "uncategorized"
+
+KNOWN_HOOK_CATEGORIES: frozenset[str] = frozenset(
+    {
+        "advisory",
+        "blocking",
+        "config",
+        "context",
+        "diagnostic",
+        "git-hooks",
+        "github-action",
+        "lifecycle",
+        "notification",
+        "session",
+        "system",
+        "validation",
+        "validators",
+        "workflow",
+        "worktree",
+    },
+)
+
+HOOK_NAME_TOOL_SEPARATOR: str = ":"
+
+SCHEMA_RELATIVE_PATH: str = "schema.sql"
+QUERIES_DIRECTORY_NAME: str = "queries"
+SQL_FILE_EXTENSION: str = ".sql"
+
+DEFAULT_QUERY_FOR_SUMMARY: str = "top_blockers_last_24_hours"
+
+JSONL_FILE_GLOB: str = "*.jsonl"
+
+FLAG_INCREMENTAL: str = "--incremental"
+FLAG_FULL_REBUILD: str = "--full-rebuild"
+FLAG_SUMMARY: str = "--summary"
+FLAG_QUERY: str = "--query"
+
+EXIT_CODE_SUCCESS: int = 0
+EXIT_CODE_ENVIRONMENT_MISSING: int = 1
+EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING: int = 0
+EXIT_CODE_UNKNOWN_QUERY: int = 2
+
+QUERY_NAME_PATTERN: str = r"[a-z0-9_]+"
+
+SENTINEL_SESSION_ID: str = "__init_probe_session__"
+SENTINEL_HOOK_EVENT: str = "InitProbe"
+SENTINEL_HOOK_NAME: str = "init_probe"
+SENTINEL_SOURCE_PATH: str = "__init_probe__"
+SENTINEL_SOURCE_LINE_NUMBER: int = 0
+
+SUMMARY_COLUMN_HEADINGS: tuple[str, str, str, str] = (
+    "hook_name",
+    "hook_category",
+    "block_count_last_24_hours",
+    "top_blocked_command_preview",
+)
+
+SUMMARY_NO_NEW_BLOCKS_MESSAGE: str = "No new blocks since last run."
+
+QUERY_NO_ROWS_RETURNED_MESSAGE: str = "No rows returned."
+
+TOP_BLOCKED_COMMAND_PREVIEW_MAX_CHARACTERS: int = 80
+
+HOOK_EVENTS_TABLE_NAME: str = "hook_events"
+
+HOOK_EVENTS_INSERT_SQL: str = (
+    "INSERT INTO hook_events ("
+    "event_timestamp, session_id, cwd, git_branch, hook_event, hook_name, "
+    "hook_category, script_path, tool_name, tool_use_id, outcome, exit_code, "
+    "duration_ms, command_excerpt, stdout_excerpt, stderr_excerpt, "
+    "source_jsonl_path, source_line_number"
+    ") VALUES ("
+    "%(event_timestamp)s, %(session_id)s, %(cwd)s, %(git_branch)s, "
+    "%(hook_event)s, %(hook_name)s, %(hook_category)s, %(script_path)s, "
+    "%(tool_name)s, %(tool_use_id)s, %(outcome)s, %(exit_code)s, "
+    "%(duration_ms)s, %(command_excerpt)s, %(stdout_excerpt)s, "
+    "%(stderr_excerpt)s, %(source_jsonl_path)s, %(source_line_number)s"
+    ") ON CONFLICT (source_jsonl_path, source_line_number) DO NOTHING"
+)
+
+HOOK_EVENTS_TRUNCATE_SQL: str = "TRUNCATE TABLE hook_events RESTART IDENTITY"
+
+HOOK_EVENTS_ROW_COUNT_SQL: str = "SELECT COUNT(*) FROM hook_events"
+
+SENTINEL_INSERT_SQL: str = (
+    "INSERT INTO hook_events ("
+    "event_timestamp, session_id, hook_event, hook_name, hook_category, "
+    "outcome, source_jsonl_path, source_line_number"
+    ") VALUES (NOW(), %s, %s, %s, %s, %s, %s, %s) RETURNING id"
+)
+
+SENTINEL_SELECT_SQL: str = "SELECT id FROM hook_events WHERE id = %s"
+
+SENTINEL_DELETE_SQL: str = "DELETE FROM hook_events WHERE id = %s"
+
+TOP_BLOCKERS_LAST_24_HOURS_SQL: str = (
+    "SELECT hook_name, hook_category, COUNT(*) AS block_count, "
+    "MIN(COALESCE(command_excerpt, stdout_excerpt, stderr_excerpt, '')) "
+    "AS top_blocked_command_preview "
+    "FROM hook_events WHERE outcome = 'blocked' "
+    "AND event_timestamp >= (NOW() - INTERVAL '1 day') "
+    "GROUP BY hook_name, hook_category "
+    "ORDER BY block_count DESC LIMIT 10"
+)
+
+EMPTY_STRING: str = ""
+NEWLINE_JOINER: str = "\n"
+SEMICOLON_SPLIT_TOKEN: str = ";"
+
+HOOKS_DIRECTORY_TOKEN: str = "/hooks/"
+
+SCRIPT_PATH_PYTHON_PREFIXES: tuple[str, ...] = ("python3 ", "python ")
+
+SUMMARY_TABLE_COLUMN_GAP: str = "  "
+
+CATEGORY_PATH_MINIMUM_PARTS: int = 2
+OFFSETS_JSON_INDENT: int = 2
+
+MISSING_ENVIRONMENT_VARIABLE_PREFIX: str = "Missing required environment variable: "
+SUCCESS_REPORT_HEADER: str = "Hook-log init succeeded."
+NEON_HOST_REPORT_LABEL: str = "Neon host:"
+TABLE_REPORT_LABEL: str = "Table:"
+ROW_COUNT_REPORT_LABEL: str = "Row count:"
+UNKNOWN_HOST_PLACEHOLDER: str = "unknown"
+SENTINEL_HOOK_CATEGORY: str = "diagnostic"
+
+MISSING_PSYCOPG_WARNING_LABEL: str = "missing_psycopg"
+MISSING_NEON_DATABASE_URL_WARNING_LABEL: str = "missing_neon_database_url"
+LEGACY_OFFSETS_FORMAT_WARNING_LABEL: str = "legacy_offsets_format"
+
+SENTINEL_SELECT_FAILURE_MESSAGE: str = (
+    "Sentinel SELECT did not return the inserted id; round-trip failed."
+)
+
+SENTINEL_INSERT_FAILURE_MESSAGE: str = (
+    "Sentinel INSERT did not return a row; round-trip failed."
+)
+
+BYTE_OFFSET_KEY: str = "byte_offset"
+LINE_NUMBER_KEY: str = "line_number"
+
+UNKNOWN_QUERY_MESSAGE_PREFIX: str = "Unknown query: "
+INVALID_QUERY_NAME_MESSAGE_PREFIX: str = "Invalid query name: "
+
+BWS_EXECUTABLE_NAME: str = "bws"
+BWS_ACCESS_TOKEN_ENV_VAR: str = "BWS_ACCESS_TOKEN"
+BWS_RUN_SEPARATOR: str = "--"
+BWS_RUN_SUBCOMMAND: str = "run"
+STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME: str = "hook_log_extractor.py"
+
+STOP_WRAPPER_DEBOUNCE_SECONDS: int = 60
+STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE: str = str(
+    _resolve_claude_home_directory()
+    / "logs"
+    / "hooks"
+    / ".state"
+    / "stop_wrapper_last_run.txt"
+)
+
+WINDOWS_OS_NAME: str = "nt"
+WINDOWS_DETACHED_PROCESS_FLAG: int = 0x00000008
+WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG: int = 0x00000200
+
+LOCK_MAXIMUM_RETRY_COUNT: int = 30
+LOCK_RETRY_SLEEP_SECONDS: float = 0.1
+

package/hooks/config/messages.py

@@ -2,3 +2,6 @@
 
 USER_FACING_NOTICE = "Agent was found guessing - sourcing opinions..."
 USER_FACING_TDD_NOTICE = "TDD gate held - writing the failing test first..."
+USER_FACING_ASKUSERQUESTION_NOTICE = (
+    "Agent asked the user in prose - rerouting through AskUserQuestion..."
+)

package/hooks/config/session_env_cleanup_constants.py

@@ -0,0 +1,18 @@
+"""Configuration constants for the session_env_cleanup SessionStart hook."""
+
+from __future__ import annotations
+
+import os
+import re
+
+SESSION_ENV_DIRECTORY = os.path.join(os.path.expanduser("~"), ".claude", "session-env")
+
+SECONDS_PER_DAY = 24 * 60 * 60
+STALE_AGE_DAYS = 7
+STALE_AGE_SECONDS = STALE_AGE_DAYS * SECONDS_PER_DAY
+
+RMTREE_ONEXC_PYTHON_VERSION = (3, 12)
+
+SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+WINDOWS_PLATFORM_TAG = "win32"

package/hooks/config/test_hook_log_extractor_constants.py

@@ -0,0 +1,123 @@
+"""Behavior tests for query-name pattern and exit-code routing contracts."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from config import hook_log_extractor_constants
+from config.hook_log_extractor_constants import (
+    EXIT_CODE_ENVIRONMENT_MISSING,
+    EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING,
+    EXIT_CODE_SUCCESS,
+    EXIT_CODE_UNKNOWN_QUERY,
+    LOCK_MAXIMUM_RETRY_COUNT,
+    LOCK_RETRY_SLEEP_SECONDS,
+    QUERY_NAME_PATTERN,
+    SENTINEL_INSERT_FAILURE_MESSAGE,
+    SENTINEL_SELECT_FAILURE_MESSAGE,
+    STOP_WRAPPER_DEBOUNCE_SECONDS,
+    STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
+    WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
+    WINDOWS_DETACHED_PROCESS_FLAG,
+)
+
+
+def _matches_query_pattern(candidate_name: str) -> bool:
+    return re.fullmatch(QUERY_NAME_PATTERN, candidate_name) is not None
+
+
+def test_query_name_pattern_allows_canonical_pre_baked_query_name() -> None:
+    assert _matches_query_pattern("top_blockers_last_24_hours")
+
+
+def test_query_name_pattern_rejects_path_traversal() -> None:
+    assert not _matches_query_pattern("../etc/passwd")
+
+
+def test_query_name_pattern_rejects_uppercase() -> None:
+    assert not _matches_query_pattern("TopBlockers")
+
+
+def test_query_name_pattern_rejects_hyphens() -> None:
+    assert not _matches_query_pattern("top-blockers")
+
+
+def test_query_name_pattern_rejects_empty_string() -> None:
+    assert not _matches_query_pattern("")
+
+
+def test_unknown_query_exit_code_distinguishes_from_success() -> None:
+    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_SUCCESS
+
+
+def test_unknown_query_exit_code_distinguishes_from_extractor_offline_fallback() -> None:
+    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING
+
+
+def test_unknown_query_exit_code_distinguishes_from_init_environment_missing() -> None:
+    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_ENVIRONMENT_MISSING
+
+
+def test_extractor_offline_fallback_matches_success_so_stop_hook_does_not_surface_failure() -> None:
+    assert EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING == EXIT_CODE_SUCCESS
+
+
+def test_sentinel_insert_failure_message_is_distinct_from_select_failure() -> None:
+    assert SENTINEL_INSERT_FAILURE_MESSAGE != SENTINEL_SELECT_FAILURE_MESSAGE
+    assert SENTINEL_INSERT_FAILURE_MESSAGE
+
+
+def test_resolver_falls_back_to_home_when_claude_home_is_empty(
+    monkeypatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_HOME", "")
+
+    assert (
+        hook_log_extractor_constants._resolve_claude_home_directory()
+        == Path.home() / ".claude"
+    )
+
+
+def test_resolver_falls_back_to_home_when_claude_home_is_whitespace(
+    monkeypatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_HOME", "   ")
+
+    assert (
+        hook_log_extractor_constants._resolve_claude_home_directory()
+        == Path.home() / ".claude"
+    )
+
+
+def test_lock_retry_constants_are_positive_and_bounded() -> None:
+    assert LOCK_MAXIMUM_RETRY_COUNT > 0
+    assert LOCK_RETRY_SLEEP_SECONDS > 0
+
+
+def test_stop_wrapper_debounce_seconds_is_positive() -> None:
+    assert STOP_WRAPPER_DEBOUNCE_SECONDS > 0
+
+
+def test_stop_wrapper_last_run_timestamp_file_is_under_claude_home() -> None:
+    expected_path = (
+        hook_log_extractor_constants._resolve_claude_home_directory()
+        / "logs"
+        / "hooks"
+        / ".state"
+        / "stop_wrapper_last_run.txt"
+    )
+    assert Path(STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE) == expected_path
+
+
+def test_windows_creation_flags_are_distinct_nonzero_bits() -> None:
+    assert WINDOWS_DETACHED_PROCESS_FLAG > 0
+    assert WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG > 0
+    assert (
+        WINDOWS_DETACHED_PROCESS_FLAG & WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
+    ) == 0

package/hooks/config/test_messages.py

@@ -15,3 +15,8 @@ def test_user_facing_notice_is_nonempty_string() -> None:
 def test_user_facing_tdd_notice_is_nonempty_string() -> None:
     assert isinstance(messages.USER_FACING_TDD_NOTICE, str)
     assert messages.USER_FACING_TDD_NOTICE
+
+
+def test_user_facing_askuserquestion_notice_is_nonempty_string() -> None:
+    assert isinstance(messages.USER_FACING_ASKUSERQUESTION_NOTICE, str)
+    assert messages.USER_FACING_ASKUSERQUESTION_NOTICE