claude-dev-env 2.3.0 → 2.5.0

package/hooks/blocking/code_review_stamp_write_blocker_parts/test_split_directory_change_into_stamp.py

@@ -0,0 +1,38 @@
+"""Behavioral tests for the split directory-change-into-stamp matcher.
+
+The matcher blocks a command that changes into the Claude home, then into a
+relative ``code-review-stamps`` directory, then runs any further command, while
+an unrelated second change or a benign command passes.
+"""
+
+from __future__ import annotations
+
+from code_review_stamp_write_blocker_parts.split_directory_change_into_stamp import (
+    changes_through_split_directory_into_stamp,
+)
+
+SPLIT_CHANGE_FORGE = "cd ~/.claude && cd code-review-stamps && echo x > f.json"
+UNRELATED_SECOND_CHANGE = "cd ~/.claude && cd hooks && echo x > f.json"
+PYTEST_RUN = "python -m pytest test_code_review_stamp_store.py"
+
+
+def test_split_change_into_stamp_then_command_is_blocked() -> None:
+    assert changes_through_split_directory_into_stamp(SPLIT_CHANGE_FORGE)
+
+
+def test_unrelated_second_change_is_not_blocked() -> None:
+    assert not changes_through_split_directory_into_stamp(UNRELATED_SECOND_CHANGE)
+
+
+def test_pytest_run_is_not_blocked() -> None:
+    assert not changes_through_split_directory_into_stamp(PYTEST_RUN)
+
+
+def test_change_into_stamp_without_following_command_is_not_blocked() -> None:
+    assert not changes_through_split_directory_into_stamp("cd ~/.claude && cd code-review-stamps")
+
+
+def test_pushd_split_change_into_stamp_then_command_is_blocked() -> None:
+    assert changes_through_split_directory_into_stamp(
+        "pushd ~/.claude && pushd code-review-stamps && cp a b"
+    )

package/hooks/blocking/code_verifier_spawn_preflight_gate.py

@@ -1,18 +1,19 @@
 #!/usr/bin/env python3
 """PreToolUse hook: pre-flight gate for the code-verifier subagent spawn.
 
-The hook fires only on an ``Agent`` tool call whose ``subagent_type`` is
+The hook fires on an ``Agent`` or ``Task`` tool call whose ``subagent_type`` is
 ``code-verifier``. Before that verification spawn runs, the hook checks the
 branch for two committability problems against the resolved base ref: a real
 merge conflict (a non-mutating trial-merge of HEAD against the base ref) and a
 CODE_RULES violation on a line added in the working tree since the merge base
-(committed on the branch or uncommitted). When
-either fires, the hook denies the spawn with a reason addressed to the spawning
-agent that names the conflicting files and the violating file:line, so that
-agent fixes them and re-spawns. Both checks fail OPEN on any infrastructure
-problem — a non-repo cwd, an absent base ref, a git or engine failure, or a
-timeout — because the authoritative fail-closed CODE_RULES enforcement already
-runs at Write time and at commit time. The hook never network-fetches and never
+(committed on the branch or uncommitted). When either fires, the hook denies
+the spawn with a reason addressed to the spawning agent that names the
+conflicting files and the violating file:line, so that agent fixes them and
+re-spawns. A CODE_RULES engine import/load failure is fail-closed (deny with a
+named load-failure section). Environmental problems — a non-repo cwd, an
+absent base ref, a git failure, an unreadable file alone, or a timeout — fail
+OPEN because the authoritative fail-closed CODE_RULES enforcement already runs
+at Write time and at commit time. The hook never network-fetches and never
 mutates the index or working tree.
 """
 
@@ -21,6 +22,7 @@ from __future__ import annotations
 import contextlib
 import io
 import json
+import re
 import subprocess
 import sys
 from pathlib import Path
@@ -43,6 +45,7 @@ from verification_verdict_store import (  # noqa: E402
 )
 
 from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # noqa: E402
+    ALL_CODE_VERIFIER_SPAWN_TOOL_NAMES,
     ALL_MERGE_HEAD_PROBE_FLAGS,
     ALL_MERGE_TREE_COMMAND_FLAGS,
     ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS,
@@ -51,6 +54,7 @@ from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # no
     CODE_RULES_SECTION_HEADER,
     CODE_VERIFIER_SUBAGENT_TYPE,
     DENY_REASON_LEAD,
+    ENGINE_LOAD_FAILURE_SECTION,
     GATE_SCRIPTS_RELATIVE_PATH,
     MERGE_CONFLICT_SECTION_HEADER,
     MERGE_TREE_CLEAN_EXIT_CODE,
@@ -58,9 +62,6 @@ from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # no
     MERGE_TREE_TIMEOUT_SECONDS,
 )
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-from hooks_constants.pr_converge_bugteam_enforcer_constants import (  # noqa: E402
-    AGENT_TOOL_NAME,
-)
 
 _scripts_dir = str(Path(__file__).resolve().parents[2] / GATE_SCRIPTS_RELATIVE_PATH)
 if _scripts_dir not in sys.path:
@@ -78,17 +79,17 @@ from code_rules_gate import (  # noqa: E402
 
 
 def _should_run(payload_by_field: dict[str, object]) -> bool:
-    """Return True only for a code-verifier Agent spawn.
+    """Return True only for a code-verifier Agent or Task spawn.
 
     Args:
         payload_by_field: The full PreToolUse hook payload (already
             JSON-parsed), keyed by top-level field name.
 
     Returns:
-        True when the tool is Agent and ``tool_input.subagent_type`` is
-        ``code-verifier``; False for every other shape.
+        True when the tool is Agent or Task and ``tool_input.subagent_type``
+        is ``code-verifier``; False for every other shape.
     """
-    if payload_by_field.get("tool_name", "") != AGENT_TOOL_NAME:
+    if payload_by_field.get("tool_name", "") not in ALL_CODE_VERIFIER_SPAWN_TOOL_NAMES:
         return False
     tool_input = payload_by_field.get("tool_input", {})
     if not isinstance(tool_input, dict):
@@ -297,7 +298,7 @@ def _tracked_file_added_lines(repo_root: str, merge_base_sha: str, relative_path
 def _code_rules_report(
     repo_root: str, all_file_paths: list[Path], all_added_lines_by_path: dict[Path, set[int]]
 ) -> str | None:
-    """Run the CODE_RULES engine and return its blocking report, or None.
+    """Run the CODE_RULES engine and return a full deny section, or None.
 
     Args:
         repo_root: The repository top-level directory.
@@ -306,19 +307,30 @@ def _code_rules_report(
             by resolved absolute path.
 
     Returns:
-        The engine's grouped file:line report when a blocking violation lands
-        on an added line, or None when the surface is clean, only an unreadable
-        changed file caused a non-zero gate exit, the engine fails to load, or
-        any engine error arises — every non-block outcome fails OPEN. The
-        harness hook timeout in hooks.json is the wall-clock bound on a runaway
-        engine.
+        A full deny section when a blocking violation lands on an added line or
+        the CODE_RULES engine fails to import/load (fail-closed). None when the
+        surface is clean, only an unreadable changed file caused a non-zero gate
+        exit, or an environmental engine error arises — those non-block outcomes
+        fail OPEN. The harness hook timeout in hooks.json is the wall-clock
+        bound on a runaway engine.
     """
     if not all_file_paths:
         return None
     try:
         validate_content = load_validate_content()
     except SystemExit:
-        return None
+        return ENGINE_LOAD_FAILURE_SECTION
+    except (
+        ImportError,
+        SyntaxError,
+        AttributeError,
+        RuntimeError,
+        TypeError,
+        NameError,
+        OSError,
+        re.error,
+    ):
+        return ENGINE_LOAD_FAILURE_SECTION
     try:
         blocking_present, captured_report = _run_gate_capturing_stderr(
             validate_content, all_file_paths, Path(repo_root), all_added_lines_by_path
@@ -327,7 +339,7 @@ def _code_rules_report(
         return None
     if not blocking_present:
         return None
-    return captured_report
+    return f"{CODE_RULES_SECTION_HEADER}\n{captured_report.strip()}"
 
 
 def _run_gate_capturing_stderr(
@@ -382,8 +394,8 @@ def _build_deny_reason(
         all_conflicting_files: The conflicting file paths from the conflict
             check, an empty list when clean, or None when that check failed open.
         base_ref: The base ref named in the conflict section header.
-        code_rules_report: The grouped report from the CODE_RULES check, or None
-            when that check found nothing or failed open.
+        code_rules_report: A full CODE_RULES deny section (violations or engine
+            load failure), or None when that check found nothing or failed open.
 
     Returns:
         The full deny reason when either check fired, or None when neither
@@ -395,7 +407,7 @@ def _build_deny_reason(
         conflict_header = MERGE_CONFLICT_SECTION_HEADER.format(base_ref=base_ref)
         reason_sections.append(f"{conflict_header}\n{conflict_lines}")
     if code_rules_report:
-        reason_sections.append(f"{CODE_RULES_SECTION_HEADER}\n{code_rules_report.strip()}")
+        reason_sections.append(code_rules_report.strip())
     if not reason_sections:
         return None
     return DENY_REASON_LEAD + "\n\n" + "\n\n".join(reason_sections)

package/hooks/blocking/config/__init__.py

@@ -1,5 +1,5 @@
-"""Configuration package for the blocking hooks.
-
-A regular package (not a namespace package) so it resolves ahead of any
-same-named package later on ``sys.path``.
-"""
+"""Configuration package for the blocking hooks.
+
+A regular package (not a namespace package) so it resolves ahead of any
+same-named package later on ``sys.path``.
+"""

package/hooks/blocking/config/code_review_enforcement_constants.py

@@ -0,0 +1,113 @@
+"""Single source of truth for the code-review enforcement gate family.
+
+Holds the stamp directory name, the ordered effort tokens (``low`` under
+``medium`` under ``high`` under ``xhigh`` under ``max``, with ``ultra`` kept
+out because it needs an interactive terminal), the effort a push and a
+pull-request creation each require, the stamp record keys, the gate and
+write-blocker messages, the store-forge shell patterns, the MCP create-PR
+tool name, and the effort comparison every gate and the stamp store share so
+the thresholds never drift between them, and the master enable flag
+(``CODE_REVIEW_ENFORCEMENT_ENABLED``, default off) that every gate and
+the stamp-directory write-blocker read before they enforce anything.
+"""
+
+from __future__ import annotations
+
+CODE_REVIEW_ENFORCEMENT_ENABLED = False
+STAMP_DIRECTORY_NAME = "code-review-stamps"
+ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER = ("low", "medium", "high", "xhigh", "max")
+PUSH_REQUIRED_EFFORT = "low"
+PR_CREATE_REQUIRED_EFFORT = "xhigh"
+STAMP_KEY_EFFORT = "effort"
+STAMP_KEY_MANIFEST_SHA256 = "manifest_sha256"
+STAMP_KEY_RECORDED_AT_EPOCH = "recorded_at_epoch"
+CODE_REVIEW_BYPASS_MARKER = "# code-review-skip"
+GATED_PUSH_SUBCOMMANDS = frozenset({"push"})
+ALL_GATED_SHELL_TOOL_NAMES = ("Bash", "PowerShell")
+ALL_WRITE_EDIT_TOOL_NAMES = ("Write", "Edit", "MultiEdit")
+MCP_CREATE_PULL_REQUEST_TOOL_NAME = "mcp__plugin_github_github__create_pull_request"
+HASH_PREVIEW_LENGTH = 16
+PRE_TOOL_USE_HOOK_EVENT_NAME = "PreToolUse"
+DENY_PERMISSION_DECISION = "deny"
+PUSH_GATE_HOOK_MODULE_NAME = "code_review_push_gate.py"
+PR_CREATE_GATE_HOOK_MODULE_NAME = "code_review_pr_create_gate.py"
+STAMP_WRITE_BLOCKER_HOOK_MODULE_NAME = "code_review_stamp_directory_write_blocker.py"
+SANCTIONED_STAMP_MINTER_FLAG = "--record-stamp"
+PUSH_GATE_CORRECTIVE_MESSAGE = (
+    "BLOCKED: [CODE_REVIEW_PUSH_GATE] This branch surface has no clean "
+    "code-review stamp at effort 'low' or higher. Run "
+    "`python invoke_code_review.py --record-stamp --cwd <dir> "
+    "--session-model <alias> low` (or a higher effort) so a clean review "
+    "mints the stamp before `git push`; any file change after minting "
+    "invalidates it. Append `# code-review-skip` as a trailing shell comment "
+    "only when the verified-commit gate's verify-skip rule for a same-surface "
+    "re-land applies. Exempt automatically: docs/image files, pytest test "
+    "files, and Python files whose docstring- and comment-stripped AST is "
+    "unchanged."
+)
+PR_CREATE_GATE_CORRECTIVE_MESSAGE = (
+    "BLOCKED: [CODE_REVIEW_PR_CREATE_GATE] This branch surface has no clean "
+    "code-review stamp at effort 'xhigh' or higher. Run "
+    "`python invoke_code_review.py --record-stamp --cwd <dir> "
+    "--session-model <alias> xhigh` (or max) so a clean review mints the "
+    "stamp before `gh pr create` or the MCP create_pull_request tool. Any "
+    "file change after minting invalidates the stamp."
+)
+STAMP_DIRECTORY_GUARD_MESSAGE = (
+    "BLOCKED: [CODE_REVIEW_STAMP_DIRECTORY_GUARD] Access to the code-review "
+    "stamp directory (~/.claude/code-review-stamps/) is denied. Only "
+    "invoke_code_review.py --record-stamp mints stamp files; a shell or "
+    "Write/Edit forge here would defeat the push and PR-create gates. "
+    "Earn a stamp by running a clean /code-review through the invoker."
+)
+RELATIVE_STAMP_DIRECTORY_PATTERN = r"(?:^|(?<=[\s;&|(='\"]))code-review-stamps[\\/]"
+STAMP_DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?code-review-stamps[\\/]?['\"]?(?=[\s;&|]|$)"
+STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN = r"(?:^|(?<=[\s;&|(='\"\\/]))"
+STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN = r"[\\/][0-9a-f]{%d}\.json"
+GH_PR_CREATE_INVOCATION_PATTERN = (
+    r"(?:^|[;&|\n`({]|\$\()[ \t]*"
+    r"(?:(?:if|then|else|elif|while|until|do|!)[ \t]+)*"
+    r"(?:[A-Za-z_][A-Za-z0-9_]*=\S+[ \t]+)*"
+    r"gh(?:[ \t]+(?:--[A-Za-z][\w-]*(?:=\S+)?|-[A-Za-z])(?:[ \t]+(?!-)\S+)?)*"
+    r"[ \t]+pr[ \t]+create\b"
+)
+ALL_STAMP_PATH_SEGMENT_NAMES = (".claude", "code-review-stamps")
+ALL_STAMP_PATH_SEGMENT_BODIES = ("claude", "code-review-stamps")
+STAMP_STORE_MODULE_NAME = "code_review_stamp_store"
+STAMP_MINT_FUNCTION_NAME = "record_clean_stamp"
+ALL_STAMP_STORE_FORGE_PATTERNS = (
+    rf"\bimport\s+{STAMP_STORE_MODULE_NAME}\b",
+    rf"\bfrom\s+{STAMP_STORE_MODULE_NAME}\s+import\b",
+    rf"\b{STAMP_MINT_FUNCTION_NAME}\s*\(",
+)
+
+
+def effort_meets_threshold(candidate_effort: str, required_effort: str) -> bool:
+    """Decide whether a recorded effort satisfies a required threshold.
+
+    ::
+
+        effort_meets_threshold("xhigh", "low")  -> True   xhigh outranks low
+        effort_meets_threshold("low", "xhigh")  -> False  low sits below xhigh
+        effort_meets_threshold("ultra", "low")  -> False  ultra is unranked
+
+    A candidate satisfies the threshold when it sits at or above the required
+    token in the ascending order. A token outside the known order — ``ultra``
+    among them — satisfies nothing, so an unrecognized stored effort clears no
+    gate.
+
+    Args:
+        candidate_effort: The effort a recorded stamp was earned at.
+        required_effort: The effort the gate demands for the action.
+
+    Returns:
+        True when both tokens are known and the candidate ranks at or above the
+        required token; False otherwise.
+    """
+    if candidate_effort not in ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER:
+        return False
+    if required_effort not in ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER:
+        return False
+    candidate_rank = ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER.index(candidate_effort)
+    required_rank = ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER.index(required_effort)
+    return candidate_rank >= required_rank

package/hooks/blocking/config/test_code_review_enforcement_constants.py

@@ -0,0 +1,113 @@
+"""Behavioral tests for the code-review enforcement constants and comparator.
+
+These exercise ``effort_meets_threshold`` against the ordered effort tokens and
+assert the push and pull-request thresholds carry the push-based names the gate
+family reads, so a rename that reintroduces commit terminology fails loudly.
+"""
+
+import importlib.util
+import pathlib
+import re
+
+_CONFIG_DIR = pathlib.Path(__file__).parent
+
+SAMPLE_ROOT_KEY_HEX_LENGTH = 16
+
+_constants_spec = importlib.util.spec_from_file_location(
+    "code_review_enforcement_constants",
+    _CONFIG_DIR / "code_review_enforcement_constants.py",
+)
+assert _constants_spec is not None
+assert _constants_spec.loader is not None
+_constants_module = importlib.util.module_from_spec(_constants_spec)
+_constants_spec.loader.exec_module(_constants_module)
+
+effort_meets_threshold = _constants_module.effort_meets_threshold
+CODE_REVIEW_ENFORCEMENT_ENABLED = _constants_module.CODE_REVIEW_ENFORCEMENT_ENABLED
+PUSH_REQUIRED_EFFORT = _constants_module.PUSH_REQUIRED_EFFORT
+PR_CREATE_REQUIRED_EFFORT = _constants_module.PR_CREATE_REQUIRED_EFFORT
+GATED_PUSH_SUBCOMMANDS = _constants_module.GATED_PUSH_SUBCOMMANDS
+ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER = _constants_module.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+PUSH_GATE_CORRECTIVE_MESSAGE = _constants_module.PUSH_GATE_CORRECTIVE_MESSAGE
+SANCTIONED_STAMP_MINTER_FLAG = _constants_module.SANCTIONED_STAMP_MINTER_FLAG
+STAMP_DIRECTORY_GUARD_MESSAGE = _constants_module.STAMP_DIRECTORY_GUARD_MESSAGE
+STAMP_DIRECTORY_NAME = _constants_module.STAMP_DIRECTORY_NAME
+GH_PR_CREATE_INVOCATION_PATTERN = _constants_module.GH_PR_CREATE_INVOCATION_PATTERN
+STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN = (
+    _constants_module.STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN
+)
+STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN = _constants_module.STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN
+
+
+def test_gh_pr_create_pattern_matches_create_but_not_edit() -> None:
+    invocation_pattern = re.compile(GH_PR_CREATE_INVOCATION_PATTERN, re.IGNORECASE)
+    assert invocation_pattern.search("gh pr create --title T --body-file b.md") is not None
+    assert invocation_pattern.search("gh pr edit 1 --title T") is None
+
+
+def test_stamp_file_pattern_fragments_match_a_stamp_file_reference() -> None:
+    stamp_file_pattern = re.compile(
+        STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN
+        + re.escape(STAMP_DIRECTORY_NAME)
+        + STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN % SAMPLE_ROOT_KEY_HEX_LENGTH,
+        re.IGNORECASE,
+    )
+    stamp_file_reference = f"cat {STAMP_DIRECTORY_NAME}/{'a' * SAMPLE_ROOT_KEY_HEX_LENGTH}.json"
+    assert stamp_file_pattern.search(stamp_file_reference) is not None
+    assert stamp_file_pattern.search("cat notes.json") is None
+
+
+def test_higher_effort_meets_a_lower_threshold() -> None:
+    assert effort_meets_threshold("xhigh", "low") is True
+
+
+def test_lower_effort_fails_a_higher_threshold() -> None:
+    assert effort_meets_threshold("low", "xhigh") is False
+
+
+def test_equal_effort_meets_the_threshold() -> None:
+    assert effort_meets_threshold("low", "low") is True
+
+
+def test_ultra_is_unranked_and_meets_nothing() -> None:
+    assert effort_meets_threshold("ultra", "low") is False
+
+
+def test_unknown_required_effort_meets_nothing() -> None:
+    assert effort_meets_threshold("low", "ultra") is False
+
+
+def test_push_requires_the_lowest_effort_token() -> None:
+    every_token_meets_push = all(
+        effort_meets_threshold(each_token, PUSH_REQUIRED_EFFORT)
+        for each_token in ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+    )
+    assert every_token_meets_push
+
+
+def test_pr_create_threshold_admits_xhigh_but_rejects_high() -> None:
+    assert effort_meets_threshold("xhigh", PR_CREATE_REQUIRED_EFFORT) is True
+    assert effort_meets_threshold("high", PR_CREATE_REQUIRED_EFFORT) is False
+
+
+def test_gated_push_subcommands_gates_push_not_commit() -> None:
+    assert "push" in GATED_PUSH_SUBCOMMANDS
+    assert "commit" not in GATED_PUSH_SUBCOMMANDS
+
+
+def test_ultra_absent_from_the_ordered_tokens() -> None:
+    assert "ultra" not in ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+
+
+def test_push_gate_message_names_the_push_action_and_low_effort() -> None:
+    assert "git push" in PUSH_GATE_CORRECTIVE_MESSAGE
+    assert "CODE_REVIEW_PUSH_GATE" in PUSH_GATE_CORRECTIVE_MESSAGE
+    assert "'low'" in PUSH_GATE_CORRECTIVE_MESSAGE
+
+
+def test_guard_message_directs_users_to_the_sanctioned_minter_flag() -> None:
+    assert SANCTIONED_STAMP_MINTER_FLAG in STAMP_DIRECTORY_GUARD_MESSAGE
+
+
+def test_enforcement_defaults_to_off() -> None:
+    assert CODE_REVIEW_ENFORCEMENT_ENABLED is False