claude-dev-env 8.96.8 → 8.97.0

package/bin/install-pstack-plugin.mjs

@@ -318,6 +318,23 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
     return { host, executable, status: 'installed', warning: null };
 }
 
+/**
+ * Build the notice that tells the user to restart each session the install reached.
+ *
+ * A running Claude Code or Codex session keeps the plugin files it loaded at
+ * start, so a plugin installed or updated under it stays unavailable there
+ * until the session restarts.
+ *
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins the install wrote.
+ * @param {ReadonlyArray<string>} allInstalledHosts The hosts the install reached.
+ * @returns {string} The restart notice.
+ */
+export function restartNotice(allSpecs, allInstalledHosts) {
+    const pluginLabels = allSpecs.map(eachSpec => eachSpec.label).join(', ');
+    return `Restart each open ${allInstalledHosts.join(' and ')} session to load ${pluginLabels}. `
+        + 'A running session keeps the plugin version it loaded at start.';
+}
+
 /**
  * Install a set of plugins from one marketplace into each host's own home.
  *
@@ -334,7 +351,9 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
  * skipped. When a host cannot replace a plugin folder because something holds
  * it, the warning names each process that holds it, so the user knows what to
- * close before running the install again.
+ * close before running the install again. When any host installs, the step
+ * prints one restart notice, because an open session keeps the plugin
+ * version it loaded at start.
  *
  * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
@@ -342,8 +361,8 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
  * @param {string} [options.codexHome] The Codex home to install into.
  * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
- * @param {object} [dependencies] Seams for the command runner and the folder locker search.
- * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
+ * @param {object} [dependencies] Seams for the command runner, the folder locker search, and the line writer.
+ * @returns {{status: string, hosts: object[], warning: string|null, restartNotice: string|null}} The outcome per host.
  */
 export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
@@ -365,7 +384,15 @@ export function installMarketplacePlugins(allSpecs, options = {}, dependencies =
     const installedCount = hostOutcomes.filter(outcome => outcome.status === 'installed').length;
     const status = failedCount > 0 ? 'failed' : (installedCount > 0 ? 'installed' : 'skipped');
     const warnings = hostOutcomes.map(outcome => outcome.warning).filter(Boolean);
-    return { status, hosts: hostOutcomes, warning: warnings.join(' ') || null };
+    const allInstalledHosts = hostOutcomes
+        .filter(outcome => outcome.status === 'installed')
+        .map(outcome => outcome.host);
+    const notice = allInstalledHosts.length > 0 ? restartNotice(allSpecs, allInstalledHosts) : null;
+    if (notice) {
+        const writeLine = dependencies.writeLine ?? (line => console.log(line));
+        writeLine(notice);
+    }
+    return { status, hosts: hostOutcomes, warning: warnings.join(' ') || null, restartNotice: notice };
 }
 
 /**

package/bin/install-pstack-plugin.test.mjs

@@ -17,6 +17,7 @@ import {
     removeOrphanedPluginVersions,
     removeStaleMarketplaceClone,
     removeRetiredMarketplacePlugins,
+    restartNotice,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 
@@ -500,3 +501,25 @@ test('should delete a half-made marketplace clone before the shared marketplace
 test('should report no removal when no stale marketplace clone exists', () => {
     assert.equal(removeStaleMarketplaceClone(join(tmpdir(), 'cde-no-such-clone')), false);
 });
+
+test('an install prints one restart notice that names each plugin and host', () => {
+    const allLoggedLines = [];
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        ...recordingRunner(),
+        writeLine: line => allLoggedLines.push(line),
+    });
+    assert.deepEqual(allLoggedLines, [restartNotice([PSTACK_PLUGIN_SPEC], ['claude', 'codex'])]);
+    assert.equal(outcome.restartNotice, allLoggedLines[0]);
+    assert.match(allLoggedLines[0], /Restart each open claude and codex session to load Pstack\./);
+});
+
+test('a run that installs nothing prints no restart notice', () => {
+    const allLoggedLines = [];
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        ...recordingRunner(() => ({ status: null, error: Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' }) })),
+        writeLine: line => allLoggedLines.push(line),
+    });
+    assert.equal(outcome.status, 'skipped');
+    assert.deepEqual(allLoggedLines, []);
+    assert.equal(outcome.restartNotice, null);
+});

package/bin/install.prompt-context.test.mjs

@@ -35,11 +35,12 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
     mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
 
     const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
-    assert.equal(userPromptHooks.length, 4);
+    assert.equal(userPromptHooks.length, 5);
     assert.equal(userPromptHooks[0].command, userCommand);
     assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
     assert.match(userPromptHooks[2].command, /lifecycle\/nested_project_hooks\.py$/);
     assert.match(userPromptHooks[3].command, /blocking\/chat_reply_gate\.py$/);
+    assert.match(userPromptHooks[4].command, /session\/plugin_change_warning\.py$/);
     assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
 
     const firstMerge = JSON.stringify(settings);

package/hooks/features/session-context.md

@@ -10,6 +10,8 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/working_style_prompt.py` injects the session's working style at session start.
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
+- `session/plugin_session_baseline_writer.py` records each plugin's `version` and `installPath` from `installed_plugins.json` to a per-session file in the system temp folder. It writes on `startup`, or when the session has no baseline yet, and leaves an existing baseline alone on `resume`, `clear`, and `compact`.
+- `session/plugin_change_warning.py` compares `installed_plugins.json` with that baseline before each prompt. It names each plugin whose version or install path changed, or that the baseline lacks, once per session, and tells the user to restart Claude Code.
 - `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. A status or progress report prefers the status flowchart from `docs/templates/artifact-page/status-flowchart.html`, unless the person asks for another shape. One flow or one comparison is an inline SVG flowchart with minimal text. A multi-part plan or evidence is an html-plan page from `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
@@ -18,6 +20,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
 - `session/compaction_recall_prompt.py` runs on `SessionStart` matcher `compact` at `10` seconds in `hooks.json`. The installer also writes it to the Codex `hooks.json`, the only `SessionStart` hook Codex gets.
 - `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, and `session/orchestrator_auto_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `session/plugin_session_baseline_writer.py` runs on `SessionStart`, matcher empty, at `10` seconds, so it sees every source. `session/plugin_change_warning.py` runs on `UserPromptSubmit`, matcher empty, at `10` seconds in `hooks.json`.
 - `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
 - `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
 
@@ -33,6 +36,7 @@ Preconditions:
 - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
+- **Plugin restart warning.** Input is a SessionStart event, an `installed_plugins.json` change, and a prompt. Run `python -m pytest packages/claude-dev-env/hooks/session/test_plugin_session_baseline_writer.py packages/claude-dev-env/hooks/session/test_plugin_change_warning.py packages/claude-dev-env/hooks/test_plugin_session_baseline.py -q`. The tests observe one warning for a changed version, a changed install path, and a plugin new since start, silence on a `lastUpdated` refresh and on a second prompt, and a warning that still fires after a `compact` SessionStart.
 - **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 

package/hooks/hooks.json

@@ -313,6 +313,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/chat_reply_gate.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/plugin_change_warning.py",
+            "timeout": 10
           }
         ]
       }
@@ -356,6 +361,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/orchestrator_auto_starter.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/plugin_session_baseline_writer.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",

package/hooks/hooks_constants/plugin_session_baseline_constants.py

@@ -0,0 +1,50 @@
+"""Constants for the plugin session baseline and the plugin change warning hooks."""
+
+from __future__ import annotations
+
+__all__ = [
+    "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",
+    "PLUGIN_CHANGE_WARNING_TEMPLATE",
+    "PLUGIN_ID_SEPARATOR",
+    "SESSION_ID_FIELD",
+    "SESSION_SOURCE_FIELD",
+    "STARTUP_SOURCE",
+    "USER_PROMPT_SUBMIT_EVENT_NAME",
+    "VERSION_FIELD",
+]
+
+CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"
+PLUGINS_DIRECTORY_NAME = "plugins"
+INSTALLED_PLUGINS_FILE_NAME = "installed_plugins.json"
+INSTALLED_PLUGINS_RECORD_KEY = "plugins"
+VERSION_FIELD = "version"
+INSTALL_PATH_FIELD = "installPath"
+
+SESSION_ID_FIELD = "session_id"
+SESSION_SOURCE_FIELD = "source"
+STARTUP_SOURCE = "startup"
+USER_PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
+
+BASELINE_RECORD_FILE_TEMPLATE = "plugin-session-baseline-{session_file_id}.json"
+BASELINE_RECORD_TEMPORARY_PREFIX = "plugin-session-baseline-"
+BASELINE_TEXT_ENCODING = "utf-8"
+BASELINE_PLUGINS_KEY = "plugins"
+BASELINE_WARNED_KEY = "warned"
+
+PLUGIN_ID_SEPARATOR = ", "
+PLUGIN_CHANGE_WARNING_TEMPLATE = (
+    "Plugin files changed after this session started: {plugin_ids}."
+    " This session keeps the plugin versions it loaded at start, so their new skills,"
+    " commands, and hooks stay unavailable here. Restart Claude Code to load them."
+)

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",
 }
 
 

package/hooks/test_plugin_session_baseline.py

@@ -0,0 +1,98 @@
+"""Behavior tests for the plugin session baseline record."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+import plugin_session_baseline
+
+PLUGIN_ID = "pstack@pstack-claude"
+
+
+@pytest.fixture(autouse=True)
+def isolated_temp_folder(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(
+        plugin_session_baseline.tempfile, "gettempdir", lambda: str(tmp_path)
+    )
+
+
+def test_installed_plugins_path_should_follow_the_config_directory(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
+    assert plugin_session_baseline.installed_plugins_path() == (
+        tmp_path / "plugins" / "installed_plugins.json"
+    )
+
+
+def test_baseline_record_path_should_name_the_session_in_the_temp_folder(
+    tmp_path: Path,
+) -> None:
+    assert plugin_session_baseline.baseline_record_path("a/b c") == (
+        tmp_path / "plugin-session-baseline-abc.json"
+    )
+
+
+def test_current_plugin_snapshot_should_keep_only_version_and_install_path(
+    tmp_path: Path,
+) -> None:
+    record_path = tmp_path / "installed_plugins.json"
+    record_path.write_text(
+        json.dumps(
+            {
+                "plugins": {
+                    PLUGIN_ID: [
+                        {
+                            "scope": "user",
+                            "installPath": "/cache/pstack/1.0.0",
+                            "version": "1.0.0",
+                            "lastUpdated": "2026-10-21T21:26:12.000Z",
+                        }
+                    ]
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+    assert plugin_session_baseline.current_plugin_snapshot(record_path) == {
+        PLUGIN_ID: [{"version": "1.0.0", "installPath": "/cache/pstack/1.0.0"}]
+    }
+
+
+def test_current_plugin_snapshot_should_read_a_malformed_record_as_empty(
+    tmp_path: Path,
+) -> None:
+    record_path = tmp_path / "installed_plugins.json"
+    record_path.write_text("{not json", encoding="utf-8")
+    assert plugin_session_baseline.current_plugin_snapshot(record_path) == {}
+
+
+def test_read_baseline_record_should_return_what_the_writer_stored() -> None:
+    snapshot = {PLUGIN_ID: [{"version": "1.0.0", "installPath": "/cache/pstack/1.0.0"}]}
+    plugin_session_baseline.write_baseline_record("session", snapshot, [PLUGIN_ID])
+    assert plugin_session_baseline.read_baseline_record("session") == {
+        "plugins": snapshot,
+        "warned": [PLUGIN_ID],
+    }
+
+
+def test_all_changed_plugin_ids_should_name_changed_and_new_plugins_only() -> None:
+    unchanged_entries = [{"version": "1.0.0", "installPath": "/cache/a/1.0.0"}]
+    baseline_snapshot = {
+        "a@m": unchanged_entries,
+        "b@m": [{"version": "1.0.0", "installPath": "/cache/b/1.0.0"}],
+    }
+    current_snapshot = {
+        "a@m": unchanged_entries,
+        "b@m": [{"version": "2.0.0", "installPath": "/cache/b/2.0.0"}],
+        "c@m": [{"version": "1.0.0", "installPath": "/cache/c/1.0.0"}],
+    }
+    assert plugin_session_baseline.all_changed_plugin_ids(
+        baseline_snapshot, current_snapshot
+    ) == [
+        "b@m",
+        "c@m",
+    ]

package/package.json

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