claude-dev-env 8.69.1 → 8.70.0

package/.agents/skills/correction/SKILL.md

@@ -1,16 +1,34 @@
 ---
 name: correction
-description: Turn a correction the user just made into a short handoff brief they paste into a corrections intake, or land the fix in this session with the fix playbook. Use when the user types /correction followed by what the agent got wrong, or /correction fix to land the fix here.
+description: File a correction the user made to an agent as one labeled GitHub issue, list the open corrections, write a handoff brief, or land the fix in this session with the fix playbook. Use when the user types /correction, /correction fix, says "file this as a correction", or asks to show the open corrections.
 argument-hint: "[fix] <what the agent got wrong, in the user's words>"
 ---
 
 # /correction
 
-The user corrected an agent and wants the fix to stick. Write one brief that records the correction. By default the user pastes it into the place that turns corrections into lasting fixes. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself.
+The user corrected an agent and wants the fix to stick. A labeled issue is the shared store a corrections project watches. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself: write the brief, then follow the fix playbook.
 
-`$ARGUMENTS` is the user's statement of the correction, after a leading `fix` when one is present. Fill the other fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. When the session does not settle a field, write `unknown` there.
+## File it
 
-Print the brief as one fenced `text` block:
+Use this for `/correction <text>` and "file this as a correction: <text>". Run:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/correction_filing.py" file <<'CORRECTION'
+<the correction, word for word>
+CORRECTION
+```
+
+Pass the user's words exactly. The quoted heredoc keeps the shell from expanding `$`, backticks, and quotes in them. Print the one line the command prints, `Filed: <url>` or `Already filed: <url>`, and nothing else.
+
+When it prints `No correction filing config`, write the brief below instead and tell the user the config file it names.
+
+## List them
+
+For "show the open corrections", run `python "${CLAUDE_SKILL_DIR}/scripts/correction_filing.py" list` and print its lines.
+
+## Brief
+
+Print one fenced `text` block. Fill the fields from this session: the transcript, the files and pull requests it touched, and the messages it sent. Write `unknown` for a field the session does not settle.
 
 ```text
 Correction: <$ARGUMENTS word for word, minus a leading fix>
@@ -28,12 +46,16 @@ Keep each field to one or two lines. Leave out the layer and the fix design; the
 
 | Mode | What follows the brief |
 |---|---|
-| Hand off, the default | Nothing. The brief is the whole reply. |
+| File, the default | The filed line, or the brief when no config exists. |
 | `fix` | Read [`playbooks/fix.md`](playbooks/fix.md) right after the brief, and run its steps from step 2. |
 
 ## Layout
 
 | File | What it holds |
 |---|---|
-| `SKILL.md` | The brief and the playbook index |
+| `SKILL.md` | Filing, the brief, and the playbook index |
 | `playbooks/fix.md` | The steps that land one correction as a control and a pull request in this session |
+| `scripts/correction_filing.py` | Files one correction as a labeled issue, deduplicated, or lists the open ones |
+| `scripts/correction_filing_constants/config/constants.py` | Config keys, issue shape, and redaction patterns |
+| `scripts/test_correction_filing.py` | Behavior tests with a stand-in `gh` |
+| `references/filing.md` | Config file, issue shape, dedupe, and commands |

package/.agents/skills/correction/references/filing.md

@@ -0,0 +1,33 @@
+# Correction filing
+
+`scripts/correction_filing.py` is the one filing path. The skill calls it.
+
+## Config
+
+The script reads `~/.claude/correction-capture.json`, or the file `CLAUDE_CORRECTION_CAPTURE_PATH` names:
+
+```json
+{"repository": "owner/name", "label": "correction"}
+```
+
+Keep this file private. Without it the script files nothing and exits 1.
+
+## Issue shape
+
+- Title: `Correction: ` and the first 72 characters of the text.
+- Body: the source (`typed`, `flag`, `reaction`, or `hook`), the text as a quote, and a hidden dedupe marker.
+- The script masks GitHub, OpenAI, Slack, and AWS tokens and email addresses before filing.
+- The script applies the label itself.
+
+## Dedupe
+
+The key is a hash of `--dedupe-key` when given, else of the whitespace-collapsed text. A caller with a message id passes it there. Before filing, the script checks `correction-capture-filed.json` beside the config file for this repository and key, then every labeled issue, open and closed, and prints `Already filed: <url>` on a key match. The local file covers the minute after filing, when the labeled-issue listing can miss a new issue.
+
+## Commands
+
+Without `--text`, `file` reads the correction from standard input.
+
+```bash
+python correction_filing.py file [--text "<text>"] [--source flag] [--dedupe-key <id>]
+python correction_filing.py list
+```

package/.agents/skills/correction/scripts/correction_filing.py

@@ -0,0 +1,327 @@
+"""File a user's correction as one labeled GitHub issue, or list the open ones.
+
+The repository and label come from a private config file, so nothing
+identifying lives in this package::
+
+    ~/.claude/correction-capture.json
+    {"repository": "owner/name", "label": "correction"}
+
+    python correction_filing.py file --text "use shorter replies"
+    Filed: https://github.com/owner/name/issues/12
+    python correction_filing.py file --text "use shorter replies"
+    Already filed: https://github.com/owner/name/issues/12
+    python correction_filing.py file <<'CORRECTION'
+    use shorter replies
+    CORRECTION
+    Already filed: https://github.com/owner/name/issues/12
+    python correction_filing.py list
+    #12 Correction: use shorter replies https://github.com/...
+
+The issue quotes only the correction text, with tokens and email addresses
+masked. A hidden dedupe marker in the body, and a local ledger of filed keys
+beside the config file, keep a replayed correction from filing twice. CLAUDE_CORRECTION_CAPTURE_PATH names another config file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import quote
+
+from correction_filing_constants.config.constants import (
+    ALL_REDACTION_PATTERNS,
+    ALL_SOURCES,
+    BODY_FIELD_TEMPLATE,
+    CLAUDE_DIRECTORY_NAME,
+    CONFIG_ENCODING,
+    CONFIG_FILE_NAME,
+    CONFIG_LABEL_KEY,
+    CONFIG_PATH_ENV_VAR,
+    CONFIG_REPOSITORY_KEY,
+    CREATED_URL_JQ_FILTER,
+    DEDUPE_KEY_LENGTH,
+    DEDUPE_MARKER_PATTERN,
+    DEDUPE_MARKER_TEMPLATE,
+    DEFAULT_SOURCE,
+    DUPLICATE_MESSAGE_TEMPLATE,
+    EMPTY_TEXT_MESSAGE,
+    FAILURE_EXIT_CODE,
+    FILED_MESSAGE_TEMPLATE,
+    GH_EXECUTABLE,
+    LABEL_FIELD_TEMPLATE,
+    LINE_SEPARATOR,
+    ISSUE_BODY_TEMPLATE,
+    ISSUES_CREATE_PATH_TEMPLATE,
+    ISSUES_LIST_JQ_FILTER,
+    ISSUES_LIST_PATH_TEMPLATE,
+    LEDGER_FILE_NAME,
+    LEDGER_KEY_TEMPLATE,
+    ISSUE_TITLE_PREFIX,
+    ISSUE_TITLE_TEXT_LENGTH,
+    LIST_LINE_TEMPLATE,
+    MISSING_CONFIG_MESSAGE_TEMPLATE,
+    NO_OPEN_CORRECTIONS_MESSAGE,
+    REDACTION_PLACEHOLDER,
+    SUCCESS_EXIT_CODE,
+    TITLE_FIELD_TEMPLATE,
+    UTF8_ENCODING,
+    WORD_SEPARATOR,
+)
+
+
+@dataclass(frozen=True)
+class FilingTarget:
+    """The repository and label a correction files into."""
+
+    repository: str
+    label: str
+
+
+class FilingConfigMissing(ValueError):
+    """Stop the run when the private config file is absent or incomplete."""
+
+
+def _config_path() -> Path:
+    """Return the config path from the environment, or the default under ~/.claude."""
+    configured_path = os.environ.get(CONFIG_PATH_ENV_VAR, "")
+    if configured_path:
+        return Path(configured_path)
+    return Path.home() / CLAUDE_DIRECTORY_NAME / CONFIG_FILE_NAME
+
+
+def load_filing_target(from_path: Path) -> FilingTarget:
+    """Read the repository and label from the config file.
+
+    Args:
+        from_path: the private config file.
+
+    Returns:
+        The repository and label to file into.
+
+    Raises:
+        FilingConfigMissing: the file is absent, unreadable, or lacks a key.
+    """
+    missing_message = MISSING_CONFIG_MESSAGE_TEMPLATE.format(path=from_path)
+    try:
+        parsed_config = json.loads(from_path.read_text(encoding=CONFIG_ENCODING))
+    except (OSError, ValueError) as error:
+        raise FilingConfigMissing(missing_message) from error
+    if not isinstance(parsed_config, dict):
+        raise FilingConfigMissing(missing_message)
+    repository = parsed_config.get(CONFIG_REPOSITORY_KEY, "")
+    label = parsed_config.get(CONFIG_LABEL_KEY, "")
+    if not isinstance(repository, str) or not isinstance(label, str):
+        raise FilingConfigMissing(missing_message)
+    if not repository or not label:
+        raise FilingConfigMissing(missing_message)
+    return FilingTarget(repository=repository, label=label)
+
+
+def _redact_sensitive_text(correction_text: str) -> str:
+    """Mask tokens, keys, and email addresses in the correction text."""
+    redacted_text = correction_text
+    for each_pattern in ALL_REDACTION_PATTERNS:
+        redacted_text = re.sub(each_pattern, REDACTION_PLACEHOLDER, redacted_text)
+    return redacted_text
+
+
+def _dedupe_key_for(correction_text: str, supplied_key: str) -> str:
+    """Return a hex key that names this correction across replays."""
+    key_source = supplied_key or WORD_SEPARATOR.join(correction_text.split())
+    full_digest = hashlib.sha256(key_source.encode(UTF8_ENCODING)).hexdigest()
+    return full_digest[:DEDUPE_KEY_LENGTH]
+
+
+def issue_title_for(correction_text: str) -> str:
+    """Return a one-line issue title cut from the correction text.
+
+    Args:
+        correction_text: the redacted correction.
+
+    Returns:
+        The prefix and the first characters of the text on one line.
+    """
+    single_line_text = WORD_SEPARATOR.join(correction_text.split())
+    return ISSUE_TITLE_PREFIX + single_line_text[:ISSUE_TITLE_TEXT_LENGTH]
+
+
+def issue_body_for(correction_text: str, source: str, dedupe_key: str) -> str:
+    """Return the issue body with the quoted correction, its source, and the marker.
+
+    Args:
+        correction_text: the redacted correction.
+        source: where the correction came from.
+        dedupe_key: the hex key the marker carries.
+
+    Returns:
+        The markdown issue body.
+    """
+    quoted_text = LINE_SEPARATOR.join(
+        "> " + each_line for each_line in correction_text.splitlines()
+    )
+    return ISSUE_BODY_TEMPLATE.format(
+        source=source,
+        quoted_text=quoted_text,
+        dedupe_marker=DEDUPE_MARKER_TEMPLATE.format(key=dedupe_key),
+    )
+
+
+def _run_gh(all_arguments: list[str]) -> str:
+    completed_process = subprocess.run(
+        [GH_EXECUTABLE, *all_arguments],
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=True,
+    )
+    return completed_process.stdout
+
+
+def _list_labeled_issues(target: FilingTarget, state: str) -> list[dict[str, object]]:
+    """Return the issues carrying the label, with number, title, url, and body."""
+    issues_path = ISSUES_LIST_PATH_TEMPLATE.format(
+        repository=target.repository, label=quote(target.label), state=state
+    )
+    issue_lines = _run_gh(["api", "--paginate", issues_path, "--jq", ISSUES_LIST_JQ_FILTER])
+    return [json.loads(each_line) for each_line in issue_lines.splitlines() if each_line.strip()]
+
+
+def _ledger_path() -> Path:
+    return _config_path().with_name(LEDGER_FILE_NAME)
+
+
+def _read_ledger() -> dict[str, str]:
+    try:
+        parsed_ledger = json.loads(_ledger_path().read_text(encoding=CONFIG_ENCODING))
+    except (OSError, ValueError):
+        return {}
+    return parsed_ledger if isinstance(parsed_ledger, dict) else {}
+
+
+def _ledger_key_for(target: FilingTarget, dedupe_key: str) -> str:
+    return LEDGER_KEY_TEMPLATE.format(repository=target.repository, dedupe_key=dedupe_key)
+
+
+def _record_in_ledger(target: FilingTarget, dedupe_key: str, issue_url: str) -> None:
+    url_by_ledger_key = _read_ledger()
+    url_by_ledger_key[_ledger_key_for(target, dedupe_key)] = issue_url
+    _ledger_path().write_text(json.dumps(url_by_ledger_key), encoding=CONFIG_ENCODING)
+
+
+def _find_filed_issue_url(target: FilingTarget, dedupe_key: str) -> str:
+    """Return the url of an issue already carrying this dedupe key, or empty."""
+    ledger_url = _read_ledger().get(_ledger_key_for(target, dedupe_key), "")
+    if ledger_url:
+        return ledger_url
+    for each_issue in _list_labeled_issues(target, "all"):
+        each_match = re.search(DEDUPE_MARKER_PATTERN, str(each_issue.get("body", "")))
+        if each_match and each_match.group(1) == dedupe_key:
+            return str(each_issue.get("url", ""))
+    return ""
+
+
+def _file_correction(
+    target: FilingTarget, correction_text: str, source: str, supplied_key: str
+) -> str:
+    """File the correction once and return the message to print."""
+    redacted_text = _redact_sensitive_text(correction_text.strip())
+    dedupe_key = _dedupe_key_for(redacted_text, supplied_key)
+    existing_url = _find_filed_issue_url(target, dedupe_key)
+    if existing_url:
+        return DUPLICATE_MESSAGE_TEMPLATE.format(url=existing_url)
+    created_url = _run_gh(
+        [
+            "api",
+            "--method",
+            "POST",
+            ISSUES_CREATE_PATH_TEMPLATE.format(repository=target.repository),
+            "-f",
+            TITLE_FIELD_TEMPLATE.format(value=issue_title_for(redacted_text)),
+            "-f",
+            BODY_FIELD_TEMPLATE.format(value=issue_body_for(redacted_text, source, dedupe_key)),
+            "-f",
+            LABEL_FIELD_TEMPLATE.format(value=target.label),
+            "--jq",
+            CREATED_URL_JQ_FILTER,
+        ]
+    ).strip()
+    _record_in_ledger(target, dedupe_key, created_url)
+    return FILED_MESSAGE_TEMPLATE.format(url=created_url)
+
+
+def _open_corrections_listing(target: FilingTarget) -> str:
+    """Return one line per open labeled issue, or a no-open line."""
+    all_open_issues = _list_labeled_issues(target, "open")
+    if not all_open_issues:
+        return NO_OPEN_CORRECTIONS_MESSAGE
+    return "".join(
+        LIST_LINE_TEMPLATE.format(
+            number=each_issue["number"],
+            title=each_issue["title"],
+            url=each_issue["url"],
+        )
+        for each_issue in all_open_issues
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="File or list user corrections.")
+    all_subcommands = parser.add_subparsers(dest="command", required=True)
+    file_parser = all_subcommands.add_parser("file", help="File one correction.")
+    file_parser.add_argument("--text", default=None)
+    file_parser.add_argument("--source", choices=ALL_SOURCES, default=DEFAULT_SOURCE)
+    file_parser.add_argument("--dedupe-key", default="")
+    all_subcommands.add_parser("list", help="List the open corrections.")
+    return parser
+
+
+def _run_command(target: FilingTarget, parsed_arguments: argparse.Namespace) -> int:
+    if parsed_arguments.command == "list":
+        sys.stdout.write(_open_corrections_listing(target))
+        return SUCCESS_EXIT_CODE
+    correction_text = (
+        sys.stdin.buffer.read().decode(UTF8_ENCODING)
+        if parsed_arguments.text is None
+        else parsed_arguments.text
+    )
+    if not correction_text.strip():
+        sys.stderr.write(EMPTY_TEXT_MESSAGE)
+        return FAILURE_EXIT_CODE
+    sys.stdout.write(
+        _file_correction(
+            target, correction_text, parsed_arguments.source, parsed_arguments.dedupe_key
+        )
+    )
+    return SUCCESS_EXIT_CODE
+
+
+def main(all_arguments: list[str]) -> int:
+    """Run the file or list command.
+
+    Args:
+        all_arguments: the command-line arguments after the script name.
+
+    Returns:
+        The process exit code.
+    """
+    parsed_arguments = _build_parser().parse_args(all_arguments)
+    try:
+        target = load_filing_target(_config_path())
+    except FilingConfigMissing as error:
+        sys.stderr.write(str(error))
+        return FAILURE_EXIT_CODE
+    try:
+        return _run_command(target, parsed_arguments)
+    except subprocess.CalledProcessError as error:
+        sys.stderr.write(error.stderr or str(error))
+        return FAILURE_EXIT_CODE
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/.agents/skills/correction/scripts/correction_filing_constants/config/constants.py

@@ -0,0 +1,56 @@
+"""Configuration constants for the correction filing command."""
+
+ALL_REDACTION_PATTERNS = (
+    r"gh[pousr]_[A-Za-z0-9]{20,}",
+    r"github_pat_[A-Za-z0-9_]{20,}",
+    r"sk-[A-Za-z0-9_-]{20,}",
+    r"xox[abprs]-[A-Za-z0-9-]{10,}",
+    r"AKIA[0-9A-Z]{16}",
+    r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}",
+)
+BODY_FIELD_TEMPLATE = "body={value}"
+ALL_SOURCES = ("typed", "flag", "reaction", "hook")
+CLAUDE_DIRECTORY_NAME = ".claude"
+CONFIG_ENCODING = "utf-8"
+CONFIG_FILE_NAME = "correction-capture.json"
+CONFIG_LABEL_KEY = "label"
+CONFIG_PATH_ENV_VAR = "CLAUDE_CORRECTION_CAPTURE_PATH"
+CONFIG_REPOSITORY_KEY = "repository"
+CREATED_URL_JQ_FILTER = ".html_url"
+DEDUPE_MARKER_PATTERN = r"<!-- correction-dedupe: ([0-9a-f]{16,64}) -->"
+DEDUPE_MARKER_TEMPLATE = "<!-- correction-dedupe: {key} -->"
+DEDUPE_KEY_LENGTH = 16
+DEFAULT_SOURCE = "typed"
+DUPLICATE_MESSAGE_TEMPLATE = "Already filed: {url}\n"
+EMPTY_TEXT_MESSAGE = "The correction text is empty. Nothing was filed.\n"
+FAILURE_EXIT_CODE = 1
+FILED_MESSAGE_TEMPLATE = "Filed: {url}\n"
+GH_EXECUTABLE = "gh"
+ISSUE_BODY_TEMPLATE = (
+    "A correction the user made to an agent.\n\n"
+    "Source: {source}\n\n"
+    "{quoted_text}\n\n"
+    "{dedupe_marker}\n"
+)
+ISSUES_CREATE_PATH_TEMPLATE = "repos/{repository}/issues"
+ISSUES_LIST_JQ_FILTER = (
+    ".[] | select(.pull_request | not) | {number, title, url: .html_url, body}"
+)
+ISSUES_LIST_PATH_TEMPLATE = "repos/{repository}/issues?labels={label}&state={state}&per_page=100"
+ISSUE_TITLE_PREFIX = "Correction: "
+ISSUE_TITLE_TEXT_LENGTH = 72
+LABEL_FIELD_TEMPLATE = "labels[]={value}"
+LEDGER_FILE_NAME = "correction-capture-filed.json"
+LEDGER_KEY_TEMPLATE = "{repository} {dedupe_key}"
+LINE_SEPARATOR = "\n"
+LIST_LINE_TEMPLATE = "#{number} {title} {url}\n"
+MISSING_CONFIG_MESSAGE_TEMPLATE = (
+    "No correction filing config at {path}. Write it as "
+    '{{"repository": "<owner>/<name>", "label": "<label>"}}. Nothing was filed.\n'
+)
+NO_OPEN_CORRECTIONS_MESSAGE = "No open corrections.\n"
+REDACTION_PLACEHOLDER = "[redacted]"
+SUCCESS_EXIT_CODE = 0
+TITLE_FIELD_TEMPLATE = "title={value}"
+UTF8_ENCODING = "utf-8"
+WORD_SEPARATOR = " "

package/.agents/skills/correction/scripts/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_* should_*

package/.agents/skills/correction/scripts/test_correction_filing.py

@@ -0,0 +1,155 @@
+"""Behavior tests for correction_filing with a stand-in gh on PATH."""
+
+from __future__ import annotations
+
+import importlib
+import io
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+correction_filing = importlib.import_module("correction_filing")
+
+STAND_IN_GH = r'''#!/usr/bin/env python3
+import json, os, sys
+from urllib.parse import parse_qs, urlsplit
+store = os.environ["STAND_IN_GH_STORE"]
+issues = json.load(open(store)) if os.path.exists(store) else []
+args = sys.argv[1:]
+if "POST" in args:
+    fields = dict(args[i + 1].split("=", 1) for i, a in enumerate(args) if a == "-f")
+    number = len(issues) + 1
+    url = "https://example.test/issues/%d" % number
+    issues.append({"number": number, "title": fields["title"], "url": url,
+                   "body": fields["body"], "label": fields["labels[]"], "state": "open"})
+    json.dump(issues, open(store, "w"))
+    print(url)
+else:
+    query = parse_qs(urlsplit(args[2]).query)
+    state = query["state"][0]
+    for i in issues:
+        if i["label"] == query["labels"][0] and (state == "all" or i["state"] == state):
+            print(json.dumps({k: i[k] for k in ("number", "title", "url", "body")}))
+'''
+
+
+@pytest.fixture
+def filing_environment(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    bin_directory = tmp_path / "bin"
+    bin_directory.mkdir()
+    gh_path = bin_directory / "gh"
+    gh_path.write_text(STAND_IN_GH, encoding="utf-8")
+    gh_path.chmod(gh_path.stat().st_mode | stat.S_IEXEC)
+    store_path = tmp_path / "issues.json"
+    config_file = tmp_path / "correction-capture.json"
+    config_file.write_text(json.dumps({"repository": "owner/name", "label": "correction"}))
+    monkeypatch.setenv("PATH", str(bin_directory) + os.pathsep + os.environ["PATH"])
+    monkeypatch.setenv("STAND_IN_GH_STORE", str(store_path))
+    monkeypatch.setenv("CLAUDE_CORRECTION_CAPTURE_PATH", str(config_file))
+    return store_path
+
+
+def _stored_issues(store_path: Path) -> list[dict[str, object]]:
+    return json.loads(store_path.read_text()) if store_path.exists() else []
+
+
+def test_should_file_one_labeled_issue_quoting_the_text(filing_environment: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert correction_filing.main(["file", "--text", "use shorter replies"]) == 0
+    all_issues = _stored_issues(filing_environment)
+    assert len(all_issues) == 1
+    assert all_issues[0]["label"] == "correction"
+    assert "> use shorter replies" in all_issues[0]["body"]
+    assert "Filed: https://example.test/issues/1" in capsys.readouterr().out
+
+
+def test_should_file_a_replayed_correction_once(filing_environment: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    correction_filing.main(["file", "--text", "stop  asking me"])
+    assert correction_filing.main(["file", "--text", "stop asking me"]) == 0
+    assert len(_stored_issues(filing_environment)) == 1
+    assert "Already filed: https://example.test/issues/1" in capsys.readouterr().out
+
+
+def test_should_dedupe_on_a_supplied_key(filing_environment: Path) -> None:
+    correction_filing.main(["file", "--text", "first", "--dedupe-key", "msg-7"])
+    correction_filing.main(["file", "--text", "second", "--dedupe-key", "msg-7"])
+    correction_filing.main(["file", "--text", "second", "--dedupe-key", "msg-8"])
+    assert len(_stored_issues(filing_environment)) == 2
+
+
+def test_should_mask_tokens_and_emails(filing_environment: Path) -> None:
+    correction_filing.main(
+        ["file", "--text", "you leaked ghp_" + "a" * 36 + " and me@example.com"]
+    )
+    body = _stored_issues(filing_environment)[0]["body"]
+    assert "ghp_" not in body and "me@example.com" not in body
+    assert body.count("[redacted]") == 2
+
+
+def test_should_file_nothing_without_config(filing_environment: Path, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    monkeypatch.setenv("CLAUDE_CORRECTION_CAPTURE_PATH", str(tmp_path / "absent.json"))
+    assert correction_filing.main(["file", "--text", "anything"]) == 1
+    assert _stored_issues(filing_environment) == []
+    assert "No correction filing config" in capsys.readouterr().err
+
+
+def test_should_file_nothing_for_empty_text(filing_environment: Path) -> None:
+    assert correction_filing.main(["file", "--text", "   "]) == 1
+    assert _stored_issues(filing_environment) == []
+
+
+def test_should_list_open_corrections(filing_environment: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    correction_filing.main(["list"])
+    assert "No open corrections." in capsys.readouterr().out
+    correction_filing.main(["file", "--text", "use plain words"])
+    capsys.readouterr()
+    correction_filing.main(["list"])
+    assert "#1 Correction: use plain words https://example.test/issues/1" in capsys.readouterr().out
+
+
+def test_should_build_title_and_body_from_text() -> None:
+    assert correction_filing.issue_title_for("a\nb") == "Correction: a b"
+    body = correction_filing.issue_body_for("x\ny", "flag", "abcdef0123456789")
+    assert "> x\n> y" in body and "Source: flag" in body
+    assert "<!-- correction-dedupe: abcdef0123456789 -->" in body
+
+
+def test_should_read_target_and_reject_incomplete_config(tmp_path: Path) -> None:
+    good = tmp_path / "good.json"
+    good.write_text(json.dumps({"repository": "o/n", "label": "l"}))
+    assert correction_filing.load_filing_target(good) == correction_filing.FilingTarget("o/n", "l")
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps({"repository": "o/n"}))
+    with pytest.raises(correction_filing.FilingConfigMissing):
+        correction_filing.load_filing_target(bad)
+
+
+def test_should_dedupe_from_the_ledger_when_the_listing_lags(filing_environment: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    correction_filing.main(["file", "--text", "keep replies short"])
+    filing_environment.write_text("[]")
+    capsys.readouterr()
+    correction_filing.main(["file", "--text", "keep replies short"])
+    assert "Already filed: https://example.test/issues/1" in capsys.readouterr().out
+
+
+def test_should_read_the_text_from_stdin_without_expanding_it(filing_environment: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    piped_bytes = 'say "$(whoami)" and `id` in caf\u00e9\n'.encode("utf-8")
+    monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO(piped_bytes), encoding="cp1252"))
+    assert correction_filing.main(["file"]) == 0
+    assert '> say "$(whoami)" and `id` in caf\u00e9' in _stored_issues(filing_environment)[0]["body"]
+
+
+def test_should_file_again_after_the_config_names_another_repository(filing_environment: Path, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    correction_filing.main(["file", "--text", "keep replies short"])
+    filing_environment.write_text("[]")
+    (tmp_path / "correction-capture.json").write_text(json.dumps({"repository": "owner/other", "label": "correction"}))
+    capsys.readouterr()
+    correction_filing.main(["file", "--text", "keep replies short"])
+    assert "Filed: https://example.test/issues/1" in capsys.readouterr().out

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

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.69.1",
+    "version": "8.70.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",
 )

package/scripts/test_agent_image_copy.py

@@ -0,0 +1,76 @@
+"""Behavior tests for the agent image copy script."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import agent_image_copy
+
+
+def test_capped_size_should_keep_the_aspect_ratio() -> None:
+    assert agent_image_copy.capped_size(1440, 2560) == (288, 512)
+    assert agent_image_copy.capped_size(2000, 1000) == (512, 256)
+    assert agent_image_copy.capped_size(300, 200) == (300, 200)
+
+
+def test_visual_tokens_should_count_28_pixel_patches() -> None:
+    assert agent_image_copy.visual_tokens(1440, 2560) == 4784
+    assert agent_image_copy.visual_tokens(288, 512) == 209
+
+
+def test_parse_crop_box_should_refuse_three_numbers() -> None:
+    assert agent_image_copy.parse_crop_box("0,0,10,20") == (0, 0, 10, 20)
+    with pytest.raises(argparse.ArgumentTypeError):
+        agent_image_copy.parse_crop_box("0,0,10")
+
+
+def test_write_agent_copy_should_write_a_capped_newer_file(tmp_path: Path) -> None:
+    source_path = tmp_path / "preview.png"
+    Image.new("RGB", (1440, 2560), "white").save(source_path)
+    copy_path = agent_image_copy.write_agent_copy(source_path, None)
+    assert copy_path.name == "preview.agent.png"
+    with Image.open(copy_path) as copy_image:
+        assert copy_image.size == (288, 512)
+    assert copy_path.stat().st_mtime >= source_path.stat().st_mtime
+
+
+def test_write_agent_copy_should_crop_before_scaling(tmp_path: Path) -> None:
+    source_path = tmp_path / "preview.png"
+    Image.new("RGB", (1440, 2560), "white").save(source_path)
+    copy_path = agent_image_copy.write_agent_copy(source_path, (0, 0, 720, 640))
+    with Image.open(copy_path) as copy_image:
+        assert copy_image.size == (512, 455)
+
+
+def test_write_agent_copy_should_write_a_cmyk_jpeg_as_rgb(tmp_path: Path) -> None:
+    source_path = tmp_path / "print.jpg"
+    Image.new("CMYK", (1000, 800)).save(source_path)
+    copy_path = agent_image_copy.write_agent_copy(source_path, None)
+    with Image.open(copy_path) as copy_image:
+        assert copy_image.mode == "RGB"
+        assert copy_image.size == (512, 410)
+
+
+def test_write_agent_copy_should_follow_the_exif_orientation(tmp_path: Path) -> None:
+    source_path = tmp_path / "phone.jpg"
+    source_image = Image.new("RGB", (1000, 600), "white")
+    all_exif_tags = source_image.getexif()
+    all_exif_tags[0x0112] = 6
+    source_image.save(source_path, exif=all_exif_tags)
+    copy_path = agent_image_copy.write_agent_copy(source_path, None)
+    with Image.open(copy_path) as copy_image:
+        assert copy_image.size == (307, 512)
+
+
+def test_main_should_print_the_copy_path(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_path = tmp_path / "shot.png"
+    Image.new("RGB", (1600, 900), "white").save(source_path)
+    assert agent_image_copy.main([str(source_path)]) == 0
+    assert "shot.agent.png 512x288 about 209 tokens" in capsys.readouterr().out