diff --git a/CLAUDE.md b/CLAUDE.md
index 000cb11..192d8c5 100755
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,7 +74,7 @@ The shared loop lives in `Agent._loop()` (`app/core/agent.py`). Subclasses overr
 | `_on_no_choices` | raise | exponential backoff | raise |
 | `_should_stop` | — | `channel.has_stopped` | — |
 
-Tool calls within a single LLM turn are dispatched in parallel via `asyncio.gather`. After each turn, the full message chain (assistant tool-call message + tool results + final response) is saved to `self.messages` with tool results truncated to `TOOL_RESULT_HISTORY_LIMIT` chars to keep context lean. `MessageHistory` (SQLite) stores only user + final assistant text for cross-session persistence.
+Tool calls within a single LLM turn are dispatched in parallel via `asyncio.gather`. After each turn, the full message chain (assistant tool-call message + tool results + final response) is saved to `self.messages` at full length. `MessageHistory` (SQLite) stores only user + final assistant text for cross-session persistence.
 
 ### Tool System
 
@@ -104,7 +104,7 @@ On startup, `load_system_context()` (`app/infra/startup.py`) loads `app/core/sys
 
 **Channel types** are defined in `ChannelType` enum (`app/channels/channel.py`): `CLI`, `TELEGRAM`, `DISCORD`, `WEB`. Each channel implements the `Channel` ABC and owns a `MessageQueue` instance. `bg_server.py` wires up enabled channels — each gets its own `MessageQueue`, `BackgroundAgent`, and set of coroutines (`run_polling`, `process_incoming`, `process_outgoing`) gathered into the event loop.
 
-**WebChannel** (`app/channels/web_channel.py`) uses `python-fasthtml` + uvicorn to serve both a browser chat UI (`GET /`) and a JSON WebSocket endpoint (`WS /ws`) on the same port. Multiple concurrent browser tabs are supported — each connection gets a UUID tracked in `_connections`. A per-connection `asyncio.Lock` in `_send_locks` serializes writes to each WebSocket. The channel also exposes `GET /api/conversations`, `GET /api/messages` (scoped to web channel only), and `GET /api/status` REST endpoints. Only `/whoami` is handled inline (it needs the per-connection client ID); all other slash commands — including `/help`, `/status`, `/stop` — are forwarded to `BackgroundAgent`'s `CommandRegistry` via the message queue with `is_command=True` in metadata so `send_message()` emits `{"type":"system"}` responses, enabling the sidebar to refresh after conversation-mutating commands.
+**WebChannel** (`app/channels/web_channel.py`) uses `python-fasthtml` + uvicorn to serve both a browser chat UI (`GET /`) and a JSON WebSocket endpoint (`WS /ws`) on the same port. Multiple concurrent browser tabs are supported — each connection gets a UUID tracked in `_connections`. A per-connection `asyncio.Lock` in `_send_locks` serializes writes to each WebSocket. The channel also exposes `GET /api/conversations`, `GET /api/messages` (scoped to web channel only), `GET /api/status`, and `POST /api/upload` REST endpoints. `POST /api/upload` accepts multipart `files` (one or more), writes each under `$ANOTHERBOT_HOME/uploads` with a UUID prefix, and returns the stored basenames; the browser (paperclip button next to the input) sends those basenames back in the WebSocket `message` frame's `files` field. `_resolve_upload_paths()` joins each basename to the upload dir (basename-only, so client paths can't traverse out) and the resolved absolute paths reach the agent via `metadata["files"]`, which `Agent._build_user_message()` encodes as image/file parts. Only `/whoami` is handled inline (it needs the per-connection client ID); all other slash commands — including `/help`, `/status`, `/stop` — are forwarded to `BackgroundAgent`'s `CommandRegistry` via the message queue with `is_command=True` in metadata so `send_message()` emits `{"type":"system"}` responses, enabling the sidebar to refresh after conversation-mutating commands.
 
 **Slash commands** are handled entirely by `BackgroundAgent`. Channel handlers (`command_handler` in Telegram, `on_message` in Discord) intercept only `/whoami` (resolved inline using the platform user object) and enqueue everything else as a plain `IncomingMessage`. `BackgroundAgent.process_incoming()` detects the leading `/` and dispatches via its own `CommandRegistry`. That registry owns the full command set: `/model`, `/status`, `/stop`, `/help`, `/list`, `/new`, `/load`, `/fork`, `/rename`, `/export`.
 
diff --git a/app/__init__.py b/app/__init__.py
old mode 100755
new mode 100644
diff --git a/app/channels/commands.py b/app/channels/commands.py
index fb8d9c5..f469d89 100644
--- a/app/channels/commands.py
+++ b/app/channels/commands.py
@@ -69,6 +69,20 @@ async def model_cmd(args: str = "") -> str:
     return f"Model set to: {args.strip()}"
 
 
+async def trace_cmd(args: str = "") -> str:
+    arg = args.strip().lower()
+    tracedir = runtime.get("tracedir")
+    if arg == "on":
+        runtime.set("trace", True)
+        return f"Tracing on. Writing to {tracedir}"
+    elif arg == "off":
+        runtime.set("trace", False)
+        return "Tracing off."
+    else:
+        state = runtime.get("trace", False)
+        return f"Tracing is {'on' if state else 'off'}. Dir: {tracedir}"
+
+
 def make_status_cmd(channel_str: str = "") -> CommandHandler:
     async def _status(args: str = "") -> str:
         uptime = datetime.now() - _STARTUP_TIME
@@ -81,11 +95,15 @@ async def _status(args: str = "") -> str:
         else:
             conv_id = runtime.get("conversation_id", "—")
             conv_name = runtime.get("conversation_name", "—")
+        tracing = runtime.get("trace", False)
+        last_trace = runtime.get("last_trace")
+        trace_line = f"on ({last_trace})" if (tracing and last_trace) else ("on" if tracing else "off")
         return (
             f"Bot status:\n"
             f"  Model:        {model}\n"
             f"  Uptime:       {hours}h {minutes}m {seconds}s\n"
-            f"  Conversation: [{conv_id}] {conv_name}"
+            f"  Conversation: [{conv_id}] {conv_name}\n"
+            f"  Tracing:      {trace_line}"
         )
     return _status
 
@@ -225,7 +243,6 @@ async def _mcp(args: str = "") -> str:
                     desc = fn.get("description", "")
                     lines.append(f"  {bare}" + (f" — {desc}" if desc else ""))
                 return "\n".join(lines)
-                return "\n".join(lines)
             else:
                 specs = mcp_manager.get_tool_specs()
                 if not specs:
diff --git a/app/channels/static/web_channel.css b/app/channels/static/web_channel.css
index 942dfbb..94b9069 100644
--- a/app/channels/static/web_channel.css
+++ b/app/channels/static/web_channel.css
@@ -318,3 +318,82 @@ body {
 #send-btn:hover   { background: var(--accent-h); }
 #send-btn:active  { transform: scale(.97); }
 #send-btn:disabled { background: var(--border); cursor: not-allowed; }
+
+/* Hide the file input without display:none — keeps it in the layout/event
+   tree so its `change` event fires reliably (Edge) when opened via the label. */
+.visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+}
+
+/* ---- attach button (a <label for="file-input">) ---- */
+#attach-btn {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    color: var(--text-muted);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    height: 42px;
+    width: 42px;
+    padding: 0;
+    margin: 0;
+    line-height: 0;          /* kill inline baseline gap (Edge alignment) */
+    flex-shrink: 0;
+    user-select: none;
+    -webkit-user-select: none;
+    transition: border-color .15s, color .15s, background .15s;
+}
+#attach-btn:hover { border-color: var(--accent); color: var(--accent); }
+#attach-btn:active { transform: scale(.97); }
+#attach-btn svg { display: block; width: 20px; height: 20px; }
+
+/* ---- attachment chips ---- */
+#attachments {
+    display: none;
+    flex-wrap: wrap;
+    gap: 8px;
+    padding: 10px 20px 0;
+    background: var(--surface);
+    flex-shrink: 0;
+}
+#attachments.has-files { display: flex; }
+
+.attach-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    max-width: 240px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 5px 8px 5px 10px;
+    font-size: 0.8rem;
+}
+.attach-name {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--text);
+}
+.attach-remove {
+    background: none;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    font-size: 1rem;
+    line-height: 1;
+    padding: 0 2px;
+    transition: color .12s;
+}
+.attach-remove:hover { color: #ef4444; }
diff --git a/app/channels/static/web_channel.js b/app/channels/static/web_channel.js
index 3fe1bc4..0981bf8 100644
--- a/app/channels/static/web_channel.js
+++ b/app/channels/static/web_channel.js
@@ -18,6 +18,11 @@
     const toggleBtn   = document.getElementById('sidebar-toggle');
     const convListEl  = document.getElementById('conv-list');
     const newConvBtn  = document.getElementById('new-conv-btn');
+    const fileInput   = document.getElementById('file-input');
+    const attachEl    = document.getElementById('attachments');
+
+    // Files staged for the next send (cleared after a successful upload).
+    let selectedFiles = [];
 
     // ---- theme ----
     const savedTheme = localStorage.getItem('ab-theme') || 'dark';
@@ -141,7 +146,7 @@
         ws.onopen = () => {
             reconnectDelay = 1000;
             setStatus('connected', 'Connected');
-            sendBtn.disabled = false;
+            refreshSendState();
             clearMessages();       // always reset DOM before reloading — prevents duplicates on reconnect
             loadConversations(true);
         };
@@ -213,14 +218,105 @@
     }
     function scrollBottom() { scrollEl.scrollTop = scrollEl.scrollHeight; }
 
+    // ---- attachments ----
+    function renderAttachments() {
+        attachEl.innerHTML = '';
+        attachEl.classList.toggle('has-files', selectedFiles.length > 0);
+        selectedFiles.forEach((file, idx) => {
+            const chip = document.createElement('div');
+            chip.className = 'attach-chip';
+            const label = document.createElement('span');
+            label.className = 'attach-name';
+            label.textContent = file.name;
+            label.title = `${file.name} (${fmtSize(file.size)})`;
+            const remove = document.createElement('button');
+            remove.className = 'attach-remove';
+            remove.type = 'button';
+            remove.textContent = '×';
+            remove.title = 'Remove attachment';
+            remove.addEventListener('click', () => {
+                selectedFiles.splice(idx, 1);
+                renderAttachments();
+                refreshSendState();
+            });
+            chip.appendChild(label);
+            chip.appendChild(remove);
+            attachEl.appendChild(chip);
+        });
+    }
+
+    function fmtSize(bytes) {
+        if (bytes < 1024) return bytes + ' B';
+        if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(0) + ' KB';
+        return (bytes / 1024 / 1024).toFixed(1) + ' MB';
+    }
+
+    function refreshSendState() {
+        const connected = ws && ws.readyState === WebSocket.OPEN;
+        const hasInput = inputEl.value.trim().length > 0 || selectedFiles.length > 0;
+        sendBtn.disabled = !connected || !hasInput;
+    }
+
+    // The attach control is a <label for="file-input">, so clicking it opens
+    // the picker natively — no JS click needed (and avoids a double-open).
+    // Copy the FileList into a real array before clearing .value: Edge can
+    // invalidate the live FileList once .value is reset mid-handler.
+    fileInput.addEventListener('change', () => {
+        const picked = Array.from(fileInput.files || []);
+        for (const file of picked) selectedFiles.push(file);
+        fileInput.value = '';   // allow re-selecting the same file later
+        renderAttachments();
+        refreshSendState();
+    });
+
+    async function uploadFiles(files) {
+        const form = new FormData();
+        files.forEach(f => form.append('files', f, f.name));
+        const res = await fetch('/api/upload', { method: 'POST', body: form });
+        if (!res.ok) {
+            let detail = '';
+            try { detail = (await res.json()).error || ''; } catch (e) { /* ignore */ }
+            throw new Error(detail || `Upload failed (${res.status})`);
+        }
+        const { files: saved } = await res.json();
+        return saved;   // [{path, name}, ...]
+    }
+
     // ---- send ----
-    function send() {
+    async function send() {
         const text = inputEl.value.trim();
-        if (!text || !ws || ws.readyState !== WebSocket.OPEN) return;
-        appendMessage(text, 'user');
-        ws.send(JSON.stringify({ type: 'message', content: text }));
+        const files = selectedFiles.slice();
+        if (sendBtn.disabled) return;
+
+        let uploaded = [];
+        if (files.length) {
+            sendBtn.disabled = true;
+            try {
+                uploaded = await uploadFiles(files);
+            } catch (e) {
+                appendMessage('Attachment upload failed: ' + e.message, 'system');
+                refreshSendState();
+                return;
+            }
+        }
+
+        const payload = { type: 'message', content: text };
+        if (uploaded.length) payload.files = uploaded.map(f => f.path);
+        try {
+            ws.send(JSON.stringify(payload));
+        } catch (err) {
+            appendMessage('Send failed: disconnected (please retry).', 'system');
+            refreshSendState();
+            return;
+        }
+
+        appendMessage(renderUserContent(text, files), 'user');
+        selectedFiles = [];
+        renderAttachments();
         inputEl.value = '';
         inputEl.style.height = '42px';
+        refreshSendState();
+
         if (text === '/new') {
             clearMessages();
         } else if (/^\/load\s+\d+/.test(text)) {
@@ -232,6 +328,12 @@
         }
     }
 
+    function renderUserContent(text, files) {
+        if (!files.length) return text;
+        const tags = files.map(f => `📎 ${f.name}`).join('  ');
+        return text ? `${text}\n\n${tags}` : tags;
+    }
+
     sendBtn.addEventListener('click', send);
     inputEl.addEventListener('keydown', (e) => {
         if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(); }
@@ -239,6 +341,7 @@
     inputEl.addEventListener('input', () => {
         inputEl.style.height = 'auto';
         inputEl.style.height = Math.min(inputEl.scrollHeight, 160) + 'px';
+        refreshSendState();
     });
 
     // sidebar pre-populate (messages already loaded via ws.onopen → loadConversations(true))
diff --git a/app/channels/web_channel.py b/app/channels/web_channel.py
index bee8d8c..95b89c5 100644
--- a/app/channels/web_channel.py
+++ b/app/channels/web_channel.py
@@ -21,7 +21,7 @@
 import uvicorn
 from pathlib import Path
 from fasthtml.common import (
-    Button, Div, Head, Html, Link, Meta, Script, Span,
+    Button, Div, Head, Html, Input, Label, Link, Meta, NotStr, Script, Span,
     Textarea, Title, Body, H1, P, fast_app,
 )
 from starlette.routing import WebSocketRoute
@@ -38,6 +38,20 @@
 # FastHTML page builder                                                        #
 # --------------------------------------------------------------------------- #
 
+# Bump when web_channel.css / web_channel.js change, so browsers (Edge caches
+# static assets aggressively) fetch the new copy instead of a stale one.
+_ASSET_VERSION = "3"
+
+# Paperclip icon for the attach button (inline so it inherits theme colors).
+_PAPERCLIP_SVG = (
+    '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" '
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round" '
+    'stroke-linejoin="round" aria-hidden="true">'
+    '<path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 '
+    '5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>'
+)
+
+
 def _build_page() -> Html:
     return Html(
         Head(
@@ -47,7 +61,7 @@ def _build_page() -> Html:
             Link(rel="preconnect", href="https://fonts.googleapis.com"),
             Link(rel="stylesheet",
                  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap"),
-            Link(rel="stylesheet", href="/static/web_channel.css"),
+            Link(rel="stylesheet", href=f"/static/web_channel.css?v={_ASSET_VERSION}"),
         ),
         Body(
             Div(
@@ -100,8 +114,36 @@ def _build_page() -> Html:
                             Div(Div(Span(), Span(), Span(), cls="dots"), cls="thinking-bubble"),
                             id="thinking",
                         ),
+                        # Selected-attachment preview chips (populated by JS)
+                        Div(id="attachments"),
                         # Input area
                         Div(
+                            # Hidden native file picker. A <label for> (not a JS
+                            # click) opens it — native label activation works
+                            # consistently across browsers (Edge included),
+                            # whereas calling input.click() on a display:none
+                            # input is unreliable in Edge. Hide it with an inline
+                            # visually-hidden style (not display:none, and not an
+                            # external CSS class): display:none suppresses the
+                            # `change` event in Edge, and an inline style can't be
+                            # defeated by a stale cached stylesheet.
+                            Input(
+                                type="file",
+                                id="file-input",
+                                multiple=True,
+                                cls="visually-hidden",
+                                style=(
+                                    "position:absolute;width:1px;height:1px;"
+                                    "padding:0;margin:-1px;overflow:hidden;"
+                                    "clip:rect(0,0,0,0);white-space:nowrap;border:0"
+                                ),
+                            ),
+                            Label(
+                                NotStr(_PAPERCLIP_SVG),
+                                id="attach-btn",
+                                title="Attach files",
+                                **{"for": "file-input"},
+                            ),
                             Textarea(
                                 id="msg-input",
                                 placeholder="Message anotherbot…  (Enter to send, Shift+Enter for newline)",
@@ -117,7 +159,7 @@ def _build_page() -> Html:
                 ),
                 id="app",
             ),
-            Script(src="/static/web_channel.js"),
+            Script(src=f"/static/web_channel.js?v={_ASSET_VERSION}"),
         ),
         lang="en",
     )
@@ -148,8 +190,14 @@ def __init__(
         self._connections: dict[str, WebSocket] = {}
         self._send_locks: dict[str, asyncio.Lock] = {}
         self._conn_lock = asyncio.Lock()
+        from .. import config as _cfg
+        self._upload_dir = _cfg.PROJECT_HOME / "uploads"
         mq.register(self, self.send_message)
 
+    # Cap on a single multipart upload request (combined across files). The
+    # agent enforces its own per-message limit when building the LLM payload.
+    _MAX_UPLOAD_BYTES = 5 * 1024 * 1024  # 5 MB
+
     # -- Channel ABC --------------------------------------------------------
 
     @property
@@ -221,6 +269,58 @@ def status_api(req):
             model = _rt.get("model", _cfg.get("model", "AI"))
             return JSONResponse({"model": model})
 
+        @rt("/api/upload", methods=["POST"])
+        async def upload_api(req):
+            """Accept one or more multipart files and store them on disk.
+
+            Returns the server-side basenames the browser then references in
+            its WebSocket ``message`` frame via the ``files`` field.  Files are
+            written under ``$ANOTHERBOT_HOME/uploads`` with a UUID prefix so
+            concurrent clients never collide.
+            """
+            from starlette.responses import JSONResponse, Response
+            form = await req.form()
+            uploads = [f for f in form.getlist("files") if getattr(f, "filename", None)]
+            if not uploads:
+                return Response("No files provided", status_code=400)
+
+            self._upload_dir.mkdir(parents=True, exist_ok=True)
+            saved: list[dict] = []
+            total = 0
+            try:
+                for uf in uploads:
+                    name = Path(uf.filename).name
+                    stored = f"{uuid.uuid4().hex}_{name}"
+                    out_path = self._upload_dir / stored
+                    too_large = False
+                    with out_path.open("wb") as out:
+                        while True:
+                            chunk = await uf.read(64 * 1024)
+                            if not chunk:
+                                break
+                            total += len(chunk)
+                            if total > self._MAX_UPLOAD_BYTES:
+                                too_large = True
+                                break
+                            out.write(chunk)
+                    if too_large:
+                        out_path.unlink(missing_ok=True)
+                        for s in saved:
+                            (self._upload_dir / s["path"]).unlink(missing_ok=True)
+                        limit_mb = max(1, self._MAX_UPLOAD_BYTES // (1024 * 1024))
+                        return JSONResponse(
+                            {"error": f"Upload exceeds {limit_mb} MB limit"},
+                            status_code=413,
+                        )
+                    saved.append({"path": stored, "name": name})
+            finally:
+                for uf in uploads:
+                    close = getattr(uf, "close", None)
+                    if close:
+                        await close()
+
+            return JSONResponse({"files": saved})
+
         # Starlette WebSocket route (low-level, for multi-client management)
         async def _ws_endpoint(ws: WebSocket) -> None:
             await ws.accept()
@@ -237,15 +337,14 @@ async def _ws_endpoint(ws: WebSocket) -> None:
                     if len(raw) > 65_536:
                         await ws.close(code=1009, reason="Message too large")
                         return
-                    content = self._extract_content(raw)
-                    if not content:
+                    content, files = self._extract_message(raw)
+                    if not content and not files:
                         continue
 
-                    if content.startswith("/"):
+                    is_command = bool(content and content.startswith("/"))
+                    if is_command:
                         cmd = content[1:].split(maxsplit=1)
-                        if not cmd:
-                            continue
-                        name = cmd[0].lower()
+                        name = cmd[0].lower() if cmd else ""
                         # /whoami is handled inline — it needs the per-connection client_id.
                         # All other commands (/help, /status, /stop, /new, /load, …) are
                         # forwarded to BackgroundAgent's CommandRegistry for consistency
@@ -257,14 +356,18 @@ async def _ws_endpoint(ws: WebSocket) -> None:
                             )
                             continue
 
+                    metadata = {
+                        "websocket_id": client_id,
+                        "is_command": is_command,
+                    }
+                    if files:
+                        metadata["files"] = files
+
                     await self.mq.incoming.put(
                         IncomingMessage(
-                            content=content,
+                            content=content or "",
                             channel=ChannelType.WEB,
-                            metadata={
-                                "websocket_id": client_id,
-                                "is_command": content.startswith("/"),
-                            },
+                            metadata=metadata,
                         )
                     )
             except WebSocketDisconnect:
@@ -333,6 +436,47 @@ def _extract_content(raw: str) -> str | None:
             return str(data.get("content") or "").strip() or None
         return raw
 
+    def _extract_message(self, raw: str) -> tuple[str | None, list[str]]:
+        """Parse a raw WebSocket frame into (text, attachment_paths).
+
+        ``files`` is a list of basenames the browser received from
+        ``/api/upload``; each is resolved against the upload dir and dropped
+        if it escapes that dir or no longer exists.
+        """
+        stripped = raw.strip()
+        if not stripped:
+            return None, []
+
+        try:
+            data = json.loads(stripped)
+        except (json.JSONDecodeError, TypeError):
+            return stripped, []
+
+        if isinstance(data, dict) and data.get("type") == "message":
+            content = str(data.get("content") or "").strip() or None
+            files = self._resolve_upload_paths(data.get("files"))
+            return content, files
+
+        return stripped, []
+
+    def _resolve_upload_paths(self, names: object) -> list[str]:
+        """Map client-supplied upload basenames to validated absolute paths.
+
+        Only the basename is honoured (joined to the upload dir), so a client
+        can never reference files outside ``self._upload_dir``.
+        """
+        if not isinstance(names, list):
+            return []
+        upload_dir = self._upload_dir.resolve()
+        resolved: list[str] = []
+        for name in names:
+            if not isinstance(name, str) or not name:
+                continue
+            candidate = (upload_dir / Path(name).name).resolve()
+            if candidate.parent == upload_dir and candidate.is_file():
+                resolved.append(str(candidate))
+        return resolved
+
     async def _safe_send_json(self, client_id: str, payload: dict) -> None:
         async with self._conn_lock:
             ws = self._connections.get(client_id)
diff --git a/app/cli/cli_agent.py b/app/cli/cli_agent.py
index a330744..29a7c65 100755
--- a/app/cli/cli_agent.py
+++ b/app/cli/cli_agent.py
@@ -53,7 +53,10 @@ async def _on_response(self, content: str | None) -> None:
 
     async def agent_loop(self, message: str, metadata: dict = None) -> str:
         self._trim_messages()
-        self.history.add_message("user", message, self.conversation_id)
+        attachments = self._as_list((metadata or {}).get("files"))
+        user_msg = self._build_user_message(message, metadata)
+        placeholder_content = self._build_placeholder_content(message, attachments)
+        self.history.add_message("user", placeholder_content, self.conversation_id)
 
         conv = self._store.get(self.conversation_id)
         system_context = get_default_sys_prompt({
@@ -62,11 +65,15 @@ async def agent_loop(self, message: str, metadata: dict = None) -> str:
             "conversation_name": conv["name"] if conv else "New Conversation",
         })
         system = [{"role": "system", "content": system_context}] if system_context else []
-        session_messages = system + self.messages[:] + [{"role": "user", "content": message}]
+        session_messages = system + self.messages[:] + [user_msg]
 
         final_content = await self._loop(session_messages, get_all_tool_specs())
 
-        self.messages.append({"role": "user", "content": message})
+        if runtime.get("trace"):
+            from ..infra.tracer import write_trace
+            write_trace(session_messages)
+
+        self.messages.append({"role": "user", "content": placeholder_content})
         self.messages.append({"role": "assistant", "content": final_content})
         self.history.add_message("assistant", final_content, self.conversation_id)
         self._store.touch(self.conversation_id)
diff --git a/app/config.py b/app/config.py
index ed9f4d8..ee9342f 100644
--- a/app/config.py
+++ b/app/config.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import sqlite3
 import tomllib
 from pathlib import Path
 
@@ -12,6 +13,21 @@
 APP_DB = PROJECT_HOME / "app.db"
 
 
+def get_db_connection(db_path: Path = APP_DB, *, timeout: float = 30.0,
+                       isolation_level: str | None = "") -> sqlite3.Connection:
+    """Open a connection to a shared SQLite db (e.g. APP_DB) with settings safe
+    for concurrent access from multiple asyncio tasks/channels.
+
+    WAL mode lets readers proceed without blocking the writer, and the longer
+    busy_timeout makes writers retry instead of immediately raising
+    "database is locked" when another connection briefly holds the write lock.
+    """
+    conn = sqlite3.connect(db_path, timeout=timeout, isolation_level=isolation_level)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(f"PRAGMA busy_timeout={int(timeout * 1000)}")
+    return conn
+
+
 def load(path: Path | str = HOME_CONFIG_PATH) -> None:
     global _config
 
diff --git a/app/core/agent.py b/app/core/agent.py
index b9e8b88..f4aaa08 100755
--- a/app/core/agent.py
+++ b/app/core/agent.py
@@ -1,5 +1,7 @@
 import asyncio
+import base64
 import json
+import mimetypes
 import os
 import platform
 import re
@@ -19,9 +21,6 @@ def _slugify(name: str) -> str:
     return re.sub(r"[^a-z0-9-]", "", name.strip().lower().replace(" ", "-"))[:40]
 
 
-TOOL_RESULT_HISTORY_LIMIT = 100
-
-
 def get_default_sys_prompt(context: dict | None = None) -> str:
     ctx = context or {}
     channel = ctx.get("channel", "cli")
@@ -75,12 +74,95 @@ def _serialize_assistant_msg(msg) -> dict:
         d = {"role": msg.role, "content": msg.content}
         if msg.tool_calls:
             d["tool_calls"] = [tc.model_dump() for tc in msg.tool_calls]
-            raw = msg.model_dump()
-            reasoning = raw.get("reasoning_content") or raw.get("reasoning")
-            if reasoning:
-                d["reasoning_content"] = reasoning
+        raw = msg.model_dump()
+        reasoning = raw.get("reasoning_content") or raw.get("reasoning")
+        if reasoning:
+            d["reasoning_content"] = reasoning
         return d
 
+
+    @staticmethod
+    def _as_list(value) -> list:
+        if value is None:
+            return []
+        if isinstance(value, (str, os.PathLike)):
+            return [value]
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                if not isinstance(item, (str, os.PathLike)):
+                    raise TypeError(
+                        f"metadata['files'] entries must be paths, got {type(item).__name__}"
+                    )
+            return list(value)
+        raise TypeError(f"metadata['files'] must be a path or list of paths, got {type(value).__name__}")
+
+    _MAX_COMBINED_ATTACHMENT_BYTES = 5 * 1024 * 1024  # 5 MB combined across all attachments
+
+    @classmethod
+    def _attachment_part(cls, attachment: str) -> dict:
+        path = Path(attachment).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"Attachment not found: {path}")
+
+        mime_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+        try:
+            raw = path.read_bytes()
+        except PermissionError as e:
+            raise PermissionError(f"Cannot read attachment: {path}") from e
+
+        log.info(f"Encoding attachment {path} ({mime_type}, {len(raw)} bytes)")
+        
+        data_url = f"data:{mime_type};base64,{base64.b64encode(raw).decode('ascii')}"
+
+        if mime_type.startswith("image/"):
+            return {
+                "type": "image_url",
+                "image_url": {"url": data_url},
+            }
+
+        return {
+            "type": "file",
+            "file": {
+                "filename": path.name,
+                "file_data": data_url,
+            },
+        }
+
+    @classmethod
+    def _build_user_message(cls, message: str, metadata: dict | None = None) -> dict:
+        metadata = metadata or {}
+        attachments = cls._as_list(metadata.get("files"))
+        if not attachments:
+            return {"role": "user", "content": message}
+
+        # Validate every path and accumulate size before encoding anything,
+        # so a bad path always raises the same clear error regardless of order.
+        total_size = 0
+        for a in attachments:
+            p = Path(a).expanduser()
+            if not p.is_file():
+                raise FileNotFoundError(f"Attachment not found: {p}")
+            try:
+                total_size += p.stat().st_size
+            except PermissionError as e:
+                raise PermissionError(f"Cannot stat attachment: {p}") from e
+        if total_size > cls._MAX_COMBINED_ATTACHMENT_BYTES:
+            raise ValueError(
+                f"Total attachment size {total_size / 1024 / 1024:.1f} MB exceeds "
+                f"{cls._MAX_COMBINED_ATTACHMENT_BYTES / 1024 / 1024:.0f} MB combined limit"
+            )
+
+        content = [{"type": "text", "text": message}]
+        content.extend(cls._attachment_part(str(a)) for a in attachments)
+        return {"role": "user", "content": content}
+
+    @staticmethod
+    def _build_placeholder_content(message: str, attachments: list) -> str:
+        if not attachments:
+            return message
+        placeholders = " ".join(f"[Attachment: {Path(a).name}]" for a in attachments)
+        return f"{message} {placeholders}"
+
     # --- hooks ---
 
     async def _on_thinking(self, content: str | None) -> None:
@@ -130,7 +212,7 @@ async def handle_tool_call(self, tool_call) -> str:
         from .tool_calls import run_tool_async  # lazy — tool_calls imports scheduled_tasks which imports Agent
         tool_name = tool_call.function.name
         try:
-            tool_args = json.loads(tool_call.function.arguments)
+            tool_args = json.loads((tool_call.function.arguments or "").strip() or "{}")
             if not await self._check_permission(tool_name, tool_args):
                 return "User denied permission to run this tool. Ask for permission to run the tool again if you want to try running it."
             await self._on_tool_start(tool_name, tool_args)
@@ -175,10 +257,11 @@ async def _loop(self, messages: list, tool_specs: list) -> str:
                     messages.append({"role": "tool", "tool_call_id": tc.id, "name": tc.function.name, "content": result})
                     log.info(f"{result[:250]}...")
             else:
+                messages.append(self._serialize_assistant_msg(assistant_message))
                 await self._on_response(assistant_message.content)
-                if finish_reason == "stop":
-                    messages.append(self._serialize_assistant_msg(assistant_message))
-                    break
+                if finish_reason not in ("stop", "length") and finish_reason is not None:
+                    log.warning(f"Unexpected finish_reason={finish_reason!r}, treating as terminal")
+                break
 
             if self._should_stop():
                 break
diff --git a/app/core/background_agent.py b/app/core/background_agent.py
index 0a73d16..b599828 100755
--- a/app/core/background_agent.py
+++ b/app/core/background_agent.py
@@ -45,7 +45,7 @@ def __init__(self, mq: MessageQueue = None, channel: Channel = None, max_iterati
         # Lazy import to avoid circular: commands imports runtime which is fine,
         # but conversation commands need self reference so we build registry here.
         from ..channels.commands import (
-            CommandRegistry, BotCommand, help_cmd, make_status_cmd, model_cmd,
+            CommandRegistry, BotCommand, help_cmd, make_status_cmd, model_cmd, trace_cmd,
             list_conversations_cmd, new_conversation_cmd, load_conversation_cmd,
             fork_conversation_cmd, rename_conversation_cmd, export_conversation_cmd,
             mcp_cmd,
@@ -53,6 +53,7 @@ def __init__(self, mq: MessageQueue = None, channel: Channel = None, max_iterati
         self.registry = CommandRegistry()
         ch = self._channel_str
         self.registry.register(BotCommand("model",  "Get or set model. Usage: /model [name]", model_cmd))
+        self.registry.register(BotCommand("trace",  "Toggle LLM tracing. Usage: /trace [on|off]", trace_cmd))
         self.registry.register(BotCommand("status", "Show bot status.", make_status_cmd(ch)))
         self.registry.register(BotCommand("stop",   "Pause the bot.", self._stop_cmd))
         self.registry.register(BotCommand("list",   "List conversations.", list_conversations_cmd(self._store, ch)))
@@ -125,7 +126,10 @@ async def agent_loop(self, message: str, metadata: dict = None) -> str:
         self._trim_messages()
         self._empty_retries = 0
         self._reply_metadata = metadata or {}
-        self.history.add_message("user", message, self.conversation_id)
+        attachments = self._as_list((metadata or {}).get("files"))
+        user_msg = self._build_user_message(message, metadata)
+        placeholder_content = self._build_placeholder_content(message, attachments)
+        self.history.add_message("user", placeholder_content, self.conversation_id)
 
         conv = self._store.get(self.conversation_id)
         system_context = get_default_sys_prompt({
@@ -134,13 +138,19 @@ async def agent_loop(self, message: str, metadata: dict = None) -> str:
             "conversation_name": conv["name"] if conv else "New Conversation",
         })
         system = [{"role": "system", "content": system_context}] if system_context else []
-        session_messages = system + self.messages[:] + [{"role": "user", "content": message}]
+        session_messages = system + self.messages[:] + [user_msg]
 
         final_content = await self._loop(session_messages, get_all_tool_specs())
 
+        if runtime.get("trace"):
+            from ..infra.tracer import write_trace
+            path = write_trace(session_messages)
+            if path:
+                runtime.set("last_trace", path.name)
+
         self.channel.clear_stopped()
 
-        self.messages.append({"role": "user", "content": message})
+        self.messages.append({"role": "user", "content": placeholder_content})
         self.messages.append({"role": "assistant", "content": final_content})
         self.history.add_message("assistant", final_content, self.conversation_id)
         self._store.touch(self.conversation_id)
diff --git a/app/core/helper_agent.py b/app/core/helper_agent.py
index f70e100..46e8132 100644
--- a/app/core/helper_agent.py
+++ b/app/core/helper_agent.py
@@ -17,5 +17,5 @@ async def run(self, prompt: str) -> str:
 
     async def agent_loop(self, message: str, metadata: dict = None) -> str:
         from .tool_calls import helper_tool_specs  # lazy — avoids circular import via scheduled_tasks
-        self.messages.append({"role": "user", "content": message})
+        self.messages.append(self._build_user_message(message, metadata))
         return await self._loop(self.messages, helper_tool_specs)
diff --git a/app/core/scheduled_tasks.py b/app/core/scheduled_tasks.py
index cb8dff2..7f9bce1 100755
--- a/app/core/scheduled_tasks.py
+++ b/app/core/scheduled_tasks.py
@@ -2,7 +2,7 @@
 
 from datetime import datetime, timedelta
 from ..infra.app_logging import log
-from ..config import APP_DB
+from ..config import APP_DB, get_db_connection
 import sqlite3
 import asyncio
 from .helper_agent import HelperAgent
@@ -19,7 +19,7 @@ def __init__(self, mqs: dict = None, channels: dict = None):
         self._init_tasks_db()
 
     def _init_tasks_db(self):
-        with sqlite3.connect(APP_DB) as conn:
+        with get_db_connection() as conn:
 
             conn.execute("""
                 CREATE TABLE IF NOT EXISTS tasks (
@@ -50,14 +50,18 @@ def _init_tasks_db(self):
             """)
 
             conn.commit()
+        conn.close()
 
 
     def load_tasks(self) -> list[dict]:
         query = """SELECT name, prompt, enabled, repeat, interval_mins,
                           last_run, next_run, delivery_channel, run_count, created_at
                    FROM tasks"""
-        with sqlite3.connect(APP_DB) as conn:
+        conn = get_db_connection()
+        try:
             rows = conn.execute(query).fetchall()
+        finally:
+            conn.close()
 
         return [{"name": n, "prompt": p, "enabled": e, "repeat": rpt,
                  "interval_mins": i, "last_run": lr, "next_run": nr,
@@ -68,48 +72,57 @@ def load_tasks(self) -> list[dict]:
     def add_task(self, name: str, prompt: str, next_run: str, interval_mins: int = 1,
                  repeat: int = 0, delivery_channel: str = "telegram", enabled: int = 1):
         now = datetime.now().isoformat()
-        with sqlite3.connect(APP_DB) as conn:
+        conn = get_db_connection()
+        try:
             try:
-                conn.execute("""
-                    INSERT INTO tasks (name, prompt, interval_mins, repeat, next_run, delivery_channel, enabled, created_at)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-                """, (name, prompt, interval_mins, repeat, next_run or now, delivery_channel, enabled, now))
-                conn.commit()
+                with conn:
+                    conn.execute("""
+                        INSERT INTO tasks (name, prompt, interval_mins, repeat, next_run, delivery_channel, enabled, created_at)
+                        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                    """, (name, prompt, interval_mins, repeat, next_run or now, delivery_channel, enabled, now))
             except sqlite3.IntegrityError:
                 raise ValueError(f"Task '{name}' already exists")
+        finally:
+            conn.close()
 
     def remove_task(self, name: str):
-        with sqlite3.connect(APP_DB) as conn:
+        with get_db_connection() as conn:
             conn.execute("DELETE FROM tasks WHERE name = ?", (name,))
             conn.commit()
+        conn.close()
 
     def update_task(self, name: str, **fields):
         if not fields:
             return
         set_clause = ", ".join(f"{col} = ?" for col in fields)
         values = list(fields.values()) + [name]
-        with sqlite3.connect(APP_DB) as conn:
-            if not conn.execute("SELECT name FROM tasks WHERE name = ?", (name,)).fetchone():
-                raise ValueError(f"Task '{name}' not found")
-            conn.execute(f"UPDATE tasks SET {set_clause} WHERE name = ?", values)
-            conn.commit()
+        conn = get_db_connection()
+        try:
+            with conn:
+                if not conn.execute("SELECT name FROM tasks WHERE name = ?", (name,)).fetchone():
+                    raise ValueError(f"Task '{name}' not found")
+                conn.execute(f"UPDATE tasks SET {set_clause} WHERE name = ?", values)
+        finally:
+            conn.close()
 
     def save_output(self, name: str, prompt: str, output: str,
                     status: str = "success", duration_secs: float = None):
-        with sqlite3.connect(APP_DB) as conn:
+        with get_db_connection() as conn:
             conn.execute("""
                 INSERT INTO task_outputs (name, prompt, output, status, duration_secs, timestamp)
                 VALUES (?, ?, ?, ?, ?, ?)
             """, (name, prompt, output, status, duration_secs, datetime.now().isoformat()))
             conn.commit()
+        conn.close()
 
     def get_output(self, name: str, num_entries: int = 5) -> list[dict]:
-        with sqlite3.connect(APP_DB) as conn:
+        with get_db_connection() as conn:
             rows = conn.execute("""
                 SELECT prompt, output, status, duration_secs, timestamp FROM task_outputs
                 WHERE name = ?
                 ORDER BY id DESC LIMIT ?
             """, (name, num_entries)).fetchall()
+        conn.close()
         return [{"prompt": p, "output": o, "status": s, "duration_secs": d, "timestamp": t}
                 for p, o, s, d, t in reversed(rows)]
 
@@ -145,10 +158,11 @@ def _after_run(self, task: dict, now: datetime):
                 intervals_passed = int(elapsed_secs // interval.total_seconds())
                 next_due = original_next + (intervals_passed + 1) * interval
             next_run = next_due.isoformat()
-            with sqlite3.connect(APP_DB) as conn:
+            with get_db_connection() as conn:
                 conn.execute("""UPDATE tasks SET last_run = ?, next_run = ?, run_count = run_count + 1
                                 WHERE name = ?""", (now.isoformat(), next_run, name))
                 conn.commit()
+            conn.close()
         else:
             self.remove_task(name)
 
diff --git a/app/infra/conversations.py b/app/infra/conversations.py
index b002190..e6618bd 100644
--- a/app/infra/conversations.py
+++ b/app/infra/conversations.py
@@ -7,16 +7,20 @@
 from datetime import datetime
 from pathlib import Path
 
-from ..config import APP_DB, PROJECT_HOME
+from ..config import APP_DB, PROJECT_HOME, get_db_connection
 from .app_logging import log
 
 
 @contextlib.contextmanager
 def _fk_conn(db_path: Path):
     """sqlite3 connection with FK constraints enforced."""
-    with sqlite3.connect(db_path) as conn:
+    conn = get_db_connection(db_path)
+    try:
         conn.execute("PRAGMA foreign_keys = ON")
-        yield conn
+        with conn:
+            yield conn
+    finally:
+        conn.close()
 
 
 class ConversationStore:
@@ -75,7 +79,7 @@ def _ensure_schema(self) -> None:
 
             # Phase 2: Migration — BEGIN IMMEDIATE for concurrency safety.
             # The WHERE conversation_id IS NULL guard makes this re-entrant.
-            mconn = sqlite3.connect(self.db_path, isolation_level=None)
+            mconn = get_db_connection(self.db_path, isolation_level=None)
             try:
                 mconn.execute("PRAGMA foreign_keys = ON")
                 mconn.execute("BEGIN IMMEDIATE")
diff --git a/app/infra/message_history.py b/app/infra/message_history.py
index cfbc930..7194cc9 100755
--- a/app/infra/message_history.py
+++ b/app/infra/message_history.py
@@ -4,7 +4,7 @@
 from datetime import datetime
 from pathlib import Path
 from .app_logging import log
-from ..config import APP_DB
+from ..config import APP_DB, get_db_connection
 
 def _est_tokens(content: str) -> int:
     return max(1, len(content) // 4)
@@ -18,7 +18,7 @@ def __init__(self, channel_type: str, db_path: Path = APP_DB):
     def _ensure_db(self):
         try:
             self.db_path.parent.mkdir(parents=True, exist_ok=True)
-            with sqlite3.connect(self.db_path) as conn:
+            with get_db_connection(self.db_path) as conn:
                 conn.execute("""
                     CREATE TABLE IF NOT EXISTS messages (
                         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -44,6 +44,7 @@ def _ensure_db(self):
                     ON messages(conversation_id)
                 """)
                 conn.commit()
+            conn.close()
 
         except sqlite3.Error as e:
             log.error(f"Error creating message history database: {str(e)}")
@@ -52,21 +53,22 @@ def _ensure_db(self):
     def add_message(self, role: str, content: str, conversation_id: int = None):
         timestamp = datetime.now().isoformat()
         est = _est_tokens(content)
-        with sqlite3.connect(self.db_path) as conn:
+        with get_db_connection(self.db_path) as conn:
             conn.execute(
                 "INSERT INTO messages (channel, role, content, timestamp, est_tokens, conversation_id) "
                 "VALUES (?, ?, ?, ?, ?, ?)",
                 (self.channel, role, content, timestamp, est, conversation_id),
             )
             conn.commit()
+        conn.close()
         log.info(f"Added message to history: role={role}, est_tokens={est}, content={content[:30]}...")
 
     def get_history(self, limit: int = 100) -> list[dict]:
-        with sqlite3.connect(self.db_path) as conn:
+        with get_db_connection(self.db_path) as conn:
             rows = conn.execute("""SELECT role, content FROM messages
                                     WHERE channel = ?
                                     ORDER BY id DESC LIMIT ?""", (self.channel, limit)).fetchall()
-            return [{"role": row[0], "content": row[1]} for row in reversed(rows)]
+        conn.close()
+        return [{"role": row[0], "content": row[1]} for row in reversed(rows)]
+
 
-    def prune_old_messages(self, older_than_days: int) -> None:
-        pass
diff --git a/app/infra/setup.py b/app/infra/setup.py
index 3a29fec..338a342 100755
--- a/app/infra/setup.py
+++ b/app/infra/setup.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from ..config import get_default_config, APP_NAME, APP_DB
+from ..config import get_default_config, APP_NAME
 from .app_logging import log
 
 def ensure_home_dir() -> None:
diff --git a/app/infra/tracer.py b/app/infra/tracer.py
new file mode 100644
index 0000000..c2b6065
--- /dev/null
+++ b/app/infra/tracer.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from ..core import runtime
+
+log = logging.getLogger(__name__)
+
+
+def write_trace(messages: list) -> Path | None:
+
+    tracedir: Path = runtime.get("tracedir")
+    model: str = runtime.get("model", "unknown")
+
+    try:
+        tracedir.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now().strftime("%m%d%Y_%H%M%S")
+        path = tracedir / f"trace_{ts}.json"
+        data = {
+            "timestamp": datetime.now().isoformat(),
+            "model": model,
+            "messages": messages,
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, default=str)
+        log.info(f"Trace written to {path}")
+        return path
+    except Exception as e:
+        log.warning(f"Failed to write trace: {e}")
+        return None
diff --git a/app/main.py b/app/main.py
index 5852e06..54da01c 100755
--- a/app/main.py
+++ b/app/main.py
@@ -4,6 +4,7 @@
 import asyncio
 import logging
 import os
+from pathlib import Path
 
 from . import config
 from .infra.app_logging import setup_logging, log
@@ -60,6 +61,10 @@ async def load_config() -> None:
 
 def parse_args():
     parser = argparse.ArgumentParser(prog="app")
+    parser.add_argument("--trace", action="store_true", default=False,
+                        help="Enable LLM call tracing")
+    parser.add_argument("--tracedir", default=str(config.PROJECT_HOME / "trace"), metavar="DIR",
+                        help="Trace output directory (default: ~/.crafterscode/trace)")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     cli_parser = subparsers.add_parser("cli", help="Run interactive CLI")
@@ -106,7 +111,7 @@ async def run_cli(args):
         return
 
     from .channels.commands import (
-        CommandRegistry, BotCommand, make_status_cmd, help_cmd, model_cmd,
+        CommandRegistry, BotCommand, make_status_cmd, help_cmd, model_cmd, trace_cmd,
         list_conversations_cmd, new_conversation_cmd, load_conversation_cmd,
         fork_conversation_cmd, rename_conversation_cmd, export_conversation_cmd,
         mcp_cmd,
@@ -114,6 +119,7 @@ async def run_cli(args):
     cli_registry = CommandRegistry()
     cli_registry.register(BotCommand("status",               "Show bot status.",                        make_status_cmd()))
     cli_registry.register(BotCommand("model",                "Get or set model. Usage: /model [name]",  model_cmd))
+    cli_registry.register(BotCommand("trace",               "Toggle LLM tracing. Usage: /trace [on|off]", trace_cmd))
     cli_registry.register(BotCommand("list",   "List conversations.",                      list_conversations_cmd(agent._store, agent._channel_str)))
     cli_registry.register(BotCommand("new",    "Start a new conversation.",                new_conversation_cmd(agent)))
     cli_registry.register(BotCommand("load",   "Load a conversation. Usage: /load <id>",   load_conversation_cmd(agent)))
@@ -155,6 +161,8 @@ async def main():
 
     runtime.set("model",  config.get("model", "deepseek/deepseek-v4-flash"))
     runtime.set("max_iterations", args.max_iterations)
+    runtime.set("trace", args.trace)
+    runtime.set("tracedir", Path(args.tracedir))
 
     from .core.mcp_manager import mcp_manager
     try:
diff --git a/tests/test_agent.py b/tests/test_agent.py
index 4cd818f..231d772 100644
--- a/tests/test_agent.py
+++ b/tests/test_agent.py
@@ -70,7 +70,7 @@ async def test_agent_loop_sends_system_context_to_llm():
     agent, mock_client = make_agent()
     with patch("app.cli.cli_agent.get_default_sys_prompt", return_value="system prompt"):
         await agent.agent_loop("hello")
-    call_messages = mock_client.chat.completions.create.call_args[1]["messages"]
+    call_messages = mock_client.chat.completions.create.call_args_list[0][1]["messages"]
     assert call_messages[0]["role"] == "system"
     assert call_messages[0]["content"] == "system prompt"
 
@@ -190,7 +190,7 @@ async def test_agent_loop_runs_tool_when_auto_approve():
 
 
 @pytest.mark.asyncio
-async def test_agent_loop_continues_when_finish_reason_not_stop():
+async def test_agent_loop_breaks_on_length_finish_reason():
     with patch("app.core.agent.Client") as MockClient:
         mock_client = MagicMock()
         MockClient.return_value.get_client.return_value = mock_client
@@ -210,23 +210,35 @@ async def test_agent_loop_continues_when_finish_reason_not_stop():
     response_partial = MagicMock()
     response_partial.choices = [choice_partial]
 
-    msg_final = MagicMock()
-    msg_final.tool_calls = None
-    msg_final.content = "final"
-    msg_final.model_dump.return_value = {"role": "assistant", "content": "final"}
-    choice_final = MagicMock()
-    choice_final.message = msg_final
-    choice_final.finish_reason = "stop"
-    response_final = MagicMock()
-    response_final.choices = [choice_final]
+    mock_client.chat.completions.create = AsyncMock(return_value=response_partial)
 
-    mock_client.chat.completions.create = AsyncMock(
-        side_effect=[response_partial, response_final]
-    )
+    result = await agent.agent_loop("continue")
+
+    assert mock_client.chat.completions.create.call_count == 1
+    assert result == "partial"
 
-    await agent.agent_loop("continue")
 
-    assert mock_client.chat.completions.create.call_count == 2
+@pytest.mark.asyncio
+async def test_agent_loop_calls_write_trace_when_enabled(tmp_path):
+    agent, _ = make_agent()
+    fake_path = tmp_path / "trace_01012026_120000.json"
+    with patch("app.core.runtime._store", {"trace": True, "tracedir": tmp_path, "model": "m"}):
+        with patch("app.infra.tracer.write_trace", return_value=fake_path) as mock_write:
+            await agent.agent_loop("hello")
+    mock_write.assert_called_once()
+    # write_trace now only receives messages (1 positional arg); tracedir/model come from runtime
+    args = mock_write.call_args[0]
+    assert len(args) == 1
+    assert isinstance(args[0], list)
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_does_not_call_write_trace_when_disabled(tmp_path):
+    agent, _ = make_agent()
+    with patch("app.core.runtime._store", {"trace": False, "tracedir": tmp_path, "model": "m"}):
+        with patch("app.infra.tracer.write_trace") as mock_write:
+            await agent.agent_loop("hello")
+    mock_write.assert_not_called()
 
 
 @pytest.mark.asyncio
@@ -268,3 +280,141 @@ async def test_agent_loop_gathers_multiple_tool_calls_in_parallel():
 
     mock_gather.assert_called_once()
     assert len(mock_gather.call_args[0]) == 2
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_sends_image_file_to_llm(tmp_path):
+    agent, mock_client = make_agent()
+    image_path = tmp_path / "screenshot.png"
+    image_path.write_bytes(b"fake image data")
+
+    await agent.agent_loop("What is in this image?", metadata={"files": [str(image_path)]})
+
+    call_messages = mock_client.chat.completions.create.call_args_list[0][1]["messages"]
+    user_message = call_messages[1]
+    assert user_message["role"] == "user"
+    assert user_message["content"][0] == {"type": "text", "text": "What is in this image?"}
+    assert user_message["content"][1]["type"] == "image_url"
+    assert user_message["content"][1]["image_url"]["url"].startswith("data:image/png;base64,")
+    stored_user_msg = agent.messages[-2]
+    assert stored_user_msg["role"] == "user"
+    # Placeholder now shows filename only, not full path
+    assert stored_user_msg["content"] == f"What is in this image? [Attachment: {image_path.name}]"
+    agent.history.add_message.assert_any_call(
+        "user", f"What is in this image? [Attachment: {image_path.name}]", agent.conversation_id
+    )
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_accepts_single_metadata_file_path(tmp_path):
+    agent, mock_client = make_agent()
+    image_path = tmp_path / "screenshot.jpg"
+    image_path.write_bytes(b"fake image data")
+
+    await agent.agent_loop("Describe this", metadata={"files": str(image_path)})
+
+    user_message = mock_client.chat.completions.create.call_args_list[0][1]["messages"][1]
+    assert user_message["content"][1]["image_url"]["url"].startswith("data:image/jpeg;base64,")
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_sends_multiple_image_files_to_llm(tmp_path):
+    agent, mock_client = make_agent()
+    png_path = tmp_path / "first.png"
+    jpg_path = tmp_path / "second.jpg"
+    png_path.write_bytes(b"first fake image data")
+    jpg_path.write_bytes(b"second fake image data")
+
+    await agent.agent_loop(
+        "Compare these images",
+        metadata={"files": [str(png_path), str(jpg_path)]},
+    )
+
+    user_message = mock_client.chat.completions.create.call_args_list[0][1]["messages"][1]
+    assert user_message["content"][0] == {"type": "text", "text": "Compare these images"}
+    assert len(user_message["content"]) == 3
+    assert user_message["content"][1]["image_url"]["url"].startswith("data:image/png;base64,")
+    assert user_message["content"][2]["image_url"]["url"].startswith("data:image/jpeg;base64,")
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_sends_metadata_files_to_llm(tmp_path):
+    agent, mock_client = make_agent()
+    file_path = tmp_path / "notes.txt"
+    file_path.write_text("plain text attachment", encoding="utf-8")
+
+    await agent.agent_loop("Summarize this file", metadata={"files": [str(file_path)]})
+
+    user_message = mock_client.chat.completions.create.call_args_list[0][1]["messages"][1]
+    assert user_message["content"][0] == {"type": "text", "text": "Summarize this file"}
+    assert user_message["content"][1]["type"] == "file"
+    assert user_message["content"][1]["file"]["filename"] == "notes.txt"
+    assert user_message["content"][1]["file"]["file_data"].startswith("data:text/plain;base64,")
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_sends_image_files_as_images(tmp_path):
+    agent, mock_client = make_agent()
+    image_path = tmp_path / "diagram.png"
+    file_path = tmp_path / "report.pdf"
+    image_path.write_bytes(b"fake image data")
+    file_path.write_bytes(b"%PDF-1.4 fake pdf data")
+
+    await agent.agent_loop(
+        "Use these attachments",
+        metadata={"files": [str(image_path), str(file_path)]},
+    )
+
+    user_message = mock_client.chat.completions.create.call_args_list[0][1]["messages"][1]
+    assert user_message["content"][1]["type"] == "image_url"
+    assert user_message["content"][1]["image_url"]["url"].startswith("data:image/png;base64,")
+    assert user_message["content"][2]["type"] == "file"
+    assert user_message["content"][2]["file"]["file_data"].startswith("data:application/pdf;base64,")
+
+
+def test_as_list_rejects_non_path_entries():
+    with pytest.raises(TypeError):
+        Agent._as_list([123])
+    with pytest.raises(TypeError):
+        Agent._as_list(123)
+    assert Agent._as_list(["a", "b"]) == ["a", "b"]
+    assert Agent._as_list("a") == ["a"]
+    assert Agent._as_list(None) == []
+
+
+def test_as_list_does_not_silently_drop_empty_string():
+    # Only None means "no attachments"; an empty string path must surface
+    # as a loud failure downstream rather than being dropped.
+    assert Agent._as_list("") == [""]
+
+
+def test_build_user_message_rejects_combined_oversized(tmp_path, monkeypatch):
+    f1 = tmp_path / "a.txt"
+    f2 = tmp_path / "b.txt"
+    f1.write_bytes(b"x" * 60)
+    f2.write_bytes(b"x" * 60)
+    monkeypatch.setattr(Agent, "_MAX_COMBINED_ATTACHMENT_BYTES", 100)
+    with pytest.raises(ValueError, match="exceeds"):
+        Agent._build_user_message("hi", metadata={"files": [str(f1), str(f2)]})
+
+
+def test_build_user_message_does_not_skip_size_check_for_missing_file(tmp_path, monkeypatch):
+    monkeypatch.setattr(Agent, "_MAX_COMBINED_ATTACHMENT_BYTES", 100)
+    with pytest.raises(FileNotFoundError):
+        Agent._build_user_message("hi", metadata={"files": ["/nonexistent/file.txt"]})
+
+
+def test_build_placeholder_content():
+    assert Agent._build_placeholder_content("hello", []) == "hello"
+    # Placeholder now shows filename only, not full path
+    assert Agent._build_placeholder_content("look", ["/tmp/a.png"]) == "look [Attachment: a.png]"
+    assert Agent._build_placeholder_content("check", ["/a.pdf", "/b.png"]) == "check [Attachment: a.pdf] [Attachment: b.png]"
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_does_not_persist_history_when_attachment_invalid(tmp_path):
+    agent, mock_client = make_agent()
+    non_file = tmp_path / "missing.png"
+    with pytest.raises(FileNotFoundError):
+        await agent.agent_loop("hi", metadata={"files": [str(non_file)]})
+    agent.history.add_message.assert_not_called()
diff --git a/tests/test_background_agent.py b/tests/test_background_agent.py
index 608e2cd..dc8a502 100644
--- a/tests/test_background_agent.py
+++ b/tests/test_background_agent.py
@@ -307,6 +307,40 @@ async def test_process_incoming_sends_error_to_user_on_agent_loop_failure():
     assert error_msg.metadata == {"chat_id": 99}
 
 
+@pytest.mark.asyncio
+async def test_agent_loop_calls_write_trace_when_enabled(tmp_path):
+    agent, _, _ = make_agent()
+    fake_path = tmp_path / "trace_01012026_120000.json"
+    with patch("app.core.runtime._store", {"trace": True, "tracedir": tmp_path, "model": "m"}):
+        with patch("app.infra.tracer.write_trace", return_value=fake_path) as mock_write:
+            await agent.agent_loop("hello")
+    mock_write.assert_called_once()
+    # write_trace now only receives messages (1 positional arg); tracedir/model come from runtime
+    args = mock_write.call_args[0]
+    assert len(args) == 1
+    assert isinstance(args[0], list)
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_does_not_call_write_trace_when_disabled(tmp_path):
+    agent, _, _ = make_agent()
+    with patch("app.core.runtime._store", {"trace": False, "tracedir": tmp_path, "model": "m"}):
+        with patch("app.infra.tracer.write_trace") as mock_write:
+            await agent.agent_loop("hello")
+    mock_write.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_agent_loop_sets_last_trace_on_success(tmp_path):
+    agent, _, _ = make_agent()
+    fake_path = tmp_path / "trace_01012026_120000.json"
+    mock_store = {"trace": True, "tracedir": tmp_path, "model": "m"}
+    with patch("app.core.runtime._store", mock_store):
+        with patch("app.infra.tracer.write_trace", return_value=fake_path):
+            await agent.agent_loop("hello")
+    assert mock_store.get("last_trace") == fake_path.name
+
+
 @pytest.mark.asyncio
 async def test_agent_loop_gathers_multiple_tool_calls_in_parallel():
     agent, mock_client, mq = make_agent()
diff --git a/tests/test_commands.py b/tests/test_commands.py
index 02eddef..93b37d6 100644
--- a/tests/test_commands.py
+++ b/tests/test_commands.py
@@ -1,7 +1,8 @@
 import pytest
+from pathlib import Path
 from unittest.mock import AsyncMock, patch
 
-from app.channels.commands import BotCommand, CommandRegistry, status_cmd, help_cmd, model_cmd
+from app.channels.commands import BotCommand, CommandRegistry, status_cmd, help_cmd, model_cmd, trace_cmd
 
 
 def make_registry(*extra: BotCommand) -> CommandRegistry:
@@ -135,3 +136,71 @@ async def test_model_cmd_sets_model():
         result = await model_cmd("new-model")
     assert "new-model" in result
     assert mock_store["model"] == "new-model"
+
+
+# --- trace_cmd ---
+
+@pytest.mark.asyncio
+async def test_trace_cmd_shows_off_when_no_args():
+    with patch("app.core.runtime._store", {"trace": False, "tracedir": Path("/tmp/traces")}):
+        result = await trace_cmd("")
+    assert "off" in result
+
+
+@pytest.mark.asyncio
+async def test_trace_cmd_shows_on_when_no_args():
+    with patch("app.core.runtime._store", {"trace": True, "tracedir": Path("/tmp/traces")}):
+        result = await trace_cmd("")
+    assert "on" in result
+
+
+@pytest.mark.asyncio
+async def test_trace_cmd_on_enables_tracing():
+    mock_store = {"trace": False, "tracedir": Path("/tmp/traces")}
+    with patch("app.core.runtime._store", mock_store):
+        result = await trace_cmd("on")
+    assert mock_store["trace"] is True
+    assert "on" in result.lower()
+
+
+@pytest.mark.asyncio
+async def test_trace_cmd_off_disables_tracing():
+    mock_store = {"trace": True, "tracedir": Path("/tmp/traces")}
+    with patch("app.core.runtime._store", mock_store):
+        result = await trace_cmd("off")
+    assert mock_store["trace"] is False
+    assert "off" in result.lower()
+
+
+@pytest.mark.asyncio
+async def test_trace_cmd_includes_tracedir_in_response():
+    with patch("app.core.runtime._store", {"trace": False, "tracedir": Path("/my/traces")}):
+        result = await trace_cmd("on")
+    assert "/my/traces" in result
+
+
+# --- status_cmd tracing line ---
+
+@pytest.mark.asyncio
+async def test_status_includes_tracing_off():
+    with patch("app.core.runtime._store", {"trace": False, "model": "m"}):
+        result = await status_cmd()
+    assert "Tracing" in result
+    assert "off" in result
+
+
+@pytest.mark.asyncio
+async def test_status_shows_tracing_on_with_filename():
+    mock_store = {"trace": True, "last_trace": "trace_06142026_103045.json", "model": "m"}
+    with patch("app.core.runtime._store", mock_store):
+        result = await status_cmd()
+    assert "on" in result
+    assert "trace_06142026_103045.json" in result
+
+
+@pytest.mark.asyncio
+async def test_status_shows_tracing_on_without_filename():
+    with patch("app.core.runtime._store", {"trace": True, "model": "m"}):
+        result = await status_cmd()
+    assert "Tracing" in result
+    assert "on" in result
diff --git a/tests/test_main.py b/tests/test_main.py
index e00af01..ceecb03 100644
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -224,6 +224,47 @@ async def fake_input_loop():
     agent_mock.agent_loop.assert_any_call("third")
 
 
+# ---------------------------------------------------------------------------
+# --trace / --tracedir
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_main_trace_defaults_to_false():
+    mock_store = {}
+    agent_mock = MagicMock()
+    agent_mock.agent_loop = AsyncMock()
+    with patch("sys.argv", ["prog", "cli", "-p", "hi", "--no-repl"]), \
+         patch("app.main.CliAgent", return_value=agent_mock), \
+         patch("app.core.runtime._store", mock_store):
+        await main()
+    assert mock_store.get("trace") is False
+
+
+@pytest.mark.asyncio
+async def test_main_trace_flag_sets_runtime_true(tmp_path):
+    mock_store = {}
+    agent_mock = MagicMock()
+    agent_mock.agent_loop = AsyncMock()
+    with patch("sys.argv", ["prog", "--trace", "--tracedir", str(tmp_path), "cli", "-p", "hi", "--no-repl"]), \
+         patch("app.main.CliAgent", return_value=agent_mock), \
+         patch("app.core.runtime._store", mock_store):
+        await main()
+    assert mock_store.get("trace") is True
+    assert mock_store.get("tracedir") == tmp_path
+
+
+@pytest.mark.asyncio
+async def test_main_tracedir_defaults_to_project_home_trace():
+    mock_store = {}
+    agent_mock = MagicMock()
+    agent_mock.agent_loop = AsyncMock()
+    with patch("sys.argv", ["prog", "cli", "-p", "hi", "--no-repl"]), \
+         patch("app.main.CliAgent", return_value=agent_mock), \
+         patch("app.core.runtime._store", mock_store):
+        await main()
+    assert "trace" in str(mock_store.get("tracedir"))
+
+
 # ---------------------------------------------------------------------------
 # initialize_mcp
 # ---------------------------------------------------------------------------
diff --git a/tests/test_tracer.py b/tests/test_tracer.py
new file mode 100644
index 0000000..97cac73
--- /dev/null
+++ b/tests/test_tracer.py
@@ -0,0 +1,49 @@
+import json
+import pytest
+from pathlib import Path
+from unittest.mock import patch
+
+from app.infra.tracer import write_trace
+
+
+def test_write_trace_creates_file(tmp_path):
+    messages = [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "hi"}]
+    with patch("app.core.runtime._store", {"tracedir": tmp_path, "model": "test-model"}):
+        path = write_trace(messages)
+    assert path is not None
+    assert path.exists()
+
+
+def test_write_trace_file_content(tmp_path):
+    messages = [{"role": "user", "content": "hello"}]
+    with patch("app.core.runtime._store", {"tracedir": tmp_path, "model": "test-model"}):
+        path = write_trace(messages)
+    data = json.loads(path.read_text())
+    assert data["model"] == "test-model"
+    assert data["messages"] == messages
+    assert "timestamp" in data
+
+
+def test_write_trace_filename_format(tmp_path):
+    with patch("app.core.runtime._store", {"tracedir": tmp_path, "model": "m"}):
+        path = write_trace([{"role": "user", "content": "hi"}])
+    assert path.name.startswith("trace_")
+    assert path.suffix == ".json"
+
+
+def test_write_trace_creates_missing_directory(tmp_path):
+    tracedir = tmp_path / "nested" / "traces"
+    with patch("app.core.runtime._store", {"tracedir": tracedir, "model": "m"}):
+        path = write_trace([{"role": "user", "content": "hi"}])
+    assert tracedir.exists()
+    assert path is not None
+    assert path.exists()
+
+
+def test_write_trace_returns_none_on_error(tmp_path):
+    # Create a file where the tracedir would need to be created as a directory
+    blocker = tmp_path / "blocker"
+    blocker.write_text("I am a file")
+    with patch("app.core.runtime._store", {"tracedir": blocker / "subdir", "model": "m"}):
+        result = write_trace([])
+    assert result is None
diff --git a/tests/test_web_channel.py b/tests/test_web_channel.py
index 3cee7bb..4c131b9 100644
--- a/tests/test_web_channel.py
+++ b/tests/test_web_channel.py
@@ -93,6 +93,118 @@ def test_extract_json_empty_content_returns_none():
     assert WebChannel._extract_content(raw) is None
 
 
+# --- _extract_message: text + attachments ---
+
+def test_extract_message_plain_text_no_files():
+    ch, _ = make_web_channel()
+    content, files = ch._extract_message("hello")
+    assert content == "hello"
+    assert files == []
+
+
+def test_extract_message_ignores_non_list_files():
+    ch, _ = make_web_channel()
+    raw = json.dumps({"type": "message", "content": "hi", "files": "nope"})
+    content, files = ch._extract_message(raw)
+    assert content == "hi"
+    assert files == []
+
+
+# --- _resolve_upload_paths: traversal protection ---
+
+def test_resolve_upload_paths_rejects_traversal(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path
+    (tmp_path / "ok.txt").write_text("x")
+    # basename-only join means traversal segments are stripped → file not found
+    assert ch._resolve_upload_paths(["../secret", "/etc/passwd"]) == []
+
+
+def test_resolve_upload_paths_accepts_known_file(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path
+    (tmp_path / "good.txt").write_text("x")
+    resolved = ch._resolve_upload_paths(["good.txt"])
+    assert resolved == [str((tmp_path / "good.txt").resolve())]
+
+
+def test_resolve_upload_paths_skips_missing(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path
+    assert ch._resolve_upload_paths(["ghost.txt"]) == []
+
+
+def test_resolve_upload_paths_ignores_non_strings(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path
+    assert ch._resolve_upload_paths([1, None, ""]) == []
+
+
+# --- /api/upload endpoint ---
+
+def test_upload_saves_files_and_returns_names(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path / "uploads"
+    ch.start()
+
+    from starlette.testclient import TestClient
+    client = TestClient(ch._fasthtml_app, raise_server_exceptions=True)
+    resp = client.post(
+        "/api/upload",
+        files=[
+            ("files", ("a.txt", b"hello", "text/plain")),
+            ("files", ("b.png", b"\x89PNG", "image/png")),
+        ],
+    )
+    assert resp.status_code == 200
+    saved = resp.json()["files"]
+    assert [s["name"] for s in saved] == ["a.txt", "b.png"]
+    # files were actually written and resolvable
+    resolved = ch._resolve_upload_paths([s["path"] for s in saved])
+    assert len(resolved) == 2
+
+
+def test_upload_rejects_empty_request(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path / "uploads"
+    ch.start()
+
+    from starlette.testclient import TestClient
+    client = TestClient(ch._fasthtml_app, raise_server_exceptions=True)
+    resp = client.post("/api/upload")
+    assert resp.status_code == 400
+
+
+def test_upload_rejects_oversized(tmp_path):
+    ch, _ = make_web_channel()
+    ch._upload_dir = tmp_path / "uploads"
+    ch._MAX_UPLOAD_BYTES = 10
+    ch.start()
+
+    from starlette.testclient import TestClient
+    client = TestClient(ch._fasthtml_app, raise_server_exceptions=True)
+    resp = client.post(
+        "/api/upload",
+        files=[("files", ("big.bin", b"x" * 50, "application/octet-stream"))],
+    )
+    assert resp.status_code == 413
+
+
+# --- _build_page: attachment UI ---
+
+def test_build_page_has_attach_controls():
+    html = str(_build_page())
+    for tok in ('id="attach-btn"', 'id="file-input"', 'id="attachments"', "<svg"):
+        assert tok in html, f"Missing {tok}"
+
+
+def test_start_registers_upload_route():
+    ch, _ = make_web_channel()
+    ch.start()
+    paths = [getattr(r, "path", None) for r in ch._fasthtml_app.router.routes]
+    assert "/api/upload" in paths
+
+
 # --- _build_page: static file references ---
 
 def test_build_page_references_static_css():