kolega-code 0.15.0__tar.gz → 0.16.0__tar.gz

{kolega_code-0.15.0 → kolega_code-0.16.0}/.gitignore

@@ -15,3 +15,4 @@ build/
 coverage.xml
 htmlcov/
 docs/kolega_reskin_project/
+docs/agent-harness-frontier-roadmap.md

{kolega_code-0.15.0 → kolega_code-0.16.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.16.0 - 2026-07-09
+
+### Added
+
+- Added support for xAI Grok 4.5 (`grok-4.5`): 500K-token context, vision input,
+  and `low`/`medium`/`high` reasoning effort. Selectable in the Settings UI,
+  `/model` picker, CLI flags, and env vars; now the default `xai` model.
+- Send a stable `x-grok-conv-id` header on xAI Chat Completions requests so
+  multi-turn agent loops pin to a cache-warm server (xAI prompt-caching guidance).
+- Added session-scoped workspace snapshots for agent file mutations: `snapshot`
+  (list/show/create/restore, including `snapshot_id='latest'` undo) and `resolve`
+  for applying or discarding pending `lsp_edit` preview actions. Restore refuses
+  on post-snapshot drift unless `force=true`.
+- Improved TUI usability inside tmux/screen when Shift-modified keys never reach
+  the app: `/attach` with no path pastes an image from the system clipboard,
+  `Alt+V` is a portable image-paste binding alongside `Ctrl+Shift+V`, startup
+  help highlights `Ctrl+J` / `/plan` / `/build` fallbacks, and a one-time
+  startup hint appears under tmux. Documented optional tmux extended-keys config
+  under Troubleshooting.
+
+### Fixed
+
+- Prevented a TUI crash when pasting long multi-line text into the composer
+  (`OSError: File name too long` from treating paste content as a path).
+- Stopped advertising host lifecycle `initialize` as a model-callable tool while
+  keeping it available for CLI/TUI startup (LSP setup).
+- Bumped `lxml-html-clean` to 0.4.5 (and transitive `lxml` to 6.1.1) to clear
+  GHSA-4jhm-jv67-739f from the dependency audit.
+
 ## 0.15.0 - 2026-07-07
 
 ### Added

{kolega_code-0.15.0 → kolega_code-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.15.0
+Version: 0.16.0
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -234,7 +234,7 @@ Requires-Dist: google-genai==2.0.1
 Requires-Dist: httpx==0.28.1
 Requires-Dist: jinja2==3.1.6
 Requires-Dist: langfuse==3.14.5
-Requires-Dist: lxml-html-clean==0.4.4
+Requires-Dist: lxml-html-clean==0.4.5
 Requires-Dist: mcp>=1.21.2
 Requires-Dist: nest-asyncio==1.6.0
 Requires-Dist: openai==1.109.1

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/astro.config.mjs

@@ -120,6 +120,10 @@ export default defineConfig({
               label: "Diagnostics & Bug Reports",
               slug: "troubleshooting/diagnostics",
             },
+            {
+              label: "Terminal & tmux shortcuts",
+              slug: "troubleshooting/terminal-tmux",
+            },
           ],
         },
         {

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/src/assets/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 79.72%"><title>coverage: 79.72%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">79.72%</text><text x="865" y="150" fill-opacity=".3" textLength="430">79.72%</text></g><text x="865" y="140" textLength="430">79.72%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 79.93%"><title>coverage: 79.93%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">79.93%</text><text x="865" y="150" fill-opacity=".3" textLength="430">79.93%</text></g><text x="865" y="140" textLength="430">79.93%</text></g></g></svg>

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/src/content/docs/configuration/providers-and-models.mdx

@@ -184,6 +184,8 @@ models in the TUI.
 | Ollama Cloud `gpt-oss:*` | `low`, `medium`, `high` | `medium` |
 | Google `gemini-2.5-pro` | `auto`, `low`, `medium`, `high` | `medium` |
 | OpenAI reasoning models | `low`, `medium`, `high` | `medium` |
+| xAI `grok-4.5` | `low`, `medium`, `high` | `medium` |
+| xAI `grok-4.3` | `none`, `low`, `medium`, `high` | `low` |
 
 ## Check what's active
 

kolega_code-0.16.0/docs/src/content/docs/troubleshooting/terminal-tmux.md

@@ -0,0 +1,67 @@
+---
+title: Terminal & tmux shortcuts
+description: Why Shift chords fail in tmux/screen and the portable fallbacks Kolega Code supports.
+---
+
+Kolega Code’s TUI uses some Shift-modified shortcuts (`Shift+Enter`, `Shift+Tab`,
+`Ctrl+Shift+V`). In a modern terminal with the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/),
+those chords reach the app. Inside **tmux** or **GNU screen**, the multiplexer
+often sits between the terminal and the app and either drops modifiers or
+never forwards the extended key sequences — so Shift chords look like plain
+keys, or never arrive at all.
+
+Kolega Code cannot invent modifier information the terminal never sends. Instead
+it provides **portable fallbacks** that work without Shift, plus optional tmux
+config if you want the original chords restored.
+
+## Portable shortcuts
+
+| Action | Preferred (capable terminals) | Portable fallback |
+| --- | --- | --- |
+| Send prompt | `Enter` | — |
+| Insert newline | `Shift+Enter` | `Ctrl+J` or `Ctrl+Enter` |
+| Toggle Plan ⇄ Build | `Shift+Tab` | `/plan` or `/build` |
+| Paste image from system clipboard | `Ctrl+Shift+V` | `Alt+V` (Option+V on macOS when the terminal treats Option as Meta) or `/attach` with no path |
+| Attach image from a file | — | `/attach <path>` or `@image.png` |
+
+On session start inside tmux/screen, the startup block prints a short reminder
+of these fallbacks.
+
+### Image paste notes
+
+- `/attach` with **no path** reads an image from the **system** clipboard (same
+  path as `Ctrl+Shift+V` / `Alt+V`). This is the most reliable option under
+  plain tmux.
+- Clipboard image reading uses host tools independent of tmux:
+  - **macOS:** `osascript` (built-in), or `pngpaste` if installed
+  - **Linux:** `xclip` or `wl-paste`
+  - **Windows / WSL:** PowerShell clipboard APIs
+- If Option+V types a special character (e.g. `√`) instead of pasting an image,
+  your terminal is not sending Alt as a modifier. Prefer `/attach`, or enable
+  “Option as Meta” / “Left Option key acts as +Esc” in the terminal settings.
+
+## Optional: restore Shift+Enter in tmux
+
+With **tmux 3.2+** and an outer terminal that supports extended keys, add to
+`~/.tmux.conf`:
+
+```tmux
+set -g extended-keys always
+set -g extended-keys-format csi-u
+set -as terminal-features 'xterm*:extkeys'
+```
+
+Then reload (`tmux source-file ~/.tmux.conf`) or restart tmux.
+
+Also make sure `default-terminal` / `terminal-overrides` match the outer
+terminal’s `$TERM` family (`xterm-256color`, `xterm-ghostty`, etc.) so the
+`extkeys` feature actually applies.
+
+After that, `Shift+Enter` and similar chords often work again inside Kolega Code.
+If they still do not, keep using the portable fallbacks above.
+
+## Related
+
+- [Chat Composer](../../tui/composer/) — full composer key reference
+- [Interface Tour](../../tui/interface/) — key bindings at a glance
+- [Slash Commands](../../tui/slash-commands/) — `/attach`, `/plan`, `/build`

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/src/content/docs/tui/composer.md

@@ -13,17 +13,24 @@ multi-line input, and drives the option lists the agent shows you.
 | --- | --- |
 | `Enter` | Send the prompt |
 | `Shift+Enter` | Insert a newline (keep typing) |
-| `Ctrl+J` | Insert a newline (alternative) |
+| `Ctrl+J` / `Ctrl+Enter` | Insert a newline (portable alternatives; prefer these inside tmux) |
 | `Ctrl+L` | Select all composer text |
 | `Cmd+A` / `⌘A` | Select all composer text on macOS, when forwarded by the terminal |
 | `Ctrl+A` | Move to the start of the current line (intentionally not select-all) |
 | `Ctrl+U` | Delete backward to the start of the line; at line start, delete the previous line |
+| `Ctrl+Shift+V` | Paste an image from the system clipboard |
+| `Alt+V` | Paste an image from the system clipboard (portable alternative when Shift chords fail) |
 
 `Ctrl+L` is the portable select-all shortcut because `Ctrl+A` is preserved for
 terminal-style line navigation. Some macOS terminal emulators reserve `Cmd+A` for
 terminal scrollback selection before the TUI can see it; `Ctrl+L` still works in
 the composer.
 
+Inside **tmux** or **screen**, Shift-modified keys often never reach the app.
+Use `Ctrl+J` for newlines and `Alt+V` or `/attach` for images. See
+[Terminal & tmux shortcuts](../../troubleshooting/terminal-tmux/) for optional
+tmux config to restore Shift+Enter.
+
 ## Queuing follow-up prompts
 
 You can keep typing while the agent is still generating. Pressing `Enter` during
@@ -45,6 +52,19 @@ If you cancel the active turn with `Ctrl+C` or `Escape`, queued follow-ups are
 restored into the composer instead of being silently sent. To discard pending
 follow-ups without stopping the active turn, run [`/queue-clear`](../slash-commands/).
 
+## Attaching images
+
+You can attach images for vision-capable models in several ways:
+
+| Method | How |
+| --- | --- |
+| System clipboard | `Ctrl+Shift+V` or `Alt+V`, or run `/attach` with no path |
+| File path | `/attach path/to/image.png` |
+| File mention | `@screenshot.png` (supported image extensions only) |
+
+Use `/detach` to clear pending attachments before sending. On a non-vision
+model, Kolega Code warns and blocks the send until you detach or switch models.
+
 ## File mentions with `@`
 
 Type `@` to reference a file. A fuzzy-searchable dropdown of project files appears

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/src/content/docs/tui/interface.md

@@ -82,14 +82,16 @@ the turn keeps running while you look around.
 
 | Keys | Action |
 | --- | --- |
-| `Shift+Tab` | Toggle Build ⇄ Plan mode |
+| `Shift+Tab` | Toggle Build ⇄ Plan mode (`/plan` / `/build` if Shift is unavailable) |
 | `Ctrl+P` | Toggle shell/edit permissions between Ask ⇄ Auto |
 | `Ctrl+O` | Show or hide the side panel |
 | `Ctrl+G` | Open the sub-agent inspector |
 | `Enter` | Send the prompt |
 | `Shift+Enter` / `Ctrl+J` | Insert a newline |
+| `Ctrl+Shift+V` / `Alt+V` | Paste an image from the system clipboard (`/attach` also works) |
 | `Ctrl+C` / `Escape` | Cancel the current generation |
 | `Ctrl+Q` | Save the session and quit |
 
 A complete composer-and-completion key reference is in
-[Chat Composer](../composer/).
+[Chat Composer](../composer/). If Shift chords fail inside tmux, see
+[Terminal & tmux shortcuts](../../troubleshooting/terminal-tmux/).

{kolega_code-0.15.0 → kolega_code-0.16.0}/docs/src/content/docs/tui/slash-commands.md

@@ -34,6 +34,8 @@ These control the app and your session.
 | --- | --- |
 | `/skills` | List available Agent Skills |
 | `/init` | Create or update `AGENTS.md` for this repository |
+| `/attach` | Attach an image: clipboard if no path, or `/attach <path>` for a file |
+| `/detach` | Remove pending image attachments |
 | `/plan` | Switch to [Plan mode](../modes/) |
 | `/build` | Switch to [Build mode](../modes/) |
 | `/sidebar` | Show or hide the side panel |

{kolega_code-0.15.0 → kolega_code-0.16.0}/kolega_code/__init__.py

@@ -151,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"

{kolega_code-0.15.0 → kolega_code-0.16.0}/kolega_code/agent/__init__.py

@@ -44,4 +44,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"

{kolega_code-0.15.0 → kolega_code-0.16.0}/kolega_code/agent/tool_backend/edit_tool.py

@@ -9,6 +9,7 @@ from .edit_preview import build_diff_preview, build_head_preview
 
 if TYPE_CHECKING:
     from kolega_code.services.lsp import LspManager
+    from kolega_code.services.snapshots import SnapshotService
 
 
 _BLOCK_PATTERN = re.compile(r"<<<<<<< SEARCH\r?\n(.*?)\r?\n=======\r?\n(.*?)\r?\n>>>>>>> REPLACE", re.DOTALL)
@@ -43,9 +44,16 @@ class ResolvedReplacement:
 
 
 class EditTool(BaseTool):
-    def __init__(self, *args, lsp_manager: Optional["LspManager"] = None, **kwargs) -> None:
+    def __init__(
+        self,
+        *args,
+        lsp_manager: Optional["LspManager"] = None,
+        snapshot_service: Optional["SnapshotService"] = None,
+        **kwargs,
+    ) -> None:
         super().__init__(*args, **kwargs)
         self._lsp_manager = lsp_manager
+        self._snapshot_service = snapshot_service
 
     async def edit(self, path: str, block: str) -> str:
         """
@@ -115,8 +123,6 @@ class EditTool(BaseTool):
                     old_content = None
 
             parent_dir = self.filesystem.get_parent(path)
-            if parent_dir and parent_dir != "." and not self.filesystem.exists(parent_dir):
-                self.filesystem.create_directory(parent_dir)
 
             # Preserve the file's dominant line ending on overwrite; new files
             # keep the line endings the caller provided (typically LF).
@@ -124,7 +130,17 @@ class EditTool(BaseTool):
                 line_ending = self._detect_dominant_line_ending(path, old_content)
                 content = self._normalize_line_endings(content, line_ending)
 
-            self.filesystem.write_text(path, content)
+            def _write() -> None:
+                if parent_dir and parent_dir != "." and not self.filesystem.exists(parent_dir):
+                    self.filesystem.create_directory(parent_dir)
+                self.filesystem.write_text(path, content)
+
+            self._record_snapshot_mutation(
+                tool_name="write",
+                reason=f"write {path}",
+                paths=self._snapshot_paths_for_write(path),
+                mutate=_write,
+            )
 
             preview = (
                 build_diff_preview(old_content, content, path)
@@ -180,7 +196,12 @@ class EditTool(BaseTool):
             blocked_msg = self._enforce_vibe_edit_policy(path)
             if blocked_msg:
                 return blocked_msg
-            self.filesystem.write_text(path, normalized_updated)
+            self._record_snapshot_mutation(
+                tool_name=tool_name,
+                reason=f"{tool_name} {path}",
+                paths=[path],
+                mutate=lambda: self.filesystem.write_text(path, normalized_updated),
+            )
 
             await self.send_edit_preview(
                 build_diff_preview(original_content, normalized_updated, path),
@@ -223,6 +244,33 @@ class EditTool(BaseTool):
             )
         return parsed_blocks
 
+    def _record_snapshot_mutation(
+        self,
+        *,
+        tool_name: str,
+        reason: str,
+        paths: list[str],
+        mutate: Callable[[], None],
+    ) -> None:
+        if self._snapshot_service is None or not self._snapshot_service.can_snapshot_paths(paths):
+            mutate()
+            return
+        self._snapshot_service.record_mutation(
+            tool_name=tool_name,
+            tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
+            reason=reason,
+            paths=paths,
+            mutate=mutate,
+        )
+
+    def _snapshot_paths_for_write(self, path: str) -> list[str]:
+        paths = [path]
+        parent = self.filesystem.get_parent(path)
+        while parent and parent != "." and not self.filesystem.exists(parent):
+            paths.append(parent)
+            parent = self.filesystem.get_parent(parent)
+        return paths
+
     def _resolve_replacement(self, content: str, block: SearchReplaceBlock) -> ResolvedReplacement:
         passes: list[tuple[str, Callable[[str, str], list[tuple[int, int]]]]] = [
             ("exact", self._exact_spans),

{kolega_code-0.15.0 → kolega_code-0.16.0}/kolega_code/agent/tool_backend/lsp_tool.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import hashlib
 import json
 from pathlib import Path
-from typing import Any, Optional, cast
+from typing import TYPE_CHECKING, Any, Optional, cast
 from urllib.parse import unquote, urlparse
 
 from .base_tool import BaseTool
@@ -13,6 +13,9 @@ from .edit_preview import build_diff_preview
 from kolega_code.services.lsp import LspManager, format_diagnostics, format_no_diagnostics
 from kolega_code.services.lsp.edits import WorkspaceEditApplier, WorkspaceEditError, WorkspaceEditResult
 
+if TYPE_CHECKING:
+    from kolega_code.services.snapshots import SnapshotService
+
 
 class LspTool(BaseTool):
     """Exposes read-only LSP operations as an agent-callable tool."""
@@ -563,9 +566,16 @@ class LspEditTool(BaseTool):
 
     _ALL_OPS = {"rename", "rename_file", "format_document", "format_range", "apply_code_action"}
 
-    def __init__(self, *args, lsp_manager: Optional[LspManager] = None, **kwargs) -> None:
+    def __init__(
+        self,
+        *args,
+        lsp_manager: Optional[LspManager] = None,
+        snapshot_service: Optional["SnapshotService"] = None,
+        **kwargs,
+    ) -> None:
         super().__init__(*args, **kwargs)
         self._lsp_manager = lsp_manager
+        self._snapshot_service = snapshot_service
 
     async def lsp_edit(
         self,
@@ -842,7 +852,17 @@ class LspEditTool(BaseTool):
                         blocked = self._first_blocked_path(preview.touched_paths)
                         if blocked:
                             return {"applied": False, "failureReason": blocked}
-                        applied = applier.apply(workspace_edit)
+                        if self._snapshot_service is not None:
+                            mutation = self._snapshot_service.record_mutation(
+                                tool_name="lsp_edit",
+                                tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
+                                reason="lsp apply_code_action workspace/applyEdit",
+                                paths=preview.touched_paths,
+                                mutate=lambda: applier.apply(workspace_edit),
+                            )
+                            applied = mutation.result
+                        else:
+                            applied = applier.apply(workspace_edit)
                         server_results.append(applied)
                         return {"applied": True}
                     except WorkspaceEditError as exc:
@@ -896,9 +916,33 @@ class LspEditTool(BaseTool):
         if should_apply and blocked:
             return blocked
 
-        result = applier.apply(edit) if should_apply else preview
+        if should_apply:
+            if self._snapshot_service is not None:
+                mutation = self._snapshot_service.record_mutation(
+                    tool_name="lsp_edit",
+                    tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
+                    reason=f"lsp_edit {operation}",
+                    paths=preview.touched_paths,
+                    mutate=lambda: applier.apply(edit),
+                )
+                result = mutation.result
+            else:
+                result = applier.apply(edit)
+        else:
+            result = preview
         await self._send_previews(result, operation)
         lines = [self._format_workspace_edit_result(operation, result)]
+        if not should_apply and self._snapshot_service is not None:
+            pending = self._snapshot_service.create_pending_workspace_edit(
+                tool_name="lsp_edit",
+                tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
+                operation=operation,
+                workspace_edit=edit,
+                touched_paths=preview.touched_paths,
+                summaries=preview.summaries,
+                previews=self._preview_payloads(preview),
+            )
+            lines.append(f'Pending action: `{pending.action_id}`. Use resolve(decision="apply") to apply it.')
         if should_apply and include_diagnostics:
             diagnostics = await self._diagnostics_for_paths(result.touched_paths)
             if diagnostics:
@@ -909,15 +953,23 @@ class LspEditTool(BaseTool):
         return WorkspaceEditApplier(self.project_path, self.filesystem).preview(edit)
 
     async def _send_previews(self, result: WorkspaceEditResult, operation: str) -> None:
-        for change in result.text_changes:
-            if change.old_text == change.new_text:
-                continue
+        for preview in self._preview_payloads(result):
             await self.send_edit_preview(
-                build_diff_preview(change.old_text, change.new_text, change.path),
+                preview,
                 tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
                 tool_name="lsp_edit",
             )
 
+    def _preview_payloads(self, result: WorkspaceEditResult) -> list[dict[str, Any]]:
+        previews: list[dict[str, Any]] = []
+        for change in result.text_changes:
+            if change.old_text == change.new_text:
+                continue
+            preview = build_diff_preview(change.old_text, change.new_text, change.path)
+            if preview:
+                previews.append(preview)
+        return previews
+
     def _format_workspace_edit_result(self, operation: str, result: WorkspaceEditResult) -> str:
         label = "Applied" if result.applied else "Preview"
         lines = [f"{label} LSP edit `{operation}`."]

kolega_code-0.16.0/kolega_code/agent/tool_backend/snapshot_tool.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from kolega_code.services.lsp.edits import WorkspaceEditApplier
+from kolega_code.services.snapshots import PendingAction, SnapshotError, SnapshotRecord, SnapshotService
+from kolega_code.tools import ToolError
+
+from .base_tool import BaseTool
+from .edit_preview import build_diff_preview
+
+if TYPE_CHECKING:
+    from kolega_code.services.lsp.edits import WorkspaceEditResult
+
+
+class SnapshotTool(BaseTool):
+    def __init__(self, *args, snapshot_service: SnapshotService, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.snapshot_service = snapshot_service
+
+    async def snapshot(
+        self,
+        action: str = "list",
+        snapshot_id: str = "",
+        paths: Optional[list[str]] = None,
+        force: bool = False,
+        limit: int = 20,
+    ) -> str:
+        """Manage file snapshots for undo, inspection, and manual checkpoints.
+
+        Actions:
+        - list: show recent snapshots for this session.
+        - show: show one snapshot's metadata and touched paths.
+        - create: create a manual checkpoint for the provided paths.
+        - restore: restore a snapshot's before-state. Use snapshot_id="latest" for undo.
+
+        Args:
+            action: One of list, show, create, or restore.
+            snapshot_id: Snapshot id to show or restore. Use latest for the newest snapshot.
+            paths: Project-relative paths for create.
+            force: Restore even when tracked files changed after the snapshot.
+            limit: Maximum number of snapshots to list.
+
+        Returns:
+            Markdown summary of the requested snapshot operation.
+        """
+        try:
+            normalized_action = action.strip().lower()
+            if normalized_action == "list":
+                return self._format_snapshot_list(self.snapshot_service.list_snapshots(limit=limit))
+            if normalized_action == "show":
+                if not snapshot_id:
+                    raise SnapshotError("snapshot_id is required for action=show.")
+                return self._format_snapshot_detail(self.snapshot_service.load_snapshot(snapshot_id))
+            if normalized_action == "create":
+                record = self.snapshot_service.create_manual_snapshot(
+                    paths=paths or (),
+                    reason="manual snapshot",
+                    tool_call_id=getattr(self.caller, "current_tool_execution_id", None),
+                )
+                return f"Created manual snapshot `{record.snapshot_id}` for {', '.join(record.touched_paths)}."
+            if normalized_action == "restore":
+                target_id = snapshot_id or "latest"
+                result = self.snapshot_service.restore_snapshot(target_id, force=force)
+                forced = " with force=true" if result.forced else ""
+                return (
+                    f"Restored snapshot `{result.snapshot_id}`{forced}.\n\n"
+                    f"Touched paths: {', '.join(result.restored_paths) or '(none)'}"
+                )
+            raise SnapshotError("action must be one of: list, show, create, restore.")
+        except SnapshotError as exc:
+            raise ToolError(str(exc)) from exc
+
+    async def resolve(self, action_id: str, decision: str, force: bool = False) -> str:
+        """Apply or discard a pending preview action.
+
+        Pending actions are created by preview-only tools such as lsp_edit(apply=false).
+        Applying a pending action checks that the source files still match the preview
+        inputs before writing, unless force=true is explicitly provided.
+
+        Args:
+            action_id: Pending action id returned by a preview-only tool.
+            decision: apply or discard.
+            force: Apply even if source hashes no longer match.
+
+        Returns:
+            Markdown summary of the resolve decision.
+        """
+        try:
+            action = self.snapshot_service.load_pending_action(action_id)
+            normalized_decision = decision.strip().lower()
+            if normalized_decision == "discard":
+                updated = self.snapshot_service.update_pending_action(action, status="discarded", message="discarded")
+                return f"Discarded pending action `{updated.action_id}`."
+            if normalized_decision != "apply":
+                raise SnapshotError("decision must be apply or discard.")
+            if action.status != "pending":
+                raise SnapshotError(f"Pending action `{action.action_id}` is already {action.status}.")
+
+            mismatches = self.snapshot_service.diff_expected_current(action.source)
+            if mismatches and not force:
+                message = self.snapshot_service._format_mismatch_error(action.action_id, mismatches)
+                self.snapshot_service.update_pending_action(action, status="stale", message=message)
+                raise SnapshotError(message)
+
+            applier = WorkspaceEditApplier(self.project_path, self.filesystem)
+            preview = applier.preview(action.workspace_edit)
+
+            def _apply() -> "WorkspaceEditResult":
+                return applier.apply(action.workspace_edit)
+
+            mutation = self.snapshot_service.record_mutation(
+                tool_name=action.tool_name or "resolve",
+                tool_call_id=getattr(self.caller, "current_tool_execution_id", None) or action.tool_call_id,
+                reason=f"resolve {action.action_id} ({action.operation})",
+                paths=preview.touched_paths,
+                mutate=_apply,
+            )
+            result = mutation.result
+            await self._send_previews(result, action)
+            updated = self.snapshot_service.update_pending_action(
+                action,
+                status="applied",
+                snapshot_id=mutation.snapshot.snapshot_id if mutation.snapshot else None,
+                message="applied",
+            )
+            snapshot_line = f"\nSnapshot: `{updated.snapshot_id}`" if updated.snapshot_id else ""
+            forced = " with force=true" if force else ""
+            return (
+                f"Applied pending action `{updated.action_id}`{forced}.\n\n"
+                + self._format_workspace_edit_result(action.operation, result)
+                + snapshot_line
+            )
+        except SnapshotError as exc:
+            raise ToolError(str(exc)) from exc
+
+    async def _send_previews(self, result: "WorkspaceEditResult", action: PendingAction) -> None:
+        for change in result.text_changes:
+            if change.old_text == change.new_text:
+                continue
+            await self.send_edit_preview(
+                build_diff_preview(change.old_text, change.new_text, change.path),
+                tool_call_id=getattr(self.caller, "current_tool_execution_id", None) or action.tool_call_id,
+                tool_name="resolve",
+            )
+
+    @staticmethod
+    def _format_snapshot_list(records: list[SnapshotRecord]) -> str:
+        if not records:
+            return "No snapshots recorded for this session."
+        lines = ["# Snapshots", ""]
+        for record in records:
+            marker = " manual" if record.manual else ""
+            lines.append(
+                f"- `{record.snapshot_id}`{marker} - {record.tool_name} - "
+                f"{record.created_at} - {', '.join(record.touched_paths) or '(none)'}"
+            )
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_snapshot_detail(record: SnapshotRecord) -> str:
+        lines = [
+            f"# Snapshot `{record.snapshot_id}`",
+            "",
+            f"- Tool: `{record.tool_name}`",
+            f"- Tool call: `{record.tool_call_id or '-'}`",
+            f"- Created: {record.created_at}",
+            f"- Reason: {record.reason or '-'}",
+            f"- Manual: {str(record.manual).lower()}",
+            "",
+            "## Paths",
+        ]
+        for path in record.touched_paths:
+            before = record.before.get(path)
+            after = record.after.get(path)
+            lines.append(f"- `{path}`: {SnapshotTool._state_label(before)} -> {SnapshotTool._state_label(after)}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_workspace_edit_result(operation: str, result: Any) -> str:
+        lines = [f"Applied LSP edit `{operation}`."]
+        for summary in result.summaries:
+            lines.append(f"- {summary}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _state_label(state: Any) -> str:
+        if state is None:
+            return "missing"
+        suffix = f":{state.sha256[:12]}" if getattr(state, "sha256", None) else ""
+        return f"{state.kind}{suffix}"