claude-dev-env 8.96.7 → 8.96.8

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/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": [

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."
+)

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -136,6 +136,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/verify_before_acting.py           -> exempt
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/artifact_dark_mode_gate.py        -> exempt
+        hooks/blocking/send_user_file_worktree_root_gate.py -> exempt
         hooks/blocking/build_eval_before_eval_write_gate.py -> exempt
         hooks/blocking/merge_over_review_offer_gate.py   -> exempt
         hooks/blocking/final_reply_gate.py               -> exempt
@@ -174,6 +175,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     The artifact page gate denies a page publish whose text is unreadable in
     dark mode. It decides how a page renders and no code or safety policy.
 
+    The send user file gate denies a SendUserFile path outside the session's
+    working directory, which the desktop file pane cannot open. It decides
+    where a sent file sits and no code or safety policy.
+
     The eval write gate denies a write to an eval file until the session
     invokes ``/claude-api build-eval``. It holds eval writes until a skill
     loads, and it judges no code or safety content.

package/scripts/policy_lint/config/constants.py

@@ -74,6 +74,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/session_title_format_gate.py",
     "blocking/image_read_size_gate.py",
     "blocking/artifact_dark_mode_gate.py",
+    "blocking/send_user_file_worktree_root_gate.py",
     "blocking/haiku_spawn_slim_gate.py",
     "blocking/build_eval_before_eval_write_gate.py",
     "blocking/merge_over_review_offer_gate.py",

package/scripts/tests/test_adapter_configuration.py

@@ -154,6 +154,14 @@ def test_new_artifact_page_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_send_user_file_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/send_user_file_worktree_root_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_eval_write_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/build_eval_before_eval_write_gate.py"],