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

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps every SendUserFile path under the session's working directory.
+
+The desktop file pane resolves a sent file only under the session's root
+folder, the ``cwd`` in the hook payload. A file elsewhere, such as a network
+share or the session scratchpad, passes SendUserFile's own check and then shows
+"Couldn't find this file" to the user::
+
+    SendUserFile {"files": ["<cwd>\\.scratch\\a.md"]}        -> allowed
+    SendUserFile {"files": ["Y:\\share\\a.md"]}               -> denied
+    SendUserFile {"files": ["<cwd>\\..\\other\\a.md"]}        -> denied
+    a relative path                                         -> joined to cwd
+    no cwd, no files list, or another tool                  -> allowed
+
+Paths compare case-insensitively with Windows rules when ``cwd`` is a Windows
+path, and with POSIX rules otherwise. The deny reason lists each outside file
+and names ``<cwd>\\.scratch\\`` as the folder to copy it into.
+"""
+
+from __future__ import annotations
+
+import ntpath
+import posixpath
+import sys
+from pathlib import Path
+from types import ModuleType
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.context_budget_constants import CWD_KEY
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.send_user_file_worktree_root_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    FILES_INPUT_KEY,
+    GATE_EVENT_NAME,
+    OFFENDING_INPUT_SEPARATOR,
+    OUTSIDE_ROOT_HEADER,
+    SCRATCH_FOLDER_INSTRUCTION,
+    SCRATCH_FOLDER_NAME,
+    SEND_USER_FILE_TOOL_NAME,
+    WINDOWS_PATH_PATTERN,
+)
+from hooks_constants.spawn_readiness_hook_constants import TOOL_INPUT_KEY, TOOL_NAME_KEY
+
+
+def _path_rules_for(working_directory: str) -> ModuleType:
+    return ntpath if WINDOWS_PATH_PATTERN.match(working_directory) else posixpath
+
+
+def is_under_working_directory(file_path: str, working_directory: str) -> bool:
+    """Return True when the file path names the working directory or a path inside it.
+
+    >>> is_under_working_directory("C:\\\\wt\\\\.scratch\\\\a.md", "c:/WT")
+    True
+    >>> is_under_working_directory("Y:\\\\share\\\\a.md", "C:\\\\wt")
+    False
+
+    Args:
+        file_path: One path from the SendUserFile ``files`` list.
+        working_directory: The session's ``cwd`` from the hook payload.
+
+    Returns:
+        True for the root itself or a path under it after joining and normalizing.
+    """
+    path_rules = _path_rules_for(working_directory)
+    root = path_rules.normcase(path_rules.normpath(working_directory))
+    candidate = path_rules.normcase(
+        path_rules.normpath(path_rules.join(working_directory, file_path))
+    )
+    if candidate == root:
+        return True
+    return candidate.startswith(root.rstrip(path_rules.sep) + path_rules.sep)
+
+
+def outside_files(tool_input: object, working_directory: str) -> list[str]:
+    """Return each SendUserFile path that sits outside the working directory.
+
+    Args:
+        tool_input: The SendUserFile tool input.
+        working_directory: The session's ``cwd`` from the hook payload.
+
+    Returns:
+        The outside paths in call order, or an empty list when no files list is present.
+    """
+    all_files = tool_input.get(FILES_INPUT_KEY) if isinstance(tool_input, dict) else None
+    if not isinstance(all_files, list):
+        return []
+    return [
+        each_file
+        for each_file in all_files
+        if isinstance(each_file, str)
+        and not is_under_working_directory(each_file, working_directory)
+    ]
+
+
+def format_block_reason(all_outside_files: list[str], working_directory: str) -> str:
+    """Return the deny message that lists the outside files and the folder to copy them into.
+
+    Args:
+        all_outside_files: Paths outside the working directory.
+        working_directory: The session's ``cwd`` from the hook payload.
+
+    Returns:
+        The message the session reads when the call is denied.
+    """
+    path_rules = _path_rules_for(working_directory)
+    scratch_folder = path_rules.join(working_directory, SCRATCH_FOLDER_NAME) + path_rules.sep
+    file_lines = "".join(f"- {each_file}\n" for each_file in all_outside_files)
+    return (
+        OUTSIDE_ROOT_HEADER.format(cwd=working_directory)
+        + file_lines
+        + SCRATCH_FOLDER_INSTRUCTION.format(scratch_folder=scratch_folder)
+    )
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None or hook_input.get(TOOL_NAME_KEY) != SEND_USER_FILE_TOOL_NAME:
+        return ALLOW_EXIT_CODE
+    working_directory = hook_input.get(CWD_KEY)
+    if not isinstance(working_directory, str) or not working_directory:
+        return ALLOW_EXIT_CODE
+    all_outside_files = outside_files(hook_input.get(TOOL_INPUT_KEY), working_directory)
+    if not all_outside_files:
+        return ALLOW_EXIT_CODE
+    block_reason = format_block_reason(all_outside_files, working_directory)
+    log_hook_block(
+        Path(__file__).name,
+        GATE_EVENT_NAME,
+        block_reason,
+        tool_name=SEND_USER_FILE_TOOL_NAME,
+        offending_input_preview=OFFENDING_INPUT_SEPARATOR.join(all_outside_files),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_send_user_file_worktree_root_gate.py

@@ -0,0 +1,126 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import send_user_file_worktree_root_gate
+
+WORKTREE_CWD = "C:\\dev\\project\\.claude\\worktrees\\feature-branch"
+SHARE_PATH = "Y:\\shared\\reports\\reflect.md"
+SCRATCHPAD_PATH = "C:\\Users\\example\\AppData\\Local\\Temp\\claude\\scratchpad\\reflect.md"
+SCRATCH_FOLDER_PATH = WORKTREE_CWD + "\\.scratch\\reflect.md"
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    hook_input: dict[str, object],
+) -> tuple[int, str]:
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = send_user_file_worktree_root_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+def send_user_file_input(all_files: object, cwd: object = WORKTREE_CWD) -> dict[str, object]:
+    return {
+        "hook_event_name": "PreToolUse",
+        "tool_name": "SendUserFile",
+        "cwd": cwd,
+        "tool_input": {"files": all_files, "status": "normal", "display": "render"},
+    }
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+@pytest.mark.parametrize("outside_path", [SHARE_PATH, SCRATCHPAD_PATH])
+def test_should_deny_a_file_outside_the_working_directory_and_name_the_scratch_folder(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], outside_path: str
+) -> None:
+    exit_code, block_reason = run_gate(monkeypatch, capsys, send_user_file_input([outside_path]))
+    assert exit_code == 2
+    assert outside_path in block_reason
+    assert WORKTREE_CWD + "\\.scratch\\" in block_reason
+
+
+@pytest.mark.parametrize(
+    "inside_path",
+    [
+        SCRATCH_FOLDER_PATH,
+        SCRATCH_FOLDER_PATH.lower(),
+        SCRATCH_FOLDER_PATH.replace("\\", "/"),
+        ".scratch\\reflect.md",
+        WORKTREE_CWD,
+    ],
+)
+def test_should_allow_a_file_under_the_working_directory(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], inside_path: str
+) -> None:
+    assert run_gate(monkeypatch, capsys, send_user_file_input([inside_path])) == (0, "")
+
+
+def test_should_deny_a_path_that_climbs_out_of_the_working_directory(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    climbing_path = WORKTREE_CWD + "\\.scratch\\..\\..\\other-worktree\\reflect.md"
+    exit_code, block_reason = run_gate(monkeypatch, capsys, send_user_file_input([climbing_path]))
+    assert exit_code == 2
+    assert climbing_path in block_reason
+
+
+def test_should_deny_a_sibling_folder_that_shares_the_working_directory_prefix(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    sibling_path = WORKTREE_CWD + "-copy\\reflect.md"
+    exit_code, block_reason = run_gate(monkeypatch, capsys, send_user_file_input([sibling_path]))
+    assert exit_code == 2
+    assert sibling_path in block_reason
+
+
+def test_should_name_only_the_outside_files_when_a_call_mixes_both(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, block_reason = run_gate(
+        monkeypatch, capsys, send_user_file_input([SCRATCH_FOLDER_PATH, SHARE_PATH])
+    )
+    assert exit_code == 2
+    assert SHARE_PATH in block_reason
+    assert "- " + SCRATCH_FOLDER_PATH not in block_reason
+
+
+def test_should_compare_posix_paths_under_a_posix_working_directory(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    posix_cwd = "/home/user/worktree"
+    assert run_gate(
+        monkeypatch, capsys, send_user_file_input([posix_cwd + "/.scratch/a.md"], posix_cwd)
+    ) == (0, "")
+    exit_code, block_reason = run_gate(
+        monkeypatch, capsys, send_user_file_input(["/tmp/a.md"], posix_cwd)
+    )
+    assert exit_code == 2
+    assert "/tmp/a.md" in block_reason
+
+
+@pytest.mark.parametrize(
+    "hook_input",
+    [
+        send_user_file_input([SHARE_PATH], cwd=None),
+        send_user_file_input([SHARE_PATH], cwd=""),
+        send_user_file_input(None),
+        send_user_file_input(SHARE_PATH),
+        {**send_user_file_input([SHARE_PATH]), "tool_name": "Read"},
+    ],
+)
+def test_should_allow_a_call_the_gate_cannot_judge(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    hook_input: dict[str, object],
+) -> None:
+    assert run_gate(monkeypatch, capsys, hook_input) == (0, "")

package/hooks/features/conduct-gates.md

@@ -20,6 +20,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `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.
 - `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.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
+- `blocking/send_user_file_worktree_root_gate.py` denies a `SendUserFile` call that names a file outside the session's working directory, the `cwd` in the hook payload. The desktop file pane opens a sent file only under that folder and shows "Couldn't find this file" for any other path. The reason lists each outside file and names `<cwd>\.scratch\` as the folder to copy it into.
 
 ## When it fires
 
@@ -39,6 +40,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
 - `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
+- `blocking/send_user_file_worktree_root_gate.py` runs on `PreToolUse`, matcher `SendUserFile`, timeout `10` seconds in `hooks.json`.
 
 ## Proving it
 
@@ -62,6 +64,7 @@ Preconditions:
 - **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.
 - **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.
 - **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
+- **Sent file root.** Input is a `SendUserFile` call for a file on `Y:\` or in the session scratchpad, with `cwd` set to a worktree. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_send_user_file_worktree_root_gate.py -q`. The adjacent test observes a denial that names the file and `<cwd>\.scratch\`; a file under `<cwd>\.scratch\` passes.
 
 ## Gotchas
 

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

@@ -214,6 +214,16 @@
           }
         ]
       },
+      {
+        "matcher": "SendUserFile",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/send_user_file_worktree_root_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Artifact|Skill",
         "hooks": [
@@ -303,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
           }
         ]
       }
@@ -346,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/hooks_constants/send_user_file_worktree_root_gate_constants.py

@@ -0,0 +1,36 @@
+"""Names and messages for the send_user_file_worktree_root_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "ALLOW_EXIT_CODE",
+    "BLOCK_EXIT_CODE",
+    "FILES_INPUT_KEY",
+    "GATE_EVENT_NAME",
+    "OFFENDING_INPUT_SEPARATOR",
+    "OUTSIDE_ROOT_HEADER",
+    "SCRATCH_FOLDER_NAME",
+    "SCRATCH_FOLDER_INSTRUCTION",
+    "SEND_USER_FILE_TOOL_NAME",
+    "WINDOWS_PATH_PATTERN",
+]
+
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+SEND_USER_FILE_TOOL_NAME = "SendUserFile"
+FILES_INPUT_KEY = "files"
+GATE_EVENT_NAME = "PreToolUse"
+OFFENDING_INPUT_SEPARATOR = ", "
+SCRATCH_FOLDER_NAME = ".scratch"
+WINDOWS_PATH_PATTERN = re.compile(r"^(?:[A-Za-z]:|\\\\)")
+OUTSIDE_ROOT_HEADER = (
+    "The desktop file pane opens a sent file only when it sits under this session's"
+    " working directory, {cwd}. These files are outside it, so the user sees"
+    ' "Couldn\'t find this file":\n'
+)
+SCRATCH_FOLDER_INSTRUCTION = (
+    "\nCopy each file into {scratch_folder} and call SendUserFile with the copied paths."
+    " If git does not ignore that folder, add .scratch/ to .git/info/exclude first."
+)