core/tools: send a deleted path to the system trash

`delete_path` is the only destructive file entry point the agent has, and it
carries `ToolTag.YOLO` — under `--yes` / `/yolo` it runs with no confirmation at
all. A delete is now a move into the desktop's own trash (freedesktop trash on
Linux, Finder trash on macOS, Recycle Bin on Windows) through `send2trash`, so
the human can put the file back with the file manager they already have. The new
`permanent=true` argument is the old behaviour, chosen on purpose.

A trashing that fails is reported, never downgraded to a deletion: the human was
told the path is recoverable, so a volume with no writable trash directory
leaves the file where it is and the error names `permanent=true` as the way to
delete it anyway. A broken install (the library is a required dependency) is
reported the same way.

Scratch paths under the OS temporary directory are still deleted for good —
nobody restores them, and a trash on the `/tmp` volume would only collect them.
The rule now lives in `tools/trash.py` (`under_system_temp`) and the temporary
workspace cleanup uses it too, instead of keeping a second copy of the check.

src/plyngent/tools/file/fs_ops.py

@@ -4,6 +4,7 @@ import shutil
 from pathlib import Path
 
 from plyngent.agent import ToolTag, invalidate_lineno_read, tool
+from plyngent.tools.trash import move_to_trash, under_system_temp
 from plyngent.tools.workspace import AccessMode, WorkspaceError, get_workspace_root, resolve_path
 
 
@@ -124,37 +125,46 @@ async def move_path(src: str, dst: str, *, overwrite: bool = False) -> str:
     return _copy_or_move_validated(source, dest, root, src=src, dst=dst, overwrite=overwrite, action="move")
 
 
-def _delete_directory(target: Path, path: str, *, recursive: bool) -> str:
-    if recursive:
-        shutil.rmtree(target)
+def _discard(target: Path, path: str, *, kind: str, permanent: bool, detail: str = "") -> str:
+    """Move *target* to the system trash (default), or delete it for good."""
+    if permanent:
+        _remove_existing(target)
         invalidate_lineno_read(str(target))
-        return f"deleted directory {path} (recursive)"
-    try:
-        _ = next(target.iterdir())
-    except StopIteration:
-        target.rmdir()
-        invalidate_lineno_read(str(target))
-        return f"deleted empty directory {path}"
-    return f"error: directory not empty: {path} (set recursive=true)"
+        return f"deleted {kind} {path}{detail}"
+    error = move_to_trash(target)
+    if error is not None:
+        return error
+    invalidate_lineno_read(str(target))
+    return f"deleted {kind} {path} (moved to system trash)"
 
 
-def _delete_target(target: Path, path: str, *, recursive: bool) -> str:
+def _delete_target(target: Path, path: str, *, recursive: bool, permanent: bool) -> str:
+    if target.is_dir() and not target.is_symlink():
+        if recursive:
+            return _discard(target, path, kind="directory", permanent=permanent, detail=" (recursive)")
+        try:
+            _ = next(target.iterdir())
+        except StopIteration:
+            return _discard(target, path, kind="empty directory", permanent=permanent)
+        return f"error: directory not empty: {path} (set recursive=true)"
     if target.is_symlink() or target.is_file():
-        kind = _kind(target)
-        target.unlink()
-        invalidate_lineno_read(str(target))
-        return f"deleted {kind} {path}"
-    if target.is_dir():
-        return _delete_directory(target, path, recursive=recursive)
+        return _discard(target, path, kind=_kind(target), permanent=permanent)
     return f"error: unsupported path type: {path}"
 
 
 @tool(tags=ToolTag.LOCAL | ToolTag.INSTANCE_STATE | ToolTag.YOLO, writes=("path",))
-async def delete_path(path: str, *, recursive: bool = False) -> str:
+async def delete_path(path: str, *, recursive: bool = False, permanent: bool = False) -> str:
     """Delete a file or directory under the workspace.
 
-    Files and empty directories are removed always. Non-empty directories require
-    ``recursive=true`` (uses ``shutil.rmtree``). The workspace root cannot be deleted.
+    The path goes to the system trash (the desktop's own trash / Recycle Bin), so
+    a deletion can be undone there; ``permanent=true`` removes it for good
+    instead. Files and empty directories are removed always, while non-empty
+    directories require ``recursive=true`` (uses ``shutil.rmtree``). The
+    workspace root cannot be deleted. When the trash is unavailable for this
+    path, nothing is deleted and the error says how to delete on purpose.
+
+    Paths under the OS temporary directory are deleted for good either way: they
+    are scratch space, not something to restore.
     """
     try:
         target = resolve_path(path, required=AccessMode.WRITE)
@@ -167,6 +177,11 @@ async def delete_path(path: str, *, recursive: bool = False) -> str:
     if target == root:
         return "error: cannot delete the workspace root"
     try:
-        return _delete_target(target, path, recursive=recursive)
+        return _delete_target(
+            target,
+            path,
+            recursive=recursive,
+            permanent=permanent or under_system_temp(target),
+        )
     except OSError as exc:
         return f"error: delete failed: {exc}"

src/plyngent/tools/temp_workspace.py

@@ -6,6 +6,7 @@ import tempfile
 from pathlib import Path
 
 from plyngent.agent import ToolTag, tool
+from plyngent.tools.trash import under_system_temp
 from plyngent.tools.workspace import (
     MAX_TEMPORARY_WORKSPACES,
     WorkspaceError,
@@ -32,22 +33,14 @@ def _sanitize_prefix(prefix: str) -> str:
     return cleaned
 
 
-def _is_under_system_temp(path: Path) -> bool:
-    """True if *path* is under the OS temporary directory (safe to rmtree)."""
-    try:
-        temp_root = Path(tempfile.gettempdir()).expanduser().resolve()
-        resolved = path.expanduser().resolve()
-        _ = resolved.relative_to(temp_root)
-    except OSError, ValueError:
-        return False
-    return True
-
-
 def cleanup_temporary_workspaces() -> int:
     """Remove directories created by :func:`new_temporary_workspace` (chat exit).
 
     Only deletes paths still under the system temp dir. Returns the number of
     directories removed. No-op when no instance is bound.
+
+    These are scratch directories, so they are removed for good rather than
+    moved to the trash the delete tool would use.
     """
     from plyngent.tools.context import get_instance
 
@@ -55,7 +48,7 @@ def cleanup_temporary_workspaces() -> int:
         return 0
     removed = 0
     for path in pop_owned_temporary_workspaces():
-        if not _is_under_system_temp(path):
+        if not under_system_temp(path):
             remove_workspace_allowlist(path)
             continue
         if path.is_dir():

src/plyngent/tools/trash.py

@@ -0,0 +1,61 @@
+"""Move a path to the system trash instead of destroying it.
+
+``delete_path`` hands every removal to :func:`move_to_trash`, so a delete the
+human approved (or YOLO skipped) can still be undone from the desktop's own
+trash. The platform work is ``send2trash``: the freedesktop trash specification
+on Linux, the Finder trash on macOS, the Recycle Bin on Windows.
+
+Scratch paths under the OS temporary directory are the exception — they are
+deleted for good, since nobody restores them and a trash on the ``/tmp`` volume
+would only collect them (see :func:`under_system_temp`).
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+
+def is_available() -> bool:
+    """True when ``send2trash`` can be imported.
+
+    It is a required dependency, so ``False`` means a broken install rather than
+    an expected absence; the delete path then reports the problem instead of
+    destroying the file.
+    """
+    from importlib.util import find_spec
+
+    return find_spec("send2trash") is not None
+
+
+def under_system_temp(path: Path) -> bool:
+    """True if *path* is under the OS temporary directory (scratch space)."""
+    try:
+        temp_root = Path(tempfile.gettempdir()).expanduser().resolve()
+        resolved = path.expanduser().resolve()
+        _ = resolved.relative_to(temp_root)
+    except OSError, ValueError:
+        return False
+    return True
+
+
+def move_to_trash(path: Path) -> str | None:
+    """Send *path* to the system trash; return an error text, or ``None`` on success.
+
+    A failure is always reported, never downgraded to a permanent delete: the
+    human was told the path is recoverable, so a trash that is unavailable for
+    this path leaves the file untouched and says how to remove it on purpose.
+    """
+    if not is_available():
+        return "error: cannot move to trash: send2trash is not installed (use permanent=true)"
+
+    from send2trash import TrashPermissionError, send2trash
+
+    try:
+        send2trash(str(path))
+    except TrashPermissionError as exc:
+        # A volume with no trash directory and no permission to create one.
+        return f"error: cannot move to trash: {exc} (use permanent=true)"
+    except OSError as exc:
+        return f"error: cannot move to trash: {exc}"
+    return None