claude-dev-env 8.69.1 → 8.71.0

package/docs/templates/html-plan/house.css

@@ -0,0 +1,26 @@
+:root { color-scheme: light dark; --ink-2: var(--ink); --ink-3: var(--ink); --accent: #7a2e14; --green: #1c5426; --amber: #5f3f06; --red: #8f1d17; --on-accent: #ffffff; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --ink-2: var(--ink); --ink-3: var(--ink); --accent: #f6bba5; --green: #9fdcaa; --amber: #f2cc80; --red: #f7b3ab; --on-accent: #1f1e1d; } }
+:root[data-theme="dark"] { --ink-2: var(--ink); --ink-3: var(--ink); --accent: #f6bba5; --green: #9fdcaa; --amber: #f2cc80; --red: #f7b3ab; --on-accent: #1f1e1d; }
+body { background: var(--paper); color: var(--ink); font: 430 16px/1.6 var(--sans); }
+small, code, bdi, .mk-cap, .mk-label, .mk-bar, .fig-cap, .c-lang, .c-lines, .c-body td,
+.pl-num, .pl-chev, .pl-bdg, p.pl-claim, doc-claim > .pl-row > .pl-claim, .pl-body > p, .pl-body > ul, .pl-body > doc-note,
+doc-ask::before, doc-ask label small, doc-ask label .sug, doc-ask label > span,
+.nw-askrow .s, .nw-askrow .q small, .nw-btn, .nw-next, .nw-respond, .nw-cbtn, .fig-zoom, .tr-name, .tr-guide, .tr-note, .cl-note, .cl-loc, .mc-to, .mc-hint { font-size: 16px !important; }
+.nw-cbtn, .cl-loc, .fig-zoom, .mc-ev[disabled], .nw-btn[disabled], svg.nw .msg.mc-past path, svg.nw .msg.mc-past text { opacity: 1 !important; }
+.nw-next, .has-comment > .nw-cbtn, .nw-cbtn.on, .nw-askrow.todo .s, .nw-asks .ttl b.todo, .nw-pop.note .k { color: var(--on-accent) !important; }
+.mk-frame.terminal .mk-bar { color: #e6e3dc; }
+doc-note, doc-note > strong:first-child { font-size: 16px !important; }
+:root { --blue: #1d4a85; --purple: #4f2f96; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --blue: #b9d3f5; --purple: #d3c3f5; } }
+:root[data-theme="dark"] { --blue: #b9d3f5; --purple: #d3c3f5; }
+doc-note, doc-note > strong:first-child, .pill, .kicker, .dek, .meta, h4, th, table, figcaption, .caption, details > summary, pre,
+.nw-toc, .nw-toc a, .nw-toc a.h3, .nw-toc a.ask, .nw-toc .ttl, .nw-pop, .nw-pop .ref, .nw-pop textarea, .nw-sheet .hint, .nw-send-state,
+.nw-sheet .body pre, .nw-asks .ttl, .nw-asks .ttl b, .nw-askrow, .nw-askrow .k, .nw-toast, .nw-pin-list, .nw-err, .nw-bar .nw-respond .n,
+doc-claim[data-l="1"] > .pl-row > .pl-num, doc-claim[data-l="2"] > .pl-row > .pl-claim { font-size: 16px !important; }
+.has-comment > .nw-cbtn, .nw-cbtn.on, .nw-bar .nw-respond .n, .nw-bar .nw-next { background: var(--accent); }
+.nw-bar .nw-respond .n.ok { background: var(--green); color: var(--on-accent); }
+.nw-bar .nw-respond .n { color: var(--on-accent); }
+doc-changes, doc-changes b, .ch-tag, .ch-n, .q-head, .q-via, .q-from, .q-at, .q-body { font-size: 16px !important; }
+.cl-head, .cl-kind, .cl-title, .cl-counts, .cl-counts b, .cl-nm, .cl-rail, .cl-tg, .c-cap, .c-pin b, .mc-now, .mc-now b, .mc-now i, .mc-now span, .nw-pin-dot, svg.nw text, svg.nw .node text.sub, svg.nw .node text.more, svg.nw .edge text, svg.nw .group text { font-size: 16px !important; }
+.cl-tg, .tr-guide { color: var(--ink); }
+.nw-pin-dot { color: var(--on-accent); }

package/hooks/blocking/image_read_size_gate.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: refuse a Read of an image larger than the agent cap.
+
+A Read of an image puts the whole picture in the context. A phone screenshot
+at 1440x2560 costs about 4,784 tokens, the most one image can cost. The hook
+reads the width and height from the file header and refuses the Read when the
+long edge passes the cap, naming the command that writes a capped copy::
+
+    Read shot.png (1440x2560)        -> refused, names agent_image_copy.py
+    Read shot.agent.png (288x512)    -> allowed
+    Read notes.md                    -> allowed
+    Read broken.png (no header)      -> allowed
+
+A missing file, a WebP or other unknown format and an unreadable header all pass, so the
+hook never fails closed.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+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_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
+)
+from hooks_constants.image_read_size_gate_constants import (
+    AGENT_COPY_SCRIPT_PATH,
+    ALL_JPEG_FRAME_MARKERS,
+    ALL_JPEG_STANDALONE_MARKERS,
+    DENY_DECISION,
+    FILE_PATH_INPUT_KEY,
+    ALL_GIF_SIGNATURES,
+    GIF_SIZE_END,
+    GIF_SIZE_START,
+    HEADER_BYTE_COUNT,
+    JPEG_FRAME_SIZE_END,
+    JPEG_FRAME_SIZE_START,
+    JPEG_MARKER_LENGTH,
+    JPEG_MARKER_PREFIX,
+    JPEG_SIGNATURE,
+    MAXIMUM_LONG_EDGE_PIXELS,
+    OVERSIZED_IMAGE_REASON_TEMPLATE,
+    PERMISSION_DECISION_REASON_KEY,
+    PNG_SIGNATURE,
+    PNG_SIZE_END,
+    PNG_SIZE_START,
+    PRE_TOOL_USE_EVENT_NAME,
+    READ_TOOL_NAME,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def _jpeg_size(header: bytes) -> tuple[int, int] | None:
+    offset = len(JPEG_SIGNATURE)
+    while offset + JPEG_FRAME_SIZE_END <= len(header):
+        if header[offset] != JPEG_MARKER_PREFIX:
+            return None
+        marker = header[offset + 1]
+        if marker == JPEG_MARKER_PREFIX:
+            offset += 1
+            continue
+        if marker in ALL_JPEG_STANDALONE_MARKERS:
+            offset += JPEG_MARKER_LENGTH
+            continue
+        if marker in ALL_JPEG_FRAME_MARKERS:
+            height, width = struct.unpack(
+                ">HH", header[offset + JPEG_FRAME_SIZE_START : offset + JPEG_FRAME_SIZE_END]
+            )
+            return width, height
+        segment_length_end = offset + JPEG_MARKER_LENGTH + JPEG_MARKER_LENGTH
+        offset += JPEG_MARKER_LENGTH + struct.unpack(">H", header[offset + JPEG_MARKER_LENGTH : segment_length_end])[0]
+    return None
+
+
+def image_size(header: bytes) -> tuple[int, int] | None:
+    """Return (width, height) read from the first bytes of a PNG, JPEG or GIF file.
+
+    ::
+
+        PNG header of a 1440x2560 file -> (1440, 2560)
+        b"plain text"                  -> None
+
+    Args:
+        header: The first bytes of the file.
+    """
+    if header.startswith(PNG_SIGNATURE) and len(header) >= PNG_SIZE_END:
+        width, height = struct.unpack(">II", header[PNG_SIZE_START:PNG_SIZE_END])
+        return width, height
+    if header.startswith(ALL_GIF_SIGNATURES) and len(header) >= GIF_SIZE_END:
+        width, height = struct.unpack("<HH", header[GIF_SIZE_START:GIF_SIZE_END])
+        return width, height
+    if header.startswith(JPEG_SIGNATURE):
+        return _jpeg_size(header)
+    return None
+
+
+def _read_header(file_path: str) -> bytes:
+    try:
+        with open(file_path, "rb") as image_file:
+            return image_file.read(HEADER_BYTE_COUNT)
+    except OSError:
+        return b""
+
+
+def oversized_image_reason(all_hook_fields: dict[str, object]) -> str | None:
+    """Return the refusal for a Read of an image over the cap, or None to allow it.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+    """
+    tool_input = all_hook_fields.get(TOOL_INPUT_KEY)
+    if all_hook_fields.get(TOOL_NAME_KEY) != READ_TOOL_NAME or not isinstance(tool_input, dict):
+        return None
+    file_path = tool_input.get(FILE_PATH_INPUT_KEY)
+    if not isinstance(file_path, str):
+        return None
+    dimensions = image_size(_read_header(file_path))
+    if dimensions is None or max(dimensions) <= MAXIMUM_LONG_EDGE_PIXELS:
+        return None
+    width, height = dimensions
+    return OVERSIZED_IMAGE_REASON_TEMPLATE.format(
+        width=width,
+        height=height,
+        maximum_edge=MAXIMUM_LONG_EDGE_PIXELS,
+        script_path=AGENT_COPY_SCRIPT_PATH,
+        image_path=file_path,
+    )
+
+
+def main() -> int:
+    """Read the PreToolUse payload and print a deny decision for an oversized image.
+
+    Returns:
+        0 in every case; the decision travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    refusal_reason = oversized_image_reason(hook_payload)
+    if refusal_reason is not None:
+        sys.stdout.write(
+            json.dumps(
+                {
+                    HOOK_SPECIFIC_OUTPUT_KEY: {
+                        HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+                        PERMISSION_DECISION_KEY: DENY_DECISION,
+                        PERMISSION_DECISION_REASON_KEY: refusal_reason,
+                    }
+                }
+            )
+        )
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

package/hooks/features/session-context.md

@@ -10,7 +10,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
 - `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
-- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
+- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires
@@ -32,7 +32,7 @@ Preconditions:
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
 - **Issue tracker start.** Input is SessionStart with its opt-in flag and a registered checkout. Run `python -m pytest packages/claude-dev-env/hooks/session/test_issue_tracker_session_starter.py -q`. The adjacent test observes issue tracker context.
-- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the template path in `additionalContext`, and silence on a publish call or another skill.
+- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 
 ## Gotchas

package/hooks/hooks.json

@@ -97,6 +97,16 @@
           }
         ]
       },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/image_read_size_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "EnterWorktree",
         "hooks": [

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -9,6 +9,8 @@ __all__ = [
     "ARTIFACT_QUICKSTART_ACTION",
     "ARTIFACT_TEMPLATE_PATH",
     "ARTIFACT_TOOL_NAME",
+    "HTML_PLAN_TEMPLATE_README_PATH",
+    "POINTER_ALTERNATIVE_PREFIX",
     "POINTER_TEXT_PREFIX",
     "SKILL_NAME_INPUT_KEY",
     "SKILL_TOOL_NAME",
@@ -21,7 +23,11 @@ ARTIFACT_QUICKSTART_ACTION = "quickstart"
 SKILL_TOOL_NAME = "Skill"
 SKILL_NAME_INPUT_KEY = "skill"
 ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
-ARTIFACT_TEMPLATE_PATH = (
-    Path(__file__).resolve().parents[2] / "docs" / "templates" / "artifact-page" / "README.md"
+TEMPLATES_DIRECTORY = Path(__file__).resolve().parents[2] / "docs" / "templates"
+ARTIFACT_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "README.md"
+HTML_PLAN_TEMPLATE_README_PATH = TEMPLATES_DIRECTORY / "html-plan" / "README.md"
+POINTER_TEXT_PREFIX = "Build this artifact page from the html-plan skill, following "
+POINTER_ALTERNATIVE_PREFIX = (
+    ". When the request names the older artifact page template,"
+    " pick the one that fits the ask from "
 )
-POINTER_TEXT_PREFIX = "Pick the artifact page template that fits the ask from "

package/hooks/hooks_constants/image_read_size_gate_constants.py

@@ -0,0 +1,41 @@
+"""Names, limits and refusal text for the image_read_size_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+READ_TOOL_NAME = "Read"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+FILE_PATH_INPUT_KEY = "file_path"
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+DENY_DECISION = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+MAXIMUM_LONG_EDGE_PIXELS = 512
+HEADER_BYTE_COUNT = 64 * 1024
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+PNG_SIZE_START = 16
+PNG_SIZE_END = 24
+GIF_SIZE_START = 6
+GIF_SIZE_END = 10
+ALL_GIF_SIGNATURES = (b"GIF87a", b"GIF89a")
+JPEG_SIGNATURE = b"\xff\xd8"
+JPEG_MARKER_PREFIX = 0xFF
+JPEG_MARKER_LENGTH = 2
+JPEG_FRAME_SIZE_START = 5
+JPEG_FRAME_SIZE_END = 9
+ALL_JPEG_FRAME_MARKERS = frozenset(
+    {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
+)
+ALL_JPEG_STANDALONE_MARKERS = frozenset(
+    {0x01, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8}
+)
+AGENT_COPY_SCRIPT_PATH = Path(__file__).resolve().parents[2] / "scripts" / "agent_image_copy.py"
+OVERSIZED_IMAGE_REASON_TEMPLATE = (
+    "This image is {width}x{height} pixels. Agents read images at {maximum_edge} pixels or less"
+    " on the long edge, because a full-size image fills the context: a 1440x2560 screenshot costs"
+    " about 4,784 tokens, and a 288x512 copy costs about 209. Write a capped copy and read that"
+    ' copy: `python3 "{script_path}" "{image_path}"` prints the path of the copy, which keeps'
+    " the aspect ratio. Crop the region you need with `--crop LEFT,TOP,RIGHT,BOTTOM` when a"
+    " detail is too small at that size. Send the full-size file to a person, never to an agent."
+)

package/hooks/hooks_constants/test_artifact_template_pointer_constants.py

@@ -1,8 +1,16 @@
 """Behavioral tests for the artifact template pointer's path."""
 
-from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+from hooks_constants.artifact_template_pointer_constants import (
+    ARTIFACT_TEMPLATE_PATH,
+    HTML_PLAN_TEMPLATE_README_PATH,
+)
 
 
 def test_template_path_names_the_packaged_template_file() -> None:
     assert ARTIFACT_TEMPLATE_PATH.is_file()
     assert ARTIFACT_TEMPLATE_PATH.parent.joinpath("README.md").is_file()
+
+
+def test_html_plan_readme_path_names_the_packaged_readme_and_house_stylesheet() -> None:
+    assert HTML_PLAN_TEMPLATE_README_PATH.is_file()
+    assert HTML_PLAN_TEMPLATE_README_PATH.parent.joinpath("house.css").is_file()

package/hooks/session/artifact_template_pointer.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: point an agent about to build an artifact page at the template.
+"""PreToolUse hook: point an agent about to build an artifact page at html-plan.
 
 Registered on ``Artifact|Skill``. It adds one line of ``additionalContext``
-naming ``docs/templates/artifact-page/template.html`` when a session starts a
-new artifact page:
+naming ``docs/templates/html-plan/README.md`` as the default and
+``docs/templates/artifact-page/README.md`` as the alternative when a
+session starts a new artifact page:
 
 ::
 
@@ -31,6 +32,8 @@ from hooks_constants.artifact_template_pointer_constants import (
     ARTIFACT_QUICKSTART_ACTION,
     ARTIFACT_TEMPLATE_PATH,
     ARTIFACT_TOOL_NAME,
+    HTML_PLAN_TEMPLATE_README_PATH,
+    POINTER_ALTERNATIVE_PREFIX,
     POINTER_TEXT_PREFIX,
     SKILL_NAME_INPUT_KEY,
     SKILL_TOOL_NAME,
@@ -77,7 +80,10 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
-            ADDITIONAL_CONTEXT_KEY: f"{POINTER_TEXT_PREFIX}{ARTIFACT_TEMPLATE_PATH}.",
+            ADDITIONAL_CONTEXT_KEY: (
+                f"{POINTER_TEXT_PREFIX}{HTML_PLAN_TEMPLATE_README_PATH}"
+                f"{POINTER_ALTERNATIVE_PREFIX}{ARTIFACT_TEMPLATE_PATH}."
+            ),
         }
     }
 

package/hooks/session/test_artifact_template_pointer.py

@@ -10,7 +10,10 @@ for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
         sys.path.insert(0, each_sys_path_entry)
 
 import artifact_template_pointer
-from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+from hooks_constants.artifact_template_pointer_constants import (
+    ARTIFACT_TEMPLATE_PATH,
+    HTML_PLAN_TEMPLATE_README_PATH,
+)
 
 HOOK_SCRIPT = Path(__file__).resolve().parent / "artifact_template_pointer.py"
 
@@ -34,7 +37,10 @@ def test_artifact_quickstart_gets_the_template_pointer() -> None:
     hook_output = json.loads(_run_hook(_payload("Artifact", {"action": "quickstart", "intent": "other"})))
     specific_output = hook_output["hookSpecificOutput"]
     assert specific_output["hookEventName"] == "PreToolUse"
-    assert str(ARTIFACT_TEMPLATE_PATH) in specific_output["additionalContext"]
+    pointer_text = specific_output["additionalContext"]
+    assert pointer_text.index(str(HTML_PLAN_TEMPLATE_README_PATH)) < pointer_text.index(
+        str(ARTIFACT_TEMPLATE_PATH)
+    )
     assert "permissionDecision" not in specific_output
 
 

package/package.json

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

package/scripts/agent_image_copy.py

@@ -0,0 +1,155 @@
+"""Write a copy of an image small enough for an agent to read.
+
+The image_read_size_gate hook refuses a Read of an image whose long edge is over
+512 pixels and names this script. The script writes ``<name>.agent.png`` next to
+the source, scaled so the long edge is 512 pixels with the aspect ratio kept,
+and prints its path::
+
+    python3 agent_image_copy.py shot.png               -> shot.agent.png (288x512)
+    python3 agent_image_copy.py shot.png --crop 0,0,720,640
+                                                       -> the top-left region, capped
+    python3 agent_image_copy.py icon.png (200x200)     -> icon.agent.png, same size
+
+The copy is newer than the source, so a check that wants a screenshot read
+after a page changed still counts it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from dev_env_scripts_constants.agent_image_copy_constants import (
+    AGENT_COPY_SUFFIX,
+    ALL_PNG_WRITABLE_MODES,
+    CROP_BOX_PART_COUNT,
+    CROP_BOX_SEPARATOR,
+    MAXIMUM_LONG_EDGE_PIXELS,
+    PNG_FALLBACK_MODE,
+    VISUAL_TOKEN_PATCH_PIXELS,
+)
+from PIL import Image, ImageOps
+
+
+def capped_size(
+    width: int, height: int, maximum_edge: int = MAXIMUM_LONG_EDGE_PIXELS
+) -> tuple[int, int]:
+    """Return the size that fits the long edge into maximum_edge with the aspect ratio kept.
+
+    ::
+
+        capped_size(1440, 2560) -> (288, 512)
+        capped_size(2000, 1000) -> (512, 256)
+        capped_size(300, 200)   -> (300, 200)
+
+    Args:
+        width: Source width in pixels.
+        height: Source height in pixels.
+        maximum_edge: The largest long edge allowed.
+
+    Returns:
+        The capped (width, height).
+    """
+    long_edge = max(width, height)
+    if long_edge <= maximum_edge:
+        return width, height
+    scale = maximum_edge / long_edge
+    return max(1, round(width * scale)), max(1, round(height * scale))
+
+
+def visual_tokens(width: int, height: int) -> int:
+    """Return the documented visual-token cost of an image: one token per 28x28 patch.
+
+    ::
+
+        visual_tokens(1440, 2560) -> 4784
+        visual_tokens(288, 512)   -> 209
+
+    Args:
+        width: Image width in pixels as the model sees it.
+        height: Image height in pixels as the model sees it.
+    """
+    return math.ceil(width / VISUAL_TOKEN_PATCH_PIXELS) * math.ceil(
+        height / VISUAL_TOKEN_PATCH_PIXELS
+    )
+
+
+def parse_crop_box(crop_text: str) -> tuple[int, int, int, int]:
+    """Return LEFT, TOP, RIGHT, BOTTOM parsed from text like ``0,0,720,640``.
+
+    Args:
+        crop_text: Four comma-separated pixel coordinates.
+
+    Returns:
+        The four coordinates as integers.
+
+    Raises:
+        argparse.ArgumentTypeError: When the text does not hold four numbers.
+    """
+    all_parts = crop_text.split(CROP_BOX_SEPARATOR)
+    if len(all_parts) != CROP_BOX_PART_COUNT:
+        raise argparse.ArgumentTypeError(
+            f"--crop takes LEFT,TOP,RIGHT,BOTTOM, got {crop_text!r}"
+        )
+    left, top, right, bottom = (int(each_part) for each_part in all_parts)
+    return left, top, right, bottom
+
+
+def write_agent_copy(
+    source_path: Path, all_crop_coordinates: tuple[int, int, int, int] | None
+) -> Path:
+    """Write the capped copy beside the source and return its path.
+
+    The copy is turned upright by its EXIF orientation before the crop, and a mode PNG
+    cannot hold, such as CMYK, is converted to RGB.
+
+    Args:
+        source_path: The full-size image.
+        all_crop_coordinates: A LEFT, TOP, RIGHT, BOTTOM region cut before scaling, or None for the whole image.
+
+    Returns:
+        The path of the written copy.
+    """
+    copy_path = source_path.with_name(source_path.stem + AGENT_COPY_SUFFIX)
+    with Image.open(source_path) as source_image:
+        upright_image = ImageOps.exif_transpose(source_image)
+        working_image = upright_image.crop(all_crop_coordinates) if all_crop_coordinates else upright_image.copy()
+    if working_image.mode not in ALL_PNG_WRITABLE_MODES:
+        working_image = working_image.convert(PNG_FALLBACK_MODE)
+    working_image = working_image.resize(
+        capped_size(*working_image.size), Image.Resampling.LANCZOS
+    )
+    working_image.save(copy_path, optimize=True)
+    return copy_path
+
+
+def main(all_arguments: list[str]) -> int:
+    """Write the capped copy named on the command line and print its path and token cost.
+
+    Args:
+        all_arguments: Command-line arguments after the program name.
+
+    Returns:
+        0 when the copy was written.
+    """
+    parser = argparse.ArgumentParser(
+        description="Write an agent-size copy of an image."
+    )
+    parser.add_argument("image_path", type=Path)
+    parser.add_argument("--crop", type=parse_crop_box, default=None)
+    parsed = parser.parse_args(all_arguments)
+    copy_path = write_agent_copy(parsed.image_path, parsed.crop)
+    with Image.open(copy_path) as copy_image:
+        width, height = copy_image.size
+    print(f"{copy_path} {width}x{height} about {visual_tokens(width, height)} tokens")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/dev_env_scripts_constants/agent_image_copy_constants.py

@@ -0,0 +1,11 @@
+"""Limits and names for the agent_image_copy script."""
+
+from __future__ import annotations
+
+MAXIMUM_LONG_EDGE_PIXELS = 512
+VISUAL_TOKEN_PATCH_PIXELS = 28
+AGENT_COPY_SUFFIX = ".agent.png"
+CROP_BOX_SEPARATOR = ","
+CROP_BOX_PART_COUNT = 4
+ALL_PNG_WRITABLE_MODES = frozenset({"1", "L", "LA", "I", "I;16", "P", "RGB", "RGBA"})
+PNG_FALLBACK_MODE = "RGB"

package/scripts/policy_lint/config/constants.py

@@ -71,6 +71,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/verify_before_acting.py",
     "blocking/session_title_format_gate.py",
     "blocking/session_title_stop_gate.py",
+    "blocking/image_read_size_gate.py",
     "blocking/artifact_dark_mode_gate.py",
     "blocking/artifact_look_gate.py",
 )