claude-dev-env 8.80.0 → 8.81.0

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -261,14 +261,24 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     return None if duplicate_reason is None else _deny(duplicate_reason)
 
 
-def _transcript_paths(all_payload_fields: dict[str, object]) -> list[str]:
+def transcript_paths(all_payload_fields: dict[str, object]) -> list[str]:
+    """Return each transcript path a hook payload names, with the subagent transcript last.
+
+    ::
+
+        transcript_path only                     -> [transcript_path]
+        transcript_path and a known agent_id     -> [transcript_path, <session>/subagents/agent-<id>.jsonl]
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
     paths = [all_payload_fields.get(field) for field in ALL_TRANSCRIPT_PATH_FIELDS]
     paths.append(_subagent_transcript_path(all_payload_fields))
     return list(dict.fromkeys(path for path in paths if isinstance(path, str) and path))
 
 
 def _is_skill_unloaded(all_payload_fields: dict[str, object]) -> bool:
-    readable_paths = _transcript_paths(all_payload_fields)
+    readable_paths = transcript_paths(all_payload_fields)
     if not readable_paths:
         return False
     statuses = [_scanned_transcript(path, _shows_skill_load) for path in readable_paths]
@@ -278,7 +288,7 @@ def _is_skill_unloaded(all_payload_fields: dict[str, object]) -> bool:
 def _is_build_eval_missing(all_payload_fields: dict[str, object]) -> bool:
     all_statuses = [
         _scanned_transcript(each_path, _shows_build_eval)
-        for each_path in _transcript_paths(all_payload_fields)
+        for each_path in transcript_paths(all_payload_fields)
     ]
     all_read_statuses = [each_status for each_status in all_statuses if each_status is not None]
     return bool(all_read_statuses) and not any(all_read_statuses)

package/hooks/blocking/pull_request_proof.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 import subprocess
 import sys
-from collections.abc import Mapping
+from collections.abc import Iterator, Mapping
 from typing import NamedTuple
 from pathlib import Path
 
@@ -130,15 +130,30 @@ def _create_arguments(all_segment_tokens: list[str]) -> list[str] | None:
     return _script_create_arguments(program, all_arguments)
 
 
+def _shell_command(all_payload_fields: Mapping[str, object]) -> str | None:
+    tool_input = all_payload_fields.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    return command
+
+
+def _all_create_argument_lists(command: str) -> Iterator[list[str]]:
+    return (
+        all_create_arguments
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+        if (all_create_arguments := _create_arguments(each_segment)) is not None
+    )
+
+
 def _shell_create_calls(command: str, working_directory: str) -> list[CreateCall]:
     return [
         CreateCall(
             title_from_arguments(all_create_arguments),
             body_from_arguments(all_create_arguments, working_directory),
         )
-        for each_text in all_wrapped_command_texts(command)
-        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
-        if (all_create_arguments := _create_arguments(each_segment)) is not None
+        for all_create_arguments in _all_create_argument_lists(command)
     ]
 
 
@@ -156,15 +171,12 @@ def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
     head_branch = None if create_fields is None else create_fields.get("head")
     if isinstance(head_branch, str):
         return head_branch
-    tool_input = all_payload_fields.get("tool_input")
-    command = tool_input.get("command") if isinstance(tool_input, dict) else None
-    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
+    command = _shell_command(all_payload_fields)
+    if command is None:
         return None
     all_head_flag_values = [
         _head_flag_value(all_create_arguments)
-        for each_text in all_wrapped_command_texts(command)
-        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
-        if (all_create_arguments := _create_arguments(each_segment)) is not None
+        for all_create_arguments in _all_create_argument_lists(command)
     ]
     return next((each_value for each_value in all_head_flag_values if each_value), None)
 
@@ -180,9 +192,8 @@ def _create_calls(all_payload_fields: Mapping[str, object]) -> list[CreateCall]:
                 body if isinstance(body, str) else "",
             )
         ]
-    tool_input = all_payload_fields.get("tool_input")
-    command = tool_input.get("command") if isinstance(tool_input, dict) else None
-    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
+    command = _shell_command(all_payload_fields)
+    if command is None:
         return []
     working_directory = all_payload_fields.get("cwd")
     return _shell_create_calls(
@@ -190,6 +201,24 @@ def _create_calls(all_payload_fields: Mapping[str, object]) -> list[CreateCall]:
     )
 
 
+def is_create_call(all_payload_fields: Mapping[str, object]) -> bool:
+    """Return whether a tool call opens a pull request.
+
+    ::
+
+        gh pr create --title t --body-file b.md         -> True
+        mcp__github__create_pull_request                -> True
+        gh pr edit 7, git push, Read                    -> False
+
+    Args:
+        all_payload_fields: A tool name and input, shaped like a PreToolUse payload.
+    """
+    command = _shell_command(all_payload_fields)
+    return create_tool_fields(all_payload_fields) is not None or (
+        command is not None and next(_all_create_argument_lists(command), None) is not None
+    )
+
+
 def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
     return [each_call.body for each_call in _create_calls(all_payload_fields)]
 

package/hooks/blocking/pull_request_proof_edit_gate.py

@@ -0,0 +1,180 @@
+"""Deny an edit to the pull request proof gate while its last deny in the session has no passing create call after it."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from blocking.codex_apply_patch import payload_patch_target_paths
+from blocking.pr_lifecycle_skill_gate import transcript_paths
+from blocking.pull_request_proof import is_create_call
+from blocking.step_note_gate import entry_content_blocks
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
+)
+from hooks_constants.pr_lifecycle_skill_gate_constants import (
+    DENY_DECISION,
+    HOOK_EVENT_NAME,
+    PERMISSION_DECISION_REASON_KEY,
+)
+from hooks_constants.pre_tool_use_dispatcher_constants import APPLY_PATCH_TOOL_NAME
+from hooks_constants.pre_tool_use_stdin import print_decision_from_stdin
+from hooks_constants.pull_request_proof_constants import (
+    ALL_PROOF_GATE_DENY_MARKERS,
+    ALL_PROOF_GATE_FILE_NAMES,
+    GATE_EDIT_BEFORE_ROUTE_REASON,
+    LINE_SEPARATOR,
+    POSIX_PATH_SEPARATOR,
+    WINDOWS_PATH_SEPARATOR,
+)
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from hooks_constants.spawn_readiness_hook_constants import (
+    TOOL_RESULT_BLOCK_TYPE,
+    TOOL_USE_BLOCK_TYPE,
+)
+
+
+def _content_blocks(transcript_line: str) -> list[dict]:
+    try:
+        entry = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(entry, dict) or not isinstance(entry.get("message"), dict):
+        return []
+    return entry_content_blocks(entry)
+
+
+def _result_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    return LINE_SEPARATOR.join(
+        each_block["text"]
+        for each_block in content
+        if isinstance(each_block, dict) and isinstance(each_block.get("text"), str)
+    )
+
+
+def _is_proof_gate_deny(all_block_fields: dict[str, object]) -> bool:
+    result_text = _result_text(all_block_fields.get("content"))
+    return any(each_marker in result_text for each_marker in ALL_PROOF_GATE_DENY_MARKERS)
+
+
+def _deny_state_after(
+    all_block_fields: dict[str, object], all_create_tool_use_ids: set[str], is_deny_open: bool
+) -> bool:
+    if all_block_fields.get("type") == TOOL_USE_BLOCK_TYPE:
+        tool_use_id = all_block_fields.get("id")
+        payload = {"tool_name": all_block_fields.get("name"), "tool_input": all_block_fields.get("input")}
+        if isinstance(tool_use_id, str) and is_create_call(payload):
+            all_create_tool_use_ids.add(tool_use_id)
+        return is_deny_open
+    if all_block_fields.get("type") != TOOL_RESULT_BLOCK_TYPE:
+        return is_deny_open
+    result_tool_use_id = all_block_fields.get("tool_use_id")
+    if not isinstance(result_tool_use_id, str) or result_tool_use_id not in all_create_tool_use_ids:
+        return is_deny_open
+    if all_block_fields.get("is_error") is True:
+        return is_deny_open or _is_proof_gate_deny(all_block_fields)
+    return False
+
+
+def has_open_deny(all_transcript_lines: Iterable[str]) -> bool:
+    """Return whether the proof gate's last deny in a transcript has no passing create call after it.
+
+    ::
+
+        create denied with the proof gate's reason             -> True
+        create denied, later create returned without an error  -> False
+        no deny from the proof gate                            -> False
+
+    A deny is an errored result of a create call that carries one of the proof gate's guide paths.
+
+    Args:
+        all_transcript_lines: The JSON lines of a session transcript, oldest first.
+    """
+    all_create_tool_use_ids: set[str] = set()
+    is_deny_open = False
+    for each_line in all_transcript_lines:
+        for each_block in _content_blocks(each_line):
+            is_deny_open = _deny_state_after(each_block, all_create_tool_use_ids, is_deny_open)
+    return is_deny_open
+
+
+def _transcript_has_open_deny(transcript_path: str) -> bool:
+    try:
+        with open(transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY) as transcript:
+            return has_open_deny(transcript)
+    except OSError:
+        return False
+
+
+def _target_paths(all_payload_fields: Mapping[str, object]) -> tuple[str, ...]:
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return ()
+    if all_payload_fields.get("tool_name") == APPLY_PATCH_TOOL_NAME:
+        try:
+            return payload_patch_target_paths(dict(all_payload_fields), tool_input)
+        except ValueError:
+            return ()
+    file_path = tool_input.get("file_path")
+    return (file_path,) if isinstance(file_path, str) else ()
+
+
+def _edits_proof_gate(all_payload_fields: Mapping[str, object]) -> bool:
+    return any(
+        Path(each_path.replace(WINDOWS_PATH_SEPARATOR, POSIX_PATH_SEPARATOR)).name.lower()
+        in ALL_PROOF_GATE_FILE_NAMES
+        for each_path in _target_paths(all_payload_fields)
+    )
+
+
+def gate_edit_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason for an edit to the proof gate while its last deny is still open, else None.
+
+    ::
+
+        Edit or apply_patch of a gate file after an open deny       -> GATE_EDIT_BEFORE_ROUTE_REASON
+        Edit of pull_request_proof.py after a later passing create  -> None
+        Edit of any other file, or no readable transcript           -> None
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input of a Write, Edit, MultiEdit or apply_patch call.
+    """
+    if not _edits_proof_gate(all_payload_fields):
+        return None
+    if any(_transcript_has_open_deny(each_path) for each_path in transcript_paths(dict(all_payload_fields))):
+        return GATE_EDIT_BEFORE_ROUTE_REASON
+    return None
+
+
+def _gate_edit_decision(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
+    reason = gate_edit_reason(all_payload_fields)
+    if reason is None:
+        return None
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME,
+            PERMISSION_DECISION_KEY: DENY_DECISION,
+            PERMISSION_DECISION_REASON_KEY: reason,
+        }
+    }
+
+
+def main() -> int:
+    """Read one Write, Edit, MultiEdit or apply_patch payload and print a deny when it edits the proof gate too soon."""
+    return print_decision_from_stdin(_gate_edit_decision)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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"

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/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/pre_tool_use_dispatcher_constants.py

@@ -87,4 +87,8 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/context_budget_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/pull_request_proof_edit_gate.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -59,9 +59,10 @@ MISSING_LOOK_REASON = (
 CHANGED_FILES_SEPARATOR = ", "
 UNREADABLE_CHANGES_REASON = (
     "Git in this directory cannot list the files this pull request changes, so the"
-    " picture check cannot tell whether people see the change. Run the create call"
-    " from a checkout of the head branch with origin fetched, or put a screenshot"
-    " link in the 'Proof in practice' section. Read " + PROOF_GUIDE_PATH + " for the full rule."
+    " picture check cannot tell whether people see the change. Put a screenshot or"
+    " Artifact link in the 'Proof in practice' section and run the create call again,"
+    " or run it from a checkout of the head branch with origin fetched. Take one of"
+    " these routes now, before any change to this gate. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
 FEATURE_TITLE_PATTERN = r"^\s*feat(\([^)]*\))?!?:"
 EVAL_HEADING_PATTERN = r"^(#{1,6})[ \t]+evals?[ \t]*#*[ \t]*$"
@@ -83,3 +84,21 @@ MISSING_BUILD_EVAL_REASON = (
     + EVAL_GUIDE_PATH
     + " for the full rule."
 )
+ALL_PROOF_GATE_DENY_MARKERS = (PROOF_GUIDE_PATH, EXISTING_WORK_GUIDE_PATH, EVAL_GUIDE_PATH)
+ALL_PROOF_GATE_FILE_NAMES = frozenset(
+    {
+        "pull_request_proof.py",
+        "pull_request_proof_constants.py",
+        "pull_request_proof_edit_gate.py",
+        "pre_tool_use_dispatcher_constants.py",
+    }
+)
+GATE_EDIT_BEFORE_ROUTE_REASON = (
+    "The pull request proof gate denied a create call in this session, and its deny"
+    " named the way through. Take that route now. Add what the deny asked for, such as"
+    " a screenshot or Artifact link in the 'Proof in practice' section, then run the"
+    " create call again. The deny text is the instruction. Edit this gate only"
+    " after a create call passes it. Read " + PROOF_GUIDE_PATH + " for the full rule."
+)
+WINDOWS_PATH_SEPARATOR = "\\"
+POSIX_PATH_SEPARATOR = "/"

package/hooks/hooks_constants/test_pre_tool_use_dispatcher_constants.py

@@ -22,12 +22,15 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (
 from pre_tool_use_dispatcher import HostedHookResult, aggregate_hosted_hook_results
 
 
-def test_roster_hosts_only_the_context_budget_gate() -> None:
-    assert len(ALL_HOSTED_HOOK_ENTRIES) == 1
-    entry = ALL_HOSTED_HOOK_ENTRIES[0]
-    assert entry.script_relative_path == "blocking/context_budget_blocker.py"
-    assert entry.is_blocking
-    assert entry.applicable_tool_names == ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES
+def test_roster_hosts_the_context_budget_and_proof_edit_gates() -> None:
+    assert len(ALL_HOSTED_HOOK_ENTRIES) == 2
+    context_budget_entry, proof_edit_entry = ALL_HOSTED_HOOK_ENTRIES
+    assert context_budget_entry.script_relative_path == "blocking/context_budget_blocker.py"
+    assert context_budget_entry.is_blocking
+    assert context_budget_entry.applicable_tool_names == ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES
+    assert proof_edit_entry.script_relative_path == "blocking/pull_request_proof_edit_gate.py"
+    assert proof_edit_entry.is_blocking
+    assert proof_edit_entry.applicable_tool_names == ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES
 
 
 def test_every_hosted_script_path_exists_under_the_hooks_root() -> None:

package/package.json

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