claude-dev-env 1.73.0 → 1.75.0

package/hooks/blocking/test_state_description_blocker.py

@@ -4,6 +4,21 @@ import json
 import os
 import subprocess
 import sys
+from pathlib import Path
+from unittest.mock import patch
+
+_BLOCKING_DIR = str(Path(__file__).resolve().parent)
+_HOOKS_ROOT = str(Path(__file__).resolve().parent.parent)
+if _BLOCKING_DIR not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIR)
+if _HOOKS_ROOT not in sys.path:
+    sys.path.insert(0, _HOOKS_ROOT)
+
+from pre_tool_use_dispatcher import NativeHook, run_native_hook  # noqa: E402
+from state_description_blocker import (  # noqa: E402
+    build_deny_payload,
+    evaluate,
+)
 
 HOOK_SCRIPT_PATH = os.path.join(
     os.path.dirname(__file__), "state_description_blocker.py"
@@ -616,3 +631,29 @@ def test_handles_non_string_tool_name():
     )
     assert result.returncode == 0
     assert result.stdout == ""
+
+
+def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
+    """A deny routed through the dispatcher's native path logs one record.
+
+    hooks.json wires this hook only through pre_tool_use_dispatcher, whose
+    native path calls evaluate() and build_deny_payload() — never main(). The
+    block must still land in the hook-blocks log, so the log call lives on
+    build_deny_payload, the function the native path executes.
+    """
+    deny_payload = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": "src/main.py", "content": VIOLATION_INSTEAD_OF_COMMENT},
+    }
+    native_hook = NativeHook(evaluate=evaluate, build_deny_payload=build_deny_payload)
+
+    with patch.object(Path, "home", return_value=tmp_path):
+        hosted_result = run_native_hook(native_hook, deny_payload, is_blocking=True)
+
+    assert hosted_result.captured_stdout
+    log_path = tmp_path / ".claude" / "logs" / "hook-blocks.log"
+    all_records = log_path.read_text(encoding="utf-8").strip().splitlines()
+    assert len(all_records) == 1
+    logged_record = json.loads(all_records[0])
+    assert logged_record["hook"] == "state_description_blocker.py"
+    assert logged_record["event"] == "PreToolUse"

package/hooks/blocking/test_verdict_directory_write_blocker.py

@@ -11,6 +11,8 @@ is denied, and commands that touch unrelated paths pass.
 import importlib.util
 import json
 import pathlib
+import shutil
+import subprocess
 import sys
 
 _HOOK_DIR = pathlib.Path(__file__).parent
@@ -718,3 +720,50 @@ def test_guard_is_registered_on_powershell() -> None:
         "verdict_directory_write_blocker.py" in each_command
         for each_command in _pretooluse_commands_for_matcher("PowerShell")
     )
+
+
+def test_hook_subprocess_imports_real_config_when_parent_holds_shadowing_config(
+    tmp_path: pathlib.Path,
+) -> None:
+    real_blocking_directory = pathlib.Path(__file__).resolve().parent
+    real_hooks_directory = real_blocking_directory.parent
+
+    staged_hooks_directory = tmp_path / "hooks"
+    staged_blocking_directory = staged_hooks_directory / "blocking"
+    staged_blocking_directory.mkdir(parents=True)
+
+    shutil.copy(
+        real_blocking_directory / "verdict_directory_write_blocker.py",
+        staged_blocking_directory / "verdict_directory_write_blocker.py",
+    )
+    shutil.copytree(
+        real_blocking_directory / "config",
+        staged_blocking_directory / "config",
+    )
+    shutil.copytree(
+        real_hooks_directory / "hooks_constants",
+        staged_hooks_directory / "hooks_constants",
+    )
+
+    shadowing_config_directory = staged_hooks_directory / "config"
+    shadowing_config_directory.mkdir(parents=True, exist_ok=True)
+    (shadowing_config_directory / "__init__.py").write_text("", encoding="utf-8")
+    (shadowing_config_directory / "unrelated_constants.py").write_text(
+        "UNRELATED_VALUE = 1\n", encoding="utf-8"
+    )
+
+    benign_payload = json.dumps(
+        {"tool_name": "Bash", "tool_input": {"command": "echo hello"}}
+    )
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(staged_blocking_directory / "verdict_directory_write_blocker.py"),
+        ],
+        input=benign_payload,
+        capture_output=True,
+        text=True,
+    )
+
+    assert "ModuleNotFoundError" not in completed.stderr
+    assert completed.returncode == 0

package/hooks/blocking/test_workflow_substitution_slot_blocker.py

@@ -23,7 +23,6 @@ hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 
 content_has_violation = hook_module.content_has_violation
-find_bare_index_segments = hook_module.find_bare_index_segments
 find_bare_path_segments = hook_module.find_bare_path_segments
 has_iteration_loop = hook_module.has_iteration_loop
 written_content = hook_module.written_content
@@ -47,37 +46,23 @@ _FIXED_TEMPLATE = (
 
 
 def test_detects_bare_index_in_path_segment() -> None:
-    assert find_bare_index_segments(
+    assert find_bare_path_segments(
         "render Path(r'${args.work_dir}\\\\cand_i\\\\plate.svg')"
     ) == {"cand_i"}
 
 
 def test_detects_quoted_key_when_token_also_appears_as_path_segment() -> None:
     looped_path_and_key = "write ${work}\\\\cand_i\\\\plate.svg\n{key: \"cand_i\", name}"
-    assert "cand_i" in find_bare_index_segments(looped_path_and_key)
+    assert "cand_i" in find_bare_path_segments(looped_path_and_key)
 
 
 def test_quoted_key_alone_without_path_segment_is_not_detected() -> None:
-    assert find_bare_index_segments('{key: "metric_i", name}') == set()
-
-
-def test_index_segments_equal_path_segments_for_looped_path_and_key() -> None:
-    looped_path_and_key = "write ${work}\\\\cand_i\\\\plate.svg\n{key: \"cand_i\", name}"
-    assert find_bare_index_segments(looped_path_and_key) == find_bare_path_segments(
-        looped_path_and_key
-    )
-
-
-def test_index_segments_equal_path_segments_for_quoted_only_key() -> None:
-    quoted_only_key = '{key: "metric_i", name}'
-    assert find_bare_index_segments(quoted_only_key) == find_bare_path_segments(
-        quoted_only_key
-    )
+    assert find_bare_path_segments('{key: "metric_i", name}') == set()
 
 
 def test_marked_substitution_slot_is_not_a_bare_segment() -> None:
     assert (
-        find_bare_index_segments(
+        find_bare_path_segments(
             "render Path(r'${args.work_dir}\\\\cand_<i>\\\\plate.svg')"
         )
         == set()

package/hooks/blocking/verdict_directory_write_blocker.py

@@ -39,7 +39,7 @@ if blocking_directory not in sys.path:
 
 hooks_directory = str(Path(__file__).resolve().parent.parent)
 if hooks_directory not in sys.path:
-    sys.path.insert(0, hooks_directory)
+    sys.path.append(hooks_directory)
 
 from config.verified_commit_constants import (  # noqa: E402
     ALL_GATED_TOOL_NAMES,
@@ -78,6 +78,7 @@ from config.verified_commit_constants import (  # noqa: E402
     WRITE_CALL_REGION_PATTERN,
 )
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )
@@ -664,6 +665,14 @@ def main() -> None:
     deny_decision = decision_for_payload(pretooluse_payload)
     if deny_decision is None:
         return
+    raw_tool_name = pretooluse_payload.get("tool_name", "")
+    tool_name_for_log = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    log_hook_block(
+        calling_hook_name="verdict_directory_write_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=VERDICT_DIRECTORY_GUARD_MESSAGE,
+        tool_name=tool_name_for_log,
+    )
     print(json.dumps(deny_decision))
     sys.stdout.flush()
 

package/hooks/blocking/verified_commit_gate.py

@@ -38,6 +38,10 @@ blocking_directory = str(Path(__file__).resolve().parent)
 if blocking_directory not in sys.path:
     sys.path.insert(0, blocking_directory)
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
 from config.verified_commit_constants import (
     ALL_GIT_BINARY_NAMES,
     CORRECTIVE_MESSAGE,
@@ -55,6 +59,7 @@ from config.verified_commit_constants import (
     VERIFICATION_BYPASS_MARKER,
     WORK_TREE_OPTION,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from verification_verdict_store import (
     branch_surface_manifest,
     is_verification_exempt_diff,
@@ -543,6 +548,12 @@ def main() -> None:
                 "permissionDecisionReason": deny_reason,
             }
         }
+        log_hook_block(
+            calling_hook_name="verified_commit_gate.py",
+            hook_event="PreToolUse",
+            block_reason=deny_reason,
+            tool_name=pretooluse_payload.get("tool_name", "") if isinstance(pretooluse_payload.get("tool_name"), str) else None,
+        )
         print(json.dumps(deny_payload))
         return
 

package/hooks/blocking/verified_commit_message_accuracy_blocker.py

@@ -24,6 +24,13 @@ import json
 import os
 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
 
 
 def is_guarded_file(file_path: str) -> bool:
@@ -136,13 +143,21 @@ def main() -> None:
     if not claims_blanket_comment_exemption(written_text):
         sys.exit(0)
 
+    corrective_message = build_corrective_message()
     deny_response = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": build_corrective_message(),
+            "permissionDecisionReason": corrective_message,
         }
     }
+    log_hook_block(
+        calling_hook_name="verified_commit_message_accuracy_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=corrective_message,
+        tool_name=tool_name,
+        offending_input_preview=file_path,
+    )
     print(json.dumps(deny_response))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/windows_rmtree_blocker.py

@@ -21,6 +21,7 @@ _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
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
 from hooks_constants.windows_rmtree_blocker_constants import PYTHON_FILE_EXTENSION  # noqa: E402
 
@@ -104,6 +105,12 @@ def main() -> None:
             "permissionDecisionReason": corrective_message,
         }
     }
+    log_hook_block(
+        calling_hook_name="windows_rmtree_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=corrective_message,
+        tool_name=tool_name,
+    )
     print(json.dumps(deny_response))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/workflow_substitution_slot_blocker.py

@@ -40,6 +40,7 @@ _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
 from hooks_constants.workflow_substitution_slot_blocker_constants import (  # noqa: E402
     CORRECTIVE_MESSAGE,
     EDIT_TOOL_NAME,
@@ -111,16 +112,12 @@ def find_bare_path_segments(content: str) -> set[str]:
     return all_path_segments
 
 
-def find_bare_index_segments(content: str) -> set[str]:
-    return find_bare_path_segments(content)
-
-
 def content_has_violation(content: str) -> bool:
     if not uses_angle_slot_convention(content):
         return False
     if not has_iteration_loop(content):
         return False
-    return bool(find_bare_index_segments(content))
+    return bool(find_bare_path_segments(content))
 
 
 def main() -> None:
@@ -150,6 +147,14 @@ def main() -> None:
             "permissionDecisionReason": CORRECTIVE_MESSAGE,
         }
     }
+    raw_tool_name_for_log = hook_input.get("tool_name", "")
+    tool_name_for_log = raw_tool_name_for_log if isinstance(raw_tool_name_for_log, str) else ""
+    log_hook_block(
+        calling_hook_name="workflow_substitution_slot_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=CORRECTIVE_MESSAGE,
+        tool_name=tool_name_for_log,
+    )
     print(json.dumps(deny_payload))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/write_existing_file_blocker.py

@@ -8,6 +8,13 @@ Exemptions: Jupyter notebooks (.ipynb) and files in ~/.claude/hooks/ (standalone
 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
 
 JUPYTER_EXTENSION = ".ipynb"
 HOOKS_DIRECTORY = os.path.normpath(os.path.expanduser("~/.claude/hooks"))
@@ -48,13 +55,21 @@ def main() -> None:
     if not os.path.exists(target_file_path):
         sys.exit(0)
 
+    deny_reason = f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead."
     denial = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead.",
+            "permissionDecisionReason": deny_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="write_existing_file_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name="Write",
+        offending_input_preview=target_file_path,
+    )
     print(json.dumps(denial))
     sys.exit(0)
 

package/hooks/hooks.json

@@ -161,6 +161,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "SendUserFile",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/send_user_file_open_locally_blocker.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionStart": [

package/hooks/hooks_constants/CLAUDE.md

@@ -22,18 +22,23 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
 | `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
 | `doc_gist_auto_publish_constants.py` | Sentinel marker and URL patterns for the doc-gist auto-publish hook |
+| `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 |
+| `duplicate_rmtree_helper_blocker_constants.py` | Sanctioned Windows-safe rmtree helper names, the definition pattern, and the exempt-path set for the duplicate-rmtree-helper blocker |
 | `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
 | `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
 | `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
+| `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
 | `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
 | `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
 | `html_companion_constants.py` | Blocked URL schemes and other config for the `.md`-to-`.html` companion hook |
 | `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
 | `md_to_html_blocker_constants.py` | Path exemptions and trigger patterns for the markdown-to-html blocker |
 | `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
+| `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |
 | `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |
 | `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
+| `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
 | `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
 | `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
 | `pr_converge_bugteam_enforcer_constants.py` | State keys and timing config for the bugteam-parallel enforcer |
@@ -43,6 +48,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
 | `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
 | `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 |
+| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
 | `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
 | `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
 | `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
@@ -51,6 +57,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
 | `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
 | `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
+| `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
 | `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
 | `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
 | `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
@@ -60,4 +67,4 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 - Every file in this package is a pure constants module — no side effects, no I/O.
 - Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
 - Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
-- `dynamic_stderr_handler.py` and `pre_tool_use_stdin.py` are utility modules (not pure constants) but live here because they are shared across many hooks.
+- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they are shared across many hooks.

package/hooks/hooks_constants/blocking_check_limits.py

@@ -30,6 +30,7 @@ DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
 MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
 DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
 MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES: int = 3
+MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES: int = 3
 MAX_STALE_TEST_NAME_TARGET_ISSUES: int = 3
 STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT: int = 2
 MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES: int = 5
@@ -40,6 +41,8 @@ MAX_DOCSTRING_STEP_DISPATCH_ISSUES: int = 5
 MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK: int = 2
 MINIMUM_TOKENS_FOR_DISPATCH_CALLEE: int = 2
 MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES: int = 3
+MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES: int = 5
+SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT: int = 1
 ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS: frozenset[str] = frozenset(
     {
         "UPPER_SNAKE_CASE",
@@ -94,6 +97,16 @@ ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "not yet read by any consumer",
 )
 
+ALL_DOCSTRING_GUARDED_FAILURE_CLAIM_PHRASES: tuple[str, ...] = (
+    "malformed payload resolves to none",
+    "malformed payload returns none",
+    "malformed response resolves to none",
+    "malformed response returns none",
+    "bad payload resolves to none",
+    "invalid payload resolves to none",
+    "malformed payload yields none",
+)
+
 MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES: int = 3
 ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES: tuple[str, ...] = (
     "no literals appear inline",

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -42,6 +42,9 @@ UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 ALL_MUST_CHECK_RETURN_FUNCTION_NAMES: frozenset[str] = frozenset({"find_and_click", "write_outcome"})
 
 DOCSTRING_ARG_ENTRY_PATTERN: re.Pattern[str] = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*[:(]")
+DOCSTRING_PLURAL_FAMILY_STOP_PATTERN: re.Pattern[str] = re.compile(
+    r"\bthe\s+([a-z][a-z]+)\s+stops\b"
+)
 INLINE_CODE_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"``?(\.?[A-Za-z_][A-Za-z0-9_.]*)``?")
 IDENTIFIER_SHAPED_TUPLE_MEMBER_PATTERN: re.Pattern[str] = re.compile(r"^\.?[A-Za-z_][A-Za-z0-9_]*$")
 ALL_DOCSTRING_ARGS_SECTION_HEADERS: tuple[str, ...] = ("Args:", "Arguments:")

package/hooks/hooks_constants/code_verifier_spawn_preflight_gate_constants.py

@@ -2,7 +2,8 @@
 
 The gate denies an ``Agent`` spawn whose ``subagent_type`` is ``code-verifier``
 when the branch carries a merge conflict against its base ref or a CODE_RULES
-violation on a line added in the uncommitted working tree. It runs two
+violation on a line added in the working tree since the merge base (committed on
+the branch or uncommitted). It runs two
 pre-flight checks before the expensive verification spawn and addresses its
 deny reason to the spawning agent so that agent fixes the named issues and
 re-spawns. Every literal the hook body reads lives here; the hook imports

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/duplicate_rmtree_helper_blocker_constants.py

@@ -0,0 +1,27 @@
+"""Configuration constants for the duplicate_rmtree_helper_blocker PreToolUse hook."""
+
+import re
+
+PYTHON_FILE_EXTENSION: str = ".py"
+
+HELPER_DEFINITION_PATTERN: re.Pattern[str] = re.compile(
+    r"^[ \t]*def[ \t]+(?:_strip_read_only_and_retry|_force_remove_tree|force_rmtree)[ \t]*\(",
+    re.MULTILINE,
+)
+
+TRIPLE_QUOTED_STRING_PATTERN: re.Pattern[str] = re.compile(
+    r'"""[\s\S]*?"""|\'\'\'[\s\S]*?\'\'\'',
+)
+
+ALL_EXEMPT_PATH_FRAGMENTS: tuple[str, ...] = (
+    "windows_rmtree_blocker.py",
+    "duplicate_rmtree_helper_blocker.py",
+    "windows_safe_rmtree.py",
+    "windows_filesystem.py",
+    "session_env_cleanup.py",
+    "_md_to_html_blocker_test_support.py",
+    "teardown_worktrees.py",
+)
+
+ALL_EXEMPT_TEST_FILE_PREFIXES: tuple[str, ...] = ("test_",)
+ALL_EXEMPT_TEST_FILE_SUFFIXES: tuple[str, ...] = ("_test.py",)

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