claude-dev-env 8.79.0 → 8.81.0

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

@@ -117,6 +117,14 @@ def test_subagent_without_invocation_is_denied(tmp_path: Path) -> None:
     _assert_denied(payload)
 
 
+def test_transcript_paths_should_add_the_subagent_transcript_after_the_session(tmp_path: Path) -> None:
+    session_path = _transcript(tmp_path)
+    subagent_path = _subagent_transcript(tmp_path, "a8865a3f3c71595ce", None)
+    payload = {"transcript_path": str(session_path), "agent_id": "a8865a3f3c71595ce"}
+    assert gate.transcript_paths(payload) == [str(session_path), str(subagent_path)]
+    assert gate.transcript_paths({"transcript_path": str(session_path)}) == [str(session_path)]
+
+
 def test_missing_subagent_transcript_keeps_session_deny(tmp_path: Path) -> None:
     payload = _payload("git push", _transcript(tmp_path))
     payload["agent_id"] = "a8865a3f3c71595ce"
@@ -156,6 +164,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 +189,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/blocking/test_pre_tool_use_dispatcher.py

@@ -806,6 +806,7 @@ def test_dispatcher_allows_clean_apply_patch_add(tmp_path: Path) -> None:
 
 ALL_RETAINED_PATHS = {
     "blocking/context_budget_blocker.py",
+    "blocking/pull_request_proof_edit_gate.py",
 }
 ALL_RETIRED_PATHS = {
     "validation/hook_format_validator.py",

package/hooks/blocking/test_pull_request_proof.py

@@ -333,3 +333,10 @@ def test_dispatch_that_names_no_head_or_runs_no_workflow_should_not_count_as_a_c
     for each_payload in all_payloads:
         assert gate.missing_proof_reason(each_payload) is None
         assert not gate.is_feature_pull_request(each_payload)
+
+
+def test_is_create_call_should_name_shell_and_mcp_creates() -> None:
+    assert gate.is_create_call(_shell("gh pr create --title t --body b"))
+    assert gate.is_create_call(_mcp_create("b"))
+    assert not gate.is_create_call(_shell("gh pr edit 7 --body b"))
+    assert not gate.is_create_call({"tool_name": "Read", "tool_input": {"file_path": "a.py"}})

package/hooks/blocking/test_pull_request_proof_edit_gate.py

@@ -0,0 +1,199 @@
+"""Behavior tests for the gate that holds an edit to the proof gate until its named route is taken."""
+
+import json
+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 pull_request_proof_edit_gate as gate
+from hooks_constants.pull_request_proof_constants import (
+    GATE_EDIT_BEFORE_ROUTE_REASON,
+    UNREADABLE_CHANGES_REASON,
+)
+
+
+def _transcript(tmp_path: Path, all_entries: list[dict[str, object]]) -> str:
+    transcript_path = tmp_path / "session.jsonl"
+    transcript_path.write_text(
+        "\n".join(json.dumps(each_entry) for each_entry in all_entries) + "\n", encoding="utf-8"
+    )
+    return str(transcript_path)
+
+
+def _tool_use(tool_use_id: object, name: str, tool_input: dict[str, object]) -> dict[str, object]:
+    return {
+        "type": "assistant",
+        "message": {"content": [{"type": "tool_use", "id": tool_use_id, "name": name, "input": tool_input}]},
+    }
+
+
+def _tool_result(tool_use_id: object, content: object, is_error: bool) -> dict[str, object]:
+    return {
+        "type": "user",
+        "message": {
+            "content": [
+                {"type": "tool_result", "tool_use_id": tool_use_id, "content": content, "is_error": is_error}
+            ]
+        },
+    }
+
+
+SHELL_CREATE_INPUT = {"command": "gh pr create --title t --body-file body.md"}
+DENIED_CREATE_ENTRIES = [
+    _tool_use("create-1", "Bash", SHELL_CREATE_INPUT),
+    _tool_result("create-1", UNREADABLE_CHANGES_REASON, True),
+]
+
+
+def _edit_payload(transcript_path: str, file_path: str) -> dict[str, object]:
+    return {
+        "tool_name": "Edit",
+        "tool_input": {"file_path": file_path, "old_string": "a", "new_string": "b"},
+        "transcript_path": transcript_path,
+    }
+
+
+GATE_FILE_PATH = "C:/workspace/x/packages/claude-dev-env/hooks/blocking/pull_request_proof.py"
+GATE_CONSTANTS_PATH = "/w/packages/claude-dev-env/hooks/hooks_constants/pull_request_proof_constants.py"
+
+
+def test_should_deny_an_edit_to_the_gate_after_its_deny_with_no_passing_create(tmp_path: Path) -> None:
+    transcript_path = _transcript(tmp_path, DENIED_CREATE_ENTRIES)
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_deny_an_edit_to_the_gate_constants_after_its_deny(tmp_path: Path) -> None:
+    transcript_path = _transcript(tmp_path, DENIED_CREATE_ENTRIES)
+    payload = _edit_payload(transcript_path, GATE_CONSTANTS_PATH)
+    payload["tool_name"] = "Write"
+    assert gate.gate_edit_reason(payload) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_read_a_deny_carried_as_text_blocks(tmp_path: Path) -> None:
+    all_text_blocks = [{"type": "text", "text": "Error: " + UNREADABLE_CHANGES_REASON}]
+    transcript_path = _transcript(
+        tmp_path,
+        [_tool_use("create-1", "Bash", SHELL_CREATE_INPUT), _tool_result("create-1", all_text_blocks, True)],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_allow_a_gate_edit_once_a_later_create_passed(tmp_path: Path) -> None:
+    transcript_path = _transcript(
+        tmp_path,
+        [
+            *DENIED_CREATE_ENTRIES,
+            _tool_use("create-2", "mcp__github__create_pull_request", {"owner": "o", "repo": "r", "body": "b"}),
+            _tool_result("create-2", "https://github.com/o/r/pull/7", False),
+        ],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) is None
+
+
+def test_should_deny_again_when_a_deny_follows_the_passing_create(tmp_path: Path) -> None:
+    transcript_path = _transcript(
+        tmp_path,
+        [
+            _tool_use("create-1", "Bash", SHELL_CREATE_INPUT),
+            _tool_result("create-1", "https://github.com/o/r/pull/7", False),
+            *DENIED_CREATE_ENTRIES,
+        ],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_allow_an_edit_to_another_file_after_the_deny(tmp_path: Path) -> None:
+    transcript_path = _transcript(tmp_path, DENIED_CREATE_ENTRIES)
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, "/w/hooks/blocking/other_gate.py")) is None
+
+
+def test_should_allow_a_gate_edit_in_a_session_this_gate_never_denied(tmp_path: Path) -> None:
+    transcript_path = _transcript(
+        tmp_path,
+        [
+            _tool_use("read-1", "Read", {"file_path": GATE_CONSTANTS_PATH}),
+            _tool_result("read-1", UNREADABLE_CHANGES_REASON, False),
+            _tool_use("other-1", "Bash", {"command": "pytest"}),
+            _tool_result("other-1", "1 failed", True),
+        ],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) is None
+
+
+def test_should_allow_a_gate_edit_without_a_readable_transcript(tmp_path: Path) -> None:
+    payload = _edit_payload(str(tmp_path / "missing.jsonl"), GATE_FILE_PATH)
+    assert gate.gate_edit_reason(payload) is None
+
+
+def test_should_deny_an_apply_patch_to_the_edit_gate_after_its_deny(tmp_path: Path) -> None:
+    transcript_path = _transcript(tmp_path, DENIED_CREATE_ENTRIES)
+    patch_text = (
+        "*** Begin Patch\n*** Update File: hooks/blocking/pull_request_proof_edit_gate.py\n"
+        "@@\n-a\n+b\n*** End Patch\n"
+    )
+    payload = {
+        "tool_name": "apply_patch",
+        "tool_input": {"command": patch_text},
+        "cwd": str(tmp_path),
+        "transcript_path": transcript_path,
+    }
+    assert gate.gate_edit_reason(payload) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_ignore_an_errored_result_of_another_tool_that_names_the_guide(tmp_path: Path) -> None:
+    transcript_path = _transcript(
+        tmp_path,
+        [
+            _tool_use("cat-1", "Bash", {"command": "cat proof-before-pull-request.md"}),
+            _tool_result("cat-1", "cat: " + UNREADABLE_CHANGES_REASON, True),
+        ],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) is None
+
+
+def test_should_skip_malformed_transcript_entries_and_keep_the_deny(tmp_path: Path) -> None:
+    transcript_path = _transcript(
+        tmp_path,
+        [
+            {"type": "user", "message": "plain text"},
+            _tool_use(["not", "a", "string"], "Bash", SHELL_CREATE_INPUT),
+            _tool_result(["not", "a", "string"], "done", False),
+            *DENIED_CREATE_ENTRIES,
+        ],
+    )
+    assert gate.gate_edit_reason(_edit_payload(transcript_path, GATE_FILE_PATH)) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_deny_a_multi_edit_of_a_case_variant_windows_path_from_the_agent_transcript(tmp_path: Path) -> None:
+    transcript_path = _transcript(tmp_path, DENIED_CREATE_ENTRIES)
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {"file_path": "C:\\workspace\\x\\hooks\\blocking\\Pull_Request_Proof.PY", "edits": []},
+        "agent_transcript_path": transcript_path,
+    }
+    assert gate.gate_edit_reason(payload) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_deny_a_subagent_edit_after_a_deny_in_its_own_transcript(tmp_path: Path) -> None:
+    session_path = _transcript(tmp_path, [])
+    subagent_directory = tmp_path / "session" / "subagents"
+    subagent_directory.mkdir(parents=True)
+    (subagent_directory / "agent-a8865a3f3c71595ce.jsonl").write_text(
+        "\n".join(json.dumps(each_entry) for each_entry in DENIED_CREATE_ENTRIES) + "\n", encoding="utf-8"
+    )
+    payload = _edit_payload(session_path, GATE_FILE_PATH)
+    payload["agent_id"] = "a8865a3f3c71595ce"
+    assert gate.gate_edit_reason(payload) == GATE_EDIT_BEFORE_ROUTE_REASON
+
+
+def test_should_allow_an_apply_patch_the_patch_parser_cannot_resolve(tmp_path: Path) -> None:
+    payload = {
+        "tool_name": "apply_patch",
+        "tool_input": {"command": "*** Begin Patch\n*** Add File: a\x00b.py\n+x\n*** End Patch\n"},
+        "cwd": str(tmp_path),
+        "transcript_path": _transcript(tmp_path, DENIED_CREATE_ENTRIES),
+    }
+    assert gate.gate_edit_reason(payload) is None

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"

package/hooks/features/bash-dispatchers.md

@@ -8,6 +8,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/msys_rev_path_rewriter.py` adds a narrow `MSYS2_ARG_CONV_EXCL` prefix for affected revision and path tokens.
 - `blocking/headless_claude_broker_gate.py` denies a headless `claude -p` or `claude --print` call and names the broker command to run instead.
 - `blocking/gh_global_account_switch_gate.py` denies `gh auth switch`, `gh auth login`, and `gh auth logout` and names the per-command `GH_TOKEN` form to run instead.
+- `blocking/cloud_graphql_gate.py` denies the `gh` commands that call GraphQL (`gh api graphql` with any flags before the endpoint, `gh pr`, `gh issue`, `gh project` and `gh discussion` except `gh pr diff` and `gh pr list --web`, `gh status`, `gh org list`, `gh release list`, `gh release view` with a tag, `gh workflow run` without `--ref`, and a few `repo`, `label`, `search`, `ruleset` and `gist` commands, read past `if`, `!` and command substitutions) and an HTTP client or `python -c` style call to `api.github.com/graphql`, with or without a port, inside a cloud session, where the proxy answers GraphQL with HTTP 403, and names the REST routes to run instead.
 - `blocking/bash_post_call_dispatcher.py` runs hosted observers and joins their context output without blocking the call.
 - `advisory/pr_done_reminder.py` adds a pull request checklist after a successful push or pull request creation.
 
@@ -17,6 +18,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/msys_rev_path_rewriter.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds. `ALL_BASH_HOSTED_HOOK_ENTRIES` selects the `Bash` tool.
 - `blocking/headless_claude_broker_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
 - `blocking/gh_global_account_switch_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
+- `blocking/cloud_graphql_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, when `CLAUDE_CODE_REMOTE` is `true`.
 - `blocking/bash_post_call_dispatcher.py` runs on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds in `hooks.json`.
 - `advisory/pr_done_reminder.py` runs inside that dispatcher on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds. `ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES` selects `Bash` and `PowerShell`.
 
@@ -29,6 +31,7 @@ Preconditions:
 - **Pre-call dispatch.** Input is a clean Bash command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_pre_tool_use_dispatcher.py -q`. The adjacent test observes the combined decision and hosted precedence.
 - **Revision rewrite.** Input is a Git command with `origin/main:.claude/settings.json`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_msys_rev_path_rewriter.py -q`. The adjacent test observes the `origin/main:` exclusion prefix.
 - **Broker gate.** Input is a `claude -p task` command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_headless_claude_broker_gate.py -q`. The adjacent test observes a denial that names the broker command.
+- **Cloud GraphQL gate.** Input is a `gh api graphql` command with `CLAUDE_CODE_REMOTE=true`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_cloud_graphql_gate.py -q`. The adjacent test observes a denial that names the REST routes, and silence outside a cloud session.
 - **Post-call dispatch.** Input is a Bash call that yields hosted context. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_post_call_dispatcher.py -q`. The adjacent test observes a joined context payload and exit code zero.
 - **Pull request reminder.** Input is a completed push or pull request creation. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_pr_done_reminder.py -q`. The adjacent test checks the reminder trigger and checklist verdict.
 

package/hooks/features/conduct-gates.md

@@ -12,7 +12,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
-- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings. 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.
+- `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.
 - `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.
 
@@ -57,4 +57,4 @@ Preconditions:
 - The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.
 - The dark mode gate denies a page publish when Node, Playwright or Chromium is missing, and its reason names the install command. It checks both dark signals, `prefers-color-scheme: dark` and `data-theme="dark"` on the root element.
-- The clean-review gate trusts the receipt. A receipt the agent writes by hand with zero findings passes, so the pr-lifecycle skill names the review loop that writes it. A `gh pr merge` that names no repository is denied, because the gate cannot tell which repository the current branch belongs to.
+- The clean-review gate trusts the receipt. A receipt the agent writes by hand with zero findings, or with every finding ruled out and a rulings link, passes, so the pr-lifecycle skill names the review loop that writes it. A `gh pr merge` that names no repository is denied, because the gate cannot tell which repository the current branch belongs to.

package/hooks/features/write-edit-blocking.md

@@ -7,12 +7,14 @@ This family decides whether an agent's file mutation can run.
 - `blocking/pre_tool_use_dispatcher.py` runs its native description check and returns one permission decision.
 - `blocking/state_description_blocker.py` rejects historical or comparative prose in supported comments, docstrings, and Markdown.
 - `blocking/context_budget_blocker.py` rejects a write that grows a skill entry, `AGENTS.md`, `CLAUDE.md`, or rule file past its context budget.
+- `blocking/pull_request_proof_edit_gate.py` rejects an edit to the pull request proof gate, its constants, this edit gate, or the dispatcher roster while the proof gate's last deny of a create call in the session has no passing create call after it.
 
 ## When it fires
 
 - `blocking/pre_tool_use_dispatcher.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds in `hooks.json`.
 - `blocking/state_description_blocker.py` runs through the dispatcher's native evaluator on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. Its evaluator checks `Write`, `Edit`, and `MultiEdit` payloads and skips `apply_patch`.
 - `blocking/context_budget_blocker.py` runs inside that dispatcher as a blocking hosted entry on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. It reads `.claude/context-budget.json` from the edited file's own repository.
+- `blocking/pull_request_proof_edit_gate.py` runs inside that dispatcher as a blocking hosted entry on `PreToolUse` for `Write`, `Edit`, `MultiEdit`, and `apply_patch`, timeout `60` seconds. It reads the session transcript the payload names and, for a subagent, its own transcript.
 
 ## Proving it
 
@@ -22,11 +24,12 @@ Preconditions:
 
 - **Dispatcher decision.** Input is a clean Write payload. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pre_tool_use_dispatcher.py -q`. The adjacent test checks that the dispatcher allows clean writes and carries denials from its checks.
 - **Context budget gate.** Input is a Write of the orchestrator skill at commit `3f2c3ef`, then at `98f45b1`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_context_budget_blocker.py -q`. The adjacent test observes a denial naming "Oversee delegated work" for the first and an allow for the second.
+- **Proof edit gate.** Input is a transcript with a proof gate deny, then an Edit of `pull_request_proof.py`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pull_request_proof_edit_gate.py -q`. The adjacent test observes a denial before a passing create call and an allow after one.
 - **Description gate.** Input is a Write containing historical prose in a Python comment. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_state_description_blocker.py -q`. The adjacent test observes a denial reason.
 
 ## Gotchas
 
-- `ALL_HOSTED_HOOK_ENTRIES` lists the blocking context budget gate. The dispatcher calls the description evaluator through its native hook table.
+- `ALL_HOSTED_HOOK_ENTRIES` lists the blocking context budget gate and the proof edit gate. The dispatcher calls the description evaluator through its native hook table.
 - The context budget gate denies only what an edit adds. A repository with no policy file uses built-in kinds and treats the file's current text as its baseline entry, so a file under its line limit may grow to the limit and a file over it may only shrink. The CI ratchet runs in `scripts/policy_lint/adapter_context_budget.py`, never in the hook. See the [context budget reference](../../.agents/skills/build-eval/reference/context-budget.md).
 - The dispatcher runs hosted entries in roster order. A hosted advisory crash stays silent; a native blocking check can deny the write.
 - `scripts/policy_lint/adapter_detectors.py` also loads `blocking/state_description_blocker.py`. Check that adapter when changing its evaluator.

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -75,4 +75,8 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
         replaced_by_plugin_name=SHELL_GUARDS_PLUGIN_NAME,
     ),
+    BashHostedHookEntry(
+        script_relative_path="blocking/cloud_graphql_gate.py",
+        applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/cloud_graphql_gate_constants.py

@@ -0,0 +1,116 @@
+"""Constants for the gate that stops cloud sessions from calling GitHub GraphQL.
+
+Holds the ``gh`` commands that call GraphQL, the ``gh`` subcommands inside
+those groups that call REST, the options that keep a GraphQL command on REST,
+the commands that call GraphQL only with an operand or only with certain
+options, the help flags that reach no network, the HTTP client and script
+interpreter programs and the GraphQL endpoint pattern they could name, the
+hook name the block log records, and the deny message that names the REST
+routes to run instead.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "GH_PROGRAM_NAME",
+    "GH_API_SUBCOMMAND",
+    "GH_GRAPHQL_ENDPOINT",
+    "GH_ENDPOINT_PATH_SEPARATOR",
+    "GH_COMMAND_PATH_LENGTH",
+    "ALL_GH_GRAPHQL_COMMAND_GROUPS",
+    "ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS",
+    "ALL_GH_GRAPHQL_COMMAND_PATHS",
+    "ALL_GH_HELP_FLAGS",
+    "ALL_GH_REST_OPTIONS_BY_COMMAND_PATH",
+    "ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND",
+    "ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH",
+    "ALL_HTTP_CLIENT_PROGRAM_NAMES",
+    "ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES",
+    "GITHUB_GRAPHQL_ENDPOINT_PATTERN",
+    "GATE_HOOK_NAME",
+    "CLOUD_GRAPHQL_DENY_REASON",
+]
+
+GH_PROGRAM_NAME: str = "gh"
+GH_API_SUBCOMMAND: str = "api"
+GH_GRAPHQL_ENDPOINT: str = "graphql"
+GH_ENDPOINT_PATH_SEPARATOR: str = "/"
+GH_COMMAND_PATH_LENGTH: int = 2
+ALL_GH_GRAPHQL_COMMAND_GROUPS: frozenset[str] = frozenset({"pr", "issue", "project", "discussion"})
+ALL_GH_REST_COMMAND_PATHS_IN_GRAPHQL_GROUPS: frozenset[tuple[str, ...]] = frozenset(
+    {("pr", "diff")}
+)
+ALL_GH_GRAPHQL_COMMAND_PATHS: frozenset[tuple[str, ...]] = frozenset(
+    {
+        ("status",),
+        ("org", "list"),
+        ("repo", "view"),
+        ("repo", "clone"),
+        ("repo", "list"),
+        ("repo", "archive"),
+        ("repo", "unarchive"),
+        ("label", "list"),
+        ("search", "prs"),
+        ("search", "issues"),
+        ("ruleset", "list"),
+        ("gist", "list"),
+        ("release", "list"),
+        ("workflow", "run"),
+        ("repo", "sync"),
+    }
+)
+ALL_GH_HELP_FLAGS: frozenset[str] = frozenset({"--help", "-h"})
+ALL_GH_REST_OPTIONS_BY_COMMAND_PATH: dict[tuple[str, ...], frozenset[str]] = {
+    ("pr", "list"): frozenset({"--web", "-w"}),
+    ("workflow", "run"): frozenset({"--ref", "-r"}),
+    ("repo", "sync"): frozenset({"--branch", "-b"}),
+}
+ALL_GH_GRAPHQL_OPTIONS_BY_COMMAND_PATH: dict[tuple[str, ...], frozenset[str]] = {
+    ("repo", "create"): frozenset({"--template", "-p"}),
+    ("repo", "edit"): frozenset(
+        {
+            "--enable-advanced-security",
+            "--enable-secret-scanning",
+            "--enable-secret-scanning-push-protection",
+        }
+    ),
+}
+ALL_GH_COMMAND_PATHS_CALLING_GRAPHQL_WITH_AN_OPERAND: frozenset[tuple[str, ...]] = frozenset(
+    {("release", "view")}
+)
+ALL_HTTP_CLIENT_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"curl", "wget", "http", "https", "invoke-restmethod", "invoke-webrequest", "irm", "iwr"}
+)
+ALL_SCRIPT_INTERPRETER_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"node", "deno", "bun", "ruby", "perl", "php"}
+)
+GITHUB_GRAPHQL_ENDPOINT_PATTERN: re.Pattern[str] = re.compile(
+    r"api\.github\.com(?::\d+)?/graphql", re.IGNORECASE
+)
+GATE_HOOK_NAME: str = "cloud_graphql_gate.py"
+CLOUD_GRAPHQL_DENY_REASON: str = (
+    "BLOCKED: the Claude Code cloud proxy answers every GitHub GraphQL request with "
+    "HTTP 403, whatever the token. gh api graphql calls it, and so do gh pr and gh issue "
+    "(all but gh pr diff and gh pr list --web), gh project, gh discussion, gh status, "
+    "gh org list, gh repo view/clone/list/archive/unarchive, gh label list, "
+    "gh search prs/issues, gh ruleset list, gh gist list, gh release list, "
+    "gh release view with a tag, gh workflow run without --ref, gh repo sync without "
+    "--branch, gh repo create --template, and gh repo edit with a security setting. "
+    "Use REST through gh api repos/{owner}/{repo}/... or the mcp__github__ tools. "
+    "Open a PR: mcp__github__create_pull_request, or gh api repos/{owner}/{repo}/pulls "
+    "--input pr.json with title, head, base, body and draft in the JSON. "
+    "Read a PR: gh api repos/{owner}/{repo}/pulls/{n}. "
+    "Checks: gh api repos/{owner}/{repo}/commits/{sha}/check-runs. "
+    "Issues: gh api repos/{owner}/{repo}/issues/{n}. "
+    "Clone: git clone https://github.com/{owner}/{repo}. "
+    "Review threads: GET /repos/{owner}/{repo}/pulls/{n}/ccr/review_threads. "
+    "Resolve a thread: POST /repos/{owner}/{repo}/pulls/{n}/ccr/comments/{comment_id}/resolve "
+    "(or /unresolve). "
+    "Auto-merge: PUT or DELETE /repos/{owner}/{repo}/pulls/{n}/ccr/auto_merge. "
+    "Draft state: POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review "
+    "or /ccr/convert_to_draft. "
+    "A query with no REST route cannot run in this session; it needs a machine outside "
+    "the cloud proxy."
+)

package/hooks/hooks_constants/cloud_session.py

@@ -0,0 +1,17 @@
+"""Tell a hook whether it runs inside a Claude Code cloud session."""
+
+from __future__ import annotations
+
+import os
+
+from hooks_constants.cloud_session_constants import (
+    CLOUD_SESSION_ENV_TRUE_VALUE,
+    CLOUD_SESSION_ENV_VAR,
+)
+
+__all__ = ["is_cloud_session"]
+
+
+def is_cloud_session() -> bool:
+    """Return True when ``CLAUDE_CODE_REMOTE`` is ``true``, whatever its case or padding."""
+    return os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE

package/hooks/hooks_constants/cloud_session_constants.py

@@ -0,0 +1,11 @@
+"""Names the environment variable and value a Claude Code cloud session sets."""
+
+from __future__ import annotations
+
+__all__ = [
+    "CLOUD_SESSION_ENV_VAR",
+    "CLOUD_SESSION_ENV_TRUE_VALUE",
+]
+
+CLOUD_SESSION_ENV_VAR: str = "CLAUDE_CODE_REMOTE"
+CLOUD_SESSION_ENV_TRUE_VALUE: str = "true"

package/hooks/hooks_constants/gh_command_words.py

@@ -0,0 +1,52 @@
+"""Read the command words and the standalone options of a ``gh`` call.
+
+::
+
+    gh -R o/r pr list --web          words ["pr", "list"], options ["-R", "--web"]
+    gh api -X POST graphql           words ["api", "graphql"], options ["-X"]
+    gh pr merge 12 --body -h         words ["pr", "merge", "12"], options ["--body"]
+
+An option's separate value is neither a word nor an option, so a value that
+looks like a flag, such as the ``-h`` body above, reads as text.
+"""
+
+from __future__ import annotations
+
+from hooks_constants.gh_command_words_constants import (
+    ALL_GH_OPTIONS_WITH_A_VALUE,
+    GH_OPTION_PREFIX,
+    GH_OPTION_VALUE_SEPARATOR,
+)
+
+__all__ = ["gh_command_words", "gh_command_words_and_options"]
+
+
+def gh_command_words_and_options(all_arguments: list[str]) -> tuple[list[str], list[str]]:
+    """Return the command words and the option names in one pass.
+
+    Each option's separate value is skipped, and an option name drops any
+    ``=value`` part.
+
+    Args:
+        all_arguments: The tokens after the ``gh`` program name.
+    """
+    all_command_words: list[str] = []
+    all_option_names: list[str] = []
+    is_option_value = False
+    for each_argument in all_arguments:
+        is_option = not is_option_value and each_argument.startswith(GH_OPTION_PREFIX)
+        if is_option:
+            all_option_names.append(each_argument.split(GH_OPTION_VALUE_SEPARATOR, 1)[0])
+        if not is_option and not is_option_value:
+            all_command_words.append(each_argument)
+        is_option_value = is_option and each_argument in ALL_GH_OPTIONS_WITH_A_VALUE
+    return all_command_words, all_option_names
+
+
+def gh_command_words(all_arguments: list[str]) -> list[str]:
+    """Return the gh arguments that are neither an option nor an option's separate value.
+
+    Args:
+        all_arguments: The tokens after the ``gh`` program name.
+    """
+    return gh_command_words_and_options(all_arguments)[0]