claude-dev-env 1.73.0 → 1.74.0

package/hooks/hooks_constants/docstring_rule_gate_count_blocker_constants.py

@@ -0,0 +1,90 @@
+"""Constants for the docstring-rule gate-count staleness blocker.
+
+The rule file ``docstring-prose-matches-implementation.md`` enumerates the
+``check_docstring_*`` gate validators that cover deterministic slices of docstring
+prose, both as a spelled-out count ("Three more gate validators", "four gated
+slices") and as a backticked list of the validator names. When a new gate
+validator is registered but the count word is left unchanged, the rule's stated
+count drifts from the validators it actually names — the same companion-doc drift
+the rule itself governs. This module holds the target rule basename, the
+spelled-out-number lookup, the code-fence pattern that marks lines to skip, the
+patterns that find the "<count> more gate validators" and "<count> gated slices"
+count clauses and the backticked ``check_*`` validator names, the args-gate name,
+the issue budget, and the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "TARGET_RULE_BASENAME",
+    "ALL_NUMBER_WORDS_BY_VALUE",
+    "CODE_FENCE_PATTERN",
+    "FREE_FORM_GATE_COUNT_PATTERN",
+    "TOTAL_GATED_SLICE_COUNT_PATTERN",
+    "GATE_VALIDATOR_NAME_PATTERN",
+    "ARGS_GATE_VALIDATOR_NAME",
+    "MAX_GATE_COUNT_ISSUES",
+    "GATE_COUNT_MESSAGE_TEMPLATE",
+    "GATE_COUNT_SYSTEM_MESSAGE",
+    "GATE_COUNT_ADDITIONAL_CONTEXT",
+]
+
+TARGET_RULE_BASENAME: str = "docstring-prose-matches-implementation.md"
+
+ALL_NUMBER_WORDS_BY_VALUE: dict[str, int] = {
+    "zero": 0,
+    "one": 1,
+    "two": 2,
+    "three": 3,
+    "four": 4,
+    "five": 5,
+    "six": 6,
+    "seven": 7,
+    "eight": 8,
+    "nine": 9,
+    "ten": 10,
+}
+
+CODE_FENCE_PATTERN: re.Pattern[str] = re.compile(r"^\s*(?:```|~~~)")
+
+FREE_FORM_GATE_COUNT_PATTERN: re.Pattern[str] = re.compile(
+    r"\b([A-Za-z]+)\s+more\s+gate\s+validators\b",
+    re.IGNORECASE,
+)
+
+TOTAL_GATED_SLICE_COUNT_PATTERN: re.Pattern[str] = re.compile(
+    r"\b([A-Za-z]+)\s+gated\s+slices\b",
+    re.IGNORECASE,
+)
+
+GATE_VALIDATOR_NAME_PATTERN: re.Pattern[str] = re.compile(r"`(check_[A-Za-z0-9_]+)`")
+
+ARGS_GATE_VALIDATOR_NAME: str = "check_docstring_args_match_signature"
+
+MAX_GATE_COUNT_ISSUES: int = 4
+
+GATE_COUNT_MESSAGE_TEMPLATE: str = (
+    "{rule_basename} states '{stated_phrase}' ({stated_count}) but names "
+    "{named_count} distinct free-form gate validator(s) ({named_validators}). The "
+    "rule's spelled-out gate count drifts from the validators it enumerates — the "
+    "companion-doc-vs-implementation drift this rule governs. Update the count "
+    "word to {named_count} and the '... gated slices' total to {total_count} in "
+    "this same change, and name every gate validator the prose counts."
+)
+
+GATE_COUNT_SYSTEM_MESSAGE: str = (
+    "Gate-validator count in docstring-prose-matches-implementation.md drifted "
+    "from the validators it names - update the count word in this same change"
+)
+
+GATE_COUNT_ADDITIONAL_CONTEXT: str = (
+    "The rule docstring-prose-matches-implementation.md states a spelled-out "
+    "count of free-form docstring gate validators ('Four more gate validators') "
+    "and a total ('five gated slices'), then names each validator in backticks "
+    "(`check_docstring_fallback_branch_coverage`, ...). When a new "
+    "`check_docstring_*` gate is added, name it in the prose and bump both count "
+    "words: the 'N more gate validators' count equals the number of distinct "
+    "free-form validators named after it, and the 'M gated slices' total equals "
+    "that count plus one for check_docstring_args_match_signature. Keep the count "
+    "words and the named-validator list in step in the same change."
+)

package/hooks/hooks_constants/hook_block_logger.py

@@ -0,0 +1,59 @@
+"""Shared fail-safe logger for hook block events.
+
+Every blocking hook calls log_hook_block at the moment it decides to block,
+so the user has a single log showing what tripped and why.
+"""
+
+import datetime
+import json
+from pathlib import Path
+
+_HOOK_BLOCKS_LOG_RELATIVE_PATH = ".claude/logs/hook-blocks.log"
+_MAX_PREVIEW_LENGTH = 500
+
+
+def log_hook_block(
+    calling_hook_name: str,
+    hook_event: str,
+    block_reason: str,
+    tool_name: str | None = None,
+    offending_input_preview: str | None = None,
+) -> None:
+    """Append one JSON record to the hook-blocks log for a block decision.
+
+    Creates the logs directory if absent. Skips logging when the home directory
+    cannot be resolved, and silently swallows all IO errors otherwise, so a
+    logging failure never changes a hook's decision.
+
+    Args:
+        calling_hook_name: The script basename of the hook that is blocking.
+        hook_event: The hook event type, e.g. ``PreToolUse`` or ``Stop``.
+        block_reason: The human-readable reason the hook is blocking.
+        tool_name: The Claude tool name when available, e.g. ``Bash``.
+        offending_input_preview: A short excerpt of the input that triggered
+            the block; truncated to 500 characters before writing.
+    """
+    try:
+        home_directory = Path.home()
+    except RuntimeError:
+        return
+
+    try:
+        log_path = home_directory / _HOOK_BLOCKS_LOG_RELATIVE_PATH
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        log_record: dict[str, str] = {
+            "timestamp": datetime.datetime.now().isoformat(),
+            "hook": calling_hook_name,
+            "event": hook_event,
+            "reason": block_reason,
+        }
+        if tool_name is not None:
+            log_record["tool"] = tool_name
+        if offending_input_preview is not None:
+            log_record["preview"] = offending_input_preview[:_MAX_PREVIEW_LENGTH]
+
+        with log_path.open("a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(log_record) + "\n")
+    except OSError:
+        pass

package/hooks/hooks_constants/multi_edit_reconstruction.py

@@ -0,0 +1,56 @@
+"""Shared helpers that reconstruct the post-edit content of an Edit or MultiEdit.
+
+Several PreToolUse blockers judge the content a write would leave on disk rather
+than the raw payload fragment, so an edit on a line the blocker watches still
+participates even when an untouched line elsewhere supplies the context. Both the
+edit-replacement applier and the edit-list extractor are identical across those
+blockers, so they live here once and are imported from each.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "apply_edits",
+    "edits_for_tool",
+]
+
+
+def apply_edits(existing_content: str, all_edits: list[dict]) -> str:
+    """Return *existing_content* with each Edit/MultiEdit replacement applied in order.
+
+    Args:
+        existing_content: The current on-disk file content.
+        all_edits: The Edit payload (as a single-element list) or MultiEdit
+            ``edits`` list, each a mapping with an ``old_string`` and a
+            ``new_string``.
+
+    Returns:
+        The content after replacing the first occurrence of each edit's
+        ``old_string`` with its ``new_string``, in list order.
+    """
+    edited_content = existing_content
+    for each_edit in all_edits:
+        if not isinstance(each_edit, dict):
+            continue
+        old_string = each_edit.get("old_string", "")
+        new_string = each_edit.get("new_string", "")
+        if isinstance(old_string, str) and isinstance(new_string, str) and old_string:
+            edited_content = edited_content.replace(old_string, new_string, 1)
+    return edited_content
+
+
+def edits_for_tool(tool_name: str, tool_input: dict) -> list[dict]:
+    """Return the edit mappings an Edit or MultiEdit payload carries.
+
+    Args:
+        tool_name: The intercepted tool — ``Edit`` or ``MultiEdit``.
+        tool_input: The tool's input payload.
+
+    Returns:
+        A single-element list holding the Edit payload, or the MultiEdit
+        ``edits`` list when it is present as a list; an empty list otherwise.
+    """
+    if tool_name == "Edit":
+        return [tool_input]
+    all_edits = tool_input.get("edits", [])
+    return all_edits if isinstance(all_edits, list) else []

package/hooks/hooks_constants/package_inventory_stale_blocker_constants.py

@@ -0,0 +1,111 @@
+"""Constants for the package-inventory stale-entry blocker.
+
+A package directory documents its own files in a sibling inventory document —
+a ``README.md`` Layout table or a ``CLAUDE.md`` "Key files" list — whose entries
+name each file in backticks. When a new production code file lands in that
+directory and the inventory carries no entry naming it, the inventory disagrees
+with the directory on the package's file set, and a reader trusting the
+inventory to map the directory misses the new file. This module holds the
+inventory document names, the production code extensions that earn an inventory
+entry, the backtick pattern that finds an inventory's named files, the code-fence
+pattern that marks lines to skip, the glob-metacharacter pattern that rejects
+pattern tokens, the non-filename pattern that rejects command-example and
+path-bearing prose spans, the minimum inventory size that marks a document as a
+maintained inventory, the filenames exempt from an entry, the scan budget, and
+the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "ALL_INVENTORY_DOCUMENT_NAMES",
+    "ALL_PRODUCTION_CODE_EXTENSIONS",
+    "PYTHON_FILE_EXTENSION",
+    "ALL_TEST_FILE_MARKERS",
+    "BACKTICK_TOKEN_PATTERN",
+    "CODE_FENCE_PATTERN",
+    "GLOB_METACHARACTER_PATTERN",
+    "NON_FILENAME_TOKEN_PATTERN",
+    "MINIMUM_INVENTORY_ENTRY_COUNT",
+    "ALL_EXEMPT_BASENAMES",
+    "ALL_EXEMPT_DIRECTORY_NAMES",
+    "MAX_INVENTORY_FILE_BYTES",
+    "STALE_INVENTORY_MESSAGE_TEMPLATE",
+    "STALE_INVENTORY_SYSTEM_MESSAGE",
+    "STALE_INVENTORY_ADDITIONAL_CONTEXT",
+]
+
+ALL_INVENTORY_DOCUMENT_NAMES: frozenset[str] = frozenset({"README.md", "CLAUDE.md"})
+
+PYTHON_FILE_EXTENSION: str = ".py"
+
+ALL_TEST_FILE_MARKERS: tuple[str, ...] = (".spec.", ".test.")
+
+ALL_PRODUCTION_CODE_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".py",
+        ".mjs",
+        ".js",
+        ".ts",
+        ".ps1",
+        ".sh",
+    }
+)
+
+BACKTICK_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"`([^`]+)`")
+
+CODE_FENCE_PATTERN: re.Pattern[str] = re.compile(r"^\s*(?:```|~~~)")
+
+GLOB_METACHARACTER_PATTERN: re.Pattern[str] = re.compile(r"[*?{}\[\]]")
+
+NON_FILENAME_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"[\s:$<>]")
+
+MINIMUM_INVENTORY_ENTRY_COUNT: int = 2
+
+ALL_EXEMPT_BASENAMES: frozenset[str] = frozenset(
+    {
+        "__init__.py",
+        "conftest.py",
+        "setup.py",
+        "_path_setup.py",
+    }
+)
+
+ALL_EXEMPT_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        "config",
+        "tests",
+        "__pycache__",
+        ".git",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
+MAX_INVENTORY_FILE_BYTES: int = 200_000
+
+STALE_INVENTORY_MESSAGE_TEMPLATE: str = (
+    "New production file `{filename}` lands in {directory}, whose inventory "
+    "document(s) ({inventories}) name {entry_count} sibling files but no entry "
+    "for `{filename}`. A package inventory names every production file in its "
+    "directory; a new file the inventory omits leaves the inventory and the "
+    "directory disagreeing on the package's file set. Add an entry naming "
+    "`{filename}` to the inventory in this same change."
+)
+
+STALE_INVENTORY_SYSTEM_MESSAGE: str = (
+    "New production file is absent from its package inventory (README.md / "
+    "CLAUDE.md) - add the inventory entry in this same change"
+)
+
+STALE_INVENTORY_ADDITIONAL_CONTEXT: str = (
+    "A package directory whose README.md or CLAUDE.md lists its files in "
+    "backticks is a maintained inventory of the package's file set. A new "
+    "production code file (.py, .mjs, .js, .ts, .ps1, .sh) in that directory "
+    "carries one inventory entry naming it. Add a row to the README.md table or "
+    "a bullet to the CLAUDE.md list naming this file, describing what it does, "
+    "in the same change that creates the file. Exempt files (no entry needed): "
+    "__init__.py, conftest.py, setup.py, _path_setup.py, files under config/ or "
+    "tests/, and test files (test_*.py, *_test.py, *.spec.*, *.test.*)."
+)

package/hooks/hooks_constants/post_tool_use_dispatcher_constants.py

@@ -2,8 +2,7 @@
 
 Holds the ordered hosted-hook list with each hook's extra command-line
 arguments and blocking flag, the PostToolUse block-decision string and key,
-and the hook-event name. The dispatcher imports these; no literals appear
-inline in the dispatcher script.
+and the hook-event name. The dispatcher imports each of these by name.
 """
 
 from __future__ import annotations

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -2,7 +2,7 @@
 
 Holds the ordered hosted-hook list with per-hook applicable-tool sets, the
 special exit codes, the deny decision string, and the hook-event name. The
-dispatcher imports these; no literals appear inline in the dispatcher script.
+dispatcher imports each of these by name.
 """
 
 from __future__ import annotations
@@ -119,6 +119,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/claude_md_orphan_file_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/package_inventory_stale_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
     HostedHookEntry(
         script_relative_path="blocking/pytest_testpaths_orphan_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
@@ -127,6 +131,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/open_questions_in_plans_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/docstring_rule_gate_count_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
     HostedHookEntry(
         script_relative_path="blocking/plain_language_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,

package/hooks/hooks_constants/send_user_file_open_locally_blocker_constants.py

@@ -0,0 +1,18 @@
+"""Configuration constants for the send_user_file_open_locally_blocker PreToolUse hook."""
+
+TOOL_NAME: str = "SendUserFile"
+
+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 in its own viewer:\n"
+    "  Start-Process pwsh -WindowStyle Hidden -ArgumentList "
+    "'-NoProfile','-File',\"$HOME\\.claude\\scripts\\Show-Asset.ps1\","
+    "'<path 1>','<path 2>'\n"
+    "Show-Asset.ps1 sizes each image window to the image and opens every other file "
+    "type in its default app. Pass every path the user named.\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_dispatcher_constants_docstrings.py

@@ -0,0 +1,44 @@
+"""Regression tests proving the dispatcher constants docstrings clear the O6 gate.
+
+The PreToolUse and PostToolUse dispatcher constants modules each carry a module
+docstring stating what the module centralizes. Neither docstring may assert that
+no literals appear inline in its companion dispatcher script — that completeness
+claim about a sibling file is the deterministic Category O6 drift the enforcer's
+check_docstring_no_inline_literal_claim blocks. These tests load the real
+modules' source and assert the check returns no issues for either.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    enforcer_path = Path(__file__).resolve().parent.parent / "blocking" / "code_rules_enforcer.py"
+    enforcer_spec = importlib.util.spec_from_file_location("code_rules_enforcer", enforcer_path)
+    assert enforcer_spec is not None
+    assert enforcer_spec.loader is not None
+    enforcer_module = importlib.util.module_from_spec(enforcer_spec)
+    enforcer_spec.loader.exec_module(enforcer_module)
+    return enforcer_module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def _check_issues_for(module_filename: str) -> list[str]:
+    module_path = Path(__file__).resolve().parent / module_filename
+    module_source = module_path.read_text(encoding="utf-8")
+    return code_rules_enforcer.check_docstring_no_inline_literal_claim(
+        module_source, str(module_path)
+    )
+
+
+def test_pre_tool_use_dispatcher_constants_docstring_clears_o6_gate() -> None:
+    assert _check_issues_for("pre_tool_use_dispatcher_constants.py") == []
+
+
+def test_post_tool_use_dispatcher_constants_docstring_clears_o6_gate() -> None:
+    assert _check_issues_for("post_tool_use_dispatcher_constants.py") == []

package/hooks/hooks_constants/test_hook_block_logger.py

@@ -0,0 +1,159 @@
+"""Tests for the shared hook block logger."""
+
+from __future__ import annotations
+
+import datetime
+import json
+import stat
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+
+
+def test_log_hook_block_writes_parseable_json_line(tmp_path: Path) -> None:
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="test_hook.py",
+            hook_event="PreToolUse",
+            block_reason="test block reason",
+            tool_name="Bash",
+            offending_input_preview="echo hello",
+        )
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    assert log_path.exists()
+    line = log_path.read_text(encoding="utf-8").strip()
+    parsed = json.loads(line)
+
+    assert "timestamp" in parsed
+    assert parsed["hook"] == "test_hook.py"
+    assert parsed["event"] == "PreToolUse"
+    assert parsed["tool"] == "Bash"
+    assert parsed["reason"] == "test block reason"
+    assert parsed["preview"] == "echo hello"
+
+
+def test_log_hook_block_creates_logs_directory(tmp_path: Path) -> None:
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="some_hook.py",
+            hook_event="Stop",
+            block_reason="stop reason",
+        )
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    assert log_path.exists()
+
+
+def test_log_hook_block_omits_none_fields(tmp_path: Path) -> None:
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="minimal_hook.py",
+            hook_event="PreToolUse",
+            block_reason="some reason",
+        )
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    line = log_path.read_text(encoding="utf-8").strip()
+    parsed = json.loads(line)
+    assert "tool" not in parsed
+    assert "preview" not in parsed
+
+
+def test_log_hook_block_appends_multiple_records(tmp_path: Path) -> None:
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="hook_a.py",
+            hook_event="PreToolUse",
+            block_reason="first",
+        )
+        log_hook_block(
+            calling_hook_name="hook_b.py",
+            hook_event="Stop",
+            block_reason="second",
+        )
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    all_lines = log_path.read_text(encoding="utf-8").strip().splitlines()
+    assert len(all_lines) == 2
+    first_parsed = json.loads(all_lines[0])
+    second_parsed = json.loads(all_lines[1])
+    assert first_parsed["hook"] == "hook_a.py"
+    assert second_parsed["hook"] == "hook_b.py"
+
+
+def test_log_hook_block_swallows_io_error_on_unwritable_log(tmp_path: Path) -> None:
+    logs_dir = tmp_path / ".claude" / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    log_path = logs_dir / "hook-blocks.log"
+    log_path.write_text("", encoding="utf-8")
+    log_path.chmod(stat.S_IREAD)
+
+    try:
+        with patch.object(Path, "home", return_value=tmp_path):
+            log_hook_block(
+                calling_hook_name="any_hook.py",
+                hook_event="PreToolUse",
+                block_reason="reason",
+            )
+    except OSError:
+        pytest.fail("log_hook_block raised OSError on unwritable log file")
+    finally:
+        log_path.chmod(stat.S_IREAD | stat.S_IWRITE)
+
+
+def test_log_hook_block_swallows_runtime_error_when_home_unresolvable() -> None:
+    def raise_home_resolution_failure() -> Path:
+        raise RuntimeError("Could not determine home directory.")
+
+    with patch.object(Path, "home", side_effect=raise_home_resolution_failure):
+        try:
+            returned_nothing = log_hook_block(
+                calling_hook_name="any_hook.py",
+                hook_event="PreToolUse",
+                block_reason="reason",
+            )
+        except RuntimeError:
+            pytest.fail("log_hook_block raised RuntimeError when home was unresolvable")
+
+    assert returned_nothing is None
+
+
+def test_log_hook_block_truncates_long_preview(tmp_path: Path) -> None:
+    long_input = "x" * 600
+
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="hook.py",
+            hook_event="PreToolUse",
+            block_reason="reason",
+            offending_input_preview=long_input,
+        )
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    line = log_path.read_text(encoding="utf-8").strip()
+    parsed = json.loads(line)
+    assert len(parsed["preview"]) <= 500
+
+
+def test_log_hook_block_timestamp_is_iso8601(tmp_path: Path) -> None:
+    before = datetime.datetime.now()
+    with patch.object(Path, "home", return_value=tmp_path):
+        log_hook_block(
+            calling_hook_name="ts_hook.py",
+            hook_event="PreToolUse",
+            block_reason="ts test",
+        )
+    after = datetime.datetime.now()
+
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    line = log_path.read_text(encoding="utf-8").strip()
+    parsed = json.loads(line)
+    parsed_timestamp = datetime.datetime.fromisoformat(parsed["timestamp"])
+    assert before <= parsed_timestamp <= after

package/hooks/lifecycle/config_change_guard.py

@@ -4,6 +4,13 @@ from datetime import datetime
 import json
 import os
 import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 AUDIT_LOG = os.path.expanduser("~/.claude/cache/config-change-audit.log")
 # pragma: no-tdd-gate
@@ -68,6 +75,11 @@ def guard_hook_injection(file_path: str) -> None:
             "decision": "block",
             "reason": block_reason,
         }
+        log_hook_block(
+            calling_hook_name="config_change_guard.py",
+            hook_event="ConfigChange",
+            block_reason=block_reason,
+        )
         print(json.dumps(block_payload))
         return
 

package/hooks/lifecycle/test_config_change_guard.py

@@ -109,3 +109,26 @@ def test_non_user_settings_source_produces_no_output(tmp_path: Path) -> None:
     assert hook_run.returncode == 0
     assert hook_run.stderr.strip() == ""
     assert hook_run.stdout.strip() == ""
+
+
+def test_block_logs_config_change_event(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("2")
+    settings_path = _make_settings_with_hook_count(5, tmp_path)
+
+    hook_run = _run_hook(
+        source="user_settings",
+        file_path=settings_path,
+        extra_env={
+            "KNOWN_HOOK_COUNT_FILE": str(known_count_file),
+            "HOME": str(fake_home),
+            "USERPROFILE": str(fake_home),
+        },
+    )
+
+    assert hook_run.returncode == 0
+    log_path = fake_home / ".claude" / "logs" / "hook-blocks.log"
+    logged_record = json.loads(log_path.read_text(encoding="utf-8").splitlines()[-1])
+    assert logged_record["event"] == "ConfigChange"

package/hooks/validation/hook_format_validator.py

@@ -7,7 +7,13 @@ Blocks if hooks use simple 'python3 ~/.claude/...' instead of the exec(open(...)
 import json
 import re
 import sys
+from pathlib import Path
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 SIMPLE_PATTERN = re.compile(
     r'python3?\s+~/\.claude/hooks/'
@@ -56,6 +62,13 @@ def main() -> None:
                 "permissionDecisionReason": message
             }
         }
+        log_hook_block(
+            calling_hook_name="hook_format_validator.py",
+            hook_event="PreToolUse",
+            block_reason=message,
+            tool_name=tool_name,
+            offending_input_preview=file_path,
+        )
         print(json.dumps(result))
         sys.exit(0)