claude-dev-env 2.2.1 → 2.4.0

package/hooks/blocking/code_review_stamp_directory_write_blocker.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""PreToolUse guard: deny shell and file-tool access to the stamp directory.
+
+The push and PR-create gates trust a single invariant: only
+``invoke_code_review.py --record-stamp`` mints stamp files under
+``~/.claude/code-review-stamps/``. settings.json cannot be the only shipped
+protection, so this guard fires on both surfaces:
+
+- Bash / PowerShell: deny any command that names the stamp directory (absolute
+  path, cd-then-relative write, cd into the stamp directory, a split directory
+  change through the Claude home into the stamp directory, stamp-file shape, a
+  path-join write, or a path assembled by obfuscation that decodes to a stamp
+  segment), or that imports the stamp store module or calls its mint function.
+- Write / Edit / MultiEdit: deny any path under the stamp directory.
+
+No legitimate workflow reaches that directory through a shell or the file
+tools: the invoker writes in-process after a clean review, so the sanctioned
+minter command names none of these matchers and passes without an allowlist.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    if _blocking_directory not in sys.path:
+        sys.path.insert(0, _blocking_directory)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_directory not in sys.path:
+        sys.path.append(_hooks_directory)
+
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+
+    register_code_review_enforcement_constants()
+    register_verified_commit_constants()
+
+    from code_review_stamp_store import stamp_directory
+    from code_review_stamp_write_blocker_parts.obfuscated_stamp_path_reference import (
+        references_obfuscated_stamp_path,
+    )
+    from code_review_stamp_write_blocker_parts.split_directory_change_into_stamp import (
+        changes_through_split_directory_into_stamp,
+        directory_change_prefix,
+    )
+    from config.code_review_enforcement_constants import (
+        ALL_GATED_SHELL_TOOL_NAMES,
+        ALL_STAMP_STORE_FORGE_PATTERNS,
+        ALL_WRITE_EDIT_TOOL_NAMES,
+        DENY_PERMISSION_DECISION,
+        PRE_TOOL_USE_HOOK_EVENT_NAME,
+        RELATIVE_STAMP_DIRECTORY_PATTERN,
+        STAMP_DIRECTORY_GUARD_MESSAGE,
+        STAMP_DIRECTORY_NAME,
+        STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN,
+        STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN,
+        STAMP_WRITE_BLOCKER_HOOK_MODULE_NAME,
+    )
+    from config.verified_commit_constants import (
+        CLAUDE_HOME_DIRECTORY_NAME,
+        CLAUDE_HOME_TARGET_BOUNDARY_PATTERN,
+        COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN,
+        DIRECTORY_CHANGE_TARGET_PATTERN,
+        NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN,
+        ROOT_KEY_HEX_LENGTH,
+        VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN,
+        VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN,
+        VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN,
+        VERDICT_PATH_GLUE_PATTERN,
+    )
+
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.pre_tool_use_stdin import (
+        read_hook_input_dictionary_from_stdin,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "code_review_stamp_directory_write_blocker: cannot import its dependencies; "
+        "ensure the blocking directory is importable."
+    ) from import_error
+
+
+def _stamp_file_relative_reference_pattern() -> str:
+    """Build the ``code-review-stamps/<root-key>.json`` stamp-file shape pattern."""
+    root_key_json_suffix = STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN % ROOT_KEY_HEX_LENGTH
+    return (
+        f"{STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN}"
+        f"{re.escape(STAMP_DIRECTORY_NAME)}{root_key_json_suffix}"
+    )
+
+
+def _references_absolute_stamp_path(command_text: str) -> bool:
+    """Decide whether a command names an absolute stamp-directory path."""
+    stamp_directory_pattern = re.compile(
+        re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN
+        + re.escape(STAMP_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    return stamp_directory_pattern.search(command_text) is not None
+
+
+def _changes_into_claude_home_then_writes_relative(command_text: str) -> bool:
+    """Decide whether a command enters the Claude home then writes the stamp dir."""
+    directory_change_into_claude_pattern = re.compile(
+        directory_change_prefix()
+        + DIRECTORY_CHANGE_TARGET_PATTERN
+        + re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + CLAUDE_HOME_TARGET_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    change_match = directory_change_into_claude_pattern.search(command_text)
+    if change_match is None:
+        return False
+    relative_stamp_pattern = re.compile(RELATIVE_STAMP_DIRECTORY_PATTERN, re.IGNORECASE)
+    return relative_stamp_pattern.search(command_text, change_match.end()) is not None
+
+
+def _changes_into_stamp_directory_then_writes(command_text: str) -> bool:
+    """Decide whether a command enters the stamp directory then runs a command."""
+    directory_change_into_stamp_pattern = re.compile(
+        directory_change_prefix()
+        + DIRECTORY_CHANGE_TARGET_PATTERN
+        + re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + r"[\\/]"
+        + re.escape(STAMP_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    change_match = directory_change_into_stamp_pattern.search(command_text)
+    if change_match is None:
+        return False
+    command_after_change_pattern = re.compile(COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN)
+    return (
+        command_after_change_pattern.search(command_text, change_match.end())
+        is not None
+    )
+
+
+def _references_stamp_file_shape(command_text: str) -> bool:
+    """Decide whether a command names a stamp file's ``<root-key>.json`` shape."""
+    stamp_file_pattern = re.compile(
+        _stamp_file_relative_reference_pattern(), re.IGNORECASE
+    )
+    return stamp_file_pattern.search(command_text) is not None
+
+
+def _segments_join_as_stamp_path(command_text: str) -> bool:
+    """Decide whether the two name segments sit adjacent in a path-join shape."""
+    home_name = re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+    stamp_name = re.escape(STAMP_DIRECTORY_NAME)
+    path_join_pattern = re.compile(
+        home_name
+        + VERDICT_PATH_GLUE_PATTERN
+        + stamp_name
+        + "|"
+        + stamp_name
+        + VERDICT_PATH_GLUE_PATTERN
+        + home_name,
+        re.IGNORECASE,
+    )
+    return path_join_pattern.search(command_text) is not None
+
+
+def _writes_with_stamp_path_intent(command_text: str) -> bool:
+    """Decide whether a write joins the two name segments into a stamp path."""
+    has_non_redirect_write = (
+        re.search(NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN, command_text) is not None
+    )
+    if not has_non_redirect_write:
+        return False
+    return _segments_join_as_stamp_path(command_text)
+
+
+def _references_store_module_or_mint_call(command_text: str) -> bool:
+    """Decide whether a command imports the stamp store or calls its mint call.
+
+    ::
+
+        python -c "from code_review_stamp_store import record_clean_stamp"  -> True
+        python -c "record_clean_stamp(root, live_hash, 'xhigh')"            -> True
+        python -m pytest test_code_review_stamp_store.py                    -> False
+
+    A forge that re-implements the mint in-process names no stamp path, so the
+    path matchers miss it. Matching the store import and the mint call closes
+    that gap. A pytest run naming the store test file matches none of these.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        True when the command imports ``code_review_stamp_store`` or calls
+        ``record_clean_stamp``; False otherwise.
+    """
+    for each_forge_pattern in ALL_STAMP_STORE_FORGE_PATTERNS:
+        if re.search(each_forge_pattern, command_text):
+            return True
+    return False
+
+
+def references_stamp_directory(command_text: str) -> bool:
+    """Decide whether a command references the code-review stamp directory.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        True when the command names the stamp directory through any matcher — a
+        store import or mint call, an absolute path, a cd-then-relative write, a
+        cd into the directory, a split directory change into the directory, a
+        stamp-file shape, a path-join write, or an obfuscation-decoded stamp
+        segment; False otherwise.
+    """
+    if _references_store_module_or_mint_call(command_text):
+        return True
+    if _references_absolute_stamp_path(command_text):
+        return True
+    if _changes_into_claude_home_then_writes_relative(command_text):
+        return True
+    if _changes_into_stamp_directory_then_writes(command_text):
+        return True
+    if changes_through_split_directory_into_stamp(command_text):
+        return True
+    if _references_stamp_file_shape(command_text):
+        return True
+    if _writes_with_stamp_path_intent(command_text):
+        return True
+    return references_obfuscated_stamp_path(command_text)
+
+
+def path_targets_stamp_directory(file_path: str) -> bool:
+    """Decide whether a Write/Edit/MultiEdit path sits under the stamp directory.
+
+    Args:
+        file_path: The path the file tool targets.
+
+    Returns:
+        True when the resolved path is under ``~/.claude/code-review-stamps/``.
+    """
+    if not file_path:
+        return False
+    try:
+        resolved_target = Path(file_path).expanduser().resolve()
+        resolved_stamp_root = stamp_directory().resolve()
+    except OSError:
+        return False
+    if resolved_target == resolved_stamp_root:
+        return True
+    try:
+        resolved_target.relative_to(resolved_stamp_root)
+    except ValueError:
+        return False
+    return True
+
+
+def build_deny_payload() -> dict[str, dict[str, str]]:
+    """Build the PreToolUse deny payload for a stamp-directory access."""
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": PRE_TOOL_USE_HOOK_EVENT_NAME,
+            "permissionDecision": DENY_PERMISSION_DECISION,
+            "permissionDecisionReason": STAMP_DIRECTORY_GUARD_MESSAGE,
+        }
+    }
+
+
+def _shell_decision(all_tool_input: dict[str, object]) -> dict[str, dict[str, str]] | None:
+    """Return the deny payload when a shell command targets the stamp directory."""
+    command_text = all_tool_input.get("command", "")
+    if not isinstance(command_text, str) or not command_text:
+        return None
+    if not references_stamp_directory(command_text):
+        return None
+    return build_deny_payload()
+
+
+def _file_decision(all_tool_input: dict[str, object]) -> dict[str, dict[str, str]] | None:
+    """Return the deny payload when a file-tool path targets the stamp directory."""
+    file_path = all_tool_input.get("file_path", "")
+    if not isinstance(file_path, str):
+        return None
+    if not path_targets_stamp_directory(file_path):
+        return None
+    return build_deny_payload()
+
+
+def decision_for_payload(
+    all_pretooluse_payload: dict[str, object],
+) -> dict[str, dict[str, str]] | None:
+    """Build the deny decision for stamp-directory shell or file-tool access.
+
+    Args:
+        all_pretooluse_payload: The PreToolUse hook payload.
+
+    Returns:
+        The deny decision mapping when a gated tool targets the stamp
+        directory; None when the tool call may proceed.
+    """
+    tool_name = all_pretooluse_payload.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        return None
+    tool_input = all_pretooluse_payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return None
+    if tool_name in ALL_GATED_SHELL_TOOL_NAMES:
+        return _shell_decision(tool_input)
+    if tool_name not in ALL_WRITE_EDIT_TOOL_NAMES:
+        return None
+    return _file_decision(tool_input)
+
+
+def main() -> None:
+    """Read the PreToolUse payload and deny stamp-directory access."""
+    pretooluse_payload = read_hook_input_dictionary_from_stdin()
+    if pretooluse_payload is None:
+        return
+    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=STAMP_WRITE_BLOCKER_HOOK_MODULE_NAME,
+        hook_event=PRE_TOOL_USE_HOOK_EVENT_NAME,
+        block_reason=STAMP_DIRECTORY_GUARD_MESSAGE,
+        tool_name=tool_name_for_log,
+    )
+    sys.stdout.write(json.dumps(deny_decision) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/code_review_stamp_store.py

@@ -0,0 +1,233 @@
+"""Read and write the per-work-tree code-review stamp files.
+
+A stamp records that a clean ``/code-review`` pass ran against an exact branch
+surface at a given effort. Each work tree keeps one JSON file under
+``~/.claude/code-review-stamps/`` mapping an effort token to the surface hash it
+was earned against, so a later push or pull-request gate can ask whether a
+clean review at the needed effort already covers the live surface. This module
+only reads and writes those files; it runs no review.
+
+::
+
+    record_clean_stamp(root, hash_a, "low")
+    stamp_covers_surface(root, hash_a, "low")   -> True   (recorded, matching)
+    stamp_covers_surface(root, hash_a, "xhigh") -> False  (low is below xhigh)
+    stamp_covers_surface(root, hash_b, "low")   -> False  (surface hash differs)
+
+Coverage fails closed: a missing, unreadable, or malformed stamp file, a hash
+that does not match, and an effort below the threshold all read as not covered.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+
+try:
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+except ModuleNotFoundError:
+    if _blocking_directory not in sys.path:
+        sys.path.insert(0, _blocking_directory)
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+
+register_code_review_enforcement_constants()
+register_verified_commit_constants()
+
+try:
+    from config.code_review_enforcement_constants import (
+        STAMP_DIRECTORY_NAME,
+        STAMP_KEY_EFFORT,
+        STAMP_KEY_MANIFEST_SHA256,
+        STAMP_KEY_RECORDED_AT_EPOCH,
+        effort_meets_threshold,
+    )
+    from config.verified_commit_constants import (
+        CLAUDE_HOME_DIRECTORY_NAME,
+        VERDICT_JSON_INDENT,
+    )
+    from verification_verdict_store import (
+        branch_surface_manifest,
+        empty_surface_hash,
+        manifest_sha256,
+        resolve_merge_base,
+        resolve_repo_root,
+        root_key_for_repo,
+    )
+except ModuleNotFoundError:
+    if _blocking_directory not in sys.path:
+        sys.path.insert(0, _blocking_directory)
+    from config.code_review_enforcement_constants import (
+        STAMP_DIRECTORY_NAME,
+        STAMP_KEY_EFFORT,
+        STAMP_KEY_MANIFEST_SHA256,
+        STAMP_KEY_RECORDED_AT_EPOCH,
+        effort_meets_threshold,
+    )
+    from config.verified_commit_constants import (
+        CLAUDE_HOME_DIRECTORY_NAME,
+        VERDICT_JSON_INDENT,
+    )
+    from verification_verdict_store import (
+        branch_surface_manifest,
+        empty_surface_hash,
+        manifest_sha256,
+        resolve_merge_base,
+        resolve_repo_root,
+        root_key_for_repo,
+    )
+
+
+def stamp_directory() -> Path:
+    """Return the shared directory holding every work tree's stamp file.
+
+    Stamps live outside any repository (under the user's Claude home) so no repo
+    accumulates untracked stamp files; every work tree's stamp shares this one
+    directory, distinguished by file name.
+
+    Returns:
+        The stamp directory under the user's Claude home.
+    """
+    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME / STAMP_DIRECTORY_NAME
+
+
+def stamp_path_for_repo(repo_root: str) -> Path:
+    """Derive the stamp file path for a repository work tree.
+
+    Keyed by the shared ``root_key_for_repo`` derivation, so every work tree
+    gets its own stamp file and a subdirectory of a work tree resolves to the
+    same key as its root.
+
+    Args:
+        repo_root: The repository top-level directory.
+
+    Returns:
+        The stamp file path for this work tree.
+    """
+    return stamp_directory() / f"{root_key_for_repo(repo_root)}.json"
+
+
+def _read_stamps_by_effort(stamp_file: Path) -> dict[str, object]:
+    """Read the per-effort stamp records for a work tree, or an empty map.
+
+    ::
+
+        <root-key>.json holds {"low": {...}, "xhigh": {...}}  -> that map
+        file missing / unreadable / not a JSON object          -> {}
+
+    A missing, unreadable, or malformed stamp file yields an empty map, so a
+    caller reading it sees no coverage and fails closed.
+
+    Args:
+        stamp_file: The per-work-tree stamp file path.
+
+    Returns:
+        The mapping of effort token to its stored record, or an empty map when
+        the file is absent, unreadable, or not a JSON object.
+    """
+    try:
+        parsed_stamps = json.loads(stamp_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(parsed_stamps, dict):
+        return {}
+    return parsed_stamps
+
+
+def record_clean_stamp(repo_root: str, bound_manifest_sha256: str, effort: str) -> Path:
+    """Write one effort's clean-review stamp for a work tree.
+
+    Reads any existing per-effort records, sets this effort's entry to the given
+    surface hash and the current epoch, and writes the map back. Recording a
+    second effort keeps the first; recording the same effort again overwrites
+    its bound hash.
+
+    Args:
+        repo_root: The repository top-level directory.
+        bound_manifest_sha256: Hash of the branch surface the clean review covered.
+        effort: The effort token the clean review ran at.
+
+    Returns:
+        The stamp file path the record was written to.
+    """
+    stamp_file = stamp_path_for_repo(repo_root)
+    stamp_file.parent.mkdir(parents=True, exist_ok=True)
+    all_stamps_by_effort = _read_stamps_by_effort(stamp_file)
+    all_stamps_by_effort[effort] = {
+        STAMP_KEY_EFFORT: effort,
+        STAMP_KEY_MANIFEST_SHA256: bound_manifest_sha256,
+        STAMP_KEY_RECORDED_AT_EPOCH: int(time.time()),
+    }
+    stamp_file.write_text(
+        json.dumps(all_stamps_by_effort, indent=VERDICT_JSON_INDENT), encoding="utf-8"
+    )
+    return stamp_file
+
+
+def stamp_covers_surface(repo_root: str, live_manifest_sha256: str, required_effort: str) -> bool:
+    """Decide whether a clean stamp covers the live surface at the needed effort.
+
+    A stored entry covers the surface when its bound hash equals the live hash
+    exactly and its effort ranks at or above the required effort. Any missing,
+    unreadable, or malformed stamp reads as not covered.
+
+    Args:
+        repo_root: The repository top-level directory.
+        live_manifest_sha256: Hash of the live branch surface the gate checks.
+        required_effort: The effort the gate demands for the action.
+
+    Returns:
+        True as soon as one stored entry matches the live hash and meets the
+        required effort; False when none match.
+    """
+    all_stamps_by_effort = _read_stamps_by_effort(stamp_path_for_repo(repo_root))
+    for each_stamp_record in all_stamps_by_effort.values():
+        if not isinstance(each_stamp_record, dict):
+            continue
+        if each_stamp_record.get(STAMP_KEY_MANIFEST_SHA256) != live_manifest_sha256:
+            continue
+        stored_effort = each_stamp_record.get(STAMP_KEY_EFFORT)
+        if not isinstance(stored_effort, str):
+            continue
+        if effort_meets_threshold(stored_effort, required_effort):
+            return True
+    return False
+
+
+def live_surface_hash(work_tree_directory: str) -> str | None:
+    """Compute the live branch-surface manifest hash for a work tree.
+
+    Resolves the work tree's repo root and merge base, then hashes the current
+    change surface — every changed path and untracked file bound by its content
+    digest — so the hash tracks the exact bytes under review.
+
+    Args:
+        work_tree_directory: A directory inside the work tree to hash.
+
+    Returns:
+        The surface manifest hash, or None when the directory is outside a work
+        tree, the merge base or manifest cannot be resolved, or the change
+        surface is empty (HEAD equals the merge base, so nothing is under review).
+    """
+    repo_root = resolve_repo_root(work_tree_directory)
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if surface_manifest_text is None:
+        return None
+    surface_hash = manifest_sha256(surface_manifest_text)
+    if surface_hash == empty_surface_hash():
+        return None
+    return surface_hash

package/hooks/blocking/code_review_stamp_write_blocker_parts/__init__.py

@@ -0,0 +1,7 @@
+"""Concern modules of the code-review stamp write blocker, wired by the entry hook.
+
+The entry hook ``code_review_stamp_directory_write_blocker.py`` imports two
+public matchers from this package to keep its own file short: a split
+directory-change matcher and an obfuscated-path-write matcher. Each mirrors the
+sibling verdict-directory guard's logic against the code-review stamp segments.
+"""

package/hooks/blocking/code_review_stamp_write_blocker_parts/conftest.py

@@ -0,0 +1,15 @@
+"""Put the blocking and hooks directories on sys.path for the parts tests.
+
+The concern modules import their shared constants as ``from config...`` against
+the sibling ``blocking/config/`` package, so the tests need the blocking
+directory (which holds that package) and the hooks directory on the path.
+"""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parents[1])
+_hooks_directory = str(Path(__file__).resolve().parents[2])
+for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+    if each_bootstrap_directory not in sys.path:
+        sys.path.insert(0, each_bootstrap_directory)