claude-dev-env 8.69.0 → 8.70.0

package/hooks/blocking/pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section."""
+"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section, or a feature pull request whose body lacks an 'Eval' section."""
 
 from __future__ import annotations
 
@@ -6,13 +6,14 @@ import re
 import subprocess
 import sys
 from collections.abc import Mapping
+from typing import NamedTuple
 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.followup_pr_dedupe import body_from_arguments
+from blocking.followup_pr_dedupe import body_from_arguments, create_tool_fields, title_from_arguments
 from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
 from hooks_constants.pull_request_proof_constants import (
     ALL_GH_CREATE_WORDS,
@@ -20,16 +21,18 @@ from hooks_constants.pull_request_proof_constants import (
     ALL_VISIBLE_FILE_SUFFIXES,
     CHANGED_FILES_SEPARATOR,
     COMMAND_MARKER,
-    CREATE_PULL_REQUEST_TOOL_SUFFIX,
     ALL_DEFAULT_BRANCH_REFERENCES,
     ALL_HEAD_FLAGS,
     HEAD_FLAG_ASSIGNMENT_PREFIX,
     REMOTE_BRANCH_PREFIX,
     UNREADABLE_CHANGES_REASON,
+    EVAL_HEADING_PATTERN,
     EXISTING_WORK_HEADING_PATTERN,
+    FEATURE_TITLE_PATTERN,
     GIT_TIMEOUT_SECONDS,
     LINE_SEPARATOR,
     MISSING_BODY_REASON,
+    MISSING_EVAL_SECTION_REASON,
     MISSING_EXISTING_WORK_REASON,
     MISSING_LOOK_REASON,
     MISSING_PROOF_REASON,
@@ -48,6 +51,13 @@ from hooks_constants.shell_command_wrappers import (
 )
 
 
+class CreateCall(NamedTuple):
+    """The title and body one pull request create call passes; None marks a value this gate cannot read."""
+
+    title: str | None
+    body: str | None
+
+
 def _heading_level(line: str, heading_pattern: str) -> int | None:
     heading = re.match(heading_pattern, line.strip(), re.IGNORECASE)
     return None if heading is None else len(heading.group(1))
@@ -120,9 +130,12 @@ def _create_arguments(all_segment_tokens: list[str]) -> list[str] | None:
     return _script_create_arguments(program, all_arguments)
 
 
-def _shell_create_bodies(command: str, working_directory: str) -> list[str | None]:
+def _shell_create_calls(command: str, working_directory: str) -> list[CreateCall]:
     return [
-        body_from_arguments(all_create_arguments, working_directory)
+        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
@@ -139,13 +152,12 @@ def _head_flag_value(all_create_arguments: list[str]) -> str | None:
 
 
 def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
-    tool_input = all_payload_fields.get("tool_input")
-    if not isinstance(tool_input, dict):
-        return None
-    head_branch = tool_input.get("head")
+    create_fields = create_tool_fields(all_payload_fields)
+    head_branch = None if create_fields is None else create_fields.get("head")
     if isinstance(head_branch, str):
         return head_branch
-    command = tool_input.get("command")
+    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
     all_head_flag_values = [
@@ -157,23 +169,77 @@ def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
     return next((each_value for each_value in all_head_flag_values if each_value), None)
 
 
-def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
-    tool_name = all_payload_fields.get("tool_name")
+def _create_calls(all_payload_fields: Mapping[str, object]) -> list[CreateCall]:
+    create_fields = create_tool_fields(all_payload_fields)
+    if create_fields is not None:
+        title = create_fields.get("title")
+        body = create_fields.get("body")
+        return [
+            CreateCall(
+                title if isinstance(title, str) else None,
+                body if isinstance(body, str) else "",
+            )
+        ]
     tool_input = all_payload_fields.get("tool_input")
-    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
-        return []
-    if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
-        body = tool_input.get("body")
-        return [body if isinstance(body, str) else ""]
-    command = tool_input.get("command")
-    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+    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 []
     working_directory = all_payload_fields.get("cwd")
-    return _shell_create_bodies(
+    return _shell_create_calls(
         command, working_directory if isinstance(working_directory, str) else ""
     )
 
 
+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)]
+
+
+def _is_feature_title(title: str | None) -> bool:
+    return title is not None and re.match(FEATURE_TITLE_PATTERN, title, re.IGNORECASE) is not None
+
+
+def is_feature_pull_request(all_payload_fields: Mapping[str, object]) -> bool:
+    """Return whether any pull request create call in the payload carries a feature title.
+
+    ::
+
+        mcp__github__create_pull_request, title "feat(hooks)!: x" -> True
+        gh pr create --title "fix: y" --body-file b.md             -> False
+        gh pr create --fill                                        -> False
+        gh pr edit, git push, any other tool                       -> False
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    return any(_is_feature_title(each_call.title) for each_call in _create_calls(all_payload_fields))
+
+
+def missing_eval_section_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a feature pull request's body has no eval section, else None.
+
+    ::
+
+        title "feat: x", body has the section     -> None
+        title "feat: x", body without it          -> MISSING_EVAL_SECTION_REASON
+        title "fix: y", body without it           -> None
+        title "feat: x", gh pr create --fill      -> None
+
+    The section is an 'Eval' heading whose text names at least one command in
+    backticks. A create command whose body this gate cannot read passes here,
+    because missing_proof_reason denies it first.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_call in _create_calls(all_payload_fields):
+        if each_call.body is None or not _is_feature_title(each_call.title):
+            continue
+        section = _section_text(each_call.body, EVAL_HEADING_PATTERN)
+        if not section or COMMAND_MARKER not in section:
+            return MISSING_EVAL_SECTION_REASON
+    return None
+
+
 def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
     """Return a deny reason when a new pull request's body has no proof, else None.
 

package/hooks/blocking/test_artifact_look_gate.py

@@ -101,6 +101,7 @@ def test_should_refuse_a_page_published_without_a_look(tmp_path: Path) -> None:
     specific_output = hook_output["hookSpecificOutput"]
     assert specific_output["permissionDecision"] == "deny"
     assert "--screenshot" in specific_output["permissionDecisionReason"]
+    assert "Attach" not in specific_output["permissionDecisionReason"]
 
 
 def test_should_allow_a_page_whose_newer_screenshot_was_read(tmp_path: Path) -> None:

package/hooks/blocking/test_followup_pr_dedupe.py

@@ -92,3 +92,36 @@ def test_body_from_arguments_reads_inline_text_and_body_files(tmp_path: Path) ->
     assert dedupe.body_from_arguments(["--body-file", "body.md"], str(tmp_path)) == "From the file."
     assert dedupe.body_from_arguments(["--body-file", "-"], str(tmp_path)) is None
     assert dedupe.body_from_arguments(["--fill"], str(tmp_path)) is None
+
+
+def test_title_from_arguments_should_read_each_title_flag_shape() -> None:
+    assert dedupe.title_from_arguments(["--title", "feat: x", "--fill"]) == "feat: x"
+    assert dedupe.title_from_arguments(["-t", "fix: y"]) == "fix: y"
+    assert dedupe.title_from_arguments(["--title=feat(x): z"]) == "feat(x): z"
+    assert dedupe.title_from_arguments(["--title-file", "t.txt"]) is None
+    assert dedupe.title_from_arguments(["--fill"]) is None
+
+
+def _dispatch_payload(all_inputs: dict[str, object]) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__actions_run_trigger",
+        "tool_input": {"method": "run_workflow", "owner": "jl-cmd", "repo": "claude-dev-env", "inputs": all_inputs},
+    }
+
+
+def test_create_tool_fields_should_read_a_pull_request_dispatch_as_a_create() -> None:
+    payload = _dispatch_payload({"head": "b", "title": "fix: y", "body": "Follow-up to #1731"})
+    assert dedupe.create_tool_fields(payload) == {
+        "head": "b",
+        "title": "fix: y",
+        "body": "Follow-up to #1731",
+        "owner": "jl-cmd",
+        "repo": "claude-dev-env",
+    }
+    reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
+    assert reason is not None and "#1769" in reason
+
+
+def test_create_tool_fields_should_skip_a_call_that_opens_no_pull_request() -> None:
+    assert dedupe.create_tool_fields(_dispatch_payload({"work_order": "wo-1"})) is None
+    assert dedupe.create_tool_fields({"tool_name": "Bash", "tool_input": {"command": "gh pr list"}}) is None

package/hooks/blocking/test_image_read_size_gate.py

@@ -0,0 +1,79 @@
+"""Behavior tests for the image read size gate."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+_BLOCKING_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _BLOCKING_DIR.parent
+for each_sys_path_entry in (str(_BLOCKING_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import image_read_size_gate
+
+HOOK_SCRIPT = _BLOCKING_DIR / "image_read_size_gate.py"
+
+
+def _image(file_path: Path, width: int, height: int) -> Path:
+    Image.new("RGB", (width, height), "white").save(file_path)
+    return file_path
+
+
+def _run_hook(file_path: Path) -> str:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(
+            {
+                "hook_event_name": "PreToolUse",
+                "tool_name": "Read",
+                "tool_input": {"file_path": str(file_path)},
+            }
+        ),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return completed.stdout
+
+
+def test_should_refuse_a_full_size_preview_read(tmp_path: Path) -> None:
+    hook_output = json.loads(_run_hook(_image(tmp_path / "preview.png", 1440, 2560)))
+    specific_output = hook_output["hookSpecificOutput"]
+    assert specific_output["permissionDecision"] == "deny"
+    assert "1440x2560" in specific_output["permissionDecisionReason"]
+    assert "agent_image_copy.py" in specific_output["permissionDecisionReason"]
+
+
+def test_should_allow_an_image_at_the_cap(tmp_path: Path) -> None:
+    assert _run_hook(_image(tmp_path / "preview.agent.png", 288, 512)) == ""
+
+
+def test_should_allow_a_text_file(tmp_path: Path) -> None:
+    notes_path = tmp_path / "notes.md"
+    notes_path.write_text("x" * 4000, encoding="utf-8")
+    assert _run_hook(notes_path) == ""
+
+
+def test_should_allow_a_missing_file(tmp_path: Path) -> None:
+    assert _run_hook(tmp_path / "gone.png") == ""
+
+
+@pytest.mark.parametrize("suffix", [".png", ".jpg", ".gif"])
+def test_image_size_reads_each_format(tmp_path: Path, suffix: str) -> None:
+    image_path = _image(tmp_path / f"wide{suffix}", 900, 300)
+    assert image_read_size_gate.image_size(image_path.read_bytes()[:65536]) == (900, 300)
+
+
+def test_oversized_image_reason_passes_other_tools(tmp_path: Path) -> None:
+    image_path = _image(tmp_path / "big.png", 2000, 2000)
+    assert (
+        image_read_size_gate.oversized_image_reason(
+            {"tool_name": "Write", "tool_input": {"file_path": str(image_path)}}
+        )
+        is None
+    )

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -14,7 +14,7 @@ if str(HOOKS_DIRECTORY) not in sys.path:
 from blocking import followup_pr_dedupe as gate_dedupe
 from blocking import pr_lifecycle_skill_gate as gate
 from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
-from hooks_constants.pull_request_proof_constants import MISSING_PROOF_REASON
+from hooks_constants.pull_request_proof_constants import MISSING_BUILD_EVAL_REASON, MISSING_PROOF_REASON
 
 PROVEN_FOLLOWUP_BODY = (
     "Follow-up to #1731\n\n## Existing work\nNothing found in open or merged pull requests.\n\n"
@@ -225,11 +225,11 @@ def test_hook_has_its_own_pre_tool_use_registration() -> None:
         each_group
         for each_group in all_groups
         if each_group["matcher"]
-        == "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)"
+        == "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)"
     ]
     assert matching_groups == [
         {
-            "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)",
+            "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)",
             "hooks": [
                 {
                     "type": "command",
@@ -283,3 +283,117 @@ def test_loaded_skill_still_denies_a_new_pull_request_without_proof(tmp_path: Pa
     exit_code, output = _run_main(_payload("gh pr create --body 'Adds a gate.'", _transcript(tmp_path, "pr-lifecycle")))
     assert exit_code == 0
     assert json.loads(output)["hookSpecificOutput"]["permissionDecisionReason"] == MISSING_PROOF_REASON
+
+
+EVALUATED_BODY = (
+    "## Existing work\nNothing found in open or merged pull requests.\n\n"
+    "## Proof in practice\nRan `python probe.py`.\n\n"
+    "## Eval\nTen labeled cases, exact-match grader. Ran `python eval.py`: 10/10.\n"
+)
+SKILL_LOAD_LINE = json.dumps(
+    {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": "pr-lifecycle"}}]}}
+)
+BUILD_EVAL_LINE = json.dumps(
+    {
+        "type": "assistant",
+        "message": {
+            "content": [{"type": "tool_use", "name": "Skill", "input": {"skill": "claude-api", "args": "build-eval"}}]
+        },
+    }
+)
+
+
+def _transcript_with_lines(tmp_path: Path, file_name: str, all_lines: list[str]) -> Path:
+    transcript_path = tmp_path / file_name
+    transcript_path.write_text("\n".join(all_lines) + "\n", encoding="utf-8")
+    return transcript_path
+
+
+def _create_payload(tmp_path: Path, title: str, transcript_path: Path) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "o", "repo": "r", "title": title, "body": EVALUATED_BODY},
+        "transcript_path": str(transcript_path),
+        "cwd": _checkout_without_visible_changes(tmp_path),
+    }
+
+
+def _assert_denied_with(payload: dict[str, object], reason: str) -> None:
+    decision = gate.decision_for(payload)
+    assert decision is not None
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert decision["hookSpecificOutput"]["permissionDecisionReason"] == reason
+
+
+def test_feature_pull_request_without_build_eval_invocation_should_be_denied(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [SKILL_LOAD_LINE])
+    _assert_denied_with(_create_payload(tmp_path, "feat: add a gate", transcript_path), MISSING_BUILD_EVAL_REASON)
+
+
+def test_feature_pull_request_with_build_eval_invocation_should_pass(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [BUILD_EVAL_LINE, SKILL_LOAD_LINE])
+    assert gate.decision_for(_create_payload(tmp_path, "feat: add a gate", transcript_path)) is None
+
+
+def test_non_feature_pull_request_without_build_eval_invocation_should_pass(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [SKILL_LOAD_LINE])
+    assert gate.decision_for(_create_payload(tmp_path, "fix: repair a gate", transcript_path)) is None
+
+
+def test_feature_pull_request_with_no_readable_transcript_should_pass(tmp_path: Path) -> None:
+    payload = _create_payload(tmp_path, "feat: add a gate", tmp_path / "missing.jsonl")
+    assert gate.decision_for(payload) is None
+
+
+def test_build_eval_check_should_ignore_an_unreadable_transcript_beside_a_readable_one(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [SKILL_LOAD_LINE])
+    payload = _create_payload(tmp_path, "feat: add a gate", transcript_path)
+    payload["agent_transcript_path"] = str(tmp_path / "missing-agent.jsonl")
+    _assert_denied_with(payload, MISSING_BUILD_EVAL_REASON)
+
+
+def test_build_eval_invocation_in_the_agent_transcript_should_pass(tmp_path: Path) -> None:
+    session_path = _transcript_with_lines(tmp_path, "session.jsonl", [SKILL_LOAD_LINE])
+    agent_path = _transcript_with_lines(tmp_path, "agent.jsonl", [BUILD_EVAL_LINE])
+    payload = _create_payload(tmp_path, "feat: add a gate", session_path)
+    payload["agent_transcript_path"] = str(agent_path)
+    assert gate.decision_for(payload) is None
+
+
+def _dispatch_payload(tmp_path: Path, all_inputs: dict[str, object], transcript_path: Path) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__actions_run_trigger",
+        "tool_input": {
+            "method": "run_workflow",
+            "owner": "o",
+            "repo": "r",
+            "workflow_id": "open.yml",
+            "ref": "main",
+            "inputs": all_inputs,
+        },
+        "transcript_path": str(transcript_path),
+        "cwd": _checkout_without_visible_changes(tmp_path),
+    }
+
+
+def test_feature_dispatch_without_build_eval_invocation_should_be_denied(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [SKILL_LOAD_LINE])
+    all_inputs = {"head": "main", "title": "feat: add a gate", "body": EVALUATED_BODY}
+    _assert_denied_with(_dispatch_payload(tmp_path, all_inputs, transcript_path), MISSING_BUILD_EVAL_REASON)
+
+
+def test_feature_dispatch_with_build_eval_invocation_should_pass(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [BUILD_EVAL_LINE, SKILL_LOAD_LINE])
+    all_inputs = {"head": "main", "title": "feat: add a gate", "body": EVALUATED_BODY}
+    assert gate.decision_for(_dispatch_payload(tmp_path, all_inputs, transcript_path)) is None
+
+
+def test_pull_request_dispatch_without_the_skill_loaded_should_be_denied(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [BUILD_EVAL_LINE])
+    all_inputs = {"head": "main", "title": "fix: repair a gate", "body": EVALUATED_BODY}
+    _assert_denied_with(_dispatch_payload(tmp_path, all_inputs, transcript_path), DENY_REASON)
+
+
+def test_dispatch_that_opens_no_pull_request_should_pass_without_the_skill(tmp_path: Path) -> None:
+    transcript_path = _transcript_with_lines(tmp_path, "session.jsonl", [BUILD_EVAL_LINE])
+    assert gate.decision_for(_dispatch_payload(tmp_path, {"work_order": "wo-1"}, transcript_path)) is None

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -724,10 +724,7 @@ def test_folded_write_edit_hooks_have_no_standalone_hooks_json_entry() -> None:
         for each_group in hooks_configuration["hooks"]["PreToolUse"]
         for each_hook in each_group["hooks"]
     ]
-    folded_script_relative_paths = (
-        "advisory/refactor_guard.py",
-        "advisory/migration_safety_advisor.py",
-    )
+    folded_script_relative_paths = ("advisory/migration_safety_advisor.py",)
     for each_script_path in folded_script_relative_paths:
         matching_commands = [
             each_command
@@ -808,7 +805,6 @@ def test_dispatcher_allows_clean_apply_patch_add(tmp_path: Path) -> None:
 
 
 ALL_RETAINED_PATHS = {
-    "advisory/refactor_guard.py",
     "advisory/migration_safety_advisor.py",
 }
 ALL_RETIRED_PATHS = {

package/hooks/blocking/test_pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Behavior tests for the proof-in-practice and existing-work checks on a new pull request."""
+"""Behavior tests for the proof-in-practice, existing-work and eval checks on a new pull request."""
 
 import subprocess
 import sys
@@ -11,6 +11,7 @@ if str(HOOKS_DIRECTORY) not in sys.path:
 from blocking import pull_request_proof as gate
 from hooks_constants.pull_request_proof_constants import (
     MISSING_BODY_REASON,
+    MISSING_EVAL_SECTION_REASON,
     MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
     UNREADABLE_CHANGES_REASON,
@@ -210,3 +211,125 @@ def test_should_read_the_head_flag_of_a_shell_create(tmp_path: Path) -> None:
     reason = gate.missing_look_reason(payload)
     assert reason is not None
     assert "page.html" in reason
+
+
+EVALUATED_BODY = SEARCHED_BODY + "\n## Eval\nTen labeled cases, exact-match grader. Ran `python eval.py`: 10/10.\n"
+EVAL_WITHOUT_COMMAND_BODY = SEARCHED_BODY + "\n## Eval\nTen labeled cases, all pass.\n"
+
+
+def _titled_mcp_create(title: object, body: object) -> dict[str, object]:
+    payload = _mcp_create(body)
+    payload["tool_input"]["title"] = title
+    return payload
+
+
+def test_feature_mcp_create_without_an_eval_section_should_be_denied() -> None:
+    payload = _titled_mcp_create("feat: add a gate", SEARCHED_BODY)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_feature_mcp_create_with_an_eval_section_naming_a_command_should_pass() -> None:
+    assert gate.missing_eval_section_reason(_titled_mcp_create("feat: add a gate", EVALUATED_BODY)) is None
+
+
+def test_feature_mcp_create_with_an_eval_heading_and_no_backtick_should_be_denied() -> None:
+    payload = _titled_mcp_create("feat: add a gate", EVAL_WITHOUT_COMMAND_BODY)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_eval_section_should_stop_at_a_heading_of_the_same_level() -> None:
+    body = SEARCHED_BODY + "\n## Evals\nCases listed.\n\n## Notes\nRan `python eval.py`.\n"
+    payload = _titled_mcp_create("feat: add a gate", body)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_fix_and_docs_titles_without_an_eval_section_should_pass() -> None:
+    for each_title in ("fix: repair a gate", "docs: describe a gate"):
+        payload = _titled_mcp_create(each_title, SEARCHED_BODY)
+        assert gate.missing_eval_section_reason(payload) is None, each_title
+        assert not gate.is_feature_pull_request(payload), each_title
+
+
+def test_feature_titles_should_count_as_features() -> None:
+    for each_title in ("feat: x", "feat(hooks)!: x", "FEAT: x", "FEAT(x)!: y", "  feat!: x"):
+        assert gate.is_feature_pull_request(_titled_mcp_create(each_title, SEARCHED_BODY)), each_title
+
+
+def test_non_feature_titles_should_not_count_as_features() -> None:
+    for each_title in ("featured: x", "feature: x", "chore: feat: x", None, 7):
+        assert not gate.is_feature_pull_request(_titled_mcp_create(each_title, SEARCHED_BODY)), each_title
+
+
+def test_gh_create_title_flag_should_be_read(tmp_path: Path) -> None:
+    (tmp_path / "b.md").write_text(SEARCHED_BODY, encoding="utf-8")
+    payload = _shell('gh pr create --title "feat: x" --body-file b.md', tmp_path)
+    assert gate.is_feature_pull_request(payload)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_gh_create_title_assignment_should_be_read(tmp_path: Path) -> None:
+    (tmp_path / "b.md").write_text(EVALUATED_BODY, encoding="utf-8")
+    payload = _shell("gh pr create --title=feat:x --body-file b.md", tmp_path)
+    assert gate.is_feature_pull_request(payload)
+    assert gate.missing_eval_section_reason(payload) is None
+
+
+def test_pull_request_script_create_title_should_be_read(tmp_path: Path) -> None:
+    (tmp_path / "b.md").write_text(SEARCHED_BODY, encoding="utf-8")
+    payload = _shell(
+        'python pull_request.py create --title "feat(x): y" --body-file b.md --repo o/r', tmp_path
+    )
+    assert gate.is_feature_pull_request(payload)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_gh_create_without_a_title_should_not_count_as_a_feature(tmp_path: Path) -> None:
+    (tmp_path / "b.md").write_text(SEARCHED_BODY, encoding="utf-8")
+    payload = _shell("gh pr create --body-file b.md", tmp_path)
+    assert not gate.is_feature_pull_request(payload)
+    assert gate.missing_eval_section_reason(payload) is None
+
+
+def test_feature_create_with_an_unreadable_body_should_leave_the_deny_to_the_proof_check() -> None:
+    payload = _shell('gh pr create --title "feat: x" --fill')
+    assert gate.missing_eval_section_reason(payload) is None
+    assert gate.missing_proof_reason(payload) == MISSING_BODY_REASON
+
+
+def _dispatch(all_inputs: dict[str, object], method: str = "run_workflow") -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__actions_run_trigger",
+        "tool_input": {
+            "method": method,
+            "owner": "o",
+            "repo": "r",
+            "workflow_id": "open.yml",
+            "ref": "main",
+            "inputs": all_inputs,
+        },
+    }
+
+
+def test_pull_request_dispatch_without_proof_should_be_denied() -> None:
+    payload = _dispatch({"head": "feature", "title": "fix: y", "body": UNPROVEN_BODY})
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_pull_request_dispatch_with_no_body_input_should_be_denied() -> None:
+    assert gate.missing_proof_reason(_dispatch({"head": "feature", "title": "fix: y"})) == MISSING_PROOF_REASON
+
+
+def test_feature_dispatch_without_an_eval_section_should_be_denied() -> None:
+    payload = _dispatch({"head": "feature", "title": "feat: x", "body": SEARCHED_BODY})
+    assert gate.is_feature_pull_request(payload)
+    assert gate.missing_eval_section_reason(payload) == MISSING_EVAL_SECTION_REASON
+
+
+def test_dispatch_that_names_no_head_or_runs_no_workflow_should_not_count_as_a_create() -> None:
+    all_payloads = [
+        _dispatch({"title": "feat: x", "body": UNPROVEN_BODY}),
+        _dispatch({"head": "feature", "title": "feat: x", "body": UNPROVEN_BODY}, "rerun_workflow_run"),
+    ]
+    for each_payload in all_payloads:
+        assert gate.missing_proof_reason(each_payload) is None
+        assert not gate.is_feature_pull_request(each_payload)

package/hooks/features/README.md

@@ -29,4 +29,5 @@ Each family page starts with a title and an agent-facing behavior summary. Its f
 - [Session context](./session-context.md) covers skill reminders, startup guidance, and the auto mode denial quick fix.
 - [Spawn routing](./spawn-routing.md) covers spawn readiness, pacing, and model selection.
 - [Observability](./observability.md) covers instruction loads, edited files, and investigation resets.
+- [Read gates](./read-gates.md) covers the image size cap on Read.
 - [Lifecycle cleanup](./lifecycle-cleanup.md) covers nested checkouts, worktree setup, and session cleanup.

package/hooks/features/conduct-gates.md

@@ -24,7 +24,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/session_title_stop_gate.py` runs on `Stop`, no matcher, timeout `10` seconds in `hooks.json`.
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
-- `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)`, timeout `10` seconds in `hooks.json`.
+- `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_look_gate.py` runs on `PreToolUse`, matcher `Artifact|Skill`, timeout `10` seconds in `hooks.json`. It speaks only on an `Artifact` publish of a `.html` or `.htm` file.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 

package/hooks/features/read-gates.md

@@ -0,0 +1,20 @@
+# Read gates
+
+This family stops a Read before it puts too much into the context. An agent that opens a full-size screenshot spends up to 4,784 visual tokens on one image, so the gate sends it to a capped copy first.
+
+## Checks
+
+- `blocking/image_read_size_gate.py` denies a Read of a PNG, JPEG or GIF file whose long edge is over 512 pixels and names `scripts/agent_image_copy.py`, which writes a `<name>.agent.png` copy at 512 pixels or less with the aspect ratio kept.
+
+## When it fires
+
+- `blocking/image_read_size_gate.py` runs on `PreToolUse`, matcher `Read`, timeout `10` seconds in `hooks.json`. It reads only the file header, so a text file, a missing file, a WebP file and an unknown format pass.
+
+## Proving it
+
+- **Full-size screenshot.** Input is a Read of a 1440x2560 PNG. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_image_read_size_gate.py -q`. The adjacent test observes a denial that names `agent_image_copy.py`; a Read of a 288x512 copy passes.
+
+## Gotchas
+
+- The copy is written after the source, so a gate that wants a screenshot read after a page changed still counts the capped copy.
+- A person gets the full-size file. The cap applies to what an agent reads.