claude-dev-env 8.78.3 → 8.80.0

package/hooks/blocking/merge_review_gate.py

@@ -1,13 +1,15 @@
 """Deny an agent's merge until a review of the merged head came back clean.
 
 The agent that drives a pull request loops a code review on it, fixing and
-pushing each finding, until one pass reports zero findings. The merge then
+pushing each finding, until one pass reports zero findings or every finding
+it reports is ruled out with a link to the posted rulings. The merge then
 names that exact head::
 
     merge, receipt says 0 findings at abc123, merge pinned to abc123 -> allow
+    merge, receipt rules out all 3 findings with a link, pinned       -> allow
     merge, receipt at abc123, merge pinned to def456                 -> deny, review again
     merge, receipt at abc123, merge names no head                    -> deny, pin it
-    merge, no receipt or the receipt counts findings                 -> deny, run the loop
+    merge, no receipt or the receipt counts open findings            -> deny, run the loop
     auto-merge or enqueue pinned to the clean head                    -> allow
     auto-merge that names no head                                     -> deny, pin it
     repository listed in CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES      -> allow
@@ -61,10 +63,13 @@ from hooks_constants.merge_review_gate_constants import (
     RECEIPT_FILE_NAME_TEMPLATE,
     RECEIPT_FINDINGS_KEY,
     RECEIPT_HEAD_KEY,
+    RECEIPT_RULED_OUT_KEY,
+    RECEIPT_RULINGS_KEY,
     REPO_FIELD,
     REPO_OPTION_PATTERN,
     REPOSITORY_SEPARATOR,
     REVIEW_COMMAND_ENVIRONMENT_VARIABLE,
+    RULINGS_LINK_PATTERN,
     STALE_REVIEW_REASON_TEMPLATE,
     UNKNOWN_TARGET_REASON,
     UNPINNED_MERGE_REASON_TEMPLATE,
@@ -228,12 +233,69 @@ def _clean_head(request: MergeRequest) -> str | None:
         )
     except (OSError, ValueError):
         return None
-    if not isinstance(receipt, dict) or receipt.get(RECEIPT_FINDINGS_KEY) != 0:
+    if not isinstance(receipt, dict) or not is_clean_receipt(
+        receipt, request.owner, request.repo, request.number
+    ):
         return None
     head = receipt.get(RECEIPT_HEAD_KEY)
     return head if isinstance(head, str) and head else None
 
 
+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 _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
+    )
+
+
 def _review_command() -> str:
     return os.environ.get(REVIEW_COMMAND_ENVIRONMENT_VARIABLE) or DEFAULT_REVIEW_COMMAND
 

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -32,7 +32,6 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     DENY_REASON,
     ENVIRONMENT_ASSIGNMENT_PATTERN,
     GH_API_COMMAND,
-    GH_OPTIONS_WITH_VALUE,
     GH_PULL_REQUEST_COMMAND,
     GIT_ACTIONS,
     GIT_GLOBAL_OPTIONS_WITH_VALUE,
@@ -49,6 +48,7 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     SUBAGENT_TRANSCRIPT_DIRECTORY_NAME,
     SUBAGENT_TRANSCRIPT_FILE_TEMPLATE,
 )
+from hooks_constants.gh_command_words import gh_command_words
 from hooks_constants.hook_specific_output_keys import (
     HOOK_SPECIFIC_OUTPUT_KEY,
     PERMISSION_DECISION_KEY,
@@ -113,13 +113,12 @@ def _is_git_action(all_words: list[str]) -> bool:
 
 
 def _is_gh_action(all_words: list[str]) -> bool:
-    action, next_index = _next_command_word(all_words, 1, GH_OPTIONS_WITH_VALUE)
-    if action == GH_PULL_REQUEST_COMMAND:
-        subcommand, _ = _next_command_word(all_words, next_index, GH_OPTIONS_WITH_VALUE)
-        return subcommand is not None
-    if action != GH_API_COMMAND:
+    all_gh_words = gh_command_words(all_words[1:])
+    if all_gh_words[:1] == [GH_PULL_REQUEST_COMMAND]:
+        return len(all_gh_words) > 1
+    if all_gh_words[:1] != [GH_API_COMMAND]:
         return False
-    all_api_arguments = all_words[next_index:]
+    all_api_arguments = all_words[all_words.index(GH_API_COMMAND, 1) + 1 :]
     if any(each_name in each_word for each_word in all_api_arguments for each_name in ALL_API_ACTION_NAMES):
         return True
     return any(

package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py

@@ -22,7 +22,7 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
 )
 
 
-def test_bash_roster_starts_only_the_msys_rewriter_and_the_two_gates() -> None:
+def test_bash_roster_starts_only_the_msys_rewriter_and_the_three_gates() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -38,4 +38,8 @@ def test_bash_roster_starts_only_the_msys_rewriter_and_the_two_gates() -> None:
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
             replaced_by_plugin_name="shell-guards",
         ),
+        BashHostedHookEntry(
+            script_relative_path="blocking/cloud_graphql_gate.py",
+            applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        ),
     )

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -270,7 +270,10 @@ def test_should_drop_the_gates_the_shell_guards_mod_holds_while_it_is_on(
 ) -> None:
     _enable_shell_guards(tmp_path, monkeypatch)
     all_script_paths = [each_entry.script_relative_path for each_entry in select_applicable_entries(BASH_TOOL_NAME)]
-    assert all_script_paths == ["blocking/msys_rev_path_rewriter.py"]
+    assert all_script_paths == [
+        "blocking/msys_rev_path_rewriter.py",
+        "blocking/cloud_graphql_gate.py",
+    ]
 
 
 def test_should_pass_a_headless_claude_command_while_the_shell_guards_mod_is_on(

package/hooks/blocking/test_cloud_graphql_gate.py

@@ -0,0 +1,210 @@
+"""Tests for cloud_graphql_gate, which stops cloud sessions from calling GitHub GraphQL."""
+
+from __future__ import annotations
+
+import base64
+import json
+from io import StringIO
+from unittest.mock import patch
+
+import pytest
+
+import cloud_graphql_gate as gate
+
+
+def _stdout_from_main(payload: dict[str, object]) -> str:
+    """Return what main() wrote to stdout for one hook payload."""
+    captured_stdout = StringIO()
+    with (
+        patch("sys.stdin", StringIO(json.dumps(payload))),
+        patch("sys.stdout", captured_stdout),
+        patch.object(gate, "log_hook_block"),
+    ):
+        gate.main()
+    return captured_stdout.getvalue()
+
+
+_ENCODED_GH_PR_LIST = base64.b64encode("gh pr list".encode("utf-16-le")).decode()
+
+
+@pytest.fixture
+def cloud_session(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Mark the hook process as running inside a Claude Code cloud session."""
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "gh api graphql -f query='query{viewer{login}}'",
+        "gh.exe api graphql -F owner=o -f query=@q.graphql",
+        "cd repo && gh api graphql --paginate -f query=@q.graphql",
+        'bash -c "gh api graphql -f query=@q.graphql"',
+        "curl -sS -X POST https://api.github.com/graphql -d @q.json",
+        "curl -H 'Authorization: Bearer x' HTTPS://API.GITHUB.COM/GRAPHQL",
+        "wget --post-data=@q.json https://api.github.com/graphql",
+        "Invoke-RestMethod -Method Post -Uri https://api.github.com/graphql -Body $q",
+        "gh pr create --draft --title t --body-file b.md",
+        "gh pr view 12 --json title",
+        "gh pr checks 12",
+        "gh issue list -L 1",
+        "gh repo clone o/r",
+        "gh repo view o/r",
+        "gh label list",
+        "gh search prs repo:o/r",
+        "gh ruleset list",
+        "gh gist list",
+        "gh api -X POST graphql -f query='mutation{x}'",
+        "gh api --method POST graphql -f query=@q.graphql",
+        "gh api -H 'Accept: application/json' graphql -f query=@q",
+        "gh api /graphql -f query=@q",
+        "gh api https://api.github.com/graphql -f query=@q",
+        "gh -R o/r pr list",
+        "gh pr -R o/r list",
+        "gh pr --repo o/r view 12",
+        "gh pr merge 12 --body -h",
+        "gh pr view 12 --web",
+        "gh issue list --web",
+        "gh project item-list 1 --owner o",
+        "gh discussion list",
+        "gh status",
+        "gh status -o o",
+        "gh org list",
+        "gh repo archive o/r --yes",
+        "gh repo unarchive o/r --yes",
+        "curl -X POST https://api.github.com:443/graphql -d @q.json",
+        "if gh pr view 12; then echo ok; fi",
+        "if true; then gh api graphql -f query=@q; fi",
+        "while gh pr list; do sleep 1; done",
+        "! gh pr list",
+        "command gh pr list",
+        "exec gh issue list",
+        'echo "$(gh pr list)"',
+        "echo `gh pr view 12`",
+        "PR_URL=$(gh pr create --title t --body-file b.md)",
+        "(gh pr view 12)",
+        "python3 -c \"import requests; requests.post('https://api.github.com/graphql')\"",
+        "node -e \"fetch('https://api.github.com/graphql', {method: 'POST'})\"",
+        "gh release list -L 1",
+        "gh release view v1 --json name",
+        "gh workflow run ci.yml",
+        "gh workflow run ci.yml -f -r",
+        "gh pr list --search -w",
+        "echo \"$(printf ')'; gh pr list)\"",
+        "x=`echo \\`gh pr list\\``",
+        'echo $(echo "$(gh api graphql -f query=@q)")',
+        "python3.12 -c \"u('https://api.github.com/graphql')\"",
+        "pypy3 -c \"u('https://api.github.com/graphql')\"",
+        'eval "gh api graphql -f query=@q"',
+        "find . -maxdepth 0 -exec gh api graphql -f query=@q \\;",
+        "Invoke-Expression 'gh pr list'",
+        'iex "gh issue list"',
+        "find . -exec true \\; -exec gh api graphql -f query=@q \\;",
+        "gh repo sync o/r",
+        "gh repo create n --template o/t",
+        "gh repo create n -p o/t --private",
+        "gh repo edit o/r --enable-secret-scanning",
+        "gh repo edit --enable-advanced-security=false",
+        'Start-Process gh -ArgumentList "api graphql -f query=@q"',
+        "Start-Process -FilePath gh -ArgumentList 'pr','list' -Wait",
+        "Start-Process -FilePath:gh -ArgumentList:'api graphql -f query=@q'",
+        "GH.EXE pr list",
+        "pwsh -EncodedCommand " + _ENCODED_GH_PR_LIST,
+    ],
+)
+def test_should_detect_a_github_graphql_call(command: str) -> None:
+    assert gate.calls_github_graphql(command) is True
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "gh api repos/o/r/pulls/1/ccr/review_threads",
+        "gh api user",
+        "gh pr diff 12",
+        "gh pr create --help",
+        "gh issue view -h",
+        "gh pr list -R o/r --help",
+        "gh pr list --web",
+        "gh pr list -w -R o/r",
+        "gh project",
+        "gh api repos/o/r/contents/docs/graphql.md",
+        "gh api repos/o/r/issues -f title=graphql",
+        "gh repo fork o/r",
+        "gh repo rename new-name",
+        "echo '$(gh pr list)'",
+        "command -v gh",
+        "gh pr view -w -h",
+        "gh pr list --state open --web",
+        "gh release view --json name",
+        "gh workflow run ci.yml --ref main",
+        "gh workflow run ci.yml -r main",
+        "gh workflow run ci.yml --ref=main",
+        "gh search repos claude-dev-env",
+        "gh run view 12",
+        "python3 scripts/review_closure.py o/r 1",
+        'eval "gh api repos/o/r/pulls/1"',
+        "gh repo sync o/r --branch main",
+        "gh repo sync -b main",
+        "gh repo create n --private",
+        "gh repo edit o/r --description d",
+        "gh api repos/o/r --preview graphql",
+        "gh api repos/o/r/issues --jq graphql",
+        "Start-Process notepad",
+        "find . -name '*.py' -exec grep -l graphql {} +",
+        "gh pr",
+        "gh run list -L 1",
+        "gh workflow list",
+        "gh label create bug",
+        "curl -sS https://api.github.com/repos/o/r",
+        'grep -rn "api.github.com/graphql" scripts',
+        'echo "gh api graphql"',
+        'git commit -m "drop gh api graphql calls"',
+    ],
+)
+def test_should_pass_rest_calls_and_text_that_only_mentions_graphql(command: str) -> None:
+    assert gate.calls_github_graphql(command) is False
+
+
+def test_should_deny_gh_api_graphql_in_a_cloud_session_and_name_the_rest_routes(
+    cloud_session: None,
+) -> None:
+    decision = json.loads(
+        _stdout_from_main(
+            {"tool_name": "Bash", "tool_input": {"command": "gh api graphql -f query=@q"}}
+        )
+    )
+    specific_output = decision["hookSpecificOutput"]
+    assert specific_output["permissionDecision"] == "deny"
+    reason = specific_output["permissionDecisionReason"]
+    assert "GET /repos/{owner}/{repo}/pulls/{n}/ccr/review_threads" in reason
+    assert "gh api repos/{owner}/{repo}/..." in reason
+    assert "mcp__github__create_pull_request" in reason
+
+
+def test_should_deny_a_powershell_endpoint_call_in_a_cloud_session(cloud_session: None) -> None:
+    command = "Invoke-RestMethod -Uri https://api.github.com/graphql -Method Post"
+    decision = json.loads(
+        _stdout_from_main({"tool_name": "PowerShell", "tool_input": {"command": command}})
+    )
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_should_stay_quiet_outside_a_cloud_session() -> None:
+    assert (
+        _stdout_from_main(
+            {"tool_name": "Bash", "tool_input": {"command": "gh api graphql -f query=@q"}}
+        )
+        == ""
+    )
+
+
+def test_should_stay_quiet_for_a_rest_call_in_a_cloud_session(cloud_session: None) -> None:
+    rest_command = "gh api repos/o/r/pulls/1/ccr/review_threads"
+    assert _stdout_from_main({"tool_name": "Bash", "tool_input": {"command": rest_command}}) == ""
+
+
+def test_should_stay_quiet_for_another_tool_in_a_cloud_session(cloud_session: None) -> None:
+    assert (
+        _stdout_from_main({"tool_name": "Write", "tool_input": {"command": "gh api graphql"}}) == ""
+    )

package/hooks/blocking/test_headless_claude_broker_gate.py

@@ -88,13 +88,18 @@ def test_other_tool_payload_emits_nothing() -> None:
     assert _stdout_from_main({"tool_name": "Write", "tool_input": {"command": 'claude -p "task"'}}) == ""
 
 
-def test_should_pass_bare_headless_claude_in_a_cloud_session(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
+@pytest.mark.parametrize("marker_value", ["true", " TRUE "])
+def test_should_pass_bare_headless_claude_in_a_cloud_session(
+    monkeypatch: pytest.MonkeyPatch, marker_value: str
+) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", marker_value)
     assert _stdout_from_main({"tool_name": "Bash", "tool_input": {"command": 'claude -p "task"'}}) == ""
 
 
-def test_should_report_a_cloud_session_only_when_the_marker_is_true(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "false")
-    assert gate.is_cloud_session() is False
-    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
-    assert gate.is_cloud_session() is True
+@pytest.mark.parametrize("marker_value", ["false", "1", ""])
+def test_should_deny_bare_headless_claude_when_the_marker_is_not_true(
+    monkeypatch: pytest.MonkeyPatch, marker_value: str
+) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", marker_value)
+    decision = json.loads(_stdout_from_main({"tool_name": "Bash", "tool_input": {"command": 'claude -p "task"'}}))
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"

package/hooks/blocking/test_merge_over_review_offer_gate.py

@@ -0,0 +1,138 @@
+"""Behavior tests for the merge-over-review decision card gate."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from blocking import merge_over_review_offer_gate as gate
+
+GATE_SCRIPT = Path(gate.__file__)
+
+
+def _card(context: str, *options: tuple[str, str]) -> dict[str, object]:
+    return {
+        "question": "What next for the pull request?",
+        "context": context,
+        "options": [{"label": label, "consequence": consequence} for label, consequence in options],
+    }
+
+
+def test_merge_option_over_open_findings_should_be_offered_over_review() -> None:
+    card = _card("The review found 9 findings.", ("Merge now", "It lands today."), ("Keep looping", "I rerun."))
+    assert gate.offers_merge_over_review(card)
+
+
+def test_merge_option_that_overrides_a_status_should_be_offered_over_review() -> None:
+    card = _card("Tests pass.", ("Merge now", "You override the status."))
+    assert gate.offers_merge_over_review(card)
+
+
+def test_card_without_a_merge_option_should_pass() -> None:
+    card = _card("The review found 9 findings.", ("Keep looping", "I rerun."), ("Drop shell checks", "Smaller diff."))
+    assert not gate.offers_merge_over_review(card)
+
+
+def test_merge_option_after_a_clean_review_should_pass() -> None:
+    card = _card("The review pass on the head came back clean.", ("Merge", "It lands."), ("Hold", "It waits."))
+    assert not gate.offers_merge_over_review(card)
+
+
+def test_merge_question_with_yes_no_options_over_unresolved_threads_should_be_offered_over_review() -> None:
+    card = {"question": "Merge PR 41 now?", "context": "3 unresolved review threads.", "options": ["Yes", "No"]}
+    assert gate.offers_merge_over_review(card)
+
+
+def test_string_options_should_be_read() -> None:
+    card = {"question": "What next?", "context": "9 findings remain.", "options": ["Merge now", "Keep looping"]}
+    assert gate.offers_merge_over_review(card)
+
+
+def test_merge_queue_option_over_findings_should_be_offered_over_review() -> None:
+    card = _card("9 findings remain.", ("Join the merge queue", "It waits for checks."), ("Wait", "It waits."))
+    assert gate.offers_merge_over_review(card)
+
+
+def test_merge_offer_in_context_over_findings_should_be_offered_over_review() -> None:
+    card = {
+        "question": "Go ahead?",
+        "context": "The PR is green and I can merge it now, but the review reports 9 findings.",
+        "options": ["Yes", "No"],
+    }
+    assert gate.offers_merge_over_review(card)
+
+
+def test_offer_and_findings_in_separate_questions_should_be_offered_over_review() -> None:
+    card = {
+        "questions": [
+            {"question": "The review reports 9 findings. Which next?", "options": ["Keep fixing", "Split it"]},
+            {"question": "Merge it now?", "options": ["Yes", "No"]},
+        ]
+    }
+    assert gate.offers_merge_over_review(card)
+
+
+def test_merge_option_over_unaddressed_review_comments_should_be_offered_over_review() -> None:
+    card = _card("3 review comments are unaddressed; 2 changes requested.", ("Merge now", "It lands."))
+    assert gate.offers_merge_over_review(card)
+
+
+def test_ship_card_about_a_pending_translation_should_pass() -> None:
+    card = {
+        "question": "Ship the README update now? The pending translation can follow.",
+        "options": ["Ship it", "Wait"],
+    }
+    assert not gate.offers_merge_over_review(card)
+
+
+def test_ask_user_question_merge_option_over_findings_should_be_offered_over_review() -> None:
+    card = {
+        "questions": [
+            {
+                "question": "The review failed with 2 findings. What next?",
+                "header": "Next step",
+                "options": [
+                    {"label": "Squash and merge", "description": "It lands now."},
+                    {"label": "Fix first", "description": "I fix both."},
+                ],
+            }
+        ]
+    }
+    assert gate.offers_merge_over_review(card)
+
+
+def test_card_about_the_merge_review_check_without_a_merge_offer_should_pass() -> None:
+    card = _card(
+        "The Merge review check reports 11 findings.", ("Keep fixing", "I rerun."), ("Split the PR", "Smaller diff.")
+    )
+    assert not gate.offers_merge_over_review(card)
+
+
+def test_merge_option_after_a_review_with_no_findings_should_pass() -> None:
+    card = _card("The review on the head found no findings.", ("Merge", "It lands."), ("Hold", "It waits."))
+    assert not gate.offers_merge_over_review(card)
+
+
+def test_decision_for_should_return_none_for_a_clean_card() -> None:
+    payload = {"tool_name": "AskUserQuestion", "tool_input": _card("All checks pass.", ("Merge", "It lands."))}
+    assert gate.decision_for(payload) is None
+
+
+def test_script_should_print_a_deny_for_a_merge_over_findings_card() -> None:
+    payload = {
+        "tool_name": "mcp__hearthbot__ask_decision",
+        "tool_input": _card("9 findings remain.", ("Merge now", "It lands.")),
+    }
+    completed = subprocess.run(
+        [sys.executable, str(GATE_SCRIPT)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed.returncode == 0
+    assert json.loads(completed.stdout)["hookSpecificOutput"]["permissionDecision"] == "deny"

package/hooks/blocking/test_merge_review_gate.py

@@ -16,6 +16,7 @@ from blocking import merge_review_gate as gate
 
 CLEAN_HEAD = "abc1234def5678abc1234def5678abc1234def56"
 NEW_HEAD = "9999999aaaaaaa9999999aaaaaaa9999999aaaaa"
+RULINGS_LINK = "https://github.com/acme/tools/pull/12#issuecomment-1"
 
 
 @pytest.fixture(autouse=True)
@@ -58,6 +59,68 @@ def test_should_allow_a_merge_pinned_to_the_clean_head() -> None:
     assert _reason(_merge_tool(CLEAN_HEAD)) is None
 
 
+def test_should_allow_a_merge_whose_findings_are_all_ruled_out_with_a_link() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 2, 2, RULINGS_LINK)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+
+
+def test_should_deny_a_merge_with_a_finding_left_open() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 3, 2, RULINGS_LINK)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+@pytest.mark.parametrize(
+    "receipt",
+    [
+        {"head": CLEAN_HEAD, "findings": 2, "ruled_out": 2},
+        {"head": CLEAN_HEAD, "findings": 2, "ruled_out": 2, "rulings": "  "},
+        {"head": CLEAN_HEAD, "findings": 2, "ruled_out": 2, "rulings": "x"},
+        {
+            "head": CLEAN_HEAD,
+            "findings": 2,
+            "ruled_out": 2,
+            "rulings": "https://github.com/acme/other/pull/12#issuecomment-1",
+        },
+        {
+            "head": CLEAN_HEAD,
+            "findings": 2,
+            "ruled_out": 2,
+            "rulings": "https://github.com/acme/tools/pull/13#issuecomment-1",
+        },
+        {
+            "head": CLEAN_HEAD,
+            "findings": 2,
+            "ruled_out": 2,
+            "rulings": "https://evil.example/?https://github.com/acme/tools/pull/12#issuecomment-1",
+        },
+        {"head": CLEAN_HEAD, "findings": True},
+        {"head": CLEAN_HEAD, "findings": "0"},
+        {"head": CLEAN_HEAD, "findings": 1, "ruled_out": True, "rulings": RULINGS_LINK},
+        {"head": CLEAN_HEAD, "findings": -1, "ruled_out": -1, "rulings": RULINGS_LINK},
+    ],
+)
+def test_is_clean_receipt_should_reject_a_receipt_it_cannot_back(receipt: dict[str, object]) -> None:
+    assert gate.is_clean_receipt(receipt, "acme", "tools", 12) is False
+
+
+def test_is_clean_receipt_should_accept_zero_findings() -> None:
+    assert gate.is_clean_receipt({"head": CLEAN_HEAD, "findings": 0}, "acme", "tools", 12) is True
+
+
+@pytest.mark.parametrize(
+    "rulings", ["x", "https://github.com/acme/tools/pull/13#issuecomment-1"]
+)
+def test_should_deny_a_merge_whose_rulings_link_is_not_a_comment_on_this_pull_request(
+    rulings: str,
+) -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 2, 2, rulings)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_name_the_ruled_out_route_in_the_deny_reason() -> None:
+    assert "--ruled-out" in _reason(_merge_tool(CLEAN_HEAD))
+
+
 def test_should_deny_a_merge_pinned_to_a_head_pushed_after_the_review() -> None:
     merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
     assert "Review the new head" in _reason(_merge_tool(NEW_HEAD))

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -156,6 +156,7 @@ def test_action_command_shapes(tmp_path: Path) -> None:
         "git --git-dir=.git push origin head",
         "gh pr create",
         "gh -R owner/repo pr --repo owner/repo merge",
+        "gh -R owner/repo api -X PUT repos/owner/repo/pulls/1/merge",
         "gh api -X PUT repos/owner/repo/pulls/1/merge",
         "gh api graphql -f query='mutation { enablePullRequestAutoMerge }'",
         "gh api graphql -f name=auto-merge",
@@ -180,6 +181,8 @@ def test_non_action_command_shapes(tmp_path: Path) -> None:
         "gh api repos/owner/repo/pulls/1/mergeability",
         "gh issue create --body-file message.txt",
         "gh pr",
+        "gh pr --repo owner/repo",
+        "gh api -H 'Accept: x' repos/owner/repo/pulls/1/mergeability",
         "GH_TOKEN=x gh issue list",
         "env -u GH_TOKEN git status",
     )

package/hooks/conftest.py

@@ -23,7 +23,7 @@ _CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME = importlib.import_module(
 ).CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME
 
 _CLOUD_SESSION_ENVIRONMENT_VARIABLE_NAME = importlib.import_module(
-    "hooks_constants.headless_claude_broker_gate_constants"
+    "hooks_constants.cloud_session_constants"
 ).CLOUD_SESSION_ENV_VAR
 
 _ROOT_ANCHORED_PROBE_PATH = "/tmp/scratch.py"