claude-dev-env 1.59.0 → 1.61.0

package/hooks/blocking/verified_commit_gate.py

@@ -0,0 +1,535 @@
+"""PreToolUse gate: git commit/push lands only behind a minted verifier verdict.
+
+Fires on Bash and PowerShell tool calls. When the command carries a
+``git commit`` or ``git push``, the gate resolves the repository the command
+targets, computes the live change-surface manifest against the merge base,
+and allows the command only when one of these holds:
+
+- the repository has no resolvable upstream base — no ``origin/HEAD``, no
+  configured tracking ref, and neither ``origin/main`` nor ``origin/master``
+  (scratch repos with no remote branch are out of scope),
+- the surface is mechanically exempt (docs/images by extension, pytest
+  test files by name convention, Python files whose docstring-stripped
+  AST is unchanged), or
+- a verdict minted by ``verifier_verdict_minter.py`` reports ``all_pass``
+  and binds to the exact live manifest hash.
+
+The surface binds every changed and untracked file's content, so slicing
+work into small commits or staging files cannot move the hash, while any
+content edit or new file after verification invalidates the verdict.
+Verdict files live under ``~/.claude/verification/`` and are minted only by
+the SubagentStop hook when a ``code-verifier`` agent finishes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from config.verified_commit_constants import (
+    ALL_GIT_BINARY_NAMES,
+    CORRECTIVE_MESSAGE,
+    DIRECTORY_CHANGE_OPTION_TERMINATOR,
+    DIRECTORY_CHANGE_PATH_OPTIONS,
+    DIRECTORY_CHANGE_PATTERN_PREFIX,
+    DIRECTORY_CHANGE_PATTERN_SUFFIX,
+    DIRECTORY_CHANGE_VERBS,
+    GATED_GIT_SUBCOMMANDS,
+    ALL_GATED_TOOL_NAMES,
+    HASH_PREVIEW_LENGTH,
+    OPTION_WITH_VALUE_STEP,
+    REPO_DIRECTORY_OPTION,
+    VALUE_TAKING_GIT_OPTIONS,
+    WORK_TREE_OPTION,
+)
+from verification_verdict_store import (
+    branch_surface_manifest,
+    is_verification_exempt_diff,
+    load_valid_verdict,
+    manifest_sha256,
+    resolve_merge_base,
+    resolve_repo_root,
+    workflow_verdict_covers_surface,
+)
+
+
+def _collapse_line_continuations(command_text: str) -> str:
+    """Remove backslash-newline line continuations the shell would erase.
+
+    Bash joins a line continuation — a backslash immediately followed by a
+    newline — by deleting both characters, so ``git \\<newline>commit``,
+    ``git commit\\<newline> -m x``, and ``g\\<newline>it commit`` all run as a
+    plain ``git commit``. Stripping the pair before tokenizing makes the token
+    stream match what the shell executes, so a continuation abutting the
+    subcommand or splitting the ``git`` word cannot evade the gate.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        The command with every backslash-newline pair removed.
+    """
+    return re.sub(r"\\\r?\n", "", command_text)
+
+
+def _quoted_spans(command_text: str) -> list[tuple[int, int]]:
+    """Find the character spans of every quoted region in a command.
+
+    Scans single- and double-quoted runs left to right so a verb sitting
+    inside a quoted ``-m`` commit message is recognised as message text
+    rather than a real shell directory change.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        The ``(start, end)`` span of each quoted region, in order.
+    """
+    quoted_region_pattern = re.compile(r"\"[^\"]*\"|'[^']*'")
+    return [
+        (each_match.start(), each_match.end())
+        for each_match in quoted_region_pattern.finditer(command_text)
+    ]
+
+
+def _is_inside_quoted_region(position: int, all_quoted_spans: list[tuple[int, int]]) -> bool:
+    """Decide whether a position falls inside any quoted region.
+
+    Args:
+        position: A character offset into the command string.
+        all_quoted_spans: The quoted-region spans from ``_quoted_spans``.
+
+    Returns:
+        True when the offset sits within a quoted region's bounds.
+    """
+    for each_span_start, each_span_end in all_quoted_spans:
+        if each_span_start <= position < each_span_end:
+            return True
+    return False
+
+
+def _containing_quoted_span(
+    position: int, all_quoted_spans: list[tuple[int, int]]
+) -> tuple[int, int] | None:
+    """Return the quoted region a position falls inside, or None.
+
+    Args:
+        position: A character offset into the command string.
+        all_quoted_spans: The quoted-region spans from ``_quoted_spans``.
+
+    Returns:
+        The ``(start, end)`` span containing the offset, or None when the
+        offset sits outside every quoted region.
+    """
+    for each_span_start, each_span_end in all_quoted_spans:
+        if each_span_start <= position < each_span_end:
+            return (each_span_start, each_span_end)
+    return None
+
+
+def _git_word_match_gates(
+    git_word_match: re.Match[str],
+    command_text: str,
+    all_quoted_spans: list[tuple[int, int]],
+) -> bool:
+    """Decide whether a ``git`` word match counts as a real invocation.
+
+    A ``git`` word outside every quoted region always gates. Inside a quoted
+    region the word gates only when the region's content, with edge quotes
+    stripped, is a path whose final ``[\\/]``-split segment is ``git`` or
+    ``git.exe`` — a wrapper-quoted binary (``"git" commit``), a quoted
+    call-operator path (``& 'C:/x/git.exe' commit``), or a quoted install
+    path whose directory components carry spaces
+    (``& "C:\\Program Files\\Git\\cmd\\git.exe" commit``). A ``git`` word that
+    is one word among prose inside a quoted string — an
+    ``echo "Next: git commit"`` mention or a ``gh pr comment -b "please git
+    commit"`` body — does not gate, because the prose's final path segment is
+    the surrounding sentence rather than a bare ``git``/``git.exe`` binary
+    name, so the shell never runs that quoted text as a command.
+
+    Args:
+        git_word_match: A ``git`` word match in the command.
+        command_text: The raw command string from the tool payload.
+        all_quoted_spans: The quoted-region spans from ``_quoted_spans``.
+
+    Returns:
+        True when the matched ``git`` word counts as a real git invocation.
+    """
+    containing_span = _containing_quoted_span(git_word_match.start(), all_quoted_spans)
+    if containing_span is None:
+        return True
+    span_start, span_end = containing_span
+    quoted_content = _strip_token_quotes(command_text[span_start:span_end])
+    final_segment = re.split(r"[\\/]", quoted_content)[-1].lower()
+    return final_segment in ALL_GIT_BINARY_NAMES
+
+
+def _strip_token_quotes(token_text: str) -> str:
+    """Remove quote characters from a token's edges.
+
+    Tokens cut from inside a quoted shell-wrapper argument can carry an
+    unpaired edge quote (``push"``), so both edges are stripped rather
+    than only matched pairs.
+
+    Args:
+        token_text: One quote-aware token from a command string.
+
+    Returns:
+        The token without leading or trailing quote characters.
+    """
+    return token_text.strip("\"'")
+
+
+def _gated_invocation_directory(all_following_tokens: list[str]) -> tuple[bool, str | None]:
+    """Walk the tokens after a ``git`` word to its first subcommand.
+
+    Skips git's global options (recording the targeted directory when one
+    appears) so a gated verb counts only in subcommand position — never as
+    an argument like ``git stash push`` or ``git log --grep commit``. The
+    ``-C`` directory wins when both ``-C`` and ``--work-tree`` are present;
+    otherwise a ``--work-tree`` value supplies the targeted directory so a
+    commit aimed at another repo's work tree gates against that work tree
+    rather than the session directory.
+
+    Args:
+        all_following_tokens: Quote-stripped tokens after the ``git`` word.
+
+    Returns:
+        Whether the first subcommand is gated, and the directory the
+        invocation targets via ``-C`` (or ``--work-tree``) when one appears.
+    """
+    repo_directory: str | None = None
+    work_tree_directory: str | None = None
+    token_index = 0
+    while token_index < len(all_following_tokens):
+        each_token = all_following_tokens[token_index]
+        option_name, attached_value = _split_option_value(each_token)
+        if option_name in VALUE_TAKING_GIT_OPTIONS:
+            option_value = (
+                attached_value
+                if attached_value is not None
+                else _value_after_option(all_following_tokens, token_index)
+            )
+            if option_name == REPO_DIRECTORY_OPTION and option_value is not None:
+                repo_directory = _expand_home_prefix(option_value)
+            if option_name == WORK_TREE_OPTION and option_value is not None:
+                work_tree_directory = _expand_home_prefix(option_value)
+            token_index += 1 if attached_value is not None else OPTION_WITH_VALUE_STEP
+            continue
+        if each_token.startswith("-"):
+            token_index += 1
+            continue
+        return (
+            each_token.lower() in GATED_GIT_SUBCOMMANDS,
+            repo_directory or work_tree_directory,
+        )
+    return (False, repo_directory or work_tree_directory)
+
+
+def _split_option_value(option_token: str) -> tuple[str, str | None]:
+    """Split a ``--name=value`` option token into its name and value.
+
+    Args:
+        option_token: One quote-stripped token after the ``git`` word.
+
+    Returns:
+        The option name and its attached value, or the whole token and None
+        when the token carries no ``=`` value.
+    """
+    if option_token.startswith("--") and "=" in option_token:
+        option_name, _, attached_value = option_token.partition("=")
+        return (option_name, attached_value)
+    return (option_token, None)
+
+
+def _value_after_option(all_following_tokens: list[str], option_index: int) -> str | None:
+    """Read the separate value token that follows a value-taking option.
+
+    Args:
+        all_following_tokens: Quote-stripped tokens after the ``git`` word.
+        option_index: Index of the value-taking option token.
+
+    Returns:
+        The next token when one exists, or None at the end of the tokens.
+    """
+    if option_index + 1 < len(all_following_tokens):
+        return all_following_tokens[option_index + 1]
+    return None
+
+
+def _expand_home_prefix(directory_token: str) -> str:
+    """Expand a leading ``~`` to the home directory the shell would use.
+
+    Git does not expand ``~`` for ``-C`` or ``--work-tree`` and never sees a
+    shell's ``cd ~`` expansion, so the gate must expand the token itself;
+    otherwise it resolves a non-existent ``~/...`` path that git rejects while
+    the shell commits in the real home-anchored repo.
+
+    Args:
+        directory_token: A directory token that may start with ``~``.
+
+    Returns:
+        The token with any leading home prefix expanded, unchanged otherwise.
+    """
+    if directory_token.startswith("~"):
+        return os.path.expanduser(directory_token)
+    return directory_token
+
+
+def _is_absolute_directory(directory_token: str) -> bool:
+    """Decide whether a directory-change target is already absolute.
+
+    Treats a POSIX root, a Windows drive or UNC root, a leading slash or
+    backslash, and a home-relative ``~`` token as absolute so they are used
+    as given rather than joined onto the active directory.
+
+    Args:
+        directory_token: The destination of a directory-change verb.
+
+    Returns:
+        True when the token names an absolute or home-anchored location.
+    """
+    if directory_token.startswith("~"):
+        return True
+    if directory_token.startswith(("/", "\\")):
+        return True
+    return os.path.isabs(directory_token)
+
+
+def _resolve_against(active_directory: str, changed_directory: str) -> str:
+    """Resolve a directory-change target against the active directory.
+
+    An absolute or home-anchored target replaces the active directory; a
+    relative target is joined onto it so a ``cd subdir`` gates against the
+    session directory's subdirectory rather than a token git would resolve
+    against the hook process's own working directory.
+
+    Args:
+        active_directory: The directory in effect before this change.
+        changed_directory: The destination of a directory-change verb.
+
+    Returns:
+        The directory the shell runs in after the change.
+    """
+    if _is_absolute_directory(changed_directory):
+        return _expand_home_prefix(changed_directory)
+    return os.path.join(active_directory, changed_directory)
+
+
+def _directory_change_target(command_text: str, match_end: int) -> str | None:
+    """Read the destination of a directory-change verb.
+
+    Walks the arguments after the verb, skipping a leading ``--`` terminator
+    and consuming the value after a PowerShell path option
+    (``-Path``/``-LiteralPath``) so the destination is the path rather than
+    the flag. A leading shell operator (``cd && git ...``) means no argument
+    and the active directory stays unchanged. Applies to every spelling in
+    ``DIRECTORY_CHANGE_VERBS`` (``cd``, ``pushd``, ``Set-Location``, ``sl``).
+
+    Args:
+        command_text: The raw command string from the tool payload.
+        match_end: The offset just past the directory-change verb word.
+
+    Returns:
+        The destination path when one follows the verb, or None for a bare
+        ``cd`` (a return to the home directory, which the gate ignores).
+    """
+    all_argument_tokens = _argument_tokens_after_verb(command_text, match_end)
+    token_index = 0
+    while token_index < len(all_argument_tokens):
+        each_token = _strip_token_quotes(all_argument_tokens[token_index])
+        if each_token == DIRECTORY_CHANGE_OPTION_TERMINATOR:
+            token_index += 1
+            continue
+        if each_token.lower() in DIRECTORY_CHANGE_PATH_OPTIONS:
+            token_index += 1
+            continue
+        return each_token
+    return None
+
+
+def _argument_tokens_after_verb(command_text: str, match_end: int) -> list[str]:
+    """Cut the run of argument tokens that follows a directory-change verb.
+
+    Reads tokens until the first shell command separator (``;``, ``&``,
+    ``|``, or a newline), so only the verb's own arguments are returned and a
+    following command is left untouched.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+        match_end: The offset just past the directory-change verb word.
+
+    Returns:
+        The quote-aware argument tokens following the verb, in order.
+    """
+    argument_run_pattern = re.compile(r"[ \t]+((?:\"[^\"]*\"|'[^']*'|[^\s;&|])+)")
+    argument_token_pattern = re.compile(r"\"[^\"]*\"|'[^']*'|[^\s;&|]+")
+    all_argument_tokens: list[str] = []
+    scan_position = match_end
+    while True:
+        run_match = argument_run_pattern.match(command_text, scan_position)
+        if run_match is None:
+            return all_argument_tokens
+        all_argument_tokens.extend(argument_token_pattern.findall(run_match.group(1)))
+        scan_position = run_match.end()
+
+
+def gated_repo_directories(command_text: str, fallback_directory: str) -> list[str]:
+    """Collect the directories of every git commit/push found in a command.
+
+    Backslash-newline line continuations are removed first so the token
+    stream matches what the shell runs (``git \\<newline>commit`` is a real
+    commit). Scans every ``git`` word in the command — the bare ``git`` and
+    the Windows ``git.exe`` spelling, a path-prefixed binary whose final
+    segment is ``git``/``git.exe`` (``/usr/bin/git``,
+    ``C:\\...\\git.exe``), and a quoted git binary whose stripped content is
+    a single token ending in ``git``/``git.exe`` (``"git" commit``,
+    ``& 'C:/x/git.exe' commit``) — and token-walks from each to its first
+    subcommand. A ``git`` word that is one word among prose inside a quoted
+    string (``echo "Next: git commit"``, a ``gh pr comment -b`` body) is left
+    alone, because the shell never runs that quoted text. A
+    directory-change verb (``cd``, ``pushd``, PowerShell ``Set-Location``,
+    or its ``sl`` alias) earlier in the command moves the active directory,
+    so a following un-``-C``'d commit/push gates against the directory the
+    shell actually runs it in rather than the session cwd. A relative
+    change target joins onto the active directory so it resolves the same
+    way the shell would, not against the hook process's own cwd.
+
+    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.
+
+    Returns:
+        One directory per detected commit/push invocation, in order; empty
+        when the command carries no gated git verb.
+    """
+    command_text = _collapse_line_continuations(command_text)
+    git_word_pattern = re.compile(
+        r"(?:^|(?<=[\s;&|(\"'/\\]))git(?:\.exe)?(?:[\"'](?=\s|$)|(?=\s|$))",
+        re.IGNORECASE,
+    )
+    directory_change_verb_alternation = "|".join(
+        re.escape(each_verb) for each_verb in sorted(DIRECTORY_CHANGE_VERBS)
+    )
+    directory_change_pattern = re.compile(
+        DIRECTORY_CHANGE_PATTERN_PREFIX
+        + directory_change_verb_alternation
+        + DIRECTORY_CHANGE_PATTERN_SUFFIX,
+        re.IGNORECASE,
+    )
+    command_token_pattern = re.compile(r"\"[^\"]*\"|'[^']*'|\S+")
+    all_quoted_spans = _quoted_spans(command_text)
+    all_directory_change_matches = [
+        each_match
+        for each_match in directory_change_pattern.finditer(command_text)
+        if not _is_inside_quoted_region(each_match.start(), all_quoted_spans)
+    ]
+    all_git_word_matches = [
+        each_match
+        for each_match in git_word_pattern.finditer(command_text)
+        if _git_word_match_gates(each_match, command_text, all_quoted_spans)
+    ]
+    all_ordered_matches = sorted(
+        all_git_word_matches + all_directory_change_matches,
+        key=lambda each_match: each_match.start(),
+    )
+    active_directory = fallback_directory
+    target_directories: list[str] = []
+    for each_match in all_ordered_matches:
+        if each_match.group().lower().strip("\"'") in DIRECTORY_CHANGE_VERBS:
+            changed_directory = _directory_change_target(command_text, each_match.end())
+            if changed_directory is not None:
+                active_directory = _resolve_against(active_directory, changed_directory)
+            continue
+        following_text = command_text[each_match.end():]
+        all_following_tokens = [
+            _strip_token_quotes(each_token)
+            for each_token in command_token_pattern.findall(following_text)
+        ]
+        is_gated, flagged_directory = _gated_invocation_directory(all_following_tokens)
+        if is_gated:
+            target_directories.append(
+                _resolve_against(active_directory, flagged_directory)
+                if flagged_directory is not None
+                else active_directory
+            )
+    return target_directories
+
+
+def deny_reason_for_directory(target_directory: str, transcript_path: str) -> str | None:
+    """Decide whether a commit/push in a directory must be blocked.
+
+    Accepts the command when a minted verdict binds to the live surface, or
+    when a workflow-spawned code-verifier emitted a passing verdict bound to
+    the same surface in its own transcript — the latter covers workflow runs,
+    where SubagentStop never fires to mint a verdict file.
+
+    Args:
+        target_directory: The directory the git command targets.
+        transcript_path: The live session's transcript path from the payload,
+            used to find a workflow code-verifier's verdict.
+
+    Returns:
+        The deny reason when the branch diff needs a verdict and neither a
+        minted nor a workflow verdict binds to it; None when the command may
+        proceed.
+    """
+    repo_root = resolve_repo_root(target_directory)
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    if is_verification_exempt_diff(repo_root, merge_base_sha):
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if surface_manifest_text is None:
+        return f"{CORRECTIVE_MESSAGE} (surface manifest failed in {repo_root})"
+    live_manifest_sha256 = manifest_sha256(surface_manifest_text)
+    if load_valid_verdict(repo_root, live_manifest_sha256) is not None:
+        return None
+    if workflow_verdict_covers_surface(transcript_path, live_manifest_sha256):
+        return None
+    hash_preview = live_manifest_sha256[:HASH_PREVIEW_LENGTH]
+    return f"{CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"
+
+
+def main() -> None:
+    """Read the PreToolUse payload and deny unverified commit/push commands."""
+    try:
+        pretooluse_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    if pretooluse_payload.get("tool_name", "") not in ALL_GATED_TOOL_NAMES:
+        return
+    command_text = pretooluse_payload.get("tool_input", {}).get("command", "")
+    if not command_text:
+        return
+    session_directory = pretooluse_payload.get("cwd", ".")
+    transcript_path = pretooluse_payload.get("transcript_path", "")
+    for each_target_directory in gated_repo_directories(command_text, session_directory):
+        deny_reason = deny_reason_for_directory(each_target_directory, transcript_path)
+        if deny_reason is None:
+            continue
+        deny_payload = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": deny_reason,
+            }
+        }
+        print(json.dumps(deny_payload))
+        return
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/verified_commit_message_accuracy_blocker.py

@@ -0,0 +1,152 @@
+#!/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
+
+
+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)
+
+    deny_response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": build_corrective_message(),
+        }
+    }
+    print(json.dumps(deny_response))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()