claude-dev-env 8.96.7 → 8.97.0

package/hooks/plugin_session_baseline.py

@@ -0,0 +1,190 @@
+"""Per-session baseline of the installed plugins, read against the live plugin record.
+
+The SessionStart baseline writer records each plugin's ``version`` and
+``installPath`` from ``installed_plugins.json`` into one JSON file per session
+in the system temp folder. The UserPromptSubmit warning hook reads the same
+file back, compares it with the live record, and lists the plugin ids it has
+already warned about under ``warned``::
+
+    plugin-session-baseline-<session id>.json
+    {"plugins": {"pstack@pstack-claude": [{"version": "1.0.0",
+      "installPath": "/cache/pstack/1.0.0"}]}, "warned": []}
+
+Fields such as ``lastUpdated`` stay out of the snapshot, so a refresh that
+changes nothing a session loads reads as unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from atomic_file_writer import write_text_atomically
+from hooks_constants.atomic_file_writer_constants import ATOMIC_WRITE_TEMPORARY_SUFFIX
+from hooks_constants.plugin_session_baseline_constants import (
+    BASELINE_PLUGINS_KEY,
+    BASELINE_RECORD_FILE_TEMPLATE,
+    BASELINE_RECORD_TEMPORARY_PREFIX,
+    BASELINE_TEXT_ENCODING,
+    BASELINE_WARNED_KEY,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
+    INSTALLED_PLUGINS_FILE_NAME,
+    INSTALLED_PLUGINS_RECORD_KEY,
+    INSTALL_PATH_FIELD,
+    PLUGINS_DIRECTORY_NAME,
+    VERSION_FIELD,
+)
+from hooks_constants.session_file_id import session_file_id
+from json_file_reader import read_json_object
+
+__all__ = [
+    "all_changed_plugin_ids",
+    "baseline_record_path",
+    "current_plugin_snapshot",
+    "installed_plugins_path",
+    "read_baseline_record",
+    "write_baseline_record",
+]
+
+PluginSnapshot = dict[str, list[dict[str, str]]]
+
+
+def installed_plugins_path() -> Path:
+    """Return the installed plugin record under the active Claude config directory."""
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
+    config_directory = (
+        Path(configured_directory)
+        if configured_directory
+        else Path.home() / DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME
+    )
+    return config_directory / PLUGINS_DIRECTORY_NAME / INSTALLED_PLUGINS_FILE_NAME
+
+
+def _loaded_fields(each_entry: object) -> dict[str, str] | None:
+    if not isinstance(each_entry, dict):
+        return None
+    version = each_entry.get(VERSION_FIELD)
+    install_path = each_entry.get(INSTALL_PATH_FIELD)
+    if not isinstance(version, str) or not isinstance(install_path, str):
+        return None
+    return {VERSION_FIELD: version, INSTALL_PATH_FIELD: install_path}
+
+
+def _sorted_entries(all_entries: list[dict[str, str]]) -> list[dict[str, str]]:
+    return sorted(
+        all_entries,
+        key=lambda each_entry: (
+            each_entry[INSTALL_PATH_FIELD],
+            each_entry[VERSION_FIELD],
+        ),
+    )
+
+
+def current_plugin_snapshot(record_path: Path) -> PluginSnapshot:
+    """Return each plugin id with the version and install path of each of its installs.
+
+    A missing, unreadable, or malformed record reads as no plugins.
+
+    Args:
+        record_path: The ``installed_plugins.json`` path.
+    """
+    installed_record = read_json_object(record_path, BASELINE_TEXT_ENCODING)
+    if installed_record is None:
+        return {}
+    all_plugins = installed_record.get(INSTALLED_PLUGINS_RECORD_KEY)
+    if not isinstance(all_plugins, dict):
+        return {}
+    snapshot: PluginSnapshot = {}
+    for each_plugin_id, each_plugin_entries in all_plugins.items():
+        if not isinstance(each_plugin_entries, list):
+            continue
+        all_loaded_entries = [
+            loaded_entry
+            for loaded_entry in (
+                _loaded_fields(each_entry) for each_entry in each_plugin_entries
+            )
+            if loaded_entry is not None
+        ]
+        snapshot[str(each_plugin_id)] = _sorted_entries(all_loaded_entries)
+    return snapshot
+
+
+def baseline_record_path(session_id: object) -> Path:
+    """Return the baseline file path for one session.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+    """
+    file_name = BASELINE_RECORD_FILE_TEMPLATE.format(
+        session_file_id=session_file_id(session_id)
+    )
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def read_baseline_record(session_id: object) -> dict[str, object] | None:
+    """Return the session's baseline record, or None when none is readable.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+    """
+    baseline_record = read_json_object(
+        baseline_record_path(session_id), BASELINE_TEXT_ENCODING
+    )
+    if baseline_record is None:
+        return None
+    if not isinstance(baseline_record.get(BASELINE_PLUGINS_KEY), dict):
+        return None
+    if not isinstance(baseline_record.get(BASELINE_WARNED_KEY), list):
+        return None
+    return baseline_record
+
+
+def write_baseline_record(
+    session_id: object, snapshot: PluginSnapshot, all_warned_plugin_ids: list[str]
+) -> None:
+    """Replace the session's baseline record.
+
+    A write that fails leaves the file as it was, so the hook never fails the session.
+
+    Args:
+        session_id: The ``session_id`` field of the hook payload.
+        snapshot: The plugin snapshot the session loaded at start.
+        all_warned_plugin_ids: The plugin ids already named in a warning.
+    """
+    serialized_record = json.dumps(
+        {
+            BASELINE_PLUGINS_KEY: snapshot,
+            BASELINE_WARNED_KEY: sorted(all_warned_plugin_ids),
+        }
+    )
+    try:
+        write_text_atomically(
+            baseline_record_path(session_id),
+            serialized_record,
+            BASELINE_TEXT_ENCODING,
+            BASELINE_RECORD_TEMPORARY_PREFIX,
+            ATOMIC_WRITE_TEMPORARY_SUFFIX,
+            False,
+        )
+    except (OSError, UnicodeError):
+        return
+
+
+def all_changed_plugin_ids(
+    baseline_snapshot: object, current_snapshot: PluginSnapshot
+) -> list[str]:
+    """Return each plugin id whose installs differ from the baseline, or that the baseline lacks.
+
+    Args:
+        baseline_snapshot: The ``plugins`` value of the baseline record.
+        current_snapshot: The live snapshot from ``current_plugin_snapshot``.
+    """
+    known_snapshot = baseline_snapshot if isinstance(baseline_snapshot, dict) else {}
+    return sorted(
+        each_plugin_id
+        for each_plugin_id, each_plugin_entries in current_snapshot.items()
+        if known_snapshot.get(each_plugin_id) != each_plugin_entries
+    )

package/hooks/session/plugin_change_warning.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: tell the user to restart when a plugin changed after start.
+
+A running Claude Code session keeps the plugin files it loaded at start. After
+an install or update, ``installed_plugins.json`` names a new ``version`` or
+``installPath``, or a plugin the session never loaded, and its new skills and
+commands stay unavailable until a restart. The hook compares the live record
+with the baseline that ``plugin_session_baseline_writer.py`` wrote at
+SessionStart and names each changed plugin once per session, in a
+``systemMessage`` for the user and in ``additionalContext`` for the agent.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.plugin_session_baseline_constants import (
+    BASELINE_PLUGINS_KEY,
+    BASELINE_WARNED_KEY,
+    PLUGIN_CHANGE_WARNING_TEMPLATE,
+    PLUGIN_ID_SEPARATOR,
+    SESSION_ID_FIELD,
+    USER_PROMPT_SUBMIT_EVENT_NAME,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from plugin_session_baseline import (
+    all_changed_plugin_ids,
+    current_plugin_snapshot,
+    installed_plugins_path,
+    read_baseline_record,
+    write_baseline_record,
+)
+
+
+def plugin_change_output(all_plugin_ids: list[str]) -> dict[str, object]:
+    """Return the hook output that names each changed plugin and asks for a restart.
+
+    Args:
+        all_plugin_ids: The plugin ids to name, in order.
+    """
+    warning_text = PLUGIN_CHANGE_WARNING_TEMPLATE.format(
+        plugin_ids=PLUGIN_ID_SEPARATOR.join(all_plugin_ids)
+    )
+    return {
+        "systemMessage": warning_text,
+        "hookSpecificOutput": {
+            "hookEventName": USER_PROMPT_SUBMIT_EVENT_NAME,
+            "additionalContext": warning_text,
+        },
+    }
+
+
+def main() -> None:
+    """Warn once per plugin when the live plugin record differs from the session baseline."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    session_id = hook_payload.get(SESSION_ID_FIELD)
+    if not isinstance(session_id, str) or not session_id:
+        return
+    baseline_record = read_baseline_record(session_id)
+    if baseline_record is None:
+        return
+    baseline_snapshot = baseline_record[BASELINE_PLUGINS_KEY]
+    all_warned_plugin_ids = [
+        str(each_plugin_id) for each_plugin_id in baseline_record[BASELINE_WARNED_KEY]
+    ]
+    all_new_plugin_ids = [
+        each_plugin_id
+        for each_plugin_id in all_changed_plugin_ids(
+            baseline_snapshot, current_plugin_snapshot(installed_plugins_path())
+        )
+        if each_plugin_id not in all_warned_plugin_ids
+    ]
+    if not all_new_plugin_ids:
+        return
+    write_baseline_record(
+        session_id, baseline_snapshot, [*all_warned_plugin_ids, *all_new_plugin_ids]
+    )
+    sys.stdout.write(json.dumps(plugin_change_output(all_new_plugin_ids)) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/plugin_session_baseline_writer.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""SessionStart hook: record the plugin versions this session loads at start.
+
+On ``startup``, and on any source when the session has no baseline yet, the
+hook writes each plugin's ``version`` and ``installPath`` from
+``installed_plugins.json`` to the session's baseline file. On ``resume``,
+``clear``, and ``compact`` it leaves an existing baseline alone, because the
+session keeps the plugin files it loaded at its first start. The
+UserPromptSubmit hook ``plugin_change_warning.py`` compares against this file.
+The hook prints nothing.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.plugin_session_baseline_constants import (
+    SESSION_ID_FIELD,
+    SESSION_SOURCE_FIELD,
+    STARTUP_SOURCE,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from plugin_session_baseline import (
+    current_plugin_snapshot,
+    installed_plugins_path,
+    read_baseline_record,
+    write_baseline_record,
+)
+
+
+def main() -> None:
+    """Write the session's plugin baseline on startup or when none exists yet."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    session_id = hook_payload.get(SESSION_ID_FIELD)
+    if not isinstance(session_id, str) or not session_id:
+        return
+    is_startup = hook_payload.get(SESSION_SOURCE_FIELD) == STARTUP_SOURCE
+    if not is_startup and read_baseline_record(session_id) is not None:
+        return
+    write_baseline_record(
+        session_id, current_plugin_snapshot(installed_plugins_path()), []
+    )
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_plugin_change_warning.py

@@ -0,0 +1,216 @@
+"""Tests for plugin_change_warning: the UserPromptSubmit plugin restart warning."""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import plugin_change_warning
+import plugin_session_baseline
+import plugin_session_baseline_writer
+
+SESSION_ID = "session-two"
+DEEPSTACK_ID = "deepstack@deepstack"
+PSTACK_ID = "pstack@pstack-claude"
+
+
+def _plugin_entry(version: str, install_path: str, last_updated: str) -> dict[str, str]:
+    return {
+        "scope": "user",
+        "installPath": install_path,
+        "version": version,
+        "installedAt": "2026-10-21T19:00:00.000Z",
+        "lastUpdated": last_updated,
+    }
+
+
+def write_installed_plugins(
+    config_directory: Path, all_plugins: dict[str, list[dict[str, str]]]
+) -> None:
+    plugins_directory = config_directory / "plugins"
+    plugins_directory.mkdir(parents=True, exist_ok=True)
+    (plugins_directory / "installed_plugins.json").write_text(
+        json.dumps({"version": 2, "plugins": all_plugins}), encoding="utf-8"
+    )
+
+
+def _run_main(main_function: object, payload: dict[str, str]) -> str:
+    payload_bytes = json.dumps(payload).encode("utf-8")
+    captured_stdout = io.StringIO()
+    with (
+        patch("sys.stdin", io.TextIOWrapper(io.BytesIO(payload_bytes))),
+        patch("sys.stdout", captured_stdout),
+    ):
+        main_function()
+    return captured_stdout.getvalue()
+
+
+def start_session(source: str) -> None:
+    _run_main(
+        plugin_session_baseline_writer.main,
+        {"session_id": SESSION_ID, "hook_event_name": "SessionStart", "source": source},
+    )
+
+
+def submit_prompt() -> dict[str, object] | None:
+    hook_output = _run_main(
+        plugin_change_warning.main,
+        {
+            "session_id": SESSION_ID,
+            "hook_event_name": "UserPromptSubmit",
+            "prompt": "run /deepstack-mode",
+        },
+    )
+    return json.loads(hook_output) if hook_output else None
+
+
+@pytest.fixture
+def config_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    claude_config_directory = tmp_path / "config"
+    state_directory = tmp_path / "state"
+    state_directory.mkdir()
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(claude_config_directory))
+    monkeypatch.setattr(
+        plugin_session_baseline.tempfile, "gettempdir", lambda: str(state_directory)
+    )
+    return claude_config_directory
+
+
+def _warning_text(hook_output: dict[str, object] | None) -> str:
+    assert hook_output is not None
+    system_message = hook_output["systemMessage"]
+    assert isinstance(system_message, str)
+    hook_specific_output = hook_output["hookSpecificOutput"]
+    assert isinstance(hook_specific_output, dict)
+    assert hook_specific_output["hookEventName"] == "UserPromptSubmit"
+    assert hook_specific_output["additionalContext"] == system_message
+    return system_message
+
+
+def test_a_changed_version_should_warn_once(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")]},
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.1.0", "/cache/pstack/1.1.0", "b")]},
+    )
+    warning_text = _warning_text(submit_prompt())
+    assert PSTACK_ID in warning_text
+    assert "Restart Claude Code" in warning_text
+    assert submit_prompt() is None
+
+
+def test_a_plugin_new_since_start_should_warn(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")]},
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {
+            PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")],
+            DEEPSTACK_ID: [_plugin_entry("3.0.0", "/cache/deepstack/3.0.0", "b")],
+        },
+    )
+    warning_text = _warning_text(submit_prompt())
+    assert DEEPSTACK_ID in warning_text
+    assert PSTACK_ID not in warning_text
+
+
+def test_a_changed_install_path_should_warn(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/old", "a")]},
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/new", "a")]},
+    )
+    assert PSTACK_ID in _warning_text(submit_prompt())
+
+
+def test_a_bare_last_updated_refresh_should_stay_quiet(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")]},
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "later")]},
+    )
+    assert submit_prompt() is None
+
+
+def test_an_install_then_compact_then_prompt_should_still_warn(
+    config_directory: Path,
+) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")]},
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {
+            PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")],
+            DEEPSTACK_ID: [_plugin_entry("3.0.0", "/cache/deepstack/3.0.0", "b")],
+        },
+    )
+    start_session("compact")
+    assert DEEPSTACK_ID in _warning_text(submit_prompt())
+
+
+def test_a_second_plugin_change_should_warn_only_for_that_plugin(
+    config_directory: Path,
+) -> None:
+    write_installed_plugins(
+        config_directory,
+        {
+            PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")],
+            DEEPSTACK_ID: [_plugin_entry("3.0.0", "/cache/deepstack/3.0.0", "a")],
+        },
+    )
+    start_session("startup")
+    write_installed_plugins(
+        config_directory,
+        {
+            PSTACK_ID: [_plugin_entry("1.1.0", "/cache/pstack/1.1.0", "b")],
+            DEEPSTACK_ID: [_plugin_entry("3.0.0", "/cache/deepstack/3.0.0", "a")],
+        },
+    )
+    assert PSTACK_ID in _warning_text(submit_prompt())
+    write_installed_plugins(
+        config_directory,
+        {
+            PSTACK_ID: [_plugin_entry("1.2.0", "/cache/pstack/1.2.0", "c")],
+            DEEPSTACK_ID: [_plugin_entry("3.1.0", "/cache/deepstack/3.1.0", "c")],
+        },
+    )
+    second_warning_text = _warning_text(submit_prompt())
+    assert DEEPSTACK_ID in second_warning_text
+    assert PSTACK_ID not in second_warning_text
+
+
+def test_a_session_without_a_baseline_should_stay_quiet(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PSTACK_ID: [_plugin_entry("1.0.0", "/cache/pstack/1.0.0", "a")]},
+    )
+    assert submit_prompt() is None

package/hooks/session/test_plugin_session_baseline_writer.py

@@ -0,0 +1,136 @@
+"""Tests for plugin_session_baseline_writer: the SessionStart plugin baseline hook."""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import plugin_session_baseline
+import plugin_session_baseline_writer
+
+SESSION_ID = "session-one"
+PLUGIN_ID = "deepstack@deepstack"
+
+
+def _plugin_entry(version: str, install_path: str, last_updated: str) -> dict[str, str]:
+    return {
+        "scope": "user",
+        "installPath": install_path,
+        "version": version,
+        "installedAt": "2026-10-21T19:00:00.000Z",
+        "lastUpdated": last_updated,
+    }
+
+
+def write_installed_plugins(
+    config_directory: Path, all_plugins: dict[str, list[dict[str, str]]]
+) -> None:
+    plugins_directory = config_directory / "plugins"
+    plugins_directory.mkdir(parents=True, exist_ok=True)
+    (plugins_directory / "installed_plugins.json").write_text(
+        json.dumps({"version": 2, "plugins": all_plugins}), encoding="utf-8"
+    )
+
+
+def run_writer(session_id: str, source: str) -> str:
+    payload_text = json.dumps(
+        {"session_id": session_id, "hook_event_name": "SessionStart", "source": source}
+    )
+    captured_stdout = io.StringIO()
+    with (
+        patch("sys.stdin", io.TextIOWrapper(io.BytesIO(payload_text.encode("utf-8")))),
+        patch("sys.stdout", captured_stdout),
+    ):
+        plugin_session_baseline_writer.main()
+    return captured_stdout.getvalue()
+
+
+@pytest.fixture
+def config_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    claude_config_directory = tmp_path / "config"
+    state_directory = tmp_path / "state"
+    state_directory.mkdir()
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(claude_config_directory))
+    monkeypatch.setattr(
+        plugin_session_baseline.tempfile, "gettempdir", lambda: str(state_directory)
+    )
+    return claude_config_directory
+
+
+def test_startup_should_record_each_plugin_version_and_install_path(
+    config_directory: Path,
+) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PLUGIN_ID: [_plugin_entry("1.0.0", "/cache/deepstack/1.0.0", "a")]},
+    )
+    assert run_writer(SESSION_ID, "startup") == ""
+    baseline_record = plugin_session_baseline.read_baseline_record(SESSION_ID)
+    assert baseline_record == {
+        "plugins": {
+            PLUGIN_ID: [{"version": "1.0.0", "installPath": "/cache/deepstack/1.0.0"}]
+        },
+        "warned": [],
+    }
+
+
+@pytest.mark.parametrize("source", ["resume", "clear", "compact"])
+def test_a_later_source_should_leave_an_existing_baseline_alone(
+    config_directory: Path, source: str
+) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PLUGIN_ID: [_plugin_entry("1.0.0", "/cache/deepstack/1.0.0", "a")]},
+    )
+    run_writer(SESSION_ID, "startup")
+    baseline_path = plugin_session_baseline.baseline_record_path(SESSION_ID)
+    baseline_text = baseline_path.read_text(encoding="utf-8")
+    write_installed_plugins(
+        config_directory,
+        {PLUGIN_ID: [_plugin_entry("2.0.0", "/cache/deepstack/2.0.0", "b")]},
+    )
+    run_writer(SESSION_ID, source)
+    assert baseline_path.read_text(encoding="utf-8") == baseline_text
+
+
+def test_resume_without_a_baseline_should_write_one(config_directory: Path) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PLUGIN_ID: [_plugin_entry("1.0.0", "/cache/deepstack/1.0.0", "a")]},
+    )
+    run_writer(SESSION_ID, "resume")
+    baseline_record = plugin_session_baseline.read_baseline_record(SESSION_ID)
+    assert baseline_record is not None
+    assert PLUGIN_ID in baseline_record["plugins"]
+
+
+def test_a_payload_without_a_session_id_should_write_nothing(
+    config_directory: Path, tmp_path: Path
+) -> None:
+    write_installed_plugins(
+        config_directory,
+        {PLUGIN_ID: [_plugin_entry("1.0.0", "/cache/deepstack/1.0.0", "a")]},
+    )
+    run_writer("", "startup")
+    assert list((tmp_path / "state").iterdir()) == []
+
+
+def test_a_missing_installed_plugins_file_should_record_an_empty_baseline(
+    config_directory: Path,
+) -> None:
+    run_writer(SESSION_ID, "startup")
+    assert plugin_session_baseline.read_baseline_record(SESSION_ID) == {
+        "plugins": {},
+        "warned": [],
+    }

package/hooks/test_context_budget_hooks.py

@@ -29,6 +29,8 @@ UNMEASURED_REASON_BY_SCRIPT = {
     "routing/thread_spawn_pace_hook.py": "quotes a usage reading capped by its own constant",
     "session/issue_tracker_session_starter.py": "emits only for a repository the user's "
     "project registry names by absolute path",
+    "session/plugin_change_warning.py": "emits only after a plugin changes on disk mid-session, "
+    "once per plugin, naming plugin ids",
 }