claude-dev-env 2.3.0 → 2.5.0

package/hooks/blocking/verified_commit_gate_parts/gated_invocations.py

@@ -81,14 +81,15 @@ def _resolved_option_value(
     return value_after_option(all_following_tokens, option_index)
 
 
-def gated_invocation_directory(all_following_tokens: list[str]) -> tuple[bool, str | None]:
+def gated_invocation_directory(
+    all_following_tokens: list[str],
+    all_gated_subcommands: frozenset[str] = GATED_GIT_SUBCOMMANDS,
+) -> tuple[bool, str | None]:
     """Walk the quote-stripped tokens after a ``git`` word to its subcommand.
 
-    ``git stash push`` is not gated ("push" is an argument); ``git commit -m
-    x`` is gated ("commit" sits in subcommand position).
-
-    Returns:
-        Whether the subcommand is gated, and its ``-C``/``--work-tree`` directory.
+    Args:
+        all_following_tokens: Quote-stripped tokens after the ``git`` word.
+        all_gated_subcommands: Subcommand names that gate; defaults to commit+push.
     """
     repo_directory: str | None = None
     work_tree_directory: str | None = None
@@ -108,7 +109,7 @@ def gated_invocation_directory(all_following_tokens: list[str]) -> tuple[bool, s
         if each_token.startswith("-"):
             token_index += 1
             continue
-        return each_token.lower() in GATED_GIT_SUBCOMMANDS, repo_directory or work_tree_directory
+        return each_token.lower() in all_gated_subcommands, repo_directory or work_tree_directory
     return False, repo_directory or work_tree_directory
 
 
@@ -167,11 +168,16 @@ def _apply_directory_change(
 
 
 def _target_directory_for_match(
-    command_text: str, git_word_match: re.Match[str], active_directory: str
+    command_text: str,
+    git_word_match: re.Match[str],
+    active_directory: str,
+    all_gated_subcommands: frozenset[str],
 ) -> str | None:
     """Resolve the gated directory for one ``git`` word match, or None."""
     all_following_tokens = _following_tokens(command_text, git_word_match.end())
-    is_gated, flagged_directory = gated_invocation_directory(all_following_tokens)
+    is_gated, flagged_directory = gated_invocation_directory(
+        all_following_tokens, all_gated_subcommands
+    )
     if not is_gated:
         return None
     if flagged_directory is None:
@@ -179,18 +185,22 @@ def _target_directory_for_match(
     return resolve_against(active_directory, flagged_directory)
 
 
-def gated_repo_directories(command_text: str, fallback_directory: str) -> list[str]:
-    """Collect the directories of every git commit/push found in a command.
+def gated_repo_directories(
+    command_text: str,
+    fallback_directory: str,
+    all_gated_subcommands: frozenset[str] = GATED_GIT_SUBCOMMANDS,
+) -> list[str]:
+    """Collect the directories of every gated git call found in a command.
 
     Args:
         command_text: The raw command string from the tool payload.
-        fallback_directory: The session working directory, used as the
-            active directory until a directory-change verb changes it and
-            when the git call carries no ``-C`` flag.
+        fallback_directory: The session working directory, the active directory
+            until a directory-change verb or a ``-C`` flag overrides it.
+        all_gated_subcommands: Subcommand names that gate; defaults to commit+push.
 
     Returns:
-        One directory per detected commit/push invocation, in order; empty
-        when the command carries no gated git verb.
+        One directory per detected gated invocation, in order; empty when the
+        command carries no gated git verb.
     """
     command_text = collapse_line_continuations(command_text)
     active_directory = fallback_directory
@@ -199,7 +209,9 @@ def gated_repo_directories(command_text: str, fallback_directory: str) -> list[s
         if each_match.group().lower().strip("\"'") in DIRECTORY_CHANGE_VERBS:
             active_directory = _apply_directory_change(command_text, each_match, active_directory)
             continue
-        target_directory = _target_directory_for_match(command_text, each_match, active_directory)
+        target_directory = _target_directory_for_match(
+            command_text, each_match, active_directory, all_gated_subcommands
+        )
         if target_directory is not None:
             target_directories.append(target_directory)
     return target_directories

package/hooks/blocking/verified_commit_gate_parts/tests/test_gated_invocations.py

@@ -59,3 +59,38 @@ def test_gated_repo_directories_gates_an_empty_work_tree_against_the_session() -
     assert gated_repo_directories("git --work-tree= commit -m x", "/session") == [
         os.path.join("/session", "")
     ]
+
+
+def test_default_gated_subcommands_gates_both_commit_and_push() -> None:
+    assert gated_repo_directories("git commit -m x", "/session") == ["/session"]
+    assert gated_repo_directories("git push", "/session") == ["/session"]
+
+
+def test_push_only_subcommands_gate_push_but_not_commit() -> None:
+    push_only = frozenset({"push"})
+    assert gated_invocation_directory(["push"], push_only)[0] is True
+    assert gated_invocation_directory(["commit", "-m", "x"], push_only)[0] is False
+
+
+def test_commit_only_subcommands_gate_commit_but_not_push() -> None:
+    commit_only = frozenset({"commit"})
+    assert gated_invocation_directory(["commit", "-m", "x"], commit_only)[0] is True
+    assert gated_invocation_directory(["push"], commit_only)[0] is False
+
+
+def test_gated_repo_directories_threads_push_only_subcommands() -> None:
+    push_only = frozenset({"push"})
+    assert gated_repo_directories("git push", "/session", push_only) == ["/session"]
+    assert gated_repo_directories("git commit -m x", "/session", push_only) == []
+
+
+def test_gated_repo_directories_accepts_the_all_gated_subcommands_keyword() -> None:
+    push_only = frozenset({"push"})
+    assert gated_repo_directories(
+        "git push", "/session", all_gated_subcommands=push_only
+    ) == ["/session"]
+
+
+def test_gated_invocation_directory_accepts_the_all_gated_subcommands_keyword() -> None:
+    push_only = frozenset({"push"})
+    assert gated_invocation_directory(["push"], all_gated_subcommands=push_only)[0] is True

package/hooks/blocking/verified_commit_message_accuracy_blocker.py

@@ -1,167 +1,167 @@
-#!/usr/bin/env python3
-"""PreToolUse hook: keep verified-commit exemption messages accurate.
-
-The verified-commit gate exempts a branch surface only when every changed path
-matches one of two narrow rules, implemented in ``is_verification_exempt_diff``:
-
-1. file extension in ``DOCS_ONLY_EXTENSIONS`` (docs and image extensions), or
-2. a ``.py`` file whose docstring/comment-stripped AST is unchanged.
-
-A comment-only change to a non-Python, non-doc file (for example ``.sh``,
-``.json``, ``.yaml``) is therefore NOT exempt: comments are ignored for
-exemption purposes only inside Python files via the AST path. A corrective or
-guard message that claims comment-only or docs-only surfaces are blanket exempt
-overstates the rule and misleads users into expecting such a change to skip
-verification.
-
-This hook fires on Write/Edit of any verified-commit constants module and denies
-content whose exemption-claim wording asserts a blanket comment-only or docs-only
-exemption. It guards the message constants at authoring time, before the change
-reaches review.
-"""
-
-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:
-    """Return True for any verified-commit constants module carrying messages."""
-    all_guarded_file_names = frozenset({"verified_commit_constants.py"})
-    return os.path.basename(file_path) in all_guarded_file_names
-
-
-def join_adjacent_string_literals(written_text: str) -> str:
-    """Collapse a closing quote, inter-literal whitespace, and an opening quote.
-
-    Write/Edit content carries the message constant as it appears in source: a
-    long sentence split across adjacent Python string literals. Between two
-    literals sit a closing quote, a newline, indentation, and an opening quote.
-    Replacing that run with a single space rejoins the prose so a phrase wrapped
-    across a literal boundary — for example ``exempt "`` then ``"automatically``
-    — reads as one continuous clause for matching.
-    """
-    inter_literal_noise_pattern = re.compile(r"[\"']\s*[\"']")
-    return inter_literal_noise_pattern.sub(" ", written_text)
-
-
-def claims_blanket_comment_exemption(written_text: str) -> bool:
-    """Return True when the text claims comment surfaces are blanket-exempt.
-
-    Rejoins source-wrapped string literals first, then matches only a genuine
-    blanket form in which a comment surface is the grammatical subject of
-    "exempt automatically". A comment surface is the bare noun ``comments`` or
-    the ``comment-only`` category — never the ``comment`` stem inside an
-    unrelated word such as ``commentary`` or the ``comment-stripped`` AST
-    qualifier.
-
-    Two blanket shapes match. The direct shape names a comment surface as the
-    immediate subject of "(are|is) exempt automatically" across a bridge that
-    crosses no period, semicolon, or comma, so an intervening predicate (for
-    example "Comments are handled, and docs are exempt automatically") leaves
-    docs, not comments, as the exemption subject and does not match. The
-    enumerated shape names a comment item inside an "...-only surfaces are
-    exempt automatically" list (for example "Docs-, comment-, and test-only
-    surfaces are exempt automatically").
-
-    An accurate sentence whose true exemption subject is docs, or that qualifies
-    comments as the stripped input to the AST comparison, does not match. This
-    isolates the overstated form the verified-commit gate does not honor for
-    non-Python files.
-    """
-    comment_surface = r"comments?-only|comments?\b(?!-)"
-    blanket_direct_claim = (
-        "(?:" + comment_surface + r")(?:[^.;,]*?\b)?(?:are|is)\s+exempt\s+automatically"
-    )
-    blanket_enumerated_claim = (
-        "(?:" + comment_surface + "|comment-)"
-        r"[^.;]*?-only\s+surfaces\s+are\s+exempt\s+automatically"
-    )
-    blanket_exemption_claim_pattern = re.compile(
-        "(?:" + blanket_direct_claim + ")|(?:" + blanket_enumerated_claim + ")",
-        re.IGNORECASE,
-    )
-    joined_text = join_adjacent_string_literals(written_text)
-    return bool(blanket_exemption_claim_pattern.search(joined_text))
-
-
-def build_corrective_message() -> str:
-    """Return the deny reason explaining the real, narrower exemption rules."""
-    accurate_exemption_phrasing = (
-        "Docs and images are exempt by extension, and Python files whose "
-        "docstring- and comment-stripped AST is unchanged; a comment-only "
-        "change to a non-Python file still needs a verdict."
-    )
-    return (
-        "BLOCKED [verified-commit-message-accuracy]: this exemption message "
-        "claims comment-only surfaces are exempt automatically, but the "
-        "verified-commit gate exempts comments only inside Python files (via the "
-        "docstring/comment stripped AST path). A comment-only change to a "
-        "non-Python file is NOT exempt and still needs a verifier verdict, so "
-        "the blanket wording misleads users.\n\nDescribe the real exemption "
-        "rules instead, for example:\n  " + accurate_exemption_phrasing
-    )
-
-
-def extract_written_text(all_written_fields: dict[str, str]) -> str:
-    """Return the Write ``content`` and Edit ``new_string`` joined for scanning."""
-    return (
-        all_written_fields.get("content", "")
-        + "\n"
-        + all_written_fields.get("new_string", "")
-    )
-
-
-def main() -> None:
-    all_write_edit_tools = frozenset({"Write", "Edit"})
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_name = hook_input.get("tool_name", "")
-    if tool_name not in all_write_edit_tools:
-        sys.exit(0)
-
-    tool_input = hook_input.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
-    if not file_path:
-        sys.exit(0)
-
-    if not is_guarded_file(file_path):
-        sys.exit(0)
-
-    written_text = extract_written_text(tool_input)
-    if not claims_blanket_comment_exemption(written_text):
-        sys.exit(0)
-
-    corrective_message = build_corrective_message()
-    deny_response = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "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)
-
-
-if __name__ == "__main__":
-    main()
+#!/usr/bin/env python3
+"""PreToolUse hook: keep verified-commit exemption messages accurate.
+
+The verified-commit gate exempts a branch surface only when every changed path
+matches one of two narrow rules, implemented in ``is_verification_exempt_diff``:
+
+1. file extension in ``DOCS_ONLY_EXTENSIONS`` (docs and image extensions), or
+2. a ``.py`` file whose docstring/comment-stripped AST is unchanged.
+
+A comment-only change to a non-Python, non-doc file (for example ``.sh``,
+``.json``, ``.yaml``) is therefore NOT exempt: comments are ignored for
+exemption purposes only inside Python files via the AST path. A corrective or
+guard message that claims comment-only or docs-only surfaces are blanket exempt
+overstates the rule and misleads users into expecting such a change to skip
+verification.
+
+This hook fires on Write/Edit of any verified-commit constants module and denies
+content whose exemption-claim wording asserts a blanket comment-only or docs-only
+exemption. It guards the message constants at authoring time, before the change
+reaches review.
+"""
+
+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:
+    """Return True for any verified-commit constants module carrying messages."""
+    all_guarded_file_names = frozenset({"verified_commit_constants.py"})
+    return os.path.basename(file_path) in all_guarded_file_names
+
+
+def join_adjacent_string_literals(written_text: str) -> str:
+    """Collapse a closing quote, inter-literal whitespace, and an opening quote.
+
+    Write/Edit content carries the message constant as it appears in source: a
+    long sentence split across adjacent Python string literals. Between two
+    literals sit a closing quote, a newline, indentation, and an opening quote.
+    Replacing that run with a single space rejoins the prose so a phrase wrapped
+    across a literal boundary — for example ``exempt "`` then ``"automatically``
+    — reads as one continuous clause for matching.
+    """
+    inter_literal_noise_pattern = re.compile(r"[\"']\s*[\"']")
+    return inter_literal_noise_pattern.sub(" ", written_text)
+
+
+def claims_blanket_comment_exemption(written_text: str) -> bool:
+    """Return True when the text claims comment surfaces are blanket-exempt.
+
+    Rejoins source-wrapped string literals first, then matches only a genuine
+    blanket form in which a comment surface is the grammatical subject of
+    "exempt automatically". A comment surface is the bare noun ``comments`` or
+    the ``comment-only`` category — never the ``comment`` stem inside an
+    unrelated word such as ``commentary`` or the ``comment-stripped`` AST
+    qualifier.
+
+    Two blanket shapes match. The direct shape names a comment surface as the
+    immediate subject of "(are|is) exempt automatically" across a bridge that
+    crosses no period, semicolon, or comma, so an intervening predicate (for
+    example "Comments are handled, and docs are exempt automatically") leaves
+    docs, not comments, as the exemption subject and does not match. The
+    enumerated shape names a comment item inside an "...-only surfaces are
+    exempt automatically" list (for example "Docs-, comment-, and test-only
+    surfaces are exempt automatically").
+
+    An accurate sentence whose true exemption subject is docs, or that qualifies
+    comments as the stripped input to the AST comparison, does not match. This
+    isolates the overstated form the verified-commit gate does not honor for
+    non-Python files.
+    """
+    comment_surface = r"comments?-only|comments?\b(?!-)"
+    blanket_direct_claim = (
+        "(?:" + comment_surface + r")(?:[^.;,]*?\b)?(?:are|is)\s+exempt\s+automatically"
+    )
+    blanket_enumerated_claim = (
+        "(?:" + comment_surface + "|comment-)"
+        r"[^.;]*?-only\s+surfaces\s+are\s+exempt\s+automatically"
+    )
+    blanket_exemption_claim_pattern = re.compile(
+        "(?:" + blanket_direct_claim + ")|(?:" + blanket_enumerated_claim + ")",
+        re.IGNORECASE,
+    )
+    joined_text = join_adjacent_string_literals(written_text)
+    return bool(blanket_exemption_claim_pattern.search(joined_text))
+
+
+def build_corrective_message() -> str:
+    """Return the deny reason explaining the real, narrower exemption rules."""
+    accurate_exemption_phrasing = (
+        "Docs and images are exempt by extension, and Python files whose "
+        "docstring- and comment-stripped AST is unchanged; a comment-only "
+        "change to a non-Python file still needs a verdict."
+    )
+    return (
+        "BLOCKED [verified-commit-message-accuracy]: this exemption message "
+        "claims comment-only surfaces are exempt automatically, but the "
+        "verified-commit gate exempts comments only inside Python files (via the "
+        "docstring/comment stripped AST path). A comment-only change to a "
+        "non-Python file is NOT exempt and still needs a verifier verdict, so "
+        "the blanket wording misleads users.\n\nDescribe the real exemption "
+        "rules instead, for example:\n  " + accurate_exemption_phrasing
+    )
+
+
+def extract_written_text(all_written_fields: dict[str, str]) -> str:
+    """Return the Write ``content`` and Edit ``new_string`` joined for scanning."""
+    return (
+        all_written_fields.get("content", "")
+        + "\n"
+        + all_written_fields.get("new_string", "")
+    )
+
+
+def main() -> None:
+    all_write_edit_tools = frozenset({"Write", "Edit"})
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name not in all_write_edit_tools:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    if not is_guarded_file(file_path):
+        sys.exit(0)
+
+    written_text = extract_written_text(tool_input)
+    if not claims_blanket_comment_exemption(written_text):
+        sys.exit(0)
+
+    corrective_message = build_corrective_message()
+    deny_response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "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)
+
+
+if __name__ == "__main__":
+    main()