claude-dev-env 2.0.1 → 2.1.0

package/hooks/blocking/verified_commit_gate_parts/CLAUDE.md

@@ -0,0 +1,28 @@
+# verified_commit_gate_parts
+
+The concern modules `verified_commit_gate.py` wires together to run the
+verified-commit gate. Each module owns one concern; the entry hook imports
+them and re-exports their surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `command_tokenization.py` | Quote-aware tokenizing of a shell command: line-continuation collapse, quoted-span detection, and deciding whether a `git` word is a real invocation |
+| `directory_resolution.py` | Resolves the active directory a `cd`/`pushd` verb leaves the shell in, and reads a directory-change verb's destination |
+| `gated_invocations.py` | Finds every gated `git commit`/`git push` in a command and the directory each one targets |
+| `deny_reason.py` | Decides whether a commit/push in a directory needs a passing verdict |
+| `deny_payload.py` | Builds the PreToolUse deny payload, including the verify-skip context that goes with it |
+| `__init__.py` | Package marker |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/verified_commit_gate_parts/tests/
+```

package/hooks/blocking/verified_commit_gate_parts/__init__.py

@@ -0,0 +1 @@
+"""Concern modules of ``verified_commit_gate_parts``, wired by the entry hook."""

package/hooks/blocking/verified_commit_gate_parts/command_tokenization.py

@@ -0,0 +1,174 @@
+"""Quote-aware tokenizing of a shell command for the verified-commit gate.
+
+::
+
+    echo "Next: git commit"   -> the quoted "git" is prose, not gated
+    "git" commit               -> the quoted "git" is a wrapper-quoted binary, gated
+
+The gate reads a raw command string, so it needs its own lightweight
+quote-awareness to tell a real ``git`` invocation from a ``git`` word sitting
+inside a quoted commit message, a ``gh pr comment`` body, or an ``echo``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from config.verified_commit_constants import ALL_GIT_BINARY_NAMES
+
+
+def collapse_line_continuations(command_text: str) -> str:
+    """Remove backslash-newline line continuations the shell would erase.
+
+    Bash joins a line continuation by deleting both characters, so
+    ``git \\<newline>commit`` runs as a plain ``git commit``. Stripping the
+    pair before tokenizing makes the token stream match what the shell
+    executes.
+
+    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 command_carries_trailing_marker(command_text: str, marker: str) -> bool:
+    """Decide whether a marker appears as a real trailing shell comment.
+
+    ::
+
+        git commit -m "wire up" # verify-skip     -> True  (real comment)
+        git commit -m "the # verify-skip hatch"   -> False (inside quotes)
+
+    The marker counts only when its leading ``#`` sits at a word boundary and
+    outside every quoted region, so a data-only mention does not trip it.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+        marker: The comment marker to detect (for example ``# verify-skip``).
+
+    Returns:
+        True when the marker begins a real trailing comment outside quotes.
+    """
+    all_quoted_spans = quoted_spans(command_text)
+    search_start = 0
+    while True:
+        marker_index = command_text.find(marker, search_start)
+        if marker_index < 0:
+            return False
+        preceding_character = command_text[marker_index - 1] if marker_index > 0 else ""
+        begins_at_word_boundary = marker_index == 0 or preceding_character.isspace()
+        is_outside_quotes = not is_inside_quoted_region(marker_index, all_quoted_spans)
+        if begins_at_word_boundary and is_outside_quotes:
+            return True
+        search_start = marker_index + 1
+
+
+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 _quoted_final_path_segment(command_text: str, all_quoted_span_bounds: tuple[int, int]) -> str:
+    """Read the lowercased final path segment of a quoted region's content."""
+    span_start, span_end = all_quoted_span_bounds
+    quoted_content = strip_token_quotes(command_text[span_start:span_end])
+    return re.split(r"[\\/]", quoted_content)[-1].lower()
+
+
+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.
+
+    ::
+
+        echo "Next: git commit"   -> quoted prose, not gated
+        "git" commit               -> quoted binary path, gated
+
+    A ``git`` word outside every quoted region always gates. Inside a quoted
+    region it gates only when the region's final ``[\\/]``-split path segment
+    is ``git`` or ``git.exe``.
+
+    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
+    return _quoted_final_path_segment(command_text, containing_span) in ALL_GIT_BINARY_NAMES

package/hooks/blocking/verified_commit_gate_parts/deny_payload.py

@@ -0,0 +1,53 @@
+"""Build the PreToolUse deny payload the verified-commit gate emits.
+
+::
+
+    deny_reason = "BLOCKED: needs a verdict"
+    build_deny_payload(deny_reason)["hookSpecificOutput"]["permissionDecision"]
+    -> "deny"
+
+The payload carries the deny decision and reason next to
+``VERIFY_SKIP_ADDITIONAL_CONTEXT``, so the blocked agent learns at the moment
+of the block when the ``# verify-skip`` marker is legitimate.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from config.verified_commit_context_constants import VERIFY_SKIP_ADDITIONAL_CONTEXT
+from config.verified_commit_gate_output_constants import (
+    DENY_PERMISSION_DECISION,
+    PRE_TOOL_USE_HOOK_EVENT_NAME,
+)
+
+
+class _HookSpecificOutput(TypedDict):
+    hookEventName: str
+    permissionDecision: str
+    permissionDecisionReason: str
+    additionalContext: str
+
+
+class DenyPayload(TypedDict):
+    hookSpecificOutput: _HookSpecificOutput
+
+
+def build_deny_payload(deny_reason: str) -> DenyPayload:
+    """Build the PreToolUse deny payload for a blocked commit/push.
+
+    Args:
+        deny_reason: The corrective message naming why the command is denied.
+
+    Returns:
+        The ``hookSpecificOutput`` deny payload, including the verify-skip
+        additional context.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": PRE_TOOL_USE_HOOK_EVENT_NAME,
+            "permissionDecision": DENY_PERMISSION_DECISION,
+            "permissionDecisionReason": deny_reason,
+            "additionalContext": VERIFY_SKIP_ADDITIONAL_CONTEXT,
+        }
+    }

package/hooks/blocking/verified_commit_gate_parts/deny_reason.py

@@ -0,0 +1,80 @@
+"""Decide whether a commit/push in a directory needs a passing verdict.
+
+::
+
+    branch has no upstream base       -> allow (nothing to verify against)
+    diff is docs/tests/AST-unchanged  -> allow (mechanically exempt)
+    a minted or workflow verdict binds -> allow
+    otherwise                          -> deny, quoting the surface hash
+
+A verdict binds by the content hash of the live change surface, not by
+work-tree location, so a verdict minted while verifying any work tree of the
+same surface clears the commit.
+"""
+
+from __future__ import annotations
+
+from config.verified_commit_constants import CORRECTIVE_MESSAGE, HASH_PREVIEW_LENGTH
+from verification_verdict_store import (
+    branch_surface_manifest,
+    is_verification_exempt_diff,
+    load_valid_verdict,
+    manifest_sha256,
+    minted_verdict_covers_surface,
+    resolve_merge_base,
+    resolve_repo_root,
+    workflow_verdict_covers_surface,
+)
+
+
+def _resolve_repo_and_base(target_directory: str) -> tuple[str, str] | None:
+    """Resolve the repo root and merge-base for a directory, or None."""
+    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
+    return repo_root, merge_base_sha
+
+
+def _verdict_covers_surface(
+    repo_root: str, live_manifest_sha256: str, transcript_path: str
+) -> bool:
+    """Decide whether any passing verdict already binds to the live surface.
+
+    A workflow-spawned code-verifier's own transcript covers the workflow
+    case, where SubagentStop never fires to mint a verdict file.
+    """
+    if load_valid_verdict(repo_root, live_manifest_sha256) is not None:
+        return True
+    if minted_verdict_covers_surface(live_manifest_sha256):
+        return True
+    return workflow_verdict_covers_surface(transcript_path, live_manifest_sha256)
+
+
+def deny_reason_for_directory(target_directory: str, transcript_path: str) -> str | None:
+    """Decide whether a commit/push in a directory must be blocked.
+
+    Args:
+        target_directory: The directory the git command targets.
+        transcript_path: The live session's transcript path from the payload.
+
+    Returns:
+        The deny reason when the branch diff needs a verdict and none binds
+        to it; None when the command may proceed.
+    """
+    repo_and_base = _resolve_repo_and_base(target_directory)
+    if repo_and_base is None:
+        return None
+    repo_root, merge_base_sha = repo_and_base
+    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 _verdict_covers_surface(repo_root, live_manifest_sha256, transcript_path):
+        return None
+    hash_preview = live_manifest_sha256[:HASH_PREVIEW_LENGTH]
+    return f"{CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"

package/hooks/blocking/verified_commit_gate_parts/directory_resolution.py

@@ -0,0 +1,170 @@
+"""Resolve the active directory a ``cd``/``pushd`` verb leaves the shell in.
+
+::
+
+    cd subdir && git commit    -> commit gates against session_dir/subdir
+    cd /repo && git commit     -> commit gates against /repo
+
+A gated git invocation with no ``-C``/``--work-tree`` flag runs in whatever
+directory the shell is in at that point in the command, so the gate walks
+each directory-change verb to know the directory the following commit
+actually targets.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+from config.verified_commit_constants import (
+    DIRECTORY_CHANGE_OPTION_TERMINATOR,
+    DIRECTORY_CHANGE_PATH_OPTIONS,
+)
+from verified_commit_gate_parts.command_tokenization import strip_token_quotes
+
+
+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 expands 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 becomes the new 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 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 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.
+
+    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