feat: bottom tool panels, PostHog error tracking, ACP agent auto-updates, and layout polish

- Add bottom tools row — right-click any tool in the picker to move it to a
  resizable bottom row (side ↔ bottom), with split ratios and height persistence
- Add renderer-side PostHog error tracking (posthog-js) with exception autocapture,
  PostHogProvider wrapper, and unified reportError() helper across all IPC handlers
- Add ACP agent auto-update system — checks registry on startup, periodically (4h),
  and on visibility change; toasts on success/failure
- Add ACP draft session lifecycle — eager session start during draft phase for
  instant MCP probing and config options loading
- Refine island layout — extract spacing/radius into CSS custom properties,
  tighter panel gaps, wider resize hit areas, tool picker redesign with
  progress ring on tasks icon
- Add "avoid grouping edits" setting — Edit/Write tools render standalone
  instead of collapsing into groups
- Remove ChangesPanel and its data layer (superseded by inline turn summaries)
- Add project icon support (emoji/lucide) via sidebar right-click
- Add git:diff-stat IPC for additions/deletions count
- Add per-session ACP analytics properties (agent name, source, launch method)
- Polish branch picker with search, terminal scrollbar auto-hide, glass border
  gradient refinements, dark mode tool picker button glow

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: OpenSource03

CLAUDE.md

@@ -299,7 +299,36 @@ Types shared between electron and renderer live in `shared/types/`. Both tsconfi
 - **`src/lib/file-access.ts`** — pure data transformation for file access tracking (extracted from FilesPanel)
 - **`src/lib/mcp-utils.ts`** — `toMcpStatusState()` (moved from types/ui.ts)
 - **`src/lib/acp-utils.ts`** — `flattenConfigOptions()` (moved from types/acp.ts)
-- **`electron/src/lib/error-utils.ts`** — `extractErrorMessage()` (replaces 3 duplicated implementations)
+- **`electron/src/lib/error-utils.ts`** — `extractErrorMessage()`, `reportError()` — shared error extraction and PostHog exception capture
+- **`src/lib/analytics.ts`** — `capture()`, `captureException()`, `reportError()` — renderer-side analytics and error tracking
+- **`src/lib/posthog.ts`** — `initPostHog()`, `syncAnalyticsSettings()` — renderer-side PostHog client (posthog-js) initialization
+
+### Error Tracking (PostHog)
+
+Two PostHog clients run in parallel, one per process:
+
+1. **Main process** (`posthog-node` in `electron/src/lib/posthog.ts`):
+   - `enableExceptionAutocapture: true` — auto-captures `process.on('uncaughtException')` and `process.on('unhandledRejection')`
+   - `captureException(error, additionalProperties?)` — manual exception capture with stack trace
+   - `captureEvent(event, properties?)` — custom analytics events
+   - Respects `analyticsEnabled` setting, uses anonymous `analyticsUserId`
+
+2. **Renderer process** (`posthog-js` + `@posthog/react` in `src/lib/posthog.ts`):
+   - Exception autocapture via `defaults: "2026-01-30"` — auto-hooks `window.onerror` and `window.onunhandledrejection`
+   - `PostHogProvider` wraps the app in `main.tsx`
+   - `ErrorBoundary.componentDidCatch` → `posthog.captureException()` for React rendering errors
+   - Starts opted-out (`opt_out_capturing_by_default: true`), syncs to main process settings via `syncAnalyticsSettings()`
+   - Uses same anonymous user ID as main process for cross-process correlation
+
+**Error reporting helpers:**
+
+- **Main process**: `reportError(label, err, context?)` from `electron/src/lib/error-utils.ts` — combines `log()` + `captureException()` in one call, returns the error message string. Use in all IPC handler catch blocks.
+- **Renderer**: `reportError(label, err, context?)` from `src/lib/analytics.ts` — combines `console.error()` + `captureException()`, returns the message string. Use in hook/component catch blocks.
+- **Renderer**: `captureException(error, properties?)` from `src/lib/analytics.ts` — PostHog-only capture (when console logging already exists).
+
+**When to use `reportError` vs leave a catch alone:**
+- **DO use `reportError`**: session start/stop failures, IPC handler errors, SDK/process spawn errors, OAuth failures, updater errors, file operation errors, user-visible errors
+- **DO NOT use `reportError`**: process kill cleanup (`/* already dead */`), JSON parse fallbacks, audio autoplay blocked, cache parse defaults, cancellation guards, analytics-internal catches (infinite recursion)
 
 ### Electron Session Handler Patterns
 
@@ -323,4 +352,5 @@ The three session IPC handlers share extracted utilities:
 - **Memo optimization** — components use `React.memo` with custom comparators for performance
 - **Component decomposition** — large components are split into focused sub-components in subdirectories (git/, tool-renderers/, mcp-renderers/, sidebar/)
 - **Hook decomposition** — large hooks are split into focused sub-hooks (session/, useEngineBase)
-- **Shared components** — reusable UI patterns extracted to shared components (`TabBar`, `PanelHeader`, `SettingRow`)
+- **Shared components** — reusable UI patterns extracted to shared components (`TabBar`, `PanelHeader`, `SettingRow`)
+- **Error tracking** — all caught errors in IPC handlers and hooks must use `reportError(label, err)` (not bare `log()`). Benign/expected catches (cleanup, parse fallbacks, cancellation guards) are exempt. See "Error Tracking (PostHog)" section for details.

README.md

@@ -109,6 +109,18 @@ Projects map to folders on disk. Spaces let you organize projects into named gro
 
 Browse and install agents from the ACP community registry directly in the app. Add custom agents by specifying a command, arguments, environment variables, and an icon. All configuration is managed through Settings — no config files.
 
+### Plan mode & permission control
+
+Work in plan mode to have the agent draft a plan before making any changes. Three permission levels — Ask First, Accept Edits, Allow All — control how much autonomy the agent has. Switch modes at any point without interrupting context.
+
+### Background task agents
+
+Task agents spawned during a session continue running in the background and are tracked in a dedicated panel. Keep working in other sessions while long-running tasks complete.
+
+### Image attachments & annotation
+
+Attach screenshots or images directly in the chat. An built-in annotation tool lets you draw, highlight, and mark up images with freehand strokes before sending them to the agent.
+
 ### Voice input & notifications
 
 Voice input via native macOS dictation or an on-device Whisper model (no API key required). Configurable OS notifications for plan approval requests, permission prompts, agent questions, and session completion.

electron/src/ipc/acp-sessions.ts

@@ -6,8 +6,9 @@ import path from "path";
 import { log } from "../lib/logger";
 import { safeSend } from "../lib/safe-send";
 import { getAgent } from "../lib/agent-registry";
+import type { InstalledAgent } from "../lib/agent-registry";
 import { getMcpAuthHeaders } from "../lib/mcp-oauth-flow";
-import { extractErrorMessage } from "../lib/error-utils";
+import { extractErrorMessage, reportError } from "../lib/error-utils";
 import { captureEvent } from "../lib/posthog";
 
 // ACP SDK is ESM-only, must be async-imported
@@ -71,6 +72,7 @@ interface ACPSessionEntry {
   connection: ClientSideConnection;
   acpSessionId: string;
   internalId: string;
+  analyticsProperties: AcpAnalyticsProperties;
   eventCounter: number;
   pendingPermissions: Map<string, { resolve: (response: unknown) => void }>;
   cwd: string;
@@ -98,6 +100,40 @@ const commandsBuffer = new Map<string, unknown[]>();
 // Only one start can be in-flight at a time (guarded by materializingRef in the renderer).
 let pendingStartProcess: { id: string; process: ChildProcess; aborted?: boolean } | null = null;
 
+type AcpAnalyticsProperties = {
+  acp_agent: string;
+  acp_agent_source: "registry" | "custom";
+  acp_agent_launch_method: "npx" | "binary" | "unknown";
+  acp_agent_registry_id?: string;
+  acp_agent_registry_version?: string;
+};
+
+function buildAcpAnalyticsProperties(agent: InstalledAgent): AcpAnalyticsProperties {
+  const registryId = agent.registryId?.trim();
+  const launchMethod = agent.binary === "npx" ? "npx" : agent.binary ? "binary" : "unknown";
+
+  if (registryId) {
+    return {
+      acp_agent: registryId,
+      acp_agent_source: "registry",
+      acp_agent_launch_method: launchMethod,
+      acp_agent_registry_id: registryId,
+      ...(agent.registryVersion ? { acp_agent_registry_version: agent.registryVersion } : {}),
+    };
+  }
+
+  const customHash = crypto.createHash("sha256").update(agent.id).digest("hex").slice(0, 12);
+  return {
+    acp_agent: `custom:${customHash}`,
+    acp_agent_source: "custom",
+    acp_agent_launch_method: launchMethod,
+  };
+}
+
+export function getAcpAnalyticsPropertiesForSession(sessionId: string): Record<string, unknown> | null {
+  return acpSessions.get(sessionId)?.analyticsProperties ?? null;
+}
+
 /** One-line summary for each ACP session update (mirrors summarizeEvent for Claude) */
 function summarizeUpdate(update: Record<string, unknown>): string {
   const kind = update.sessionUpdate as string;
@@ -423,6 +459,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
     }
 
     let connResult: AcpConnectionResult | null = null;
+    const analyticsProperties = buildAcpAnalyticsProperties(agentDef);
     try {
       connResult = await createAcpConnection(agentDef as { binary: string; args?: string[]; env?: Record<string, string>; name: string }, getMainWindow, "ACP_SPAWN");
       const { proc, connection, pendingPermissions, internalId, supportsLoadSession } = connResult;
@@ -444,6 +481,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         connection,
         acpSessionId: sessionResult.sessionId,
         internalId,
+        analyticsProperties,
         eventCounter: 0,
         pendingPermissions,
         cwd: options.cwd,
@@ -463,7 +501,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
       // Startup succeeded — clear the pending tracker before returning
       pendingStartProcess = null;
 
-      void captureEvent("session_created", { engine: "acp" });
+      void captureEvent("session_created", { engine: "acp", ...analyticsProperties });
 
       return {
         sessionId: internalId,
@@ -485,11 +523,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         return { cancelled: true };
       }
 
-      const msg = extractErrorMessage(err);
-      log("ACP_SPAWN", `ERROR: ${msg}`);
-      if (err instanceof Error && err.stack) {
-        log("ACP_SPAWN", `Stack: ${err.stack}`);
-      }
+      const msg = reportError("ACP_SPAWN", err, { engine: "acp", ...analyticsProperties });
       return { error: msg };
     }
   });
@@ -511,6 +545,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
     }
 
     let connResult: AcpConnectionResult | null = null;
+    const analyticsProperties = buildAcpAnalyticsProperties(agentDef);
     try {
       connResult = await createAcpConnection(agentDef as { binary: string; args?: string[]; env?: Record<string, string>; name: string }, getMainWindow, "ACP_REVIVE");
       const { proc, connection, pendingPermissions, internalId, supportsLoadSession } = connResult;
@@ -523,7 +558,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
 
       if (supportsLoadSession && options.agentSessionId) {
         // Restore full context — suppress history replay from reaching the renderer
-        const entry: ACPSessionEntry = { process: proc, connection, acpSessionId: options.agentSessionId, internalId, eventCounter: 0, pendingPermissions, cwd: options.cwd, supportsLoadSession, isReloading: true };
+        const entry: ACPSessionEntry = { process: proc, connection, acpSessionId: options.agentSessionId, internalId, analyticsProperties, eventCounter: 0, pendingPermissions, cwd: options.cwd, supportsLoadSession, isReloading: true };
         acpSessions.set(internalId, entry);
         const loadResult = await connection.loadSession({ sessionId: options.agentSessionId, cwd: options.cwd, mcpServers: acpMcpServers });
         entry.isReloading = false;
@@ -536,14 +571,14 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         // Fall back to fresh session — UI messages already restored from disk
         const sessionResult = await connection.newSession({ cwd: options.cwd, mcpServers: acpMcpServers });
         acpSessionId = sessionResult.sessionId;
-        const entry: ACPSessionEntry = { process: proc, connection, acpSessionId, internalId, eventCounter: 0, pendingPermissions, cwd: options.cwd, supportsLoadSession, isReloading: false };
+        const entry: ACPSessionEntry = { process: proc, connection, acpSessionId, internalId, analyticsProperties, eventCounter: 0, pendingPermissions, cwd: options.cwd, supportsLoadSession, isReloading: false };
         acpSessions.set(internalId, entry);
         configOptions = resolveConfigOptions(sessionResult, internalId, "ACP_REVIVE");
         log("ACP_REVIVE", `newSession fallback, session=${acpSessionId.slice(0, 12)}`);
       }
 
       const mcpStatuses = (options.mcpServers ?? []).map(s => ({ name: s.name, status: "connected" as const }));
-      void captureEvent("session_revived", { engine: "acp", success: true });
+      void captureEvent("session_revived", { engine: "acp", success: true, ...analyticsProperties });
       return { sessionId: internalId, agentSessionId: acpSessionId, usedLoad, configOptions, mcpStatuses };
     } catch (err) {
       // Kill process and clean up any partial session entry
@@ -552,8 +587,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         acpSessions.delete(connResult.internalId);
         configBuffer.delete(connResult.internalId);
       }
-      const msg = extractErrorMessage(err);
-      log("ACP_REVIVE", `ERROR: ${msg}`);
+      const msg = reportError("ACP_REVIVE", err, { engine: "acp", ...analyticsProperties });
       return { error: msg };
     }
   });
@@ -594,7 +628,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
     } catch (err) {
       const msg = extractErrorMessage(err);
       const surfacedError = msg === "Internal error" && session.lastStderrError ? session.lastStderrError : msg;
-      log("ACP_SEND", `ERROR: session=${sessionId.slice(0, 8)} ${surfacedError}`);
+      reportError("ACP_PROMPT_ERR", err, { engine: "acp", sessionId, surfacedError });
       return { error: surfacedError };
     }
   });
@@ -681,8 +715,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
       log("ACP_RELOAD", `session=${sessionId.slice(0, 8)} loadSession OK`);
       return { ok: true, supportsLoad: true };
     } catch (err) {
-      const msg = extractErrorMessage(err);
-      log("ACP_RELOAD", `ERROR: session=${sessionId.slice(0, 8)} loadSession failed: ${msg}`);
+      const msg = reportError("ACP_RELOAD_ERR", err, { engine: "acp", sessionId });
       return { error: msg, supportsLoad: true };
     }
   });
@@ -707,8 +740,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
       log("ACP_CANCEL", `session=${sessionId.slice(0, 8)} acknowledged`);
       return { ok: true };
     } catch (err) {
-      const msg = extractErrorMessage(err);
-      log("ACP_CANCEL", `ERROR: session=${sessionId.slice(0, 8)} ${msg}`);
+      const msg = reportError("ACP_CANCEL_ERR", err, { engine: "acp", sessionId });
       return { error: msg };
     }
   });
@@ -755,8 +787,8 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
         throw configErr;
       }
     } catch (err) {
-      log("ACP_CONFIG", `ERROR: session=${sessionId.slice(0, 8)} ${extractErrorMessage(err)}`);
-      return { error: extractErrorMessage(err) };
+      const errMsg = reportError("ACP_CONFIG_ERR", err, { engine: "acp", sessionId, configId });
+      return { error: errMsg };
     }
   });
 

electron/src/ipc/cc-import.ts

@@ -3,7 +3,7 @@ import path from "path";
 import fs from "fs";
 import crypto from "crypto";
 import os from "os";
-import { log } from "../lib/logger";
+import { reportError } from "../lib/error-utils";
 
 interface SessionPreview {
   firstUserMessage: string;
@@ -243,7 +243,7 @@ export function register(): void {
       result.sort((a, b) => b.fileModified - a.fileModified);
       return result;
     } catch (err) {
-      log("CC_SESSIONS:LIST_ERR", (err as Error).message);
+      reportError("CC_SESSIONS:LIST_ERR", err);
       return [];
     }
   });
@@ -260,8 +260,8 @@ export function register(): void {
       const messages = parseJsonlToUIMessages(filePath);
       return { messages, ccSessionId };
     } catch (err) {
-      log("CC_SESSIONS:IMPORT_ERR", (err as Error).message);
-      return { error: (err as Error).message };
+      const errMsg = reportError("CC_SESSIONS:IMPORT_ERR", err);
+      return { error: errMsg };
     }
   });
 }