claude-dev-env 8.91.0 → 8.92.1

package/.agents/skills/e-code-review/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 
 # e-code-review
 
-**Pick a level, load its file, run it.** Each file has the same steps, angles, caps, and fields as the built-in `/code-review` recipe for that level. Only the wording differs, where this repo's prose rules require it.
+**Pick a level, load its file, run it.** Each file has the same steps, angles, caps, and fields as the built-in `/code-review` recipe for that level. Only the wording differs, where this repo's prose rules require it. A question about `/code-review` asks about the built-in recipe, so answer it from the built-in text and use these files only for `/e-code-review`.
 
 | Level | File | Shape |
 |---|---|---|

package/.agents/skills/efficient-review/SKILL.md

@@ -21,7 +21,7 @@ When the plan runtime is `other`, the model is deferred. The running agent appli
 
 ## Loop
 
-Check each finding against the code. Fix every one that holds. Run the review again until a pass reports none. The steps are in [reference/criteria.md](reference/criteria.md).
+Check each finding against the code. Fix every one that holds. Run the review again until a pass reports none. Before a merge, [the pr-lifecycle review loop](../pr-lifecycle/reference/review-loop-before-merge.md) sets how many full passes run. The steps are in [reference/criteria.md](reference/criteria.md).
 
 ## Reading guide
 

package/.agents/skills/efficient-review/reference/criteria.md

@@ -18,4 +18,4 @@ An empty list is a valid review. End with a json block. Each finding has `file`,
 
 ## Loop
 
-Fix every finding that holds, including a file the diff did not touch. Then run the review again. Stop when a pass reports no finding that holds.
+Fix every finding that holds, including a file the diff did not touch. Then run the review again. Stop when a pass reports no finding that holds. Before a merge, [the pr-lifecycle review loop](../../pr-lifecycle/reference/review-loop-before-merge.md) sets how many full passes run.

package/.agents/skills/pr-lifecycle/reference/review-loop-before-merge.md

@@ -2,10 +2,11 @@
 
 A pull request the agent made merges only after a code review of its head comes back clean. Loop it:
 
-1. Review the head with the command `CLAUDE_MERGE_REVIEW_COMMAND` names. Where it is unset, run `/code-review high --max-findings all` against the base.
+1. Review the head with the command `CLAUDE_MERGE_REVIEW_COMMAND` names. Where it is unset, run `/code-review high --max-findings all` against the base. This is a full pass.
 2. Record the pass: `python3 ~/.claude/scripts/merge_review_receipt.py <owner>/<name> <number> <head sha> <finding count>`.
 3. Fix every valid finding, push, and review the new head. Answer each finding you rule out on the pull request with its file:line evidence.
-4. Repeat until a pass records `CLEAN`. A pass whose every finding is ruled out records `CLEAN` with `--ruled-out <finding count> --rulings <link to the rulings comment on this pull request>`.
-5. Merge pinned to that head: `expectedHeadSha` on the merge tool, or `--match-head-commit` on `gh pr merge`.
+4. The first three passes are full passes. Each later pass is `/code-review low --fix <number>`. It reads only the pull request's diff against its base and leaves its fixes uncommitted. Name the number: after a push, a bare `/code-review low` diffs the branch against its own upstream and sees nothing. Commit and push those fixes, then run the next pass on the new head. A pass that reported findings records its finding count, even when `--fix` fixed them all.
+5. Repeat until a pass records `CLEAN`. A pass whose every finding is ruled out records `CLEAN` with `--ruled-out <finding count> --rulings <link to the rulings comment on this pull request>`.
+6. Merge pinned to that head: `expectedHeadSha` on the merge tool, or `--match-head-commit` on `gh pr merge`.
 
 `hooks/blocking/merge_review_gate.py` denies any other merge. In a merge-queue repository, enqueue with `gh pr merge <number> --repo <owner>/<name> --auto --match-head-commit <head sha>`; auto-merge that names no head is denied. A repository whose own CI and merge queue review and merge its pull requests is listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`, comma separated as `owner/name`, and skips the gate.

package/bin/install-constants.mjs

@@ -181,6 +181,7 @@ export const ALL_CODEX_NATIVE_PRE_TOOL_USE_MATCHERS = new Set([
 ]);
 export const ALL_CODEX_NATIVE_STOP_HOOK_SCRIPT_NAMES = new Set([
     'open_tasks_stop_gate.py',
+    'owned_pr_merge_stop_gate.py',
 ]);
 export const ALL_CODEX_NATIVE_SESSION_START_HOOK_SCRIPT_NAMES = new Set([
     'compaction_recall_prompt.py',

package/bin/install.cursor-rules.test.mjs

@@ -141,8 +141,9 @@ test('seeds one editable policy and one native Codex routing hook', () => {
         assert.equal(allCodexPostToolUseCommands.length, 1, 'Codex gets the owned PR review loop and no other PostToolUse hook');
         assert.match(allCodexPostToolUseCommands[0], /advisory\/owned_pr_review_loop\.py/);
         const allCodexStopCommands = firstCodexHooks.hooks.Stop.flatMap(group => group.hooks.map(hook => hook.command));
-        assert.equal(allCodexStopCommands.length, 1, 'Codex gets the open tasks Stop gate and no other Stop hook');
+        assert.equal(allCodexStopCommands.length, 2, 'Codex gets the open tasks and owned PR merge Stop gates and no other Stop hook');
         assert.match(allCodexStopCommands[0], /open_tasks_stop_gate\.py/);
+        assert.match(allCodexStopCommands[1], /owned_pr_merge_stop_gate\.py/);
         const allCodexSessionStartGroups = firstCodexHooks.hooks.SessionStart;
         assert.deepEqual(allCodexSessionStartGroups.map(group => group.matcher), ['compact']);
         const allCodexSessionStartCommands = allCodexSessionStartGroups.flatMap(group => group.hooks.map(hook => hook.command));

package/hooks/advisory/owned_pr_review_loop.py

@@ -14,6 +14,9 @@ block to the agent's context::
     3. Babysit. Follow the pstack babysit playbook ...
     4. Ship. Follow the pstack shipping playbook ...
 
+Each reported pull request also goes into the session record, so the owned
+pull request Stop gate holds the turn until it merges.
+
 The pull request URL in the tool response is the proof that a pull request
 opened, so the hook needs no network call and reads the same on Claude Code
 and Codex.
@@ -77,6 +80,7 @@ try:
         all_wrapped_command_texts,
         segment_program_and_arguments,
     )
+    from owned_pr_session_record import record_pull_request
 except ImportError as import_error:
     raise ImportError(
         "owned_pr_review_loop: cannot import its dependencies; "
@@ -336,7 +340,8 @@ def build_review_loop_context(all_pull_request_fields: dict[str, str]) -> str:
 def main() -> None:
     """Add the review-loop instructions after a pull request opens on an owned repository.
 
-    Reads the PostToolUse payload from stdin. Every quiet branch returns with
+    Reads the PostToolUse payload from stdin. The pull request also goes into
+    the session record that the owned pull request Stop gate reads. Every quiet branch returns with
     no output, so this hook can never alter or block a tool call.
     """
     hook_payload = read_hook_input_dictionary_from_stdin()
@@ -358,6 +363,7 @@ def main() -> None:
         ALL_PRESET_REPOSITORY_DIGESTS,
     ):
         return
+    record_pull_request(hook_payload.get("session_id"), pull_request)
     write_post_tool_use_context_to_stdout(build_review_loop_context(pull_request))
 
 

package/hooks/advisory/test_owned_pr_review_loop.py

@@ -281,12 +281,29 @@ def test_should_name_every_step_and_skill_in_the_context() -> None:
     )
     assert "jl-cmd-projects/claude-dev-env#42" in context
     assert "efficient-review" in context
+    assert "three full passes" in context
+    assert "/code-review low --fix 42" in context
     assert "gh pr ready 42 --repo jl-cmd-projects/claude-dev-env" in context
     assert "poteto-mode/playbooks/babysit.md" in context
     assert "poteto-mode/playbooks/shipping.md" in context
     assert "merged" in context
 
 
+def test_should_carry_the_owner_approval_to_merge() -> None:
+    context = owned_pr_review_loop.build_review_loop_context(
+        {
+            "owner": "jl-cmd-projects",
+            "repository": "claude-dev-env",
+            "number": "42",
+            "url": OWNED_PR_URL,
+        }
+    )
+    assert "The repository owner installed this hook" in context
+    assert "approves every step above, the merge included" in context
+    assert "without asking first" in context
+    assert "Your task now runs past opening this PR to its merge" in context
+
+
 def test_main_should_emit_the_loop_after_gh_pr_create_on_an_owned_repository() -> None:
     stdout = _run_hook(_shell_payload("gh pr create --fill", f"{OWNED_PR_URL}\n"))
     payload = json.loads(stdout)
@@ -367,3 +384,11 @@ def test_hooks_json_should_route_shell_and_mcp_create_calls_to_the_hook() -> Non
         "mcp__codex_apps__github_create_pull_request",
     ):
         assert re.fullmatch(all_matchers[0], each_tool_name), each_tool_name
+
+
+def test_should_leave_a_held_pull_request_with_the_user() -> None:
+    context = owned_pr_review_loop.build_review_loop_context(
+        {"owner": "jl-cmd-projects", "repository": "claude-dev-env", "number": "42", "url": OWNED_PR_URL}
+    )
+    assert "When the user asked to hold this PR or to read it before it merges" in context
+    assert "Blocked: jl-cmd-projects/claude-dev-env#42 - the user holds the merge." in context

package/hooks/blocking/owned_pr_merge_stop_gate.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Stop hook that keeps a session working until its owned pull requests merge.
+
+The owned pull request review-loop hook records each pull request the agent
+opens on an owned repository outside the preset list. At the end of a turn
+this gate asks GitHub for the state of each recorded pull request::
+
+    allow: every recorded pull request reads closed (merged or closed)
+    allow: the reply has "Blocked: acme/widgets#42 - the owner must approve"
+    block: acme/widgets#42 reads open and the reply names no blocker for it
+
+A block sends the open pull requests back as the reason, so the model keeps
+working the loop. Claude Code ends the turn after eight blocks in a row, and
+Codex turns the reason into a continuation prompt. A state lookup that fails,
+such as a missing ``gh`` or no network, counts as closed, so the gate never
+holds a turn on a fact it could not read. The failure goes to stderr, where
+the host shows it in the hook log.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.owned_pr_merge_stop_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    BLOCK_REASON_PREFIX,
+    BLOCK_REASON_SUFFIX,
+    BLOCKED_LINE_PATTERN,
+    BLOCKED_TEXT_GROUP_INDEX,
+    BOLD_MARKER,
+    DECISION_KEY,
+    GH_API_SUBCOMMAND,
+    GH_JQ_OPTION,
+    GH_PROGRAM_NAME,
+    HOOK_EVENT_NAME,
+    LAST_ASSISTANT_MESSAGE_KEY,
+    LOOKUP_FAILURE_TEMPLATE,
+    NAME_END_PATTERN,
+    NAME_START_PATTERN,
+    OPEN_PULL_REQUEST_STATE,
+    PULL_REQUEST_ENDPOINT_TEMPLATE,
+    PULL_REQUEST_LINE_TEMPLATE,
+    PULL_REQUEST_REFERENCE_TEMPLATE,
+    PULL_REQUEST_STATE_QUERY,
+    REASON_KEY,
+    SESSION_ID_KEY,
+    STATE_QUERY_TIMEOUT_SECONDS,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from owned_pr_session_record import all_recorded_pull_requests
+
+
+def is_pull_request_open(all_pull_request_fields: dict[str, str]) -> bool:
+    """Return True when GitHub reports the pull request as open.
+
+    Args:
+        all_pull_request_fields: The owner, repository, number, and url fields.
+    """
+    endpoint = PULL_REQUEST_ENDPOINT_TEMPLATE.format(**all_pull_request_fields)
+    try:
+        completed = subprocess.run(
+            [GH_PROGRAM_NAME, GH_API_SUBCOMMAND, endpoint, GH_JQ_OPTION, PULL_REQUEST_STATE_QUERY],
+            capture_output=True,
+            text=True,
+            timeout=STATE_QUERY_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as lookup_error:
+        sys.stderr.write(LOOKUP_FAILURE_TEMPLATE.format(endpoint=endpoint, detail=lookup_error))
+        return False
+    if completed.returncode != 0:
+        sys.stderr.write(LOOKUP_FAILURE_TEMPLATE.format(endpoint=endpoint, detail=completed.stderr.strip()))
+    return completed.returncode == 0 and completed.stdout.strip() == OPEN_PULL_REQUEST_STATE
+
+
+def is_reported_blocked(all_pull_request_fields: dict[str, str], reply_text: str) -> bool:
+    """Return True when a Blocked: line of the reply names the pull request.
+
+    The line names it by ``owner/repository#number`` or by its url. Bold
+    markers such as ``**Blocked:**`` are ignored.
+
+    Args:
+        all_pull_request_fields: The owner, repository, number, and url fields.
+        reply_text: The closing reply of the turn.
+    """
+    all_names = (
+        PULL_REQUEST_REFERENCE_TEMPLATE.format(**all_pull_request_fields).lower(),
+        all_pull_request_fields["url"].lower(),
+    )
+    all_blocked_texts = (
+        each_match.group(BLOCKED_TEXT_GROUP_INDEX).lower()
+        for each_match in map(BLOCKED_LINE_PATTERN.match, reply_text.replace(BOLD_MARKER, "").splitlines())
+        if each_match
+    )
+    all_name_patterns = [NAME_START_PATTERN + re.escape(each_name) + NAME_END_PATTERN for each_name in all_names]
+    return any(
+        re.search(each_pattern, each_text)
+        for each_text in all_blocked_texts
+        for each_pattern in all_name_patterns
+    )
+
+
+def unfinished_pull_requests(all_hook_input_fields: dict[str, object]) -> list[dict[str, str]]:
+    """Return the recorded pull requests that are open and not reported blocked.
+
+    Args:
+        all_hook_input_fields: The Stop hook payload.
+    """
+    reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
+    reply_text = reply_value if isinstance(reply_value, str) else ""
+    return [
+        each_pull_request
+        for each_pull_request in all_recorded_pull_requests(
+            all_hook_input_fields.get(SESSION_ID_KEY)
+        )
+        if not is_reported_blocked(each_pull_request, reply_text)
+        and is_pull_request_open(each_pull_request)
+    ]
+
+
+def block_reason_for(all_open_pull_requests: list[dict[str, str]]) -> str:
+    """Return the block reason that lists each open pull request.
+
+    Args:
+        all_open_pull_requests: The pull requests that hold the turn.
+    """
+    all_lines = (PULL_REQUEST_LINE_TEMPLATE.format(**each) for each in all_open_pull_requests)
+    return BLOCK_REASON_PREFIX + "".join(all_lines) + BLOCK_REASON_SUFFIX
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    all_open_pull_requests = unfinished_pull_requests(hook_input)
+    if not all_open_pull_requests:
+        return ALLOW_EXIT_CODE
+    block_reason = block_reason_for(all_open_pull_requests)
+    log_hook_block(Path(__file__).name, HOOK_EVENT_NAME, block_reason)
+    sys.stdout.write(json.dumps({DECISION_KEY: BLOCK_DECISION, REASON_KEY: block_reason}))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_merge_review_gate.py

@@ -178,6 +178,12 @@ def test_should_name_the_configured_review_command(monkeypatch: pytest.MonkeyPat
     assert "`/team-review`" in _reason(_merge_tool(CLEAN_HEAD))
 
 
+def test_should_name_the_low_fix_pass_after_three_full_reviews_in_the_deny_reason() -> None:
+    reason = _reason(_merge_tool(CLEAN_HEAD))
+    assert "three full passes" in reason
+    assert "`/code-review low --fix 12`" in reason
+
+
 def test_should_allow_auto_merge_pinned_to_the_clean_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 {CLEAN_HEAD}"

package/hooks/blocking/test_owned_pr_merge_stop_gate.py

@@ -0,0 +1,163 @@
+"""Behavior tests for the owned pull request merge Stop gate."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+import owned_pr_merge_stop_gate
+import owned_pr_session_record
+
+SESSION_ID = "session-abc"
+PULL_REQUEST = {
+    "owner": "jl-cmd",
+    "repository": "snake-game",
+    "number": "9",
+    "url": "https://github.com/jl-cmd/snake-game/pull/9",
+}
+
+
+@pytest.fixture(autouse=True)
+def isolated_temp_folder(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(owned_pr_session_record.tempfile, "gettempdir", lambda: str(tmp_path))
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+
+def _gh_reports(
+    monkeypatch: pytest.MonkeyPatch, state_text: str, exit_code: int = 0
+) -> list[list[str]]:
+    all_calls: list[list[str]] = []
+
+    def fake_run(all_arguments: list[str], **_: object) -> subprocess.CompletedProcess[str]:
+        all_calls.append(all_arguments)
+        return subprocess.CompletedProcess(all_arguments, exit_code, stdout=state_text, stderr="")
+
+    monkeypatch.setattr(owned_pr_merge_stop_gate.subprocess, "run", fake_run)
+    return all_calls
+
+
+def _run_gate(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> str:
+    hook_input = {
+        "hook_event_name": "Stop",
+        "session_id": SESSION_ID,
+        "last_assistant_message": reply_text,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    assert owned_pr_merge_stop_gate.main() == 0
+    return capsys.readouterr().out
+
+
+def test_main_should_block_while_a_recorded_pull_request_is_open(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    all_calls = _gh_reports(monkeypatch, "open\n")
+    decision = json.loads(_run_gate(monkeypatch, capsys, "Draft PR is open."))
+    assert decision["decision"] == "block"
+    assert PULL_REQUEST["url"] in decision["reason"]
+    assert "/efficient-review" in decision["reason"]
+    assert all_calls == [["gh", "api", "repos/jl-cmd/snake-game/pulls/9", "--jq", ".state"]]
+
+
+def test_main_should_allow_once_the_pull_request_is_closed(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "closed\n")
+    assert _run_gate(monkeypatch, capsys, "Merged.") == ""
+
+
+def test_main_should_allow_a_blocked_line_that_names_the_pull_request(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "open\n")
+    reply_text = "Review is clean.\nBlocked: jl-cmd/snake-game#9 - the owner must approve the merge"
+    assert _run_gate(monkeypatch, capsys, reply_text) == ""
+
+
+def test_main_should_block_when_the_blocked_line_names_another_pull_request(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "open\n")
+    reply_text = "Blocked: jl-cmd/snake-game#90 - the owner must approve the merge"
+    assert json.loads(_run_gate(monkeypatch, capsys, reply_text))["decision"] == "block"
+
+
+def test_main_should_allow_when_the_state_lookup_fails(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "", exit_code=1)
+    assert _run_gate(monkeypatch, capsys, "Draft PR is open.") == ""
+
+
+def test_main_should_allow_a_session_that_opened_no_owned_pull_request(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    all_calls = _gh_reports(monkeypatch, "open\n")
+    assert _run_gate(monkeypatch, capsys, "Done.") == ""
+    assert all_calls == []
+
+
+def test_is_pull_request_open_should_read_the_github_state(monkeypatch: pytest.MonkeyPatch) -> None:
+    _gh_reports(monkeypatch, "open\n")
+    assert owned_pr_merge_stop_gate.is_pull_request_open(PULL_REQUEST)
+
+
+def test_is_reported_blocked_should_accept_the_url() -> None:
+    reply_text = f"- Blocked: {PULL_REQUEST['url']} - needs the owner"
+    assert owned_pr_merge_stop_gate.is_reported_blocked(PULL_REQUEST, reply_text)
+
+
+def test_unfinished_pull_requests_should_list_the_open_one(monkeypatch: pytest.MonkeyPatch) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "open\n")
+    hook_input: dict[str, object] = {"session_id": SESSION_ID, "last_assistant_message": "Open."}
+    assert owned_pr_merge_stop_gate.unfinished_pull_requests(hook_input) == [PULL_REQUEST]
+
+
+def test_block_reason_for_should_name_each_pull_request_and_the_blocked_form() -> None:
+    reason = owned_pr_merge_stop_gate.block_reason_for([PULL_REQUEST])
+    assert PULL_REQUEST["url"] in reason
+    assert "Blocked: <owner>/<repository>#<number>" in reason
+
+
+def test_main_should_report_a_failed_lookup_on_stderr(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    _gh_reports(monkeypatch, "", exit_code=1)
+    hook_input = {"hook_event_name": "Stop", "session_id": SESSION_ID, "last_assistant_message": "Open."}
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8"))))
+    owned_pr_merge_stop_gate.main()
+    assert "could not read repos/jl-cmd/snake-game/pulls/9" in capsys.readouterr().err
+
+
+def test_is_reported_blocked_should_accept_a_bold_blocked_label() -> None:
+    reply_text = "**Blocked:** jl-cmd/snake-game#9 - the owner must approve the merge"
+    assert owned_pr_merge_stop_gate.is_reported_blocked(PULL_REQUEST, reply_text)
+
+
+def test_is_reported_blocked_should_skip_a_longer_owner_that_ends_with_the_name() -> None:
+    suffix_pull_request = {**PULL_REQUEST, "owner": "cmd", "url": "https://github.com/cmd/snake-game/pull/9"}
+    reply_text = "Blocked: jl-cmd/snake-game#9 - the owner must approve the merge"
+    assert not owned_pr_merge_stop_gate.is_reported_blocked(suffix_pull_request, reply_text)
+
+
+def test_block_reason_for_should_name_a_user_hold_as_a_blocker() -> None:
+    assert "asked to hold the PR or to read it first" in owned_pr_merge_stop_gate.block_reason_for([PULL_REQUEST])
+
+
+def test_is_reported_blocked_should_require_the_colon_after_blocked() -> None:
+    reply_text = "Blocked while CI runs on jl-cmd/snake-game#9."
+    assert not owned_pr_merge_stop_gate.is_reported_blocked(PULL_REQUEST, reply_text)

package/hooks/features/bash-dispatchers.md

@@ -11,7 +11,8 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `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.
-- `advisory/owned_pr_review_loop.py` adds review-loop instructions after the agent opens a pull request on an owned repository outside the preset list of repositories that run their own automated review: run efficient-review until clean, mark the pull request ready, babysit it, and ship it to merge.
+- `advisory/owned_pr_review_loop.py` adds review-loop instructions after the agent opens a pull request on an owned repository outside the preset list of repositories that run their own automated review: run efficient-review until clean, mark the pull request ready, babysit it, and ship it to merge. It also records the pull request for the session in `owned_pr_session_record.py`.
+- `blocking/owned_pr_merge_stop_gate.py` holds the end of a turn while a recorded pull request reads open on GitHub and the closing reply has no `Blocked:` line that names it. A failed state lookup passes.
 
 ## When it fires
 
@@ -23,6 +24,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `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`.
 - `advisory/owned_pr_review_loop.py` runs on `PostToolUse`, matcher `Bash|PowerShell|exec_command|shell_command|mcp__.*__(create_pull_request|github_create_pull_request)`, timeout `10` seconds in `hooks.json`. It wakes on `gh pr create`, `gh pr new`, a POST to `gh api repos/<owner>/<repo>/pulls`, and an MCP pull request creation. The installer also registers it on Codex `PostToolUse` through `ALL_CODEX_NATIVE_POST_TOOL_USE_HOOK_SCRIPT_NAMES`.
+- `blocking/owned_pr_merge_stop_gate.py` runs on `Stop`, timeout `60` seconds in `hooks.json`. The installer also registers it on Codex `Stop` through `ALL_CODEX_NATIVE_STOP_HOOK_SCRIPT_NAMES`.
 
 ## Proving it
 
@@ -37,6 +39,7 @@ Preconditions:
 - **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.
 - **Owned pull request review loop.** Input is a pull request creation result on an owned repository. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_owned_pr_review_loop.py -q`. The adjacent test observes the review-loop block for owned repositories and silence for the preset and foreign repositories.
+- **Owned pull request merge gate.** Input is a `session_record_path` file that lists `jl-cmd/snake-game#9` and a `gh` stub that reports `open`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_owned_pr_merge_stop_gate.py packages/claude-dev-env/hooks/test_owned_pr_session_record.py -q`. The adjacent test observes a `block` decision that names the pull request; `closed` and a `Blocked: jl-cmd/snake-game#9 - ...` line pass.
 
 ## Gotchas
 

package/hooks/features/conduct-gates.md

@@ -17,7 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `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/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.
+- `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_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.
 

package/hooks/hooks.json

@@ -385,6 +385,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_tasks_stop_gate.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/owned_pr_merge_stop_gate.py",
+            "timeout": 60
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_title_turn_gate.py",

package/hooks/hooks_constants/merge_review_gate_constants.py

@@ -54,8 +54,10 @@ RECORD_COMMAND = "python3 ~/.claude/scripts/merge_review_receipt.py"
 NO_CLEAN_REVIEW_REASON_TEMPLATE = (
     "{slug}#{number} has no clean review on the head you are merging. Run the review "
     "loop: review the pull request head with `{review_command}`, fix and push every "
-    "finding, and review again "
-    "until a pass reports zero findings or every finding is ruled out with file:line "
+    "finding, and review again. After three full passes, each later pass is "
+    "`/code-review low --fix {number}`, which names the pull request so the diff "
+    "covers its base: commit and push its fixes, then review the new head. "
+    "Repeat until a pass reports zero findings or every finding is ruled out with file:line "
     "evidence. Record that pass with `"
     + RECORD_COMMAND
     + " {slug} {number} <head sha> <finding count>`, adding `--ruled-out <finding count> "

package/hooks/hooks_constants/owned_pr_merge_stop_gate_constants.py

@@ -0,0 +1,37 @@
+"""Constants for the owned pull request merge Stop gate."""
+
+import re
+
+HOOK_EVENT_NAME = "Stop"
+SESSION_ID_KEY = "session_id"
+LAST_ASSISTANT_MESSAGE_KEY = "last_assistant_message"
+DECISION_KEY = "decision"
+BLOCK_DECISION = "block"
+REASON_KEY = "reason"
+ALLOW_EXIT_CODE = 0
+GH_PROGRAM_NAME = "gh"
+GH_API_SUBCOMMAND = "api"
+GH_JQ_OPTION = "--jq"
+PULL_REQUEST_ENDPOINT_TEMPLATE = "repos/{owner}/{repository}/pulls/{number}"
+PULL_REQUEST_STATE_QUERY = ".state"
+OPEN_PULL_REQUEST_STATE = "open"
+STATE_QUERY_TIMEOUT_SECONDS = 10
+LOOKUP_FAILURE_TEMPLATE = "owned_pr_merge_stop_gate: could not read {endpoint}: {detail}\n"
+BLOCKED_LINE_PATTERN: re.Pattern[str] = re.compile(
+    r"^\s*(?:[-*]\s*)?blocked\s*:(.*)$", re.IGNORECASE
+)
+BLOCKED_TEXT_GROUP_INDEX = 1
+BOLD_MARKER = "**"
+NAME_START_PATTERN = r"(?<![0-9A-Za-z_./-])"
+NAME_END_PATTERN = r"(?![0-9A-Za-z/])"
+PULL_REQUEST_REFERENCE_TEMPLATE = "{owner}/{repository}#{number}"
+PULL_REQUEST_LINE_TEMPLATE = "\n- {url}"
+BLOCK_REASON_PREFIX = "You opened these owned pull requests and they are still open:"
+BLOCK_REASON_SUFFIX = (
+    "\nThe repository owner approves the whole owned PR loop, the merge included."
+    " Keep working now: run /efficient-review until a pass is clean, mark the PR ready,"
+    " babysit CI and review threads, then merge it and read it back as merged."
+    " End the turn early only with one line per pull request:"
+    " 'Blocked: <owner>/<repository>#<number> - <what only the owner can give>'."
+    " A user who asked to hold the PR or to read it first is such a blocker."
+)

package/hooks/hooks_constants/owned_pr_review_loop_constants.py

@@ -48,6 +48,9 @@ __all__ = [
     "ALL_DECLARED_URL_KEYS",
     "JSON_OBJECT_OPENER",
     "REVIEW_LOOP_CONTEXT_TEMPLATE",
+    "SESSION_RECORD_FILE_TEMPLATE",
+    "SESSION_RECORD_TEMPORARY_PREFIX",
+    "ALL_PULL_REQUEST_FIELD_NAMES",
 ]
 
 NAME_DIGEST_TEXT_ENCODING: str = "utf-8"
@@ -99,13 +102,21 @@ ALREADY_EXISTS_MARKER: str = "already exists"
 ALL_DECLARED_URL_KEYS: tuple[str, ...] = ("html_url", "url")
 JSON_OBJECT_OPENER: str = "{"
 
+SESSION_RECORD_FILE_TEMPLATE: str = "owned-pr-loop-{session_file_id}.json"
+SESSION_RECORD_TEMPORARY_PREFIX: str = "owned-pr-loop-"
+ALL_PULL_REQUEST_FIELD_NAMES: tuple[str, ...] = ("owner", "repository", "number", "url")
+
 REVIEW_LOOP_CONTEXT_TEMPLATE: str = (
     "=== OWNED PR REVIEW LOOP (context reminder, never a block) ===\n"
     "You opened {owner}/{repository}#{number}  {url}\n"
     "This repository has no automated review, so you own the review and the merge.\n"
+    "Your task now runs past opening this PR to its merge, also when your brief\n"
+    "asked for a draft or stopped at opening it.\n"
     "1. Review loop. Load the efficient-review skill (/efficient-review). Review the\n"
     "   branch, check each finding against the code, fix every one that holds, push,\n"
-    "   and review again. Repeat until a pass reports no findings.\n"
+    "   and review again. After three full passes, each later pass is\n"
+    "   /code-review low --fix {number}; commit and push its fixes, then review the new head.\n"
+    "   Repeat until a pass reports no findings.\n"
     "2. Mark ready. Once the loop is clean, CI is green, and no review thread is open,\n"
     "   mark the PR ready for review (gh pr ready {number} --repo {owner}/{repository},\n"
     "   or update_pull_request with draft false).\n"
@@ -116,5 +127,9 @@ REVIEW_LOOP_CONTEXT_TEMPLATE: str = (
     "4. Ship. Follow the pstack shipping playbook (poteto-mode/playbooks/shipping.md)\n"
     "   to land the PR, or the pr-lifecycle skill outside poteto-mode. Read the PR\n"
     "   back and confirm it reads merged.\n"
-    "Run each step yourself. The task ends at a merged PR or a named blocker."
+    "The repository owner installed this hook and\n"
+    "approves every step above, the merge included. Run each step yourself\n"
+    "without asking first. The task ends at a merged PR or a named blocker.\n"
+    "When the user asked to hold this PR or to read it before it merges, stop\n"
+    "after step 3 and end with: Blocked: {owner}/{repository}#{number} - the user holds the merge."
 )

package/hooks/owned_pr_session_record.py

@@ -0,0 +1,104 @@
+"""Session record of the owned pull requests an agent opened.
+
+The owned pull request review-loop hook writes each pull request it reports
+into one JSON file per session in the system temp folder. The owned pull
+request Stop gate reads the same file back::
+
+    owned-pr-loop-<session id>.json
+    [{"owner": "acme", "repository": "widgets", "number": "42",
+      "url": "https://github.com/acme/widgets/pull/42"}]
+
+Both Claude Code and Codex send ``session_id`` to PostToolUse and Stop hooks,
+so the file links the two hooks on either host.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from atomic_file_writer import write_text_atomically
+from hooks_constants.atomic_file_writer_constants import ATOMIC_WRITE_TEMPORARY_SUFFIX
+from hooks_constants.owned_pr_review_loop_constants import (
+    ALL_PULL_REQUEST_FIELD_NAMES,
+    NAME_DIGEST_TEXT_ENCODING,
+    SESSION_RECORD_FILE_TEMPLATE,
+    SESSION_RECORD_TEMPORARY_PREFIX,
+)
+from hooks_constants.session_file_id import session_file_id
+
+__all__ = ["session_record_path", "all_recorded_pull_requests", "record_pull_request"]
+
+
+def session_record_path(session_id: object) -> Path:
+    """Return the record file path for one session.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+    """
+    file_name = SESSION_RECORD_FILE_TEMPLATE.format(session_file_id=session_file_id(session_id))
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def _is_session_id(session_id: object) -> bool:
+    return isinstance(session_id, str) and bool(session_id)
+
+
+def _is_pull_request_entry(entry: object) -> bool:
+    return isinstance(entry, dict) and all(
+        isinstance(entry.get(each_field), str) for each_field in ALL_PULL_REQUEST_FIELD_NAMES
+    )
+
+
+def all_recorded_pull_requests(session_id: object) -> list[dict[str, str]]:
+    """Return the pull requests recorded for the session, oldest first.
+
+    A payload with no session id, or a missing, unreadable, or malformed
+    file, reads as an empty record.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+    """
+    if not _is_session_id(session_id):
+        return []
+    try:
+        record_text = session_record_path(session_id).read_text(encoding=NAME_DIGEST_TEXT_ENCODING)
+        all_entries = json.loads(record_text)
+    except (OSError, ValueError):
+        return []
+    if not isinstance(all_entries, list):
+        return []
+    return [each_entry for each_entry in all_entries if _is_pull_request_entry(each_entry)]
+
+
+def record_pull_request(session_id: object, all_pull_request_fields: dict[str, str]) -> None:
+    """Add one pull request to the session record, once per url.
+
+    A payload with no session id records nothing. A write that fails leaves
+    the record as it was, so the PostToolUse hook still adds its context.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+        all_pull_request_fields: The owner, repository, number, and url fields.
+    """
+    if not _is_session_id(session_id):
+        return
+    all_entries = all_recorded_pull_requests(session_id)
+    if any(each_entry["url"] == all_pull_request_fields["url"] for each_entry in all_entries):
+        return
+    new_entry = {
+        each_field: all_pull_request_fields[each_field]
+        for each_field in ALL_PULL_REQUEST_FIELD_NAMES
+    }
+    try:
+        write_text_atomically(
+            session_record_path(session_id),
+            json.dumps([*all_entries, new_entry]),
+            NAME_DIGEST_TEXT_ENCODING,
+            SESSION_RECORD_TEMPORARY_PREFIX,
+            ATOMIC_WRITE_TEMPORARY_SUFFIX,
+            False,
+        )
+    except (OSError, UnicodeError):
+        return

package/hooks/test_owned_pr_session_record.py

@@ -0,0 +1,46 @@
+"""Behavior tests for the owned pull request session record."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import owned_pr_session_record
+
+SESSION_ID = "session-abc"
+PULL_REQUEST = {
+    "owner": "jl-cmd",
+    "repository": "snake-game",
+    "number": "9",
+    "url": "https://github.com/jl-cmd/snake-game/pull/9",
+}
+
+
+@pytest.fixture(autouse=True)
+def isolated_temp_folder(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(owned_pr_session_record.tempfile, "gettempdir", lambda: str(tmp_path))
+
+
+def test_session_record_path_should_name_the_session_in_the_temp_folder(tmp_path: Path) -> None:
+    assert (
+        owned_pr_session_record.session_record_path("a/b c") == tmp_path / "owned-pr-loop-abc.json"
+    )
+
+
+def test_record_pull_request_should_keep_one_entry_per_url() -> None:
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    owned_pr_session_record.record_pull_request(SESSION_ID, PULL_REQUEST)
+    assert owned_pr_session_record.all_recorded_pull_requests(SESSION_ID) == [PULL_REQUEST]
+
+
+def test_record_pull_request_should_skip_a_payload_without_a_session_id(tmp_path: Path) -> None:
+    owned_pr_session_record.record_pull_request(None, PULL_REQUEST)
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_all_recorded_pull_requests_should_read_a_malformed_file_as_empty() -> None:
+    owned_pr_session_record.session_record_path(SESSION_ID).write_text(
+        "{not json", encoding="utf-8"
+    )
+    assert owned_pr_session_record.all_recorded_pull_requests(SESSION_ID) == []

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -140,6 +140,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/merge_over_review_offer_gate.py   -> exempt
         hooks/blocking/final_reply_gate.py               -> exempt
         hooks/blocking/open_tasks_stop_gate.py           -> exempt
+        hooks/blocking/owned_pr_merge_stop_gate.py       -> exempt
         hooks/blocking/session_title_turn_gate.py        -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
@@ -186,6 +187,11 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     ``Blocked:`` or ``Open:``. It decides when a turn may end and no code or
     safety policy.
 
+    The owned pull request Stop gate holds the end of a turn while a pull
+    request the session opened on an owned repository is still open and the
+    closing reply names no ``Blocked:`` line for it. It decides when a turn may
+    end and no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -79,6 +79,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/merge_over_review_offer_gate.py",
     "blocking/final_reply_gate.py",
     "blocking/open_tasks_stop_gate.py",
+    "blocking/owned_pr_merge_stop_gate.py",
     "blocking/session_title_turn_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})