claude-dev-env 8.99.0 → 8.100.0

package/hooks/blocking/merge_review_gate_parts/receipts.py

@@ -0,0 +1,192 @@
+"""Read the review receipts ``scripts/merge_review_receipt.py`` writes.
+
+A numbered receipt covers one pull request. An open receipt covers one head
+reviewed before its pull request opened.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.merge_review_gate_constants import (
+    ALL_RECEIPT_DIRECTORY_SEGMENTS,
+    OPEN_HEAD_PATTERN,
+    OPEN_RECEIPT_DIRECTORY_NAME,
+    OPEN_RECEIPT_FILE_NAME_TEMPLATE,
+    OPEN_RECEIPT_GLOB_TEMPLATE,
+    OPEN_RECEIPT_HEAD_PATTERN,
+    RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE,
+    RECEIPT_FILE_NAME_TEMPLATE,
+    RECEIPT_FINDINGS_KEY,
+    RECEIPT_HEAD_KEY,
+    RECEIPT_RULED_OUT_KEY,
+    RECEIPT_RULINGS_KEY,
+    RULINGS_LINK_PATTERN,
+)
+
+
+def receipt_directory() -> Path:
+    """Return the folder that holds one review receipt per pull request.
+
+    Returns:
+        The folder CLAUDE_MERGE_REVIEW_RECEIPT_DIR names, else ``~/.claude/merge-reviews``.
+    """
+    override = os.environ.get(RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE)
+    if override:
+        return Path(override)
+    return Path.home().joinpath(*ALL_RECEIPT_DIRECTORY_SEGMENTS)
+
+
+def receipt_path(owner: str, repo: str, number: int) -> Path:
+    """Return where the review receipt for one pull request lives.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        number: Pull request number.
+
+    Returns:
+        The receipt file path.
+    """
+    return receipt_directory() / RECEIPT_FILE_NAME_TEMPLATE.format(
+        owner=owner.casefold(), repo=repo.casefold(), number=number
+    )
+
+
+def open_receipt_path(owner: str, repo: str, head: str) -> Path:
+    """Return where the review receipt for a head reviewed before its pull request opened lives.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        head: The commit the pass reviewed.
+
+    Returns:
+        The receipt file path.
+    """
+    return (
+        receipt_directory()
+        / OPEN_RECEIPT_DIRECTORY_NAME
+        / OPEN_RECEIPT_FILE_NAME_TEMPLATE.format(
+            owner=owner.casefold(), repo=repo.casefold(), head=head.casefold()
+        )
+    )
+
+
+def has_clean_open_review(repo: str, head: str) -> bool:
+    """Return whether a pass recorded before the pull request opened found zero findings at a head.
+
+    The head may be a full or an abbreviated commit, matched against each
+    recorded head by prefix. The owner is left out of the match, since a
+    checkout whose origin still names a transferred repository's old owner
+    opens against the new one::
+
+        open receipt {head: abc1234..., findings: 0}, head abc1234 -> True
+        open receipt {head: abc1234..., findings: 2}, head abc1234 -> False
+        no open receipt for the repository                          -> False
+
+    Args:
+        repo: Repository name.
+        head: The commit the open or merge names.
+
+    Returns:
+        True when a clean open receipt covers that head.
+    """
+    if not OPEN_HEAD_PATTERN.fullmatch(head):
+        return False
+    folder = receipt_directory() / OPEN_RECEIPT_DIRECTORY_NAME
+    pattern = OPEN_RECEIPT_GLOB_TEMPLATE.format(repo=repo.casefold())
+    return any(_is_clean_open_receipt(each_path, head) for each_path in folder.glob(pattern))
+
+
+def _is_clean_open_receipt(path: Path, head: str) -> bool:
+    try:
+        all_receipt_fields = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(all_receipt_fields, dict):
+        return False
+    recorded_head = all_receipt_fields.get(RECEIPT_HEAD_KEY)
+    return (
+        isinstance(recorded_head, str)
+        and OPEN_RECEIPT_HEAD_PATTERN.fullmatch(recorded_head) is not None
+        and same_commit(recorded_head, head)
+        and _is_count(all_receipt_fields.get(RECEIPT_FINDINGS_KEY))
+        and all_receipt_fields.get(RECEIPT_FINDINGS_KEY) == 0
+    )
+
+
+def is_clean_receipt(
+    all_receipt_fields: dict[str, object], owner: str, repo: str, number: int
+) -> bool:
+    """Return whether a recorded pass lets the merge through.
+
+    A pass is clean when it reported zero findings, or when every finding it
+    reported is ruled out and the receipt links the rulings comment posted on
+    this same pull request::
+
+        findings 0                                                -> clean
+        findings 2, ruled out 2, .../acme/tools/pull/12#issuecomment-9 -> clean
+        findings 2, ruled out 2, .../acme/other/pull/12#issuecomment-9 -> not clean
+
+    Args:
+        all_receipt_fields: The parsed receipt of one review pass.
+        owner: Owner of the pull request the merge targets.
+        repo: Repository of the pull request the merge targets.
+        number: Number of the pull request the merge targets.
+
+    Returns:
+        True when the pass counts as clean.
+    """
+    finding_count = all_receipt_fields.get(RECEIPT_FINDINGS_KEY)
+    if not _is_count(finding_count):
+        return False
+    return finding_count == 0 or _rules_out_every_finding(
+        all_receipt_fields, finding_count, owner, repo, number
+    )
+
+
+def same_commit(first: str, second: str) -> bool:
+    """Return whether two commit names match, one being a prefix of the other.
+
+    Args:
+        first: A full or abbreviated commit.
+        second: A full or abbreviated commit.
+
+    Returns:
+        True when the shorter name starts the longer one.
+    """
+    shorter, longer = sorted((first.casefold(), second.casefold()), key=len)
+    return longer.startswith(shorter)
+
+
+def _is_count(candidate: object) -> bool:
+    return isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0
+
+
+def _rules_out_every_finding(
+    all_receipt_fields: dict[str, object], finding_count: object, owner: str, repo: str, number: int
+) -> bool:
+    ruled_out_count = all_receipt_fields.get(RECEIPT_RULED_OUT_KEY)
+    return (
+        _is_count(ruled_out_count)
+        and ruled_out_count == finding_count
+        and _links_rulings_on(all_receipt_fields.get(RECEIPT_RULINGS_KEY), owner, repo, number)
+    )
+
+
+def _links_rulings_on(rulings: object, owner: str, repo: str, number: int) -> bool:
+    rulings_match = RULINGS_LINK_PATTERN.fullmatch(rulings) if isinstance(rulings, str) else None
+    return (
+        rulings_match is not None
+        and rulings_match["owner"].casefold() == owner.casefold()
+        and rulings_match["repo"].casefold() == repo.casefold()
+        and int(rulings_match["number"]) == number
+    )

package/hooks/blocking/test_merge_review_gate.py

@@ -1,5 +1,6 @@
 """Behavior tests for the clean-review merge gate."""
 
+import subprocess
 import sys
 from pathlib import Path
 
@@ -199,3 +200,220 @@ def test_should_deny_auto_merge_pinned_to_a_newer_head() -> None:
     merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
     command = f"gh pr merge 12 --repo acme/tools --auto --match-head-commit {NEW_HEAD}"
     assert "Review the new head" in _reason(_bash(command))
+
+
+def _git(folder: Path, *all_arguments: str) -> str:
+    completed = subprocess.run(
+        ["git", "-C", str(folder), *all_arguments], capture_output=True, text=True, check=True
+    )
+    return completed.stdout.strip()
+
+
+@pytest.fixture
+def branch_checkout(tmp_path: Path) -> tuple[Path, str]:
+    folder = tmp_path / "checkout"
+    folder.mkdir()
+    _git(folder, "init", "--quiet", "--initial-branch", "main")
+    _git(folder, "remote", "add", "origin", "https://github.com/acme/tools.git")
+    _git(folder, "checkout", "--quiet", "-b", "feature")
+    _git(
+        folder,
+        "-c",
+        "user.name=t",
+        "-c",
+        "user.email=t@example.com",
+        "commit",
+        "--quiet",
+        "--allow-empty",
+        "-m",
+        "first",
+    )
+    return folder, _git(folder, "rev-parse", "HEAD")
+
+
+def _create_tool(folder: Path, head: str = "feature") -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "acme", "repo": "tools", "head": head, "base": "main"},
+        "cwd": str(folder),
+    }
+
+
+def _bash_in(folder: Path, command: str) -> dict[str, object]:
+    return {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": str(folder)}
+
+
+def test_should_deny_a_pull_request_open_with_no_review(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    reason = _reason(_create_tool(folder))
+    assert f"no clean review for head {head}" in reason
+    assert f"acme/tools open {head} 0" in reason
+
+
+def test_should_allow_a_pull_request_open_reviewed_clean_at_its_head(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_create_tool(folder)) is None
+
+
+def test_should_deny_a_pull_request_open_whose_pass_found_findings(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 2)
+    assert "no clean review" in _reason(_create_tool(folder))
+
+
+def test_should_deny_a_pull_request_open_after_a_push_past_the_review(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, _head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", NEW_HEAD, 0)
+    assert "no clean review" in _reason(_create_tool(folder))
+
+
+def test_should_read_gh_pr_create_with_repo_and_head(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    command = "gh pr create --repo acme/tools --head feature --title t --body b"
+    assert "no clean review" in _reason(_bash_in(folder, command))
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_bash_in(folder, command)) is None
+
+
+def test_should_read_gh_pr_create_repository_from_origin(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_bash_in(folder, "gh pr create --fill")) is None
+
+
+def test_should_read_the_pull_request_script_create(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    command = "python scripts/pull_request.py create --repo acme/tools --head feature"
+    assert f"head {head}" in _reason(_bash_in(folder, command))
+
+
+def test_should_deny_a_pull_request_open_whose_head_cannot_be_read(tmp_path: Path) -> None:
+    reason = _reason(_create_tool(tmp_path, head="missing-branch"))
+    assert "names no repository or head commit" in reason
+
+
+def test_should_allow_a_pull_request_open_in_an_exempt_repository(
+    branch_checkout: tuple[Path, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    folder, _head = branch_checkout
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", "acme/tools")
+    assert _reason(_create_tool(folder)) is None
+
+
+def test_should_allow_a_merge_pinned_to_the_head_reviewed_clean_before_open() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+    command = f"gh pr merge 12 --repo acme/tools --match-head-commit {CLEAN_HEAD[:7]}"
+    assert _reason(_bash(command)) is None
+
+
+def test_should_deny_a_merge_pinned_past_the_head_reviewed_before_open() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(NEW_HEAD))
+
+
+def test_should_deny_an_unpinned_merge_with_only_an_open_review() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool())
+
+
+def test_should_not_accept_an_open_review_from_another_repository() -> None:
+    merge_review_receipt.record_open_review("acme/other", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_accept_an_open_review_recorded_under_the_old_owner() -> None:
+    merge_review_receipt.record_open_review("oldowner/tools", CLEAN_HEAD, 0)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+
+
+def test_should_deny_a_merge_whose_numbered_pass_found_findings_at_the_open_reviewed_head() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 2)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_ignore_an_open_receipt_whose_head_is_not_a_commit(receipt_folder: Path) -> None:
+    heads_folder = receipt_folder / "heads"
+    heads_folder.mkdir()
+    (heads_folder / "acme__tools__a.json").write_text('{"head": "a", "findings": 0}', encoding="utf-8")
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_check_a_merge_chained_after_a_reviewed_open(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    command = (
+        "gh pr create --repo acme/tools --head feature --fill && "
+        f"gh pr merge 12 --repo acme/tools --match-head-commit {NEW_HEAD}"
+    )
+    assert "no clean review" in _reason(_bash_in(folder, command))
+
+
+def test_should_read_the_pushed_branch_before_the_local_one(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, local_head = branch_checkout
+    _git(
+        folder,
+        "-c",
+        "user.name=t",
+        "-c",
+        "user.email=t@example.com",
+        "commit",
+        "--quiet",
+        "--allow-empty",
+        "-m",
+        "pushed",
+    )
+    pushed_head = _git(folder, "rev-parse", "HEAD")
+    _git(folder, "update-ref", "refs/remotes/origin/feature", pushed_head)
+    _git(folder, "reset", "--quiet", "--hard", local_head)
+    merge_review_receipt.record_open_review("acme/tools", local_head, 0)
+    assert f"head {pushed_head}" in _reason(_create_tool(folder))
+
+
+def test_should_not_match_an_open_receipt_on_a_short_pinned_head() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD[:3]))
+
+
+def test_should_allow_an_open_in_an_exempt_repository_with_an_unread_head(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", "acme/tools")
+    assert _reason(_create_tool(tmp_path, head="missing-branch")) is None
+
+
+def test_should_skip_options_quoted_inside_the_title_or_body(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    command = (
+        "gh pr create --repo acme/tools --title 'use -R other/x' "
+        f"--body \"curl -H 'Accept: x'; -H {NEW_HEAD}\" --head feature"
+    )
+    assert _reason(_bash_in(folder, command)) is None
+
+
+def test_should_read_the_head_in_the_folder_a_cd_moves_to(
+    branch_checkout: tuple[Path, str], tmp_path: Path
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    assert _reason(_bash_in(elsewhere, f'cd "{folder}" && gh pr create --fill')) is None
+    assert "names no repository or head commit" in _reason(
+        _bash_in(folder, f'cd "{elsewhere}" && gh pr create --repo acme/tools --fill')
+    )

package/hooks/blocking/tests/test_open_request.py

@@ -0,0 +1,38 @@
+"""Behavioral tests for reading a pull request open from a PreToolUse payload.
+
+gh pr create --repo acme/tools --title "--head evil" -> acme/tools, quoted option ignored
+mcp create_pull_request {owner, repo}                -> acme/tools, no head
+gh pr merge 12                                       -> no open
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from blocking.merge_review_gate_parts.open_request import OpenRequest, open_request_from
+
+
+def _shell_payload(command: str, folder: Path) -> dict[str, object]:
+    return {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": str(folder)}
+
+
+def test_should_read_the_repository_and_ignore_options_quoted_in_the_title(tmp_path: Path) -> None:
+    payload = _shell_payload('gh pr create --repo acme/tools --title "--head evil"', tmp_path)
+    assert open_request_from(payload) == OpenRequest(owner="acme", repo="tools", head=None)
+
+
+def test_should_read_the_create_tool_with_no_head_branch(tmp_path: Path) -> None:
+    payload = {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "acme", "repo": "tools"},
+        "cwd": str(tmp_path),
+    }
+    assert open_request_from(payload) == OpenRequest(owner="acme", repo="tools", head=None)
+
+
+def test_should_return_none_for_a_command_that_opens_nothing(tmp_path: Path) -> None:
+    assert open_request_from(_shell_payload("gh pr merge 12", tmp_path)) is None
+
+
+def test_should_name_the_slug_from_owner_and_repo() -> None:
+    assert OpenRequest(owner="acme", repo="tools", head=None).slug == "acme/tools"

package/hooks/blocking/tests/test_receipts.py

@@ -0,0 +1,57 @@
+"""Behavioral tests for the merge review receipt readers.
+
+open receipt {head: <full sha>, findings: 0}, head <short sha> -> clean
+open receipt {head: <full sha>, findings: 1}, head <short sha> -> not clean
+numbered receipt path                                         -> lowercased owner and repo
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from blocking.merge_review_gate_parts.receipts import (
+    has_clean_open_review,
+    open_receipt_path,
+    receipt_path,
+    same_commit,
+)
+
+HEAD = "abc1234def5678abc1234def5678abc1234def56"
+
+
+@pytest.fixture(autouse=True)
+def receipt_folder(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_RECEIPT_DIR", str(tmp_path))
+    return tmp_path
+
+
+def _write_open_receipt(finding_count: int) -> None:
+    path = open_receipt_path("acme", "tools", HEAD)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"head": HEAD, "findings": finding_count}), encoding="utf-8")
+
+
+def test_should_find_a_clean_open_review_by_short_head_under_any_owner() -> None:
+    _write_open_receipt(0)
+    assert has_clean_open_review("Tools", HEAD[:7]) is True
+
+
+def test_should_reject_an_open_review_that_counts_findings() -> None:
+    _write_open_receipt(1)
+    assert has_clean_open_review("tools", HEAD[:7]) is False
+
+
+def test_should_reject_a_head_that_is_not_a_commit() -> None:
+    _write_open_receipt(0)
+    assert has_clean_open_review("tools", "main") is False
+
+
+def test_should_lowercase_owner_and_repo_in_the_numbered_receipt_path(receipt_folder: Path) -> None:
+    assert receipt_path("Acme", "Tools", 12) == receipt_folder / "acme__tools__12.json"
+
+
+def test_should_match_commits_by_prefix_in_either_order() -> None:
+    assert same_commit(HEAD[:7].upper(), HEAD) is True
+    assert same_commit(HEAD, "def5678") is False

package/hooks/features/conduct-gates.md

@@ -20,7 +20,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
 - `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, or test files.
 - `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
-- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes.
+- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes. It also denies a pull request open, through `gh pr create`, `pull_request.py create` or a `create_pull_request` tool, until a pass recorded as `merge_review_receipt.py <owner/name> open <head> 0` covers the head the pull request opens with. A merge pinned to that same head passes on the open receipt.
 - `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 - `blocking/send_user_file_worktree_root_gate.py` denies a `SendUserFile` call that names a file outside the session's working directory, the `cwd` in the hook payload. The desktop file pane opens a sent file only under that folder and shows "Couldn't find this file" for any other path. The reason lists each outside file and names `<cwd>\.scratch\` as the folder to copy it into.
@@ -43,7 +43,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/resolve_thread_reply_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__resolve_review_thread|mcp__.*__pull_request_review_write`, timeout `10` seconds in `hooks.json`.
 - `blocking/verify_before_commit_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell`, timeout `30` seconds in `hooks.json`.
 - `blocking/build_eval_before_eval_write_gate.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|apply_patch`, timeout `10` seconds in `hooks.json`.
-- `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
+- `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
 - `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 - `blocking/send_user_file_worktree_root_gate.py` runs on `PreToolUse`, matcher `SendUserFile`, timeout `10` seconds in `hooks.json`.
@@ -70,7 +70,7 @@ Preconditions:
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
 - **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a tests-only commit, and a repository with no verify skill pass.
 - **Eval write.** Input is a Write to `evals/cases.json` with no build-eval call in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_build_eval_before_eval_write_gate.py -q`. The adjacent test observes a denial, then an allow once the call appears; a write outside an eval path passes.
-- **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass.
+- **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass. An open with no clean open receipt at its head is denied; an open reviewed clean at its head, and a merge pinned to that head, pass.
 - **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review pass.
 - **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 - **Sent file root.** Input is a `SendUserFile` call for a file on `Y:\` or in the session scratchpad, with `cwd` set to a worktree. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_send_user_file_worktree_root_gate.py -q`. The adjacent test observes a denial that names the file and `<cwd>\.scratch\`; a file under `<cwd>\.scratch\` passes.

package/hooks/hooks.json

@@ -133,7 +133,7 @@
         ]
       },
       {
-        "matcher": "Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)",
+        "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge)",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/merge_review_gate_constants.py

@@ -1,4 +1,4 @@
-"""Named constants for merge_review_gate, the clean-review merge gate."""
+"""Named constants for merge_review_gate, the clean-review open and merge gate."""
 
 from __future__ import annotations
 
@@ -10,12 +10,39 @@ PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
 
 MERGE_TOOL_SUFFIX = "__merge_pull_request"
 AUTO_MERGE_TOOL_SUFFIX = "__enable_pr_auto_merge"
+CREATE_TOOL_SUFFIX = "__create_pull_request"
 ALL_SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
 
 OWNER_FIELD = "owner"
 REPO_FIELD = "repo"
 NUMBER_FIELD = "pullNumber"
 EXPECTED_HEAD_FIELD = "expectedHeadSha"
+HEAD_BRANCH_FIELD = "head"
+CWD_FIELD = "cwd"
+
+GH_PR_CREATE_PATTERN = re.compile(r"(?:^|[\s;&|(])gh(?:\.exe)?\s+pr\s+create\b(?P<rest>[^;&|]*)")
+PULL_REQUEST_SCRIPT_CREATE_PATTERN = re.compile(
+    r"pull_request\.py[\"']?\s+create\b(?P<rest>[^;&|]*)"
+)
+HEAD_OPTION_PATTERN = re.compile(r"(?<!\S)(?:-H|--head)(?:=|\s+)[\"']?(?P<head>[^\s\"']+)")
+CHANGE_FOLDER_PATTERN = re.compile(
+    r"(?:^|[;&|(]\s*)(?:cd|pushd|Set-Location|sl)\s+(?:-Path\s+|-LiteralPath\s+)?"
+    r"(?P<folder>\"[^\"]*\"|'[^']*'|[^\s;&|)]+)",
+    re.IGNORECASE,
+)
+CREATE_TEXT_OPTION_PATTERN = re.compile(
+    r"(?<!\S)(?:-t|--title|-b|--body|-F|--body-file)(?:=|\s+)(?:\"[^\"]*\"|'[^']*'|\S+)"
+)
+ORIGIN_URL_PATTERN = re.compile(
+    r"github\.com[:/](?P<owner>[\w.-]+)/(?P<repo>[\w.-]+?)(?:\.git)?/?$"
+)
+GIT_TIMEOUT_SECONDS = 3
+ALL_ORIGIN_URL_ARGUMENTS = ("remote", "get-url", "origin")
+OPEN_HEAD_PATTERN = re.compile(r"[0-9a-fA-F]{7,40}")
+OPEN_RECEIPT_HEAD_PATTERN = re.compile(r"[0-9a-fA-F]{40}")
+REPOSITORY_SLUG_PATTERN = re.compile(r"[\w.-]+/[\w.-]+")
+REMOTE_BRANCH_PREFIX = "origin/"
+CURRENT_HEAD_REFERENCE = "HEAD"
 
 GH_PR_MERGE_PATTERN = re.compile(r"(?:^|[\s;&|(])gh(?:\.exe)?\s+pr\s+merge\b(?P<rest>[^;&|]*)")
 GH_API_MERGE_PATTERN = re.compile(
@@ -44,6 +71,10 @@ DEFAULT_REVIEW_COMMAND = "/code-review high --max-findings all"
 RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE = "CLAUDE_MERGE_REVIEW_RECEIPT_DIR"
 ALL_RECEIPT_DIRECTORY_SEGMENTS = (".claude", "merge-reviews")
 RECEIPT_FILE_NAME_TEMPLATE = "{owner}__{repo}__{number}.json"
+OPEN_RECEIPT_DIRECTORY_NAME = "heads"
+OPEN_RECEIPT_FILE_NAME_TEMPLATE = "{owner}__{repo}__{head}.json"
+OPEN_RECEIPT_GLOB_TEMPLATE = "*__{repo}__*.json"
+OPEN_TARGET_WORD = "open"
 REPOSITORY_SEPARATOR = ","
 RECEIPT_HEAD_KEY = "head"
 RECEIPT_FINDINGS_KEY = "findings"
@@ -84,3 +115,17 @@ UNKNOWN_TARGET_REASON = (
     "This merge names no repository and pull request number the review gate can read. "
     "Name both, such as `gh pr merge 12 --repo owner/name --match-head-commit <sha>`."
 )
+NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE = (
+    "{slug} has no clean review for head {head}, which this pull request would open with. "
+    "Review the branch diff with `{review_command}`, fix and push every finding, and review "
+    "again until a pass reports zero findings. Record that pass with `"
+    + RECORD_COMMAND
+    + " {slug} "
+    + OPEN_TARGET_WORD
+    + " {head} 0`, then open the pull request. The merge accepts that receipt while the "
+    "head stays {head}."
+)
+UNKNOWN_OPEN_TARGET_REASON = (
+    "This pull request names no repository or head commit the review gate can read. Run it "
+    "from the branch checkout, or pass `--repo owner/name` and `--head <pushed branch>`."
+)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.99.0",
+    "version": "8.100.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {