claude-dev-env 8.100.1 → 8.101.0

package/hooks/advisory/edit_lint_context.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""PostToolUse hook that runs a repository's lint on each file the agent edits.
+
+The agent edits ``tools/report.py`` in a repository that opts in. The hook runs
+that repository's lint command on the file and hands the findings back to the
+agent, so it fixes them in the same turn::
+
+    environment list:  owner/repo
+    <repo>/.claude/edit-lint.json:
+        {"file_suffixes": [".py"],
+         "command": ["python", "lint.py", "--advisory", "{file}"]}
+
+    Edit tools/report.py  ->  additionalContext:
+        "The repository's lint found these problems in tools/report.py ..."
+
+A repository takes part only when its origin ``owner/repo`` slug is in
+``CLAUDE_EDIT_LINT_REPOSITORIES``, it commits ``.claude/edit-lint.json``, and
+its root sits inside the session's project folder, the folder Claude Code's
+workspace trust covers. A checkout elsewhere never runs its declared command.
+The command runs from the repository root, and ``{file}`` in it becomes the
+edited path with every symlink resolved. Its standard output is the findings; empty output adds nothing.
+A command that exits non-zero, times out, or cannot start adds nothing and
+writes one diagnostic line to stderr. The hook never blocks and never edits
+the file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    _blocking_directory = str(Path(_hooks_directory) / "blocking")
+    for each_bootstrap_directory in (_hooks_directory, _blocking_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+    from hooks_constants.edit_lint_context_constants import (
+        ALL_EDIT_TOOL_NAMES,
+        ALL_GIT_TOPLEVEL_COMMAND,
+        COMMAND_KEY,
+        CONFIG_RELATIVE_PATH,
+        FILE_PLACEHOLDER,
+        FILE_SUFFIXES_KEY,
+        FINDINGS_CONTEXT_TEMPLATE,
+        GIT_COMMAND_TIMEOUT_SECONDS,
+        LINT_COMMAND_TIMEOUT_SECONDS,
+        LINT_FAILURE_DIAGNOSTIC_TEMPLATE,
+        MAXIMUM_FINDINGS_CHARACTERS,
+        PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE,
+        REPOSITORIES_ENVIRONMENT_VARIABLE,
+        REPOSITORY_SEPARATOR,
+        TRUNCATION_NOTICE,
+    )
+    from hooks_constants.post_tool_use_context import write_post_tool_use_context_to_stdout
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.subprocess_window import hidden_window_creation_flags
+    from pii_prevention_blocker_parts.repository_exemption import repository_origin_slug
+except ImportError as import_error:
+    raise ImportError(
+        "edit_lint_context: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+@dataclass(frozen=True)
+class EditLintConfig:
+    """A repository's edit lint settings from ``.claude/edit-lint.json``.
+
+    Attributes:
+        all_file_suffixes: File suffixes the command lints, such as ``.py``.
+        all_command_parts: The command and its arguments, with ``{file}``
+            where the edited path goes.
+    """
+
+    all_file_suffixes: tuple[str, ...]
+    all_command_parts: tuple[str, ...]
+
+
+def opted_in_repository_slugs() -> frozenset[str]:
+    """Return the lowercased ``owner/repo`` slugs the environment value lists.
+
+    Returns:
+        Each non-empty comma-separated entry of
+        ``CLAUDE_EDIT_LINT_REPOSITORIES``, stripped and lowercased.
+    """
+    listed = os.environ.get(REPOSITORIES_ENVIRONMENT_VARIABLE, "")
+    return frozenset(
+        each.strip().casefold() for each in listed.split(REPOSITORY_SEPARATOR) if each.strip()
+    )
+
+
+def repository_root_of(file_path: Path) -> Path | None:
+    """Return the git work tree root that holds the file, or None.
+
+    Args:
+        file_path: Absolute path of the edited file.
+
+    Returns:
+        The work tree root, or None when the file sits outside a git work tree
+        or git cannot run.
+    """
+    try:
+        completed_process = subprocess.run(
+            list(ALL_GIT_TOPLEVEL_COMMAND),
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=str(file_path.parent),
+            creationflags=hidden_window_creation_flags(),
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    return Path(completed_process.stdout.strip())
+
+
+def is_inside_project_directory(repository_root: Path) -> bool:
+    """Return whether the repository root sits inside the session's project folder.
+
+    Args:
+        repository_root: The git work tree root.
+
+    Returns:
+        True when ``CLAUDE_PROJECT_DIR`` is set and the resolved root equals it
+        or sits below it. False when the variable is unset or the root lies
+        outside it.
+    """
+    project_directory = os.environ.get(PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE, "")
+    if not project_directory:
+        return False
+    resolved_root = repository_root.resolve()
+    resolved_project = Path(project_directory).resolve()
+    return resolved_root == resolved_project or resolved_project in resolved_root.parents
+
+
+def load_edit_lint_config(repository_root: Path) -> EditLintConfig | None:
+    """Read the repository's ``.claude/edit-lint.json``, or None when unusable.
+
+    Args:
+        repository_root: The git work tree root.
+
+    Returns:
+        The parsed settings, or None when the file is missing, is not JSON, or
+        lacks a non-empty string list under ``file_suffixes`` or ``command``.
+    """
+    try:
+        raw_config = json.loads(
+            (repository_root / CONFIG_RELATIVE_PATH).read_text(encoding="utf-8")
+        )
+    except (OSError, ValueError):
+        return None
+    if not isinstance(raw_config, dict):
+        return None
+    all_file_suffixes = _string_tuple(raw_config.get(FILE_SUFFIXES_KEY))
+    all_command_parts = _string_tuple(raw_config.get(COMMAND_KEY))
+    if not all_file_suffixes or not all_command_parts:
+        return None
+    return EditLintConfig(all_file_suffixes, all_command_parts)
+
+
+def _string_tuple(raw_value: object) -> tuple[str, ...]:
+    if not isinstance(raw_value, list):
+        return ()
+    if not all(isinstance(each, str) and each for each in raw_value):
+        return ()
+    return tuple(raw_value)
+
+
+def lint_findings(config: EditLintConfig, repository_root: Path, file_path: Path) -> str:
+    """Run the lint command on one file and return its findings text.
+
+    Args:
+        config: The repository's edit lint settings.
+        repository_root: The directory the command runs from.
+        file_path: The edited file, put where ``{file}`` stands.
+
+    Returns:
+        The command's standard output, stripped. An empty string when the
+        command printed nothing, exited non-zero, timed out, or could not
+        start.
+    """
+    completed_process = _run_lint_command(config, repository_root, file_path)
+    if completed_process is None:
+        return ""
+    if completed_process.returncode != 0:
+        last_error_line = (completed_process.stderr.strip().splitlines() or [""])[-1]
+        _write_failure_diagnostic(
+            file_path, f"exit {completed_process.returncode}: {last_error_line}"
+        )
+        return ""
+    return completed_process.stdout.strip()
+
+
+def _run_lint_command(
+    config: EditLintConfig, repository_root: Path, file_path: Path
+) -> subprocess.CompletedProcess[str] | None:
+    all_arguments = [
+        each_part.replace(FILE_PLACEHOLDER, str(file_path))
+        for each_part in config.all_command_parts
+    ]
+    try:
+        return subprocess.run(
+            all_arguments,
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=LINT_COMMAND_TIMEOUT_SECONDS,
+            cwd=str(repository_root),
+            creationflags=hidden_window_creation_flags(),
+        )
+    except subprocess.TimeoutExpired:
+        _write_failure_diagnostic(file_path, "timed out")
+    except OSError as start_error:
+        _write_failure_diagnostic(file_path, str(start_error))
+    return None
+
+
+def _write_failure_diagnostic(file_path: Path, failure_text: str) -> None:
+    sys.stderr.write(LINT_FAILURE_DIAGNOSTIC_TEMPLATE % (file_path, failure_text))
+
+
+def findings_context(file_label: str, findings_text: str) -> str:
+    """Return the note the agent reads, with the findings cut to the size limit.
+
+    Args:
+        file_label: The edited file as the note names it.
+        findings_text: The lint command's findings.
+
+    Returns:
+        The note text.
+    """
+    if len(findings_text) > MAXIMUM_FINDINGS_CHARACTERS:
+        findings_text = findings_text[:MAXIMUM_FINDINGS_CHARACTERS] + TRUNCATION_NOTICE.format(
+            limit=MAXIMUM_FINDINGS_CHARACTERS
+        )
+    return FINDINGS_CONTEXT_TEMPLATE.format(file=file_label, findings=findings_text)
+
+
+def _edited_file_path(all_hook_fields: dict[str, object]) -> Path | None:
+    if all_hook_fields.get("tool_name") not in ALL_EDIT_TOOL_NAMES:
+        return None
+    tool_input = all_hook_fields.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return None
+    raw_path = tool_input.get("file_path")
+    if not isinstance(raw_path, str) or not raw_path:
+        return None
+    file_path = Path(raw_path)
+    if not file_path.is_absolute() or not file_path.is_file():
+        return None
+    return file_path.resolve()
+
+
+def main() -> None:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return
+    all_opted_in_slugs = opted_in_repository_slugs()
+    if not all_opted_in_slugs:
+        return
+    file_path = _edited_file_path(hook_input)
+    if file_path is None:
+        return
+    repository_root = repository_root_of(file_path)
+    if repository_root is None or not is_inside_project_directory(repository_root):
+        return
+    if repository_origin_slug(repository_root) not in all_opted_in_slugs:
+        return
+    config = load_edit_lint_config(repository_root)
+    if config is None or file_path.suffix not in config.all_file_suffixes:
+        return
+    findings_text = lint_findings(config, repository_root, file_path)
+    if not findings_text:
+        return
+    try:
+        file_label = file_path.relative_to(repository_root.resolve()).as_posix()
+    except ValueError:
+        file_label = str(file_path)
+    write_post_tool_use_context_to_stdout(findings_context(file_label, findings_text))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/advisory/test_edit_lint_context.py

@@ -0,0 +1,269 @@
+"""Behavior tests for the edit lint context hook.
+
+Each test builds a disposable git repository whose origin points at a
+github.com slug and whose ``.claude/edit-lint.json`` names a small lint script.
+The script prints one finding for every line holding ``BAD``. The hook runs
+through the PostToolUse dispatcher the way the live entry runs it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+try:
+    advisory_directory = str(Path(__file__).resolve().parent)
+    if advisory_directory not in sys.path:
+        sys.path.insert(0, advisory_directory)
+    import edit_lint_context
+except ImportError as import_error:
+    raise ImportError(
+        "test_edit_lint_context: cannot import its sibling modules; "
+        "ensure the advisory directory is importable."
+    ) from import_error
+
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+DISPATCHER_PATH = HOOKS_DIRECTORY / "validation" / "post_tool_use_dispatcher.py"
+HOOKS_JSON_PATH = HOOKS_DIRECTORY / "hooks.json"
+ORIGIN_SLUG = "LintOwner/lint-repo"
+ORIGIN_URL = f"https://github.com/{ORIGIN_SLUG}.git"
+LINT_SCRIPT_SOURCE = (
+    "import sys\n"
+    "path = sys.argv[1]\n"
+    "for number, line in enumerate(open(path, encoding='utf-8'), 1):\n"
+    "    if 'BAD' in line:\n"
+    "        print(f'{path}:{number}: F821 undefined name')\n"
+    "    if 'CRASH' in line:\n"
+    "        sys.stderr.write('lint tool missing\\n')\n"
+    "        sys.exit(3)\n"
+)
+DISPATCHER_TIMEOUT_SECONDS = 60
+
+
+def _git_environment() -> dict[str, str]:
+    return {
+        each_name: each_value
+        for each_name, each_value in os.environ.items()
+        if not each_name.upper().startswith("GIT_")
+    }
+
+
+def _run_git(repository_root: Path, *all_arguments: str) -> None:
+    subprocess.run(
+        ["git", *all_arguments],
+        cwd=repository_root,
+        check=True,
+        capture_output=True,
+        env=_git_environment(),
+    )
+
+
+@pytest.fixture
+def lint_repository(tmp_path: Path) -> Path:
+    repository_root = tmp_path / "lint-repo"
+    repository_root.mkdir()
+    _run_git(repository_root, "init", "--quiet")
+    _run_git(repository_root, "remote", "add", "origin", ORIGIN_URL)
+    (repository_root / "lint.py").write_text(LINT_SCRIPT_SOURCE, encoding="utf-8")
+    config_path = repository_root / ".claude" / "edit-lint.json"
+    config_path.parent.mkdir()
+    config_path.write_text(
+        json.dumps({"file_suffixes": [".py"], "command": [sys.executable, "lint.py", "{file}"]}),
+        encoding="utf-8",
+    )
+    return repository_root
+
+
+def _run_dispatcher(
+    tool_name: str,
+    file_path: Path,
+    listed_repositories: str | None,
+    project_directory: Path | None = None,
+) -> str:
+    environment = _git_environment()
+    environment["CLAUDE_PROJECT_DIR"] = str(project_directory or file_path.parents[-2])
+    environment.pop("CLAUDE_EDIT_LINT_REPOSITORIES", None)
+    if listed_repositories is not None:
+        environment["CLAUDE_EDIT_LINT_REPOSITORIES"] = listed_repositories
+    completed_process = subprocess.run(
+        [sys.executable, str(DISPATCHER_PATH)],
+        input=json.dumps({"tool_name": tool_name, "tool_input": {"file_path": str(file_path)}}),
+        capture_output=True,
+        text=True,
+        env=environment,
+        timeout=DISPATCHER_TIMEOUT_SECONDS,
+        check=False,
+    )
+    assert completed_process.returncode == 0, completed_process.stderr
+    return completed_process.stdout.strip()
+
+
+def _additional_context(dispatcher_output: str) -> str:
+    return json.loads(dispatcher_output)["hookSpecificOutput"]["additionalContext"]
+
+
+def should_add_findings_after_an_edit_in_an_opted_in_repository(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("VALUE = 1\nRESULT = BAD\n", encoding="utf-8")
+
+    note = _additional_context(_run_dispatcher("Edit", edited_file, ORIGIN_SLUG.lower()))
+
+    assert "module.py:2: F821 undefined name" in note
+    assert note.startswith("The repository's lint found these problems in module.py")
+
+
+def should_add_findings_after_a_write_and_a_multi_edit(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("RESULT = BAD\n", encoding="utf-8")
+
+    for each_tool_name in ("Write", "MultiEdit"):
+        note = _additional_context(_run_dispatcher(each_tool_name, edited_file, ORIGIN_SLUG))
+        assert "module.py:1: F821" in note
+
+
+def should_pass_the_lint_command_the_path_with_symlinks_resolved(
+    lint_repository: Path, tmp_path: Path
+) -> None:
+    package_directory = lint_repository / "package"
+    package_directory.mkdir()
+    (package_directory / "module.py").write_text("RESULT = BAD\n", encoding="utf-8")
+    linked_directory = tmp_path / "linked-package"
+    linked_directory.symlink_to(package_directory, target_is_directory=True)
+
+    note = _additional_context(
+        _run_dispatcher("Edit", linked_directory / "module.py", ORIGIN_SLUG)
+    )
+
+    assert f"{(package_directory / 'module.py').resolve()}:1: F821" in note
+    assert "linked-package" not in note
+
+
+def should_add_nothing_when_the_environment_lists_no_repository(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("RESULT = BAD\n", encoding="utf-8")
+
+    assert _run_dispatcher("Edit", edited_file, None) == ""
+    assert _run_dispatcher("Edit", edited_file, "other/repo") == ""
+
+
+def should_add_nothing_for_a_repository_outside_the_project_folder(
+    lint_repository: Path, tmp_path: Path
+) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("RESULT = BAD\n", encoding="utf-8")
+    other_project = tmp_path / "other-project"
+    other_project.mkdir()
+
+    assert _run_dispatcher("Edit", edited_file, ORIGIN_SLUG, other_project) == ""
+
+
+def should_accept_a_root_inside_the_project_folder(
+    lint_repository: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(lint_repository.parent))
+    assert edit_lint_context.is_inside_project_directory(lint_repository)
+
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(lint_repository / "package"))
+    assert not edit_lint_context.is_inside_project_directory(lint_repository)
+
+
+def should_add_nothing_after_a_clean_edit(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("VALUE = 1\n", encoding="utf-8")
+
+    assert _run_dispatcher("Edit", edited_file, ORIGIN_SLUG) == ""
+
+
+def should_add_nothing_for_a_suffix_the_repository_does_not_lint(lint_repository: Path) -> None:
+    edited_file = lint_repository / "notes.md"
+    edited_file.write_text("BAD\n", encoding="utf-8")
+
+    assert _run_dispatcher("Edit", edited_file, ORIGIN_SLUG) == ""
+
+
+def should_add_nothing_when_the_lint_command_fails(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("RESULT = BAD\nCRASH\n", encoding="utf-8")
+
+    assert _run_dispatcher("Edit", edited_file, ORIGIN_SLUG) == ""
+
+
+def should_add_nothing_for_a_file_outside_a_git_repository(tmp_path: Path) -> None:
+    loose_file = tmp_path / "loose.py"
+    loose_file.write_text("RESULT = BAD\n", encoding="utf-8")
+
+    assert _run_dispatcher("Edit", loose_file, ORIGIN_SLUG) == ""
+
+
+def should_register_the_dispatcher_for_edit_write_and_multi_edit() -> None:
+    registrations = json.loads(HOOKS_JSON_PATH.read_text(encoding="utf-8"))
+    all_matchers = [
+        each_group["matcher"]
+        for each_group in registrations["hooks"]["PostToolUse"]
+        if any(
+            "post_tool_use_dispatcher.py" in each_hook["command"]
+            for each_hook in each_group["hooks"]
+        )
+    ]
+
+    assert all_matchers == ["Write|Edit|MultiEdit"]
+
+
+def should_read_listed_slugs_lowercased(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_EDIT_LINT_REPOSITORIES", " Owner/One , ,owner/two")
+
+    assert edit_lint_context.opted_in_repository_slugs() == frozenset({"owner/one", "owner/two"})
+
+
+def should_find_the_work_tree_root_of_a_nested_file(lint_repository: Path) -> None:
+    nested_directory = lint_repository / "package"
+    nested_directory.mkdir()
+    nested_file = nested_directory / "inner.py"
+    nested_file.write_text("VALUE = 1\n", encoding="utf-8")
+
+    found_root = edit_lint_context.repository_root_of(nested_file)
+
+    assert found_root is not None
+    assert found_root.resolve() == lint_repository.resolve()
+
+
+def should_reject_a_config_without_a_command(lint_repository: Path) -> None:
+    config_path = lint_repository / ".claude" / "edit-lint.json"
+    config_path.write_text(json.dumps({"file_suffixes": [".py"], "command": []}), encoding="utf-8")
+
+    assert edit_lint_context.load_edit_lint_config(lint_repository) is None
+
+
+def should_load_the_suffixes_and_command(lint_repository: Path) -> None:
+    config = edit_lint_context.load_edit_lint_config(lint_repository)
+
+    assert config == edit_lint_context.EditLintConfig(
+        (".py",), (sys.executable, "lint.py", "{file}")
+    )
+
+
+def should_return_the_lint_output_for_one_file(lint_repository: Path) -> None:
+    edited_file = lint_repository / "module.py"
+    edited_file.write_text("RESULT = BAD\n", encoding="utf-8")
+    config = edit_lint_context.load_edit_lint_config(lint_repository)
+    assert config is not None
+
+    assert edit_lint_context.lint_findings(config, lint_repository, edited_file) == (
+        f"{edited_file}:1: F821 undefined name"
+    )
+
+
+def should_cut_long_findings_to_the_limit() -> None:
+    long_findings = "x" * 5000
+
+    note = edit_lint_context.findings_context("module.py", long_findings)
+
+    assert "x" * 4000 in note
+    assert "x" * 4001 not in note
+    assert note.endswith("[edit lint output cut at 4000 characters]")

package/hooks/features/post-write-validation.md

@@ -1,16 +1,18 @@
 # Post-write validation
 
-This family checks a completed Write or Edit call and formats eligible new source files. The agent receives a combined block decision if a hosted check blocks.
+This family checks a completed Write, Edit or MultiEdit call, formats eligible new source files, and runs an opted-in repository's lint on the edited file. The agent receives a combined block decision if a hosted check blocks.
 
 ## Checks
 
 - `validation/post_tool_use_dispatcher.py` runs the post-write roster in order and combines any block reasons.
 - `workflow/auto_formatter.py` formats eligible untracked source files after a Write and never blocks the write.
+- `advisory/edit_lint_context.py` runs the lint command a repository names in `.claude/edit-lint.json` on the edited file and adds its findings to the agent's context. It runs only for a repository whose origin `owner/repo` slug is listed in `CLAUDE_EDIT_LINT_REPOSITORIES`, comma-separated, and whose root sits inside `CLAUDE_PROJECT_DIR`, the folder the session's workspace trust covers. It never blocks and never edits the file.
 
 ## When it fires
 
-- `validation/post_tool_use_dispatcher.py` runs on `PostToolUse`, matcher `Write|Edit`, timeout `180` seconds in `hooks.json`.
-- `workflow/auto_formatter.py` runs inside that dispatcher on `PostToolUse`, matcher `Write|Edit`, timeout `180` seconds, as named by `ALL_POST_HOSTED_HOOK_ENTRIES`. Its eligibility check accepts only a Write of an untracked source file.
+- `validation/post_tool_use_dispatcher.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit`, timeout `180` seconds in `hooks.json`.
+- `workflow/auto_formatter.py` runs inside that dispatcher on `PostToolUse`, matcher `Write|Edit|MultiEdit`, timeout `180` seconds, as named by `ALL_POST_HOSTED_HOOK_ENTRIES`. Its eligibility check accepts only a Write of an untracked source file.
+- `advisory/edit_lint_context.py` runs inside that dispatcher after the formatter, so it lints the file as the formatter left it.
 
 ## Proving it
 
@@ -19,10 +21,12 @@ Preconditions:
 - Run each command from the repository root with Python and pytest available. The formatter tests make disposable repositories.
 
 - **Post-write dispatch.** Input is an Edit of plain text. Run `python -m pytest packages/claude-dev-env/hooks/validation/test_post_tool_use_dispatcher.py -q`. The adjacent test observes an allow result and the hosted formatter's selection.
+- **Edit lint context.** Input is an Edit, Write or MultiEdit of a file in a disposable repository that lists a lint script. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_edit_lint_context.py -q`. The adjacent test observes the findings note for an opted-in repository and no output for a clean edit, an unlisted repository, an unlisted suffix, or a failed lint command.
 - **Formatter eligibility.** Input is a Write of an untracked source file. Run `python -m pytest packages/claude-dev-env/hooks/workflow/test_auto_formatter.py -q`. The adjacent test observes formatting for eligible writes and no edit of a tracked file.
 
 ## Gotchas
 
-- The current post-write roster contains only `workflow/auto_formatter.py`. The dispatcher's docstring mentions other hosted work from an older roster, so use the roster for membership.
+- The current post-write roster contains `workflow/auto_formatter.py` and `advisory/edit_lint_context.py`. The dispatcher's docstring mentions other hosted work from an older roster, so use the roster for membership.
 - The formatter can change the file after the original Write. A later hosted script would read the formatted file because the dispatcher preserves roster order.
 - Formatter eligibility protects the hook tree and checks whether the file is tracked.
+- The edit lint command's standard output is the findings. A repository's command prints nothing on a clean file and sends progress lines to stderr. A non-zero exit adds no note and writes one diagnostic line to stderr, so the command runs the lint in a mode that exits 0 when it reports findings.

package/hooks/hooks.json

@@ -477,7 +477,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/edit_lint_context_constants.py

@@ -0,0 +1,40 @@
+"""Constants for the PostToolUse hook that lints each edited file."""
+
+from __future__ import annotations
+
+__all__ = [
+    "REPOSITORIES_ENVIRONMENT_VARIABLE",
+    "REPOSITORY_SEPARATOR",
+    "PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE",
+    "CONFIG_RELATIVE_PATH",
+    "FILE_SUFFIXES_KEY",
+    "COMMAND_KEY",
+    "FILE_PLACEHOLDER",
+    "ALL_EDIT_TOOL_NAMES",
+    "ALL_GIT_TOPLEVEL_COMMAND",
+    "GIT_COMMAND_TIMEOUT_SECONDS",
+    "LINT_COMMAND_TIMEOUT_SECONDS",
+    "MAXIMUM_FINDINGS_CHARACTERS",
+    "TRUNCATION_NOTICE",
+    "FINDINGS_CONTEXT_TEMPLATE",
+    "LINT_FAILURE_DIAGNOSTIC_TEMPLATE",
+]
+
+REPOSITORIES_ENVIRONMENT_VARIABLE = "CLAUDE_EDIT_LINT_REPOSITORIES"
+REPOSITORY_SEPARATOR = ","
+PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE = "CLAUDE_PROJECT_DIR"
+CONFIG_RELATIVE_PATH = ".claude/edit-lint.json"
+FILE_SUFFIXES_KEY = "file_suffixes"
+COMMAND_KEY = "command"
+FILE_PLACEHOLDER = "{file}"
+ALL_EDIT_TOOL_NAMES = frozenset({"Write", "Edit", "MultiEdit"})
+ALL_GIT_TOPLEVEL_COMMAND = ("git", "rev-parse", "--show-toplevel")
+GIT_COMMAND_TIMEOUT_SECONDS = 10
+LINT_COMMAND_TIMEOUT_SECONDS = 60
+MAXIMUM_FINDINGS_CHARACTERS = 4000
+TRUNCATION_NOTICE = "\n[edit lint output cut at {limit} characters]"
+FINDINGS_CONTEXT_TEMPLATE = (
+    "The repository's lint found these problems in {file} after this edit. "
+    "Fix them in this turn:\n{findings}"
+)
+LINT_FAILURE_DIAGNOSTIC_TEMPLATE = "[edit_lint_context] lint command for %s did not finish: %s\n"

package/hooks/hooks_constants/post_tool_use_dispatcher_constants.py

@@ -58,4 +58,8 @@ ALL_POST_HOSTED_HOOK_ENTRIES: tuple[PostHostedHookEntry, ...] = (
         script_relative_path="workflow/auto_formatter.py",
         is_blocking=False,
     ),
+    PostHostedHookEntry(
+        script_relative_path="advisory/edit_lint_context.py",
+        is_blocking=False,
+    ),
 )

package/hooks/validation/test_post_tool_use_dispatcher.py

@@ -366,4 +366,5 @@ def test_live_roster_contains_only_nonblocking_hooks() -> None:
     assert all(not each_entry.is_blocking for each_entry in ALL_POST_HOSTED_HOOK_ENTRIES)
     assert tuple(each_entry.script_relative_path for each_entry in ALL_POST_HOSTED_HOOK_ENTRIES) == (
         "workflow/auto_formatter.py",
+        "advisory/edit_lint_context.py",
     )

package/package.json

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