claude-dev-env 8.100.0 → 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/blocking/test_verify_before_commit_gate.py

@@ -43,13 +43,32 @@ TOOL_RESULT_ENTRY = {
     },
 }
 
+REFUSED_TOOL_RESULT_ENTRY = {
+    "type": "user",
+    "message": {
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": "toolu_1",
+                "content": "<tool_use_error>Skill verify cannot be used with Skill tool</tool_use_error>",
+                "is_error": True,
+            }
+        ]
+    },
+}
+
 
 def _skill_entry(skill_name: str) -> dict[str, object]:
     return {
         "type": "assistant",
         "message": {
             "content": [
-                {"type": "tool_use", "name": "Skill", "input": {"skill": skill_name}}
+                {
+                    "type": "tool_use",
+                    "id": "toolu_1",
+                    "name": "Skill",
+                    "input": {"skill": skill_name},
+                }
             ]
         },
     }
@@ -197,6 +216,33 @@ def test_docs_only_commit_passes(repository: Path, tmp_path: Path) -> None:
     )
 
 
+def test_data_files_under_docs_folder_pass(repository: Path, tmp_path: Path) -> None:
+    (repository / "docs" / "records").mkdir(parents=True)
+    (repository / "docs" / "records" / "proof.json").write_text("{}\n", encoding="utf-8")
+    (repository / "docs" / "ruleset.yaml").write_text("rules: []\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert not _is_denied(
+        _payload("git commit -m records", repository, _unverified(tmp_path))
+    )
+
+
+def test_code_under_docs_folder_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "docs").mkdir()
+    (repository / "docs" / "conf.py").write_text("VALUE = 2\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert _is_denied(
+        _payload("git commit -m conf", repository, _unverified(tmp_path))
+    )
+
+
+def test_json_outside_docs_folder_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "config.json").write_text("{}\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert _is_denied(
+        _payload("git commit -m config", repository, _unverified(tmp_path))
+    )
+
+
 def test_tests_only_commit_passes(repository: Path, tmp_path: Path) -> None:
     (repository / "test_app.py").write_text(
         "def test_value() -> None:\n    pass\n", encoding="utf-8"
@@ -219,6 +265,15 @@ def test_docs_plus_code_commit_is_denied(repository: Path, tmp_path: Path) -> No
     )
 
 
+def test_refused_verify_skill_call_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "app.py").write_text("VALUE = 2\n", encoding="utf-8")
+    _git(repository, "add", "app.py")
+    transcript_path = _transcript(
+        tmp_path, PROMPT_ENTRY, _skill_entry("verify"), REFUSED_TOOL_RESULT_ENTRY
+    )
+    assert _is_denied(_payload("git commit -m change", repository, transcript_path))
+
+
 def test_verify_skill_call_after_the_last_prompt_passes(
     repository: Path, tmp_path: Path
 ) -> None:

package/hooks/blocking/verify_before_commit_gate.py

@@ -33,6 +33,8 @@ from hooks_constants.verify_before_commit_gate_constants import (
     ALL_ADD_EVERYTHING_OPTIONS,
     ALL_COMMIT_ALL_OPTIONS,
     ALL_COMMIT_VALUED_SHORT_FLAGS,
+    ALL_DOCS_DATA_EXTENSIONS,
+    ALL_DOCS_DIRECTORY_NAMES,
     ALL_DOCS_EXTENSIONS,
     ALL_GIT_EXECUTABLES,
     ALL_SLASH_COMMAND_MARKERS,
@@ -176,7 +178,12 @@ def _is_docs_or_test_path(repository_path: str) -> bool:
     path = PurePosixPath(repository_path)
     if path.suffix.lower() in ALL_DOCS_EXTENSIONS or path.name in ALL_TEST_FILE_NAMES:
         return True
-    if any(each_part in ALL_TEST_DIRECTORY_NAMES for each_part in path.parts[:-1]):
+    all_directory_parts = path.parts[:-1]
+    if path.suffix.lower() in ALL_DOCS_DATA_EXTENSIONS and any(
+        each_part in ALL_DOCS_DIRECTORY_NAMES for each_part in all_directory_parts
+    ):
+        return True
+    if any(each_part in ALL_TEST_DIRECTORY_NAMES for each_part in all_directory_parts):
         return True
     return (
         path.name.startswith(ALL_TEST_FILE_PREFIXES)
@@ -245,6 +252,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
         git commit, code staged, no verify since the last prompt      -> DENY_REASON
         git add app.py; git commit, empty index, no verify            -> DENY_REASON
         git commit, only docs or test files                           -> None
+        git commit, only data files (.json, .jsonl, .yaml, .yml,
+            .csv) under a docs folder                                 -> None
+        git commit, a .py file under a docs folder                    -> DENY_REASON
         git commit after a verify Skill call or a /verify prompt      -> None
         git commit in a repository with no verify skill directory     -> None
         transcript missing or unreadable, or git fails                -> None

package/hooks/features/conduct-gates.md

@@ -18,7 +18,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
 - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
-- `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, or test files.
+- `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call whose result comes back without an error, or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, test files, or `.json`, `.jsonl`, `.yaml`, `.yml`, or `.csv` files under a `docs` folder.
 - `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
 - `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes. It also denies a pull request open, through `gh pr create`, `pull_request.py create` or a `create_pull_request` tool, until a pass recorded as `merge_review_receipt.py <owner/name> open <head> 0` covers the head the pull request opens with. A merge pinned to that same head passes on the open receipt.
 - `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
@@ -68,7 +68,7 @@ Preconditions:
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
-- **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a tests-only commit, and a repository with no verify skill pass.
+- **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a commit of data files under a `docs` folder, a tests-only commit, and a repository with no verify skill pass. A `.py` file under `docs` and a `.json` file outside `docs` still deny.
 - **Eval write.** Input is a Write to `evals/cases.json` with no build-eval call in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_build_eval_before_eval_write_gate.py -q`. The adjacent test observes a denial, then an allow once the call appears; a write outside an eval path passes.
 - **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass. An open with no clean open receipt at its head is denied; an open reviewed clean at its head, and a merge pinned to that head, pass.
 - **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review pass.

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/hooks_constants/verify_before_commit_gate_constants.py

@@ -3,7 +3,7 @@
 DENY_REASON = (
     "This repository has a verify skill, and this commit changes code. Invoke the verify "
     "skill with the Skill tool, run the check it routes you to, then run the same command again. "
-    "A commit that changes only docs or tests passes without it."
+    "A commit that changes only docs, data files under a docs folder, or tests passes without it."
 )
 SKILL_NAME = "verify"
 ALL_SLASH_COMMAND_MARKERS = ("<command-name>/verify</command-name>",)
@@ -47,6 +47,8 @@ ALL_DOCS_EXTENSIONS = frozenset(
         ".ico",
     }
 )
+ALL_DOCS_DIRECTORY_NAMES = frozenset({"docs"})
+ALL_DOCS_DATA_EXTENSIONS = frozenset({".json", ".jsonl", ".yaml", ".yml", ".csv"})
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests", "test", "__tests__"})
 ALL_TEST_FILE_PREFIXES = ("test_",)
 ALL_TEST_FILE_SUFFIXES = ("_test.py",)

package/hooks/test_transcript_skill_scan.py

@@ -18,9 +18,14 @@ from transcript_skill_scan import (
 )
 
 
-def _skill_entry(name: str) -> str:
+def _skill_entry(name: str, tool_use_id: str = "toolu_skill") -> str:
     return json.dumps(
-        {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": name}}]}}
+        {
+            "type": "assistant",
+            "message": {
+                "content": [{"type": "tool_use", "id": tool_use_id, "name": "Skill", "input": {"skill": name}}]
+            },
+        }
     )
 
 
@@ -144,12 +149,40 @@ def _prompt_entry(content: object) -> str:
 
 
 def test_skill_since_last_prompt_survives_tool_results_and_skill_bodies() -> None:
-    tool_result = _prompt_entry([{"type": "tool_result", "content": "Launching skill: verify"}])
+    tool_result = _prompt_entry(
+        [{"type": "tool_result", "tool_use_id": "toolu_skill", "content": "Launching skill: verify"}]
+    )
     skill_body = json.dumps({"type": "user", "isMeta": True, "message": {"content": "Base directory for this skill"}})
     lines = [_prompt_entry("Commit it."), _skill_entry("verify"), tool_result, skill_body]
     assert is_skill_loaded_since_last_prompt(lines, ("verify",), ())
 
 
+def test_refused_skill_load_leaves_the_skill_unloaded() -> None:
+    refused_result = _prompt_entry(
+        [
+            {
+                "type": "tool_result",
+                "tool_use_id": "toolu_skill",
+                "content": "<tool_use_error>Skill verify cannot be used with Skill tool</tool_use_error>",
+                "is_error": True,
+            }
+        ]
+    )
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify"), refused_result]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
+def test_skill_call_with_no_result_yet_leaves_the_skill_unloaded() -> None:
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify")]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
+def test_result_for_another_call_leaves_the_skill_unloaded() -> None:
+    other_result = _prompt_entry([{"type": "tool_result", "tool_use_id": "toolu_other", "content": "done"}])
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify"), other_result]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
 def test_next_prompt_drops_a_skill_loaded_in_the_last_turn() -> None:
     lines = [_prompt_entry("First."), _skill_entry("verify"), _prompt_entry([{"type": "text", "text": "Second."}])]
     assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())

package/hooks/transcript_skill_scan.py

@@ -44,6 +44,17 @@ def _named_skill_inputs(
     all_entry_fields: dict[str, object],
     skill_names: Collection[str],
     accepts_plugin_prefix: bool = True,
+) -> Iterator[dict[str, object]]:
+    for each_block in _named_skill_blocks(all_entry_fields, skill_names, accepts_plugin_prefix):
+        skill_input = each_block["input"]
+        if isinstance(skill_input, dict):
+            yield skill_input
+
+
+def _named_skill_blocks(
+    all_entry_fields: dict[str, object],
+    skill_names: Collection[str],
+    accepts_plugin_prefix: bool = True,
 ) -> Iterator[dict[str, object]]:
     message = all_entry_fields.get("message")
     if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(message, dict):
@@ -61,7 +72,7 @@ def _named_skill_inputs(
             invoked_name == name or (accepts_plugin_prefix and invoked_name.endswith(":" + name))
             for name in skill_names
         ):
-            yield each_block["input"]
+            yield each_block
 
 
 def _invokes_skill(
@@ -183,11 +194,15 @@ def is_skill_loaded_since_last_prompt(
     ::
 
         prompt, Skill verify, tool result, skill body   -> True
+        prompt, Skill verify, tool result with is_error -> False
+        prompt, Skill verify, no tool result yet        -> False
         prompt, Skill verify, prompt                    -> False
         prompt carrying the /verify command marker      -> True
         prompt with the marker, compact boundary        -> False
 
-    A tool result and a meta entry, such as the skill body, leave the turn open.
+    A Skill call counts once its tool result comes back without an error, so a
+    refused load leaves the skill unloaded. A tool result and a meta entry, such
+    as the skill body, leave the turn open.
 
     Args:
         all_transcript_lines: JSON transcript entries, one per line.
@@ -195,13 +210,23 @@ def is_skill_loaded_since_last_prompt(
         slash_command_markers: Accepted user command tags.
     """
     loaded = False
+    all_pending_ids: set[object] = set()
     for each_line in all_transcript_lines:
         all_entry_fields = _parsed_entry(each_line)
         if all_entry_fields is None:
             continue
         if all_entry_fields.get("subtype") == COMPACT_BOUNDARY_SUBTYPE or _is_user_prompt(all_entry_fields):
             loaded = False
-        loaded = loaded or _invokes_skill(all_entry_fields, skill_names, slash_command_markers)
+            all_pending_ids = set()
+        command_text = _user_command_text(all_entry_fields)
+        if command_text is not None:
+            loaded = loaded or any(marker in command_text for marker in slash_command_markers)
+        all_pending_ids.update(
+            each_block["id"]
+            for each_block in _named_skill_blocks(all_entry_fields, skill_names)
+            if each_block.get("id") is not None
+        )
+        loaded = loaded or bool(all_pending_ids & _succeeded_result_ids(all_entry_fields))
     return loaded
 
 

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.0",
+    "version": "8.101.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {