claude-dev-env 1.72.0 → 1.74.0

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

@@ -0,0 +1,68 @@
+"""Constants for the PostToolUse dispatcher that hosts the after-write hooks.
+
+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 each of these by name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "BLOCK_DECISION",
+    "DECISION_KEY",
+    "REASON_KEY",
+    "HOOK_EVENT_NAME",
+    "EMPTY_REASON_BLOCK_FALLBACK",
+    "PLUGIN_ROOT_PLACEHOLDER",
+    "PostHostedHookEntry",
+    "ALL_POST_HOSTED_HOOK_ENTRIES",
+]
+
+BLOCK_DECISION = "block"
+DECISION_KEY = "decision"
+REASON_KEY = "reason"
+HOOK_EVENT_NAME = "PostToolUse"
+EMPTY_REASON_BLOCK_FALLBACK = "[dispatcher] hook blocked with no reason — write blocked"
+
+PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"
+
+
+@dataclass(frozen=True)
+class PostHostedHookEntry:
+    """A single hosted PostToolUse hook with its run-time arguments and flags.
+
+    Attributes:
+        script_relative_path: Hook path relative to the hooks/ directory.
+        extra_argument_relative_paths: Command-line arguments the live entry
+            passes after the script path, each a path relative to the plugin
+            root (the hooks/ parent). The dispatcher resolves each to an
+            absolute path and exposes them as the hook's argv tail, so a hook
+            that reads sys.argv[1] resolves the same path the live entry gives
+            it. An empty tuple means the live entry passes no extra arguments.
+        is_blocking: True when this hook can emit a block decision and a crash
+            should surface a blocking signal; False when the hook only performs
+            a side effect and never blocks.
+    """
+
+    script_relative_path: str
+    extra_argument_relative_paths: tuple[str, ...] = field(default_factory=tuple)
+    is_blocking: bool = field(default=False)
+
+
+ALL_POST_HOSTED_HOOK_ENTRIES: tuple[PostHostedHookEntry, ...] = (
+    PostHostedHookEntry(
+        script_relative_path="validation/mypy_validator.py",
+        is_blocking=True,
+    ),
+    PostHostedHookEntry(
+        script_relative_path="workflow/auto_formatter.py",
+        is_blocking=False,
+    ),
+    PostHostedHookEntry(
+        script_relative_path="workflow/doc_gist_auto_publish.py",
+        extra_argument_relative_paths=(PLUGIN_ROOT_PLACEHOLDER,),
+        is_blocking=False,
+    ),
+)

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -0,0 +1,143 @@
+"""Constants for the PreToolUse dispatcher that hosts Write/Edit/MultiEdit hooks.
+
+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 each of these by name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "DENY_DECISION",
+    "ALLOW_DECISION",
+    "HOOK_EVENT_NAME",
+    "BLOCKING_CRASH_EXIT_CODE",
+    "EXIT_CODE_TWO_DENY_REASON",
+    "WRITE_TOOL_NAME",
+    "EDIT_TOOL_NAME",
+    "MULTI_EDIT_TOOL_NAME",
+    "ALL_WRITE_AND_EDIT_TOOL_NAMES",
+    "ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES",
+    "STATE_DESCRIPTION_BLOCKER_MODULE_NAME",
+    "PLAIN_LANGUAGE_BLOCKER_MODULE_NAME",
+    "HostedHookEntry",
+    "ALL_HOSTED_HOOK_ENTRIES",
+]
+
+DENY_DECISION = "deny"
+ALLOW_DECISION = "allow"
+HOOK_EVENT_NAME = "PreToolUse"
+BLOCKING_CRASH_EXIT_CODE = 2
+EXIT_CODE_TWO_DENY_REASON = "[dispatcher] hook denied via exit code 2 — write blocked"
+
+WRITE_TOOL_NAME = "Write"
+EDIT_TOOL_NAME = "Edit"
+MULTI_EDIT_TOOL_NAME = "MultiEdit"
+
+ALL_WRITE_AND_EDIT_TOOL_NAMES: frozenset[str] = frozenset({WRITE_TOOL_NAME, EDIT_TOOL_NAME})
+ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES: frozenset[str] = frozenset(
+    {WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}
+)
+
+
+STATE_DESCRIPTION_BLOCKER_MODULE_NAME = "state_description_blocker"
+PLAIN_LANGUAGE_BLOCKER_MODULE_NAME = "plain_language_blocker"
+
+
+@dataclass(frozen=True)
+class HostedHookEntry:
+    """A single hosted hook with its applicable-tools constraint and blocking flag.
+
+    Attributes:
+        script_relative_path: Hook path relative to the hooks/ directory.
+        applicable_tool_names: Tool names this hook applies to. The dispatcher
+            skips the hook when the payload's tool is not in this set.
+        is_blocking: True when a crash surfaces a blocking signal; False when the
+            hook is advisory and a crash stays silent.
+        native_module_name: The importable module name whose evaluate function
+            the dispatcher calls in-process for this hook, or None when the hook
+            runs via runpy under __main__. The named module exposes a function
+            named NATIVE_EVALUATE_FUNCTION_NAME taking the payload dict and
+            returning a deny-reason string or None.
+    """
+
+    script_relative_path: str
+    applicable_tool_names: frozenset[str]
+    is_blocking: bool = field(default=True)
+    native_module_name: str | None = field(default=None)
+
+
+ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
+    HostedHookEntry(
+        script_relative_path="blocking/write_existing_file_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/sensitive_file_protector.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="validation/hook_format_validator.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/code_rules_enforcer.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/tdd_enforcer.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/windows_rmtree_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/state_description_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+        native_module_name=STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/subprocess_budget_completeness.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/hook_prose_detector_consistency.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/verified_commit_message_accuracy_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/workflow_substitution_slot_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
+    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,
+    ),
+    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,
+        native_module_name=PLAIN_LANGUAGE_BLOCKER_MODULE_NAME,
+    ),
+)

package/hooks/hooks_constants/pytest_testpaths_orphan_blocker_constants.py

@@ -0,0 +1,79 @@
+"""Constants for the pytest unregistered-test-directory blocker.
+
+A package whose ``pyproject.toml`` declares ``[tool.pytest.ini_options]`` with an
+explicit ``testpaths`` list runs only the directories that list names. A
+``test_*.py`` file written into a directory that no ``testpaths`` entry covers is
+collected by no default ``pytest`` run, so the test silently never executes and a
+regression in the code it guards passes the standard suite undetected. This
+module holds the marker filename that anchors a pytest package, the key name
+that identifies an explicit ``testpaths`` allowlist, the test-file basename
+pattern, the package-root entry tokens and glob metacharacters that classify a
+``testpaths`` entry, the directory names the upward search prunes, the search
+budget, and the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "PYPROJECT_FILENAME",
+    "TESTPATHS_KEY",
+    "TEST_FILE_BASENAME_PATTERN",
+    "PACKAGE_ROOT_ENTRY",
+    "PACKAGE_ROOT_ENTRY_PREFIX",
+    "GLOB_METACHARACTERS",
+    "ALL_PRUNED_PARENT_DIRECTORY_NAMES",
+    "MAX_PARENT_DIRECTORIES_SEARCHED",
+    "UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE",
+    "UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE",
+    "UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT",
+]
+
+PYPROJECT_FILENAME: str = "pyproject.toml"
+
+TESTPATHS_KEY: str = "testpaths"
+
+TEST_FILE_BASENAME_PATTERN: re.Pattern[str] = re.compile(r"^test_.+\.py$")
+
+PACKAGE_ROOT_ENTRY: str = "."
+
+PACKAGE_ROOT_ENTRY_PREFIX: str = "./"
+
+GLOB_METACHARACTERS: frozenset[str] = frozenset({"*", "?", "["})
+
+ALL_PRUNED_PARENT_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
+MAX_PARENT_DIRECTORIES_SEARCHED: int = 40
+
+UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE: str = (
+    "Test file {test_file} lands in a directory that the pytest config at "
+    "{pyproject} does not collect. That pyproject declares an explicit testpaths "
+    "allowlist, and no entry covers {test_directory} (relative to the package "
+    "root). A default `pytest` run from the package root never collects this file, "
+    "so the test silently never runs and a regression it would catch passes the "
+    "suite undetected. Add the directory to the testpaths list in {pyproject} "
+    "(for example `{suggested_entry}`) in the same change that adds the test."
+)
+
+UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE: str = (
+    "test file lands outside the pytest testpaths allowlist - add its directory to "
+    "testpaths so the default suite collects it"
+)
+
+UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT: str = (
+    "When a package's pyproject.toml declares [tool.pytest.ini_options] with an "
+    "explicit testpaths list, that list is the complete set of directories a "
+    "default pytest run collects. A test_*.py file written into a directory no "
+    "testpaths entry covers is collected by nobody: the default run skips it and "
+    "the regression it guards goes unnoticed. To resolve:\n"
+    "  - add the test file's directory (relative to the package root) to the "
+    "testpaths list in pyproject.toml, or\n"
+    "  - move the test under a directory the testpaths list already covers."
+)

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"