From 180c5d6a69a299aac1fab10de4b5fb6d756ccfaf Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 15:49:32 -0400
Subject: [PATCH 1/9] fix: resolve Claude Agent SDK cli path in packaged builds

Resolve the unpacked @anthropic-ai/claude-agent-sdk cli.js before falling
back to the legacy claude-code path, fixing agent startup failures in
packaged apps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/IDE_BUILD_PLAN.md                    |   6 +-
 electron-builder.yml                      |  12 +-
 packages/main/src/chat/cliAgentManager.ts | 133 +++++++++++++++-------
 tests/unit/cliAgentManager.test.ts        |  79 ++++++++++++-
 4 files changed, 179 insertions(+), 51 deletions(-)

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index c014f1b..5804572 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -660,7 +660,7 @@ Terminal pane supports tabs internally. One tab for the interactive shell, one f
 Replace raw terminal with structured integration:
 
 ```typescript
-import { query } from '@anthropic-ai/claude-code'
+import { query } from '@anthropic-ai/claude-agent-sdk'
 
 const agentProcess = new UtilityProcess('./agent-worker.js', {
   env: { ANTHROPIC_API_KEY: getStoredApiKey() },
@@ -1043,7 +1043,7 @@ The full workspace switching experience. You can create two workspaces, start Cl
   - Display: estimated cost (token count × pricing)
 
 - [ ] **5.2** Claude Agent SDK integration
-  - Install `@anthropic-ai/claude-code`
+  - Install `@anthropic-ai/claude-agent-sdk`
   - Build `AgentWorker` UtilityProcess that runs the SDK's `query()` loop
   - Implement IPC message protocol between AgentWorker and renderer
   - Stream events to `AgentPane`: `file_read`, `file_write`, `command_run`, `thinking`, `complete`
@@ -1365,7 +1365,7 @@ Track milestone completion here. Update as you go.
 | 5.1c CLI native session hydration       | ✅ Complete    | `ClaudeNativeSessionWatcher.loadMessages(sessionId)` reads `~/.claude/projects/<slug>/<sessionId>.jsonl`, skips sidechains / thinking / file-history blocks, and maps rows to `CliAgentMessage[]`. IPC `cli-agent:load-messages` takes `(workspaceId, conversationId)`, returns `[]` when that workspace is not active (avoids native-prefix reads against the wrong project dir), and `useCliAgent` uses a hydrate generation guard, avoids clobbering a non-empty transcript with a stale empty IPC result, clears transcript only when the workspace+conversation key changes, and re-fetches native history once when `CONVERSATION_LIST_CHANGED` reports a `claude-native` row with messages but the pane is still empty. `CliAgentPane` waits on `historyHydrated`. Aide-managed sessions use `ConversationStore.loadMessages`. `CliAgentManager.start` sets `claudeSessionId` from `claude-native:<uuid>` for `--resume`.                               |
 | 5.1d CLI multi-tab isolation            | ✅ Complete    | New `cliAgentPane` instances receive a provisional `conversationId` (`crypto.randomUUID()` from `agent.open` and default workspace layout in `workspaceSwitcher`). `useCliAgent` stops calling `cliAgentGetSession(workspaceId)` without a session id so tabs are not hydrated from `CliAgentManager.getSession`'s first in-memory match for the workspace. Command `agent.open` (e.g. Cmd+K Cmd+A) always adds a new agent panel for parallel work instead of focusing an existing tab.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | 5.1e Multi-worktree agent orchestration | ✅ Complete    | Per-panel worktree isolation: `worktreePath` threaded through `CliAgentManager.start()` → spawn `cwd`, `CliAgentSession`, IPC, `useCliAgent` hook, `CliAgentPane` params. `AgentTab` custom tab component with branch badge pill (registered in `DockviewContainer.tabComponents`). "Start Agent in Worktree" button + context menu entry in `WorktreePanel`/`WorktreeItem`. Built-in agent isolation via `ToolContext.effectiveRoot` in `agentTools.ts` (terminal_exec, search_files, git_status, git_diff). `ChatSession.worktreePath` loaded from `ConversationMeta`. Worktree removal confirmation guard. Terminal panels from worktrees also get branch badges.                                                                                                                                                                                                                                                                                           |
-| 5.2 Claude Agent SDK integration        | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| 5.2 Claude Agent SDK integration        | ✅ Complete    | `CliAgentManager` streams Claude responses via `@anthropic-ai/claude-agent-sdk` `query()`, persists/resumes sessions, and now resolves the packaged executable from the SDK's own unpacked `cli.js` before falling back to the legacy `@anthropic-ai/claude-code` path. This fixes packaged-app startup failures caused by stale Claude Code path resolution. OpenCode/Codex SDK integration remains future work.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 5.3 Diff preview before apply           | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | 5.4 Agent edit highlighting in editor   | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | 5.5 Crash recovery                      | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
diff --git a/electron-builder.yml b/electron-builder.yml
index 6ad94a4..cac1d09 100644
--- a/electron-builder.yml
+++ b/electron-builder.yml
@@ -12,10 +12,12 @@ files:
   - node_modules/**/*
 
 asarUnpack:
-  - "**/node-pty/**"
-  - "**/@vscode/ripgrep/**"
-  - "**/@anthropic-ai/claude-code/**"
-  - "**/.pnpm/@anthropic-ai+claude-code@*/node_modules/@anthropic-ai/claude-code/**"
+  - '**/node-pty/**'
+  - '**/@vscode/ripgrep/**'
+  - '**/@anthropic-ai/claude-agent-sdk/**'
+  - '**/.pnpm/@anthropic-ai+claude-agent-sdk@*/node_modules/@anthropic-ai/claude-agent-sdk/**'
+  - '**/@anthropic-ai/claude-code/**'
+  - '**/.pnpm/@anthropic-ai+claude-code@*/node_modules/@anthropic-ai/claude-code/**'
 
 extraMetadata:
   main: packages/main/dist/index.js
@@ -35,7 +37,7 @@ mac:
   gatekeeperAssess: false
 
 dmg:
-  artifactName: "${productName}-${version}-${os}-${arch}.${ext}"
+  artifactName: '${productName}-${version}-${os}-${arch}.${ext}'
 
 linux:
   target:
diff --git a/packages/main/src/chat/cliAgentManager.ts b/packages/main/src/chat/cliAgentManager.ts
index cfa308a..21d8b63 100644
--- a/packages/main/src/chat/cliAgentManager.ts
+++ b/packages/main/src/chat/cliAgentManager.ts
@@ -10,23 +10,29 @@
  * loop that normalizes SDK messages into CliAgentMessage and emits them
  * via IPC. Session continuity uses the SDK's `resume` option.
  *
- * The SDK needs `pathToClaudeCodeExecutable` to find the Claude Code CLI.
- * Resolution order: explicit setting → bundled in app → workspace
- * node_modules → global `claude` in PATH.
+ * The SDK ships its own `cli.js`, but packaged Electron apps need that file
+ * unpacked onto the real filesystem so a child Node process can execute it.
+ * Resolution order: explicit setting -> bundled Agent SDK in app -> legacy
+ * bundled Claude Code package -> workspace node_modules -> global `claude`.
  */
 
 import { randomUUID } from 'crypto'
 import { execFileSync } from 'child_process'
 import { existsSync } from 'fs'
-import { join, dirname } from 'path'
+import { join } from 'path'
 import { app, type WebContents } from 'electron'
 import { query } from '@anthropic-ai/claude-agent-sdk'
 import type { Query } from '@anthropic-ai/claude-agent-sdk'
 import { IpcChannels, deriveTitle } from '@aide/shared'
 import type {
-  AgentBackend, CliAgentProcessStatus, CliAgentMessage,
-  CliAgentSession, CliAgentStreamDelta,
-  CliAgentStatusPayload, CliAgentResultPayload, CliAgentMessagePayload,
+  AgentBackend,
+  CliAgentProcessStatus,
+  CliAgentMessage,
+  CliAgentSession,
+  CliAgentStreamDelta,
+  CliAgentStatusPayload,
+  CliAgentResultPayload,
+  CliAgentMessagePayload,
   ConversationListChangedPayload,
 } from '@aide/shared'
 import type { ConversationStore } from './conversationStore'
@@ -67,11 +73,12 @@ export interface CliAgentManagerOpts {
 }
 
 function comparableHistoryCount(messages: CliAgentMessage[]): number {
-  return messages.filter((message) =>
-    message.type === 'user' ||
-    message.type === 'assistant' ||
-    message.type === 'tool_use' ||
-    message.type === 'tool_result'
+  return messages.filter(
+    (message) =>
+      message.type === 'user' ||
+      message.type === 'assistant' ||
+      message.type === 'tool_use' ||
+      message.type === 'tool_result',
   ).length
 }
 
@@ -131,7 +138,10 @@ export class CliAgentManager {
       if (meta?.claudeSessionId) {
         existingClaudeSessionId = meta.claudeSessionId
       }
-      const saved = await this.conversationStore.loadMessages(conversationId) as { messages?: CliAgentMessage[], claudeSessionId?: string } | null
+      const saved = (await this.conversationStore.loadMessages(conversationId)) as {
+        messages?: CliAgentMessage[]
+        claudeSessionId?: string
+      } | null
       if (saved?.messages) {
         existingMessages = saved.messages
       }
@@ -199,10 +209,7 @@ export class CliAgentManager {
    * Send a prompt to the CLI agent. Starts an SDK query that streams
    * messages back via IPC. Uses `resume` for conversation continuity.
    */
-  async send(
-    sessionId: string,
-    content: string,
-  ): Promise<{ success: true } | { error: string }> {
+  async send(sessionId: string, content: string): Promise<{ success: true } | { error: string }> {
     const session = this.sessions.get(sessionId)
     if (!session) return { error: 'Session not found' }
 
@@ -228,9 +235,12 @@ export class CliAgentManager {
     session.lastError = undefined
 
     // Fire and forget the consumption loop
-    this.consumeQuery(session, content).catch(err => {
+    this.consumeQuery(session, content).catch((err) => {
       const errMsg = err instanceof Error ? err.message : String(err)
-      console.error(`[CliAgentManager] Unhandled consumeQuery error for session ${session.id}:`, errMsg)
+      console.error(
+        `[CliAgentManager] Unhandled consumeQuery error for session ${session.id}:`,
+        errMsg,
+      )
       if (err instanceof Error && err.stack) console.error(`[CliAgentManager] Stack:`, err.stack)
       session.lastError = errMsg
       this.setStatus(session, 'error')
@@ -340,10 +350,26 @@ export class CliAgentManager {
     const bundledCandidates: string[] = []
     if (app.isPackaged) {
       bundledCandidates.push(
-        join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+        join(
+          process.resourcesPath,
+          'app.asar.unpacked',
+          'node_modules',
+          '@anthropic-ai',
+          'claude-agent-sdk',
+          'cli.js',
+        ),
+        join(
+          process.resourcesPath,
+          'app.asar.unpacked',
+          'node_modules',
+          '@anthropic-ai',
+          'claude-code',
+          'cli.js',
+        ),
       )
     }
     bundledCandidates.push(
+      join(app.getAppPath(), 'node_modules', '@anthropic-ai', 'claude-agent-sdk', 'cli.js'),
       join(app.getAppPath(), 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
     )
     for (const candidate of bundledCandidates) {
@@ -355,11 +381,16 @@ export class CliAgentManager {
     }
 
     // 3. Workspace-local installation
-    const workspaceCli = join(this.workspaceRoot, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js')
-    if (existsSync(workspaceCli)) {
-      console.log(`[CliAgentManager] Using workspace Claude Code: ${workspaceCli}`)
-      this.resolvedClaudeCodePath = workspaceCli
-      return workspaceCli
+    const workspaceCandidates = [
+      join(this.workspaceRoot, 'node_modules', '@anthropic-ai', 'claude-agent-sdk', 'cli.js'),
+      join(this.workspaceRoot, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+    ]
+    for (const candidate of workspaceCandidates) {
+      if (existsSync(candidate)) {
+        console.log(`[CliAgentManager] Using workspace Claude Code: ${candidate}`)
+        this.resolvedClaudeCodePath = candidate
+        return candidate
+      }
     }
 
     // 4. Global `claude` in PATH
@@ -380,10 +411,7 @@ export class CliAgentManager {
 
   // ─── SDK Query Consumption ──────────────────
 
-  private async consumeQuery(
-    session: CliAgentSessionInternal,
-    prompt: string,
-  ): Promise<void> {
+  private async consumeQuery(session: CliAgentSessionInternal, prompt: string): Promise<void> {
     const abortController = new AbortController()
     session.abortController = abortController
 
@@ -391,7 +419,9 @@ export class CliAgentManager {
     console.log(`[CliAgentManager] Starting SDK query for session ${session.id}`)
     console.log(`[CliAgentManager]   cwd: ${cwd}`)
     console.log(`[CliAgentManager]   resume: ${session.claudeSessionId ?? '(new session)'}`)
-    console.log(`[CliAgentManager]   prompt: ${prompt.slice(0, 200)}${prompt.length > 200 ? '...' : ''}`)
+    console.log(
+      `[CliAgentManager]   prompt: ${prompt.slice(0, 200)}${prompt.length > 200 ? '...' : ''}`,
+    )
 
     // Collect stderr output for diagnostics
     const stderrChunks: string[] = []
@@ -399,7 +429,8 @@ export class CliAgentManager {
     // Resolve the Claude Code executable path for the SDK
     const executablePath = this.resolveClaudeCodeExecutable()
     if (!executablePath) {
-      session.lastError = 'Claude Code CLI not found. Install @anthropic-ai/claude-code globally or set agent.claudeCodePath in settings.'
+      session.lastError =
+        'Claude Code CLI not found. Install @anthropic-ai/claude-code globally or set agent.claudeCodePath in settings.'
       const errorMsg: CliAgentMessage = {
         id: randomUUID(),
         type: 'error',
@@ -464,7 +495,9 @@ export class CliAgentManager {
         messageCount++
         this.handleSDKMessage(session, message)
       }
-      console.log(`[CliAgentManager] Query completed for session ${session.id} — ${messageCount} messages received`)
+      console.log(
+        `[CliAgentManager] Query completed for session ${session.id} — ${messageCount} messages received`,
+      )
     } catch (err) {
       if (!abortController.signal.aborted) {
         const errMsg = err instanceof Error ? err.message : String(err)
@@ -516,7 +549,9 @@ export class CliAgentManager {
 
     // Log all non-streaming messages (stream_event is too noisy)
     if (type !== 'stream_event') {
-      console.log(`[CliAgentManager] SDK message: type=${type}${subtype ? ` subtype=${subtype}` : ''} session=${session.id.slice(0, 8)}`)
+      console.log(
+        `[CliAgentManager] SDK message: type=${type}${subtype ? ` subtype=${subtype}` : ''} session=${session.id.slice(0, 8)}`,
+      )
     }
 
     if (type === 'system') {
@@ -536,7 +571,10 @@ export class CliAgentManager {
       this.setStatus(session, 'rate_limited')
     } else {
       // Log unknown message types so we can add handling later
-      console.log(`[CliAgentManager] Unhandled SDK message type: ${type}`, JSON.stringify(message).slice(0, 500))
+      console.log(
+        `[CliAgentManager] Unhandled SDK message type: ${type}`,
+        JSON.stringify(message).slice(0, 500),
+      )
     }
   }
 
@@ -549,7 +587,9 @@ export class CliAgentManager {
       const sdkSessionId = message.session_id as string | undefined
       if (sdkSessionId) {
         session.claudeSessionId = sdkSessionId
-        this.conversationStore?.updateMeta(session.id, { claudeSessionId: sdkSessionId }).catch(() => {})
+        this.conversationStore
+          ?.updateMeta(session.id, { claudeSessionId: sdkSessionId })
+          .catch(() => {})
       }
 
       session.model = (message.model as string) ?? undefined
@@ -679,7 +719,9 @@ export class CliAgentManager {
     const resultSessionId = message.session_id as string | undefined
     if (resultSessionId && !session.claudeSessionId) {
       session.claudeSessionId = resultSessionId
-      this.conversationStore?.updateMeta(session.id, { claudeSessionId: resultSessionId }).catch(() => {})
+      this.conversationStore
+        ?.updateMeta(session.id, { claudeSessionId: resultSessionId })
+        .catch(() => {})
     }
 
     // Build detailed error content for non-success results
@@ -689,9 +731,14 @@ export class CliAgentManager {
       if (errors?.length) {
         errorDetail = errors.join('\n')
       }
-      console.error(`[CliAgentManager] Result error for session ${session.id.slice(0, 8)}: subtype=${subtype}`)
+      console.error(
+        `[CliAgentManager] Result error for session ${session.id.slice(0, 8)}: subtype=${subtype}`,
+      )
       if (errorDetail) console.error(`[CliAgentManager] Error details:\n${errorDetail}`)
-      console.error(`[CliAgentManager] Full result message:`, JSON.stringify(message).slice(0, 2000))
+      console.error(
+        `[CliAgentManager] Full result message:`,
+        JSON.stringify(message).slice(0, 2000),
+      )
     }
 
     const msg: CliAgentMessage = {
@@ -737,7 +784,11 @@ export class CliAgentManager {
   }
 
   private emitMessage(session: CliAgentSessionInternal, msg: CliAgentMessage): void {
-    const ipcMsg: CliAgentMessagePayload = { ...msg, workspaceId: session.workspaceId, sessionId: session.id }
+    const ipcMsg: CliAgentMessagePayload = {
+      ...msg,
+      workspaceId: session.workspaceId,
+      sessionId: session.id,
+    }
     this.getWebContents()?.send(IpcChannels.CLI_AGENT_MESSAGE, ipcMsg)
 
     if (session.processStatus === 'rate_limited' && msg.type !== 'status') {
@@ -756,7 +807,7 @@ export class CliAgentManager {
     await this.conversationStore.updateMeta(session.id, {
       updatedAt: Date.now(),
       messageCount: session.messages.length,
-      firstMessage: session.messages.find(m => m.type === 'user')?.content.slice(0, 100),
+      firstMessage: session.messages.find((m) => m.type === 'user')?.content.slice(0, 100),
       claudeSessionId: session.claudeSessionId,
       worktreePath: session.worktreePath,
     })
@@ -765,7 +816,7 @@ export class CliAgentManager {
   private async maybeAutoTitle(session: CliAgentSessionInternal, content: string): Promise<void> {
     if (!this.conversationStore) return
 
-    const userMessages = session.messages.filter(m => m.type === 'user')
+    const userMessages = session.messages.filter((m) => m.type === 'user')
     if (userMessages.length !== 1) return
 
     const meta = await this.conversationStore.get(session.id)
diff --git a/tests/unit/cliAgentManager.test.ts b/tests/unit/cliAgentManager.test.ts
index d807c1b..666da7d 100644
--- a/tests/unit/cliAgentManager.test.ts
+++ b/tests/unit/cliAgentManager.test.ts
@@ -1,6 +1,26 @@
-import { describe, it, expect, vi } from 'vitest'
+import { beforeEach, describe, it, expect, vi } from 'vitest'
 import type { CliAgentMessage } from '@aide/shared'
 
+const mocks = vi.hoisted(() => ({
+  execFileSync: vi.fn(),
+  existsSync: vi.fn(),
+  query: vi.fn(),
+}))
+
+vi.mock('child_process', () => ({
+  default: {
+    execFileSync: mocks.execFileSync,
+  },
+  execFileSync: mocks.execFileSync,
+}))
+
+vi.mock('fs', () => ({
+  default: {
+    existsSync: mocks.existsSync,
+  },
+  existsSync: mocks.existsSync,
+}))
+
 vi.mock('electron', () => ({
   app: {
     isPackaged: false,
@@ -9,11 +29,26 @@ vi.mock('electron', () => ({
 }))
 
 vi.mock('@anthropic-ai/claude-agent-sdk', () => ({
-  query: vi.fn(),
+  query: mocks.query,
 }))
 
+import { app } from 'electron'
 import { CliAgentManager } from '@main/chat/cliAgentManager'
 
+const existsSyncMock = vi.mocked(mocks.existsSync)
+const execFileSyncMock = vi.mocked(mocks.execFileSync)
+const queryMock = vi.mocked(mocks.query)
+const appMock = app as { isPackaged: boolean; getAppPath: () => string }
+
+function makeQueryStub() {
+  return {
+    close: vi.fn(),
+    async *[Symbol.asyncIterator]() {
+      return
+    },
+  }
+}
+
 function makeStore(overrides: Record<string, unknown> = {}) {
   return {
     get: vi.fn().mockResolvedValue(null),
@@ -27,6 +62,20 @@ function makeStore(overrides: Record<string, unknown> = {}) {
 }
 
 describe('CliAgentManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    appMock.isPackaged = false
+    existsSyncMock.mockReturnValue(false)
+    execFileSyncMock.mockImplementation(() => {
+      throw new Error('not found')
+    })
+    queryMock.mockReturnValue(makeQueryStub() as never)
+    Object.defineProperty(process, 'resourcesPath', {
+      value: '/resources',
+      configurable: true,
+    })
+  })
+
   it('prefers fresher native Claude history over the stored shadow copy', async () => {
     const storedMessages: CliAgentMessage[] = [
       { id: 'u-1', type: 'user', content: 'old prompt', timestamp: 1 },
@@ -84,4 +133,30 @@ describe('CliAgentManager', () => {
 
     expect(manager.getSessionById('conv-2')?.messages).toEqual(storedMessages)
   })
+
+  it('uses the unpacked Agent SDK cli in packaged builds', async () => {
+    appMock.isPackaged = true
+    const expectedCliPath =
+      '/resources/app.asar.unpacked/node_modules/@anthropic-ai/claude-agent-sdk/cli.js'
+    existsSyncMock.mockImplementation((candidate) => candidate === expectedCliPath)
+
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+    })
+
+    const started = await manager.start('ws-1', 'claude-code')
+    if ('error' in started) throw new Error(started.error)
+
+    await manager.send(started.sessionId, 'hello from test')
+
+    expect(queryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        prompt: 'hello from test',
+        options: expect.objectContaining({
+          pathToClaudeCodeExecutable: expectedCliPath,
+        }),
+      }),
+    )
+  })
 })

From bab71adf90b0ed371fc087f97c3bf453df0a53bf Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 15:49:43 -0400
Subject: [PATCH 2/9] refactor: adopt shared ui primitives in chat pane

Introduce reusable Button and related UI components and migrate chat pane
elements to use them for a more consistent look and feel.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../src/components/chat/ChatInput.tsx         |  24 +-
 .../src/components/chat/MessageBubble.tsx     |   6 +-
 .../src/components/chat/MessageList.tsx       |   2 +
 .../src/components/chat/ModeSelector.tsx      |  28 +-
 .../components/chat/PermissionTierBadge.tsx   |  18 +-
 .../src/components/chat/ToolCallCard.tsx      | 127 ++-
 .../src/components/chat/WorkingSetPicker.tsx  |  12 +-
 .../src/components/panes/ChatPane.tsx         |  12 +-
 packages/renderer/src/components/ui/Badge.tsx |  19 +
 .../renderer/src/components/ui/Button.tsx     |  23 +
 .../src/components/ui/SegmentedControl.tsx    |  45 ++
 packages/renderer/src/main.tsx                |   1 +
 packages/renderer/src/styles/chat-pane.css    | 726 ++++++------------
 .../renderer/src/styles/cli-agent-pane.css    |  39 +-
 packages/renderer/src/styles/global.css       |  31 +
 packages/renderer/src/styles/ui.css           | 172 +++++
 16 files changed, 652 insertions(+), 633 deletions(-)
 create mode 100644 packages/renderer/src/components/ui/Badge.tsx
 create mode 100644 packages/renderer/src/components/ui/Button.tsx
 create mode 100644 packages/renderer/src/components/ui/SegmentedControl.tsx
 create mode 100644 packages/renderer/src/styles/ui.css

diff --git a/packages/renderer/src/components/chat/ChatInput.tsx b/packages/renderer/src/components/chat/ChatInput.tsx
index 751e3e2..d0e4b15 100644
--- a/packages/renderer/src/components/chat/ChatInput.tsx
+++ b/packages/renderer/src/components/chat/ChatInput.tsx
@@ -1,5 +1,6 @@
 import { useRef, useCallback, useState } from 'react'
 import type { ChatMode, ChatSessionStatus } from '@aide/shared'
+import { Button } from '../ui/Button'
 
 interface ChatInputProps {
   onSend: (content: string) => void
@@ -8,13 +9,7 @@ interface ChatInputProps {
   mode: ChatMode
 }
 
-const PLACEHOLDERS: Record<ChatMode, string> = {
-  ask: 'Ask a question...',
-  edit: 'Describe changes...',
-  agent: 'What should I do?',
-}
-
-export function ChatInput({ onSend, onStop, status, mode }: ChatInputProps) {
+export function ChatInput({ onSend, onStop, status }: ChatInputProps) {
   const textareaRef = useRef<HTMLTextAreaElement>(null)
   const [value, setValue] = useState('')
   const isActive = status !== 'idle'
@@ -68,22 +63,23 @@ export function ChatInput({ onSend, onStop, status, mode }: ChatInputProps) {
         value={value}
         onChange={handleChange}
         onKeyDown={handleKeyDown}
-        placeholder={PLACEHOLDERS[mode]}
+        placeholder="Ask, edit, or build…"
         rows={1}
         disabled={isActive}
       />
       {isActive ? (
-        <button className="chat-input__btn-stop" onClick={onStop} title="Stop">
-          <div className="chat-input__btn-stop__icon" />
-        </button>
+        <Button variant="danger" size="sm" onClick={onStop} title="Stop">
+          Stop
+        </Button>
       ) : (
-        <button
-          className="chat-input__btn-send"
+        <Button
+          variant="accent"
+          size="sm"
           onClick={handleSend}
           disabled={!value.trim()}
         >
           Send
-        </button>
+        </Button>
       )}
     </div>
   )
diff --git a/packages/renderer/src/components/chat/MessageBubble.tsx b/packages/renderer/src/components/chat/MessageBubble.tsx
index 357cf3f..f0d858a 100644
--- a/packages/renderer/src/components/chat/MessageBubble.tsx
+++ b/packages/renderer/src/components/chat/MessageBubble.tsx
@@ -17,7 +17,8 @@ export function MessageBubble({ message, isStreaming, streamingContent }: Messag
       message.toolResults?.map((r) => r.output).filter(Boolean).join('\n\n') || message.content
     return (
       <div className={`chat-msg chat-msg--tool-result${isError ? ' chat-msg--tool-result-error' : ''}`}>
-        {output}
+        <div className="chat-msg__role">{isError ? 'Tool error' : 'Tool result'}</div>
+        <div className="chat-msg__body">{output}</div>
       </div>
     )
   }
@@ -25,7 +26,7 @@ export function MessageBubble({ message, isStreaming, streamingContent }: Messag
   if (message.role === 'user') {
     return (
       <div className="chat-msg chat-msg--user">
-        <span className="chat-msg__prefix">&gt;</span>
+        <div className="chat-msg__role">You</div>
         <div className="chat-msg__body">{message.content}</div>
       </div>
     )
@@ -43,6 +44,7 @@ function AssistantMessage({ content, isStreaming }: { content: string; isStreami
 
   return (
     <div className="chat-msg chat-msg--assistant">
+      <div className="chat-msg__role">Claude</div>
       <div className="chat-msg__body">
         {/* Safe: HTML is sanitized through DOMPurify in renderMarkdown */}
         <span dangerouslySetInnerHTML={{ __html: html }} />
diff --git a/packages/renderer/src/components/chat/MessageList.tsx b/packages/renderer/src/components/chat/MessageList.tsx
index 733f079..a1e81c7 100644
--- a/packages/renderer/src/components/chat/MessageList.tsx
+++ b/packages/renderer/src/components/chat/MessageList.tsx
@@ -46,6 +46,7 @@ export function MessageList({
 
   return (
     <div className="chat-messages" ref={scrollRef} onScroll={handleScroll}>
+      <div className="chat-messages__inner">
       {messages.map((msg) => {
         const isStreamingThis = msg.id === streamingMessageId
         return (
@@ -91,6 +92,7 @@ export function MessageList({
       {status === 'awaiting_approval' && (
         <div className="chat-status chat-status--warning">Waiting for approval</div>
       )}
+      </div>
     </div>
   )
 }
diff --git a/packages/renderer/src/components/chat/ModeSelector.tsx b/packages/renderer/src/components/chat/ModeSelector.tsx
index 3fe812a..24277cc 100644
--- a/packages/renderer/src/components/chat/ModeSelector.tsx
+++ b/packages/renderer/src/components/chat/ModeSelector.tsx
@@ -1,4 +1,5 @@
 import type { ChatMode } from '@aide/shared'
+import { SegmentedControl } from '../ui/SegmentedControl'
 
 interface ModeSelectorProps {
   mode: ChatMode
@@ -6,25 +7,20 @@ interface ModeSelectorProps {
   disabled: boolean
 }
 
-const MODES: { value: ChatMode; label: string }[] = [
-  { value: 'ask', label: 'ASK' },
-  { value: 'edit', label: 'EDIT' },
-  { value: 'agent', label: 'AGENT' },
+const OPTIONS: { value: ChatMode; label: string }[] = [
+  { value: 'ask', label: 'Ask' },
+  { value: 'edit', label: 'Edit' },
+  { value: 'agent', label: 'Agent' },
 ]
 
 export function ModeSelector({ mode, onModeChange, disabled }: ModeSelectorProps) {
   return (
-    <div className={`chat-mode-selector${disabled ? ' chat-mode-selector--disabled' : ''}`}>
-      {MODES.map((m) => (
-        <button
-          key={m.value}
-          className={`chat-mode-selector__btn${m.value === mode ? ' chat-mode-selector__btn--active' : ''}`}
-          onClick={() => onModeChange(m.value)}
-          disabled={disabled}
-        >
-          {m.label}
-        </button>
-      ))}
-    </div>
+    <SegmentedControl
+      options={OPTIONS}
+      value={mode}
+      onChange={onModeChange}
+      disabled={disabled}
+      ariaLabel="Chat mode"
+    />
   )
 }
diff --git a/packages/renderer/src/components/chat/PermissionTierBadge.tsx b/packages/renderer/src/components/chat/PermissionTierBadge.tsx
index c22076b..bd05562 100644
--- a/packages/renderer/src/components/chat/PermissionTierBadge.tsx
+++ b/packages/renderer/src/components/chat/PermissionTierBadge.tsx
@@ -1,10 +1,13 @@
 import { useState, useEffect } from 'react'
 import type { PermissionTier } from '@aide/shared'
+import { Badge } from '../ui/Badge'
 
-const TIER_CONFIG: Record<PermissionTier, { label: string; icon: string; className: string }> = {
-  'confirm': { label: 'Confirm', icon: '⛨', className: 'confirm' },
-  'auto-approve': { label: 'Auto', icon: '⚡', className: 'auto' },
-  'autopilot': { label: 'Autopilot', icon: '◉', className: 'autopilot' },
+type BadgeVariant = 'warning' | 'info' | 'success'
+
+const TIER_CONFIG: Record<PermissionTier, { label: string; icon: string; variant: BadgeVariant }> = {
+  'confirm': { label: 'Confirm', icon: '⛨', variant: 'warning' },
+  'auto-approve': { label: 'Auto', icon: '⚡', variant: 'info' },
+  'autopilot': { label: 'Autopilot', icon: '◉', variant: 'success' },
 }
 
 interface PermissionTierBadgeProps {
@@ -41,9 +44,8 @@ export function PermissionTierBadge({ workspaceId }: PermissionTierBadgeProps) {
   const config = TIER_CONFIG[tier]
 
   return (
-    <div className={`perm-tier-badge perm-tier-badge--${config.className}`} title={`Permission tier: ${config.label}`}>
-      <span className="perm-tier-badge__icon">{config.icon}</span>
-      <span className="perm-tier-badge__label">{config.label}</span>
-    </div>
+    <Badge variant={config.variant} icon={config.icon} title={`Permission tier: ${config.label}`}>
+      {config.label}
+    </Badge>
   )
 }
diff --git a/packages/renderer/src/components/chat/ToolCallCard.tsx b/packages/renderer/src/components/chat/ToolCallCard.tsx
index be366e5..18006bb 100644
--- a/packages/renderer/src/components/chat/ToolCallCard.tsx
+++ b/packages/renderer/src/components/chat/ToolCallCard.tsx
@@ -1,5 +1,7 @@
-import { useState, useRef, useEffect } from 'react'
+import { useState } from 'react'
 import type { ToolCall } from '@aide/shared'
+import { Badge } from '../ui/Badge'
+import { Button } from '../ui/Button'
 
 interface ToolCallCardProps {
   toolCall: ToolCall
@@ -18,11 +20,16 @@ const TOOL_ICONS: Record<string, string> = {
   browser_read: '◎',
 }
 
-const STATUS_META: Record<string, { label: string; className: string }> = {
-  pending: { label: 'awaiting', className: 'pending' },
-  approved: { label: 'approved', className: 'approved' },
-  rejected: { label: 'denied', className: 'rejected' },
-  completed: { label: 'done', className: 'completed' },
+type BadgeVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info'
+
+const STATUS_META: Record<
+  string,
+  { label: string; className: string; variant: BadgeVariant }
+> = {
+  pending: { label: 'awaiting', className: 'pending', variant: 'warning' },
+  approved: { label: 'approved', className: 'approved', variant: 'success' },
+  rejected: { label: 'denied', className: 'rejected', variant: 'error' },
+  completed: { label: 'done', className: 'completed', variant: 'success' },
 }
 
 function formatToolInput(input: Record<string, unknown>): string {
@@ -63,12 +70,6 @@ function getToolSummary(name: string, input: Record<string, unknown>): string {
 
 export function ToolCallCard({ toolCall, onApprove, onReject }: ToolCallCardProps) {
   const [expanded, setExpanded] = useState(false)
-  const [animateIn, setAnimateIn] = useState(false)
-  const cardRef = useRef<HTMLDivElement>(null)
-
-  useEffect(() => {
-    requestAnimationFrame(() => setAnimateIn(true))
-  }, [])
 
   const meta = STATUS_META[toolCall.status] ?? STATUS_META.pending
   const icon = TOOL_ICONS[toolCall.name] ?? '⬡'
@@ -77,74 +78,50 @@ export function ToolCallCard({ toolCall, onApprove, onReject }: ToolCallCardProp
   const isDone = toolCall.status === 'completed' || toolCall.status === 'approved'
 
   return (
-    <div
-      ref={cardRef}
-      className={`tc-card tc-card--${meta.className}${animateIn ? ' tc-card--visible' : ''}${isPending ? ' tc-card--awaiting' : ''}`}
-    >
-      {/* Tier glow bar */}
-      <div className="tc-card__glow" />
-
-      <div className="tc-card__main">
-        {/* Tool icon + name row */}
-        <div className="tc-card__header">
-          <span className="tc-card__icon">{icon}</span>
-          <div className="tc-card__title-group">
-            <span className="tc-card__name">{toolCall.name}</span>
-            {summary && <span className="tc-card__summary">{summary}</span>}
-          </div>
-          <div className="tc-card__status-area">
-            <span className={`tc-card__dot tc-card__dot--${meta.className}`} />
-            <span className="tc-card__status-label">{meta.label}</span>
-            {toolCall.autoApproved && (
-              <span className="tc-card__auto-tag">auto</span>
-            )}
-          </div>
+    <div className={`tc-card tc-card--${meta.className}`}>
+      <div className="tc-card__header">
+        <span className="tc-card__icon">{icon}</span>
+        <span className="tc-card__name">{toolCall.name}</span>
+        {summary && (
+          <>
+            <span className="tc-card__sep">·</span>
+            <span className="tc-card__summary">{summary}</span>
+          </>
+        )}
+        <div className="tc-card__status-area">
+          {toolCall.autoApproved && <Badge variant="info">auto</Badge>}
+          <Badge variant={meta.variant}>{meta.label}</Badge>
         </div>
+      </div>
 
-        {/* Expandable input detail */}
-        <button
-          className="tc-card__expand-btn"
-          onClick={() => setExpanded(!expanded)}
-          aria-expanded={expanded}
-        >
-          <span className={`tc-card__chevron${expanded ? ' tc-card__chevron--open' : ''}`}>▸</span>
-          {expanded ? 'Hide details' : 'Show details'}
-        </button>
+      <button
+        className="tc-card__expand-btn"
+        onClick={() => setExpanded(!expanded)}
+        aria-expanded={expanded}
+      >
+        <span className={`tc-card__chevron${expanded ? ' tc-card__chevron--open' : ''}`}>▸</span>
+        {expanded ? 'Hide details' : 'Show details'}
+      </button>
 
-        {expanded && (
-          <pre className="tc-card__detail">
-            {formatToolInput(toolCall.input)}
-          </pre>
-        )}
+      {expanded && <pre className="tc-card__detail">{formatToolInput(toolCall.input)}</pre>}
 
-        {/* Approval buttons */}
-        {isPending && !toolCall.autoApproved && (
-          <div className="tc-card__actions">
-            <button
-              className="tc-card__btn tc-card__btn--allow"
-              onClick={() => onApprove(toolCall.id)}
-            >
-              <span className="tc-card__btn-icon">✓</span>
-              Allow
-            </button>
-            <button
-              className="tc-card__btn tc-card__btn--deny"
-              onClick={() => onReject(toolCall.id)}
-            >
-              <span className="tc-card__btn-icon">✕</span>
-              Deny
-            </button>
-          </div>
-        )}
+      {isPending && !toolCall.autoApproved && (
+        <div className="tc-card__actions">
+          <Button variant="outline" size="sm" onClick={() => onApprove(toolCall.id)}>
+            ✓ Allow
+          </Button>
+          <Button variant="danger" size="sm" onClick={() => onReject(toolCall.id)}>
+            ✕ Deny
+          </Button>
+        </div>
+      )}
 
-        {/* Completed state — subtle checkmark */}
-        {isDone && !toolCall.autoApproved && (
-          <div className="tc-card__resolved">
-            <span className="tc-card__resolved-icon">✓</span>
-            executed
-          </div>
-        )}
-      </div>
+      {isDone && !toolCall.autoApproved && (
+        <div className="tc-card__resolved">
+          <span className="tc-card__resolved-icon">✓</span>
+          executed
+        </div>
+      )}
     </div>
   )
 }
diff --git a/packages/renderer/src/components/chat/WorkingSetPicker.tsx b/packages/renderer/src/components/chat/WorkingSetPicker.tsx
index 791c62d..94d8484 100644
--- a/packages/renderer/src/components/chat/WorkingSetPicker.tsx
+++ b/packages/renderer/src/components/chat/WorkingSetPicker.tsx
@@ -1,4 +1,5 @@
 import { useState, useCallback, useEffect, useRef } from 'react'
+import { Button } from '../ui/Button'
 
 interface WorkingSetPickerProps {
   workingSet: string[]
@@ -62,23 +63,26 @@ export function WorkingSetPicker({ workingSet, onWorkingSetChange, workspaceRoot
 
   return (
     <div className="chat-working-set">
+      <span className="chat-working-set__label">Working set</span>
       {workingSet.map((path) => (
         <span key={path} className="chat-working-set__chip" title={path}>
           {basename(path)}
           <button
             className="chat-working-set__chip-remove"
             onClick={() => removeFile(path)}
+            aria-label={`Remove ${basename(path)}`}
           >
             &times;
           </button>
         </span>
       ))}
-      <button
-        className="chat-working-set__add"
+      <Button
+        variant="ghost"
+        size="sm"
         onClick={() => setDropdownOpen(!dropdownOpen)}
       >
-        +
-      </button>
+        + Add
+      </Button>
 
       {dropdownOpen && (
         <div className="chat-working-set__dropdown">
diff --git a/packages/renderer/src/components/panes/ChatPane.tsx b/packages/renderer/src/components/panes/ChatPane.tsx
index 1fb7c25..17f3498 100644
--- a/packages/renderer/src/components/panes/ChatPane.tsx
+++ b/packages/renderer/src/components/panes/ChatPane.tsx
@@ -46,11 +46,13 @@ export function ChatPane({ params, api }: IDockviewPanelProps<ChatPanelParams>)
           <PermissionTierBadge workspaceId={params?.workspaceId} />
         </div>
         {chat.mode === 'edit' && (
-          <WorkingSetPicker
-            workingSet={chat.workingSet}
-            onWorkingSetChange={chat.setWorkingSet}
-            workspaceRoot={params?.worktreePath ?? params?.workspaceRoot}
-          />
+          <div className="chat-pane__header-row">
+            <WorkingSetPicker
+              workingSet={chat.workingSet}
+              onWorkingSetChange={chat.setWorkingSet}
+              workspaceRoot={params?.worktreePath ?? params?.workspaceRoot}
+            />
+          </div>
         )}
       </div>
 
diff --git a/packages/renderer/src/components/ui/Badge.tsx b/packages/renderer/src/components/ui/Badge.tsx
new file mode 100644
index 0000000..916f2e3
--- /dev/null
+++ b/packages/renderer/src/components/ui/Badge.tsx
@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react'
+
+type BadgeVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info'
+
+interface BadgeProps {
+  variant?: BadgeVariant
+  icon?: ReactNode
+  title?: string
+  children: ReactNode
+}
+
+export function Badge({ variant = 'neutral', icon, title, children }: BadgeProps) {
+  return (
+    <span className={`ui-badge ui-badge--${variant}`} title={title}>
+      {icon != null && <span className="ui-badge__icon">{icon}</span>}
+      <span className="ui-badge__label">{children}</span>
+    </span>
+  )
+}
diff --git a/packages/renderer/src/components/ui/Button.tsx b/packages/renderer/src/components/ui/Button.tsx
new file mode 100644
index 0000000..85c70ef
--- /dev/null
+++ b/packages/renderer/src/components/ui/Button.tsx
@@ -0,0 +1,23 @@
+import { forwardRef } from 'react'
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+type ButtonVariant = 'ghost' | 'outline' | 'accent' | 'danger'
+type ButtonSize = 'sm' | 'md'
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant
+  size?: ButtonSize
+  children?: ReactNode
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'ghost', size = 'md', className, children, type = 'button', ...rest },
+  ref,
+) {
+  const cls = `ui-btn ui-btn--${variant} ui-btn--${size}${className ? ` ${className}` : ''}`
+  return (
+    <button ref={ref} type={type} className={cls} {...rest}>
+      {children}
+    </button>
+  )
+})
diff --git a/packages/renderer/src/components/ui/SegmentedControl.tsx b/packages/renderer/src/components/ui/SegmentedControl.tsx
new file mode 100644
index 0000000..b3b9e96
--- /dev/null
+++ b/packages/renderer/src/components/ui/SegmentedControl.tsx
@@ -0,0 +1,45 @@
+interface SegmentedControlOption<T extends string> {
+  value: T
+  label: string
+}
+
+interface SegmentedControlProps<T extends string> {
+  options: SegmentedControlOption<T>[]
+  value: T
+  onChange: (value: T) => void
+  disabled?: boolean
+  ariaLabel?: string
+}
+
+export function SegmentedControl<T extends string>({
+  options,
+  value,
+  onChange,
+  disabled,
+  ariaLabel,
+}: SegmentedControlProps<T>) {
+  return (
+    <div
+      className={`ui-segmented${disabled ? ' ui-segmented--disabled' : ''}`}
+      role="tablist"
+      aria-label={ariaLabel}
+    >
+      {options.map((opt) => {
+        const active = opt.value === value
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            disabled={disabled}
+            className={`ui-segmented__btn${active ? ' ui-segmented__btn--active' : ''}`}
+            onClick={() => onChange(opt.value)}
+          >
+            {opt.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/packages/renderer/src/main.tsx b/packages/renderer/src/main.tsx
index 47ebad3..f7fe2be 100644
--- a/packages/renderer/src/main.tsx
+++ b/packages/renderer/src/main.tsx
@@ -17,6 +17,7 @@ import './styles/find-in-files.css'
 import './styles/gitignore-modal.css'
 import './styles/welcome-pane.css'
 import './styles/settings-pane.css'
+import './styles/ui.css'
 import './styles/chat-pane.css'
 
 const rootElement = document.getElementById('root')
diff --git a/packages/renderer/src/styles/chat-pane.css b/packages/renderer/src/styles/chat-pane.css
index 6020ab0..1453c24 100644
--- a/packages/renderer/src/styles/chat-pane.css
+++ b/packages/renderer/src/styles/chat-pane.css
@@ -6,184 +6,30 @@
   height: 100%;
   background: var(--bg-base);
   color: var(--text-primary);
-  font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', sans-serif;
-  font-size: 13px;
+  font-family: var(--font-ui);
+  font-size: var(--font-size-sm);
   line-height: 1.4;
 }
 
+/* --- Header ----------------------------------------------------- */
+
 .chat-pane__header {
   flex-shrink: 0;
-  padding: 6px 8px;
-  border-bottom: 1px solid var(--border-base);
   background: var(--bg-elevated);
+  border-bottom: 1px solid var(--border-base);
 }
 
 .chat-pane__header-row {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 8px;
-}
-
-.chat-pane__footer {
-  flex-shrink: 0;
-  padding: 6px 8px;
-  border-top: 1px solid var(--border-base);
-  background: var(--bg-elevated);
-}
-
-/* --- Mode Selector ---------------------------------------------- */
-
-.chat-mode-selector {
-  display: flex;
-  border: 1px solid var(--border-base);
-  border-radius: 4px;
-  overflow: hidden;
-  height: 22px;
-}
-
-.chat-mode-selector--disabled {
-  opacity: 0.5;
-  pointer-events: none;
-}
-
-.chat-mode-selector__btn {
-  flex: 1;
-  border: none;
-  background: transparent;
-  color: var(--text-secondary);
-  font-family: inherit;
-  font-size: 10px;
-  font-weight: 600;
-  letter-spacing: 0.05em;
-  text-transform: uppercase;
-  cursor: pointer;
-  padding: 0 4px;
-  transition: background 0.1s, color 0.1s;
-}
-
-.chat-mode-selector__btn:not(:last-child) {
-  border-right: 1px solid var(--border-base);
-}
-
-.chat-mode-selector__btn:hover {
-  background: var(--bg-hover);
-}
-
-.chat-mode-selector__btn--active {
-  background: var(--bg-selection);
-  color: var(--text-primary);
-}
-
-/* --- Working Set ------------------------------------------------ */
-
-.chat-working-set {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 4px;
-  margin-top: 6px;
-  position: relative;
-}
-
-.chat-working-set__chip {
-  display: inline-flex;
-  align-items: center;
-  gap: 3px;
-  background: var(--bg-sunken);
-  border: 1px solid var(--border-subtle);
-  border-radius: 3px;
-  padding: 1px 6px;
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
-  color: var(--text-secondary);
-  max-width: 160px;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.chat-working-set__chip-remove {
-  border: none;
-  background: none;
-  color: var(--text-muted);
-  cursor: pointer;
-  padding: 0;
-  font-size: 12px;
-  line-height: 1;
-  flex-shrink: 0;
-}
-
-.chat-working-set__chip-remove:hover {
-  color: var(--text-error);
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-4);
+  min-height: 36px;
 }
 
-.chat-working-set__add {
-  border: 1px dashed var(--border-subtle);
-  background: none;
-  color: var(--text-muted);
-  border-radius: 3px;
-  padding: 1px 8px;
-  font-size: 12px;
-  cursor: pointer;
-  line-height: 1;
-}
-
-.chat-working-set__add:hover {
-  border-color: var(--accent);
-  color: var(--accent);
-}
-
-.chat-working-set__dropdown {
-  position: absolute;
-  top: 100%;
-  left: 0;
-  right: 0;
-  margin-top: 4px;
-  background: var(--bg-overlay);
-  border: 1px solid var(--border-base);
-  border-radius: 4px;
-  max-height: 200px;
-  overflow-y: auto;
-  z-index: 100;
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
-}
-
-.chat-working-set__dropdown-input {
-  width: 100%;
-  border: none;
-  border-bottom: 1px solid var(--border-base);
-  background: transparent;
-  color: var(--text-primary);
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
-  padding: 5px 8px;
-  outline: none;
-  box-sizing: border-box;
-}
-
-.chat-working-set__dropdown-item {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 3px 8px;
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
-  color: var(--text-secondary);
-  cursor: pointer;
-  border: none;
-  background: none;
-  width: 100%;
-  text-align: left;
-}
-
-.chat-working-set__dropdown-item:hover {
-  background: var(--bg-hover);
-}
-
-.chat-working-set__dropdown-item--selected {
-  color: var(--text-muted);
-  opacity: 0.6;
+.chat-pane__header-row + .chat-pane__header-row {
+  border-top: 1px solid var(--border-subtle);
 }
 
 /* --- Messages --------------------------------------------------- */
@@ -194,54 +40,65 @@
   overflow-x: hidden;
 }
 
+.chat-messages__inner {
+  max-width: 720px;
+  margin: 0 auto;
+  padding: var(--space-5) var(--space-4) var(--space-6);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-5);
+}
+
 .chat-messages__empty {
   display: flex;
   align-items: center;
   justify-content: center;
   height: 100%;
   color: var(--text-muted);
-  font-size: 13px;
+  font-size: var(--font-size-md);
 }
 
 /* --- Message Bubble --------------------------------------------- */
 
 .chat-msg {
-  padding: 8px 12px;
-  border-bottom: 1px solid var(--border-subtle);
-}
-
-.chat-msg--user {
   display: flex;
-  gap: 6px;
+  flex-direction: column;
+  gap: var(--space-2);
 }
 
-.chat-msg__prefix {
-  flex-shrink: 0;
+.chat-msg__role {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  font-size: var(--font-size-xs);
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
   color: var(--text-muted);
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
-  line-height: 1.6;
-  user-select: none;
 }
 
-.chat-msg__body {
+.chat-msg__role::after {
+  content: '';
   flex: 1;
-  min-width: 0;
-  overflow-wrap: break-word;
+  height: 1px;
+  background: var(--border-subtle);
+  min-width: var(--space-5);
 }
 
-.chat-msg--user .chat-msg__body {
+.chat-msg__body {
   color: var(--text-primary);
-  white-space: pre-wrap;
+  font-size: var(--font-size-lg);
+  line-height: 1.6;
+  overflow-wrap: break-word;
 }
 
-.chat-msg--assistant .chat-msg__body {
-  color: var(--text-secondary);
+.chat-msg--user .chat-msg__body {
+  white-space: pre-wrap;
 }
 
 /* Markdown content within assistant messages */
 .chat-msg--assistant .chat-msg__body p {
-  margin: 0 0 8px 0;
+  margin: 0 0 var(--space-3) 0;
 }
 
 .chat-msg--assistant .chat-msg__body p:last-child {
@@ -251,30 +108,30 @@
 .chat-msg--assistant .chat-msg__body pre {
   background: var(--bg-sunken);
   border: 1px solid var(--border-subtle);
-  border-radius: 3px;
-  padding: 8px 10px;
-  margin: 6px 0;
+  border-radius: var(--radius-md);
+  padding: var(--space-3) var(--space-4);
+  margin: var(--space-3) 0;
   overflow-x: auto;
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 12px;
-  line-height: 1.4;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-md);
+  line-height: 1.5;
 }
 
 .chat-msg--assistant .chat-msg__body code {
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 12px;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-md);
 }
 
 .chat-msg--assistant .chat-msg__body :not(pre) > code {
   background: var(--bg-sunken);
-  padding: 1px 4px;
-  border-radius: 2px;
+  padding: 1px var(--space-2);
+  border-radius: var(--radius-sm);
 }
 
 .chat-msg--assistant .chat-msg__body ul,
 .chat-msg--assistant .chat-msg__body ol {
-  margin: 4px 0;
-  padding-left: 20px;
+  margin: var(--space-2) 0;
+  padding-left: var(--space-5);
 }
 
 .chat-msg--assistant .chat-msg__body a {
@@ -287,235 +144,231 @@
 }
 
 /* Tool result message */
-.chat-msg--tool-result {
+.chat-msg--tool-result .chat-msg__body {
   background: var(--bg-sunken);
+  border: 1px solid var(--border-subtle);
   border-left: 2px solid var(--border-subtle);
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
+  border-radius: var(--radius-md);
+  padding: var(--space-3) var(--space-4);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
   color: var(--text-secondary);
   white-space: pre-wrap;
-  overflow-wrap: break-word;
+  line-height: 1.5;
 }
 
-.chat-msg--tool-result-error {
+.chat-msg--tool-result-error .chat-msg__body {
   border-left-color: var(--text-error);
 }
 
 /* Streaming cursor */
 .chat-msg__cursor {
+  display: inline-block;
+  margin-left: 1px;
   color: var(--accent);
-  animation: chat-cursor-blink 530ms step-end infinite;
+  animation: chat-cursor-blink 1s steps(2, jump-none) infinite;
 }
 
-/* --- Permission Tier Badge -------------------------------------- */
+@keyframes chat-cursor-blink {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
 
-.perm-tier-badge {
-  display: inline-flex;
+/* --- Working Set ------------------------------------------------ */
+
+.chat-working-set {
+  display: flex;
+  flex-wrap: wrap;
   align-items: center;
-  gap: 4px;
-  padding: 2px 8px;
-  border-radius: 3px;
-  font-size: 10px;
+  gap: var(--space-2);
+  position: relative;
+  flex: 1;
+  min-width: 0;
+}
+
+.chat-working-set__label {
+  font-size: var(--font-size-xs);
   font-weight: 600;
-  letter-spacing: 0.04em;
+  letter-spacing: 0.05em;
   text-transform: uppercase;
-  border: 1px solid var(--border-subtle);
-  background: var(--bg-sunken);
   color: var(--text-muted);
-  transition: background 0.2s, color 0.2s, border-color 0.2s;
-  cursor: default;
-  flex-shrink: 0;
+  margin-right: var(--space-2);
 }
 
-.perm-tier-badge__icon {
-  font-size: 11px;
-  line-height: 1;
-}
-
-.perm-tier-badge--confirm {
-  border-color: color-mix(in srgb, var(--text-warning) 30%, transparent);
-  color: var(--text-warning);
+.chat-working-set__chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  background: var(--bg-sunken);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  padding: 1px var(--space-2) 1px var(--space-3);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  color: var(--text-secondary);
+  max-width: 180px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
-.perm-tier-badge--auto {
-  border-color: color-mix(in srgb, var(--text-info) 30%, transparent);
-  color: var(--text-info);
+.chat-working-set__chip-remove {
+  border: none;
+  background: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 0;
+  font-size: var(--font-size-md);
+  line-height: 1;
+  flex-shrink: 0;
+  transition: color var(--motion-fast);
 }
 
-.perm-tier-badge--autopilot {
-  border-color: color-mix(in srgb, var(--text-success) 30%, transparent);
-  background: color-mix(in srgb, var(--text-success) 6%, transparent);
-  color: var(--text-success);
+.chat-working-set__chip-remove:hover {
+  color: var(--text-error);
 }
 
-/* --- Tool Call Card (redesigned) -------------------------------- */
-
-.tc-card {
-  margin: 6px 10px;
-  border-radius: 6px;
+.chat-working-set__dropdown {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  margin-top: var(--space-2);
+  background: var(--bg-overlay);
   border: 1px solid var(--border-base);
-  background: var(--bg-elevated);
-  overflow: hidden;
-  position: relative;
-  opacity: 0;
-  transform: translateY(4px);
-  transition: opacity 0.2s ease-out, transform 0.2s ease-out;
+  border-radius: var(--radius-md);
+  max-height: 220px;
+  overflow-y: auto;
+  z-index: 100;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.35);
 }
 
-.tc-card--visible {
-  opacity: 1;
-  transform: translateY(0);
+.chat-working-set__dropdown-input {
+  width: 100%;
+  border: none;
+  border-bottom: 1px solid var(--border-base);
+  background: transparent;
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  padding: var(--space-2) var(--space-3);
+  outline: none;
 }
 
-/* Left accent glow bar */
-.tc-card__glow {
-  position: absolute;
-  top: 0;
-  left: 0;
-  bottom: 0;
-  width: 3px;
-  border-radius: 3px 0 0 3px;
-  background: var(--border-subtle);
-  transition: background 0.3s;
+.chat-working-set__dropdown-item {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-3);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  color: var(--text-secondary);
+  cursor: pointer;
+  border: none;
+  background: none;
+  width: 100%;
+  text-align: left;
 }
 
-.tc-card--pending .tc-card__glow {
-  background: var(--text-warning);
-  box-shadow: 0 0 8px color-mix(in srgb, var(--text-warning) 30%, transparent);
-  animation: tc-glow-pulse 2s ease-in-out infinite;
+.chat-working-set__dropdown-item:hover {
+  background: var(--bg-hover);
 }
 
-.tc-card--approved .tc-card__glow,
-.tc-card--completed .tc-card__glow {
-  background: var(--text-success);
+.chat-working-set__dropdown-item--selected {
+  color: var(--text-muted);
+  opacity: 0.6;
 }
 
-.tc-card--rejected .tc-card__glow {
-  background: var(--text-error);
-}
+/* --- Tool Call Card --------------------------------------------- */
 
-@keyframes tc-glow-pulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.5; }
+.tc-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3) var(--space-3) var(--space-3) var(--space-4);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-subtle);
+  border-left: 2px solid var(--border-subtle);
+  border-radius: var(--radius-md);
 }
 
-.tc-card__main {
-  padding: 8px 10px 8px 14px;
+.tc-card--pending {
+  border-left-color: var(--text-warning);
+}
+.tc-card--approved,
+.tc-card--completed {
+  border-left-color: var(--text-success);
+}
+.tc-card--rejected {
+  border-left-color: var(--text-error);
+  opacity: 0.7;
 }
 
-/* Header row */
 .tc-card__header {
   display: flex;
   align-items: center;
-  gap: 8px;
+  gap: var(--space-3);
+  min-width: 0;
 }
 
 .tc-card__icon {
   flex-shrink: 0;
-  width: 24px;
-  height: 24px;
+  width: 18px;
+  height: 18px;
   display: flex;
   align-items: center;
   justify-content: center;
-  font-size: 12px;
-  font-weight: 700;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
   color: var(--text-secondary);
-  background: var(--bg-sunken);
-  border: 1px solid var(--border-subtle);
-  border-radius: 4px;
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
   line-height: 1;
 }
 
-.tc-card__title-group {
-  flex: 1;
-  min-width: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 1px;
-}
-
 .tc-card__name {
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
   font-weight: 600;
   color: var(--text-primary);
-  line-height: 1.2;
+  flex-shrink: 0;
+}
+
+.tc-card__sep {
+  color: var(--text-muted);
+  flex-shrink: 0;
 }
 
 .tc-card__summary {
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 10px;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
   color: var(--text-muted);
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
-  line-height: 1.2;
+  flex: 1;
+  min-width: 0;
 }
 
-/* Status area */
 .tc-card__status-area {
   flex-shrink: 0;
   display: flex;
   align-items: center;
-  gap: 5px;
-}
-
-.tc-card__dot {
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  flex-shrink: 0;
-}
-
-.tc-card__dot--pending {
-  background: var(--text-warning);
-  animation: chat-pulse 1.5s ease-in-out infinite;
-}
-
-.tc-card__dot--approved,
-.tc-card__dot--completed {
-  background: var(--text-success);
-}
-
-.tc-card__dot--rejected {
-  background: var(--text-error);
-}
-
-.tc-card__status-label {
-  font-size: 10px;
-  color: var(--text-muted);
-  text-transform: uppercase;
-  letter-spacing: 0.03em;
-  font-weight: 500;
-}
-
-.tc-card__auto-tag {
-  font-size: 9px;
-  font-weight: 700;
-  letter-spacing: 0.04em;
-  text-transform: uppercase;
-  color: var(--text-info, var(--accent));
-  background: color-mix(in srgb, var(--text-info, var(--accent)) 10%, transparent);
-  border-radius: 3px;
-  padding: 1px 5px;
-  line-height: 1;
+  gap: var(--space-2);
 }
 
-/* Expand/collapse */
 .tc-card__expand-btn {
-  display: flex;
+  display: inline-flex;
   align-items: center;
-  gap: 4px;
-  margin-top: 4px;
+  gap: var(--space-2);
   padding: 0;
   border: none;
   background: none;
   color: var(--text-muted);
-  font-family: inherit;
-  font-size: 10px;
+  font-family: var(--font-ui);
+  font-size: var(--font-size-xs);
   cursor: pointer;
-  transition: color 0.1s;
+  align-self: flex-start;
+  transition: color var(--motion-fast);
 }
 
 .tc-card__expand-btn:hover {
@@ -524,109 +377,55 @@
 
 .tc-card__chevron {
   display: inline-block;
-  font-size: 10px;
-  transition: transform 0.15s ease;
+  font-size: var(--font-size-xs);
+  transition: transform var(--motion-base);
 }
 
 .tc-card__chevron--open {
   transform: rotate(90deg);
 }
 
-/* Detail preview */
 .tc-card__detail {
-  margin: 6px 0 2px;
-  padding: 6px 8px;
+  margin: 0;
+  padding: var(--space-3);
   background: var(--bg-sunken);
   border: 1px solid var(--border-subtle);
-  border-radius: 4px;
-  font-family: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
-  font-size: 11px;
+  border-radius: var(--radius-sm);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
   color: var(--text-secondary);
   white-space: pre-wrap;
   overflow-wrap: break-word;
-  max-height: 140px;
+  max-height: 160px;
   overflow-y: auto;
   line-height: 1.5;
 }
 
-/* Approval actions */
 .tc-card__actions {
   display: flex;
-  gap: 6px;
-  margin-top: 8px;
-}
-
-.tc-card__btn {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  border-radius: 4px;
-  padding: 4px 12px;
-  font-family: inherit;
-  font-size: 11px;
-  font-weight: 600;
-  cursor: pointer;
-  transition: background 0.15s, transform 0.1s;
-}
-
-.tc-card__btn:active {
-  transform: scale(0.97);
-}
-
-.tc-card__btn-icon {
-  font-size: 11px;
-  line-height: 1;
-}
-
-.tc-card__btn--allow {
-  border: 1px solid var(--text-success);
-  color: var(--text-success);
-  background: transparent;
-}
-
-.tc-card__btn--allow:hover {
-  background: color-mix(in srgb, var(--text-success) 12%, transparent);
-}
-
-.tc-card__btn--deny {
-  border: 1px solid var(--text-error);
-  color: var(--text-error);
-  background: transparent;
-}
-
-.tc-card__btn--deny:hover {
-  background: color-mix(in srgb, var(--text-error) 12%, transparent);
+  gap: var(--space-2);
 }
 
-/* Resolved state */
 .tc-card__resolved {
   display: flex;
   align-items: center;
-  gap: 4px;
-  margin-top: 4px;
-  font-size: 10px;
+  gap: var(--space-2);
+  font-size: var(--font-size-xs);
   color: var(--text-muted);
 }
 
 .tc-card__resolved-icon {
   color: var(--text-success);
-  font-size: 11px;
-}
-
-/* Awaiting state */
-.tc-card--awaiting {
-  border-color: color-mix(in srgb, var(--text-warning) 40%, var(--border-base));
 }
 
 /* --- Status Line ------------------------------------------------ */
 
 .chat-status {
-  padding: 6px 12px;
-  font-size: 11px;
+  padding: var(--space-2) var(--space-4);
+  font-size: var(--font-size-sm);
   font-style: italic;
   color: var(--text-muted);
   border-left: 2px solid var(--accent);
-  margin: 4px 12px;
 }
 
 .chat-status--warning {
@@ -636,26 +435,41 @@
 
 /* --- Chat Input ------------------------------------------------- */
 
+.chat-pane__footer {
+  flex-shrink: 0;
+  padding: var(--space-3) var(--space-4);
+  border-top: 1px solid var(--border-base);
+  background: var(--bg-elevated);
+}
+
 .chat-input {
   display: flex;
   align-items: flex-end;
-  gap: 6px;
+  gap: var(--space-3);
+  background: var(--bg-sunken);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  padding: var(--space-2) var(--space-2) var(--space-2) var(--space-3);
+  transition: border-color var(--motion-base);
+}
+
+.chat-input:focus-within {
+  border-color: var(--accent);
 }
 
 .chat-input__textarea {
   flex: 1;
-  background: var(--bg-sunken);
-  border: 1px solid var(--border-base);
-  border-radius: 4px;
-  padding: 6px 10px;
-  font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', sans-serif;
-  font-size: 13px;
-  line-height: 1.4;
+  background: transparent;
+  border: none;
+  padding: var(--space-2) 0;
+  font-family: var(--font-ui);
+  font-size: var(--font-size-lg);
+  line-height: 1.5;
   color: var(--text-primary);
   resize: none;
   outline: none;
-  min-height: 20px;
-  max-height: 146px; /* ~8 lines */
+  min-height: 22px;
+  max-height: 160px;
   overflow-y: auto;
 }
 
@@ -663,58 +477,6 @@
   color: var(--text-muted);
 }
 
-.chat-input__textarea:focus {
-  border-color: var(--accent);
-}
-
-.chat-input__btn-send {
-  border: none;
-  background: none;
-  color: var(--accent);
-  font-family: inherit;
-  font-size: 11px;
-  font-weight: 600;
-  cursor: pointer;
-  padding: 4px 6px;
-  flex-shrink: 0;
-  line-height: 1;
-}
-
-.chat-input__btn-send:disabled {
-  color: var(--text-muted);
-  cursor: default;
-}
-
-.chat-input__btn-stop {
-  border: none;
-  background: none;
-  cursor: pointer;
-  padding: 4px 6px;
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
-
-.chat-input__btn-stop__icon {
-  width: 10px;
-  height: 10px;
-  background: var(--text-error);
-  border-radius: 2px;
-}
-
-/* --- Animations ------------------------------------------------- */
-
-@keyframes chat-cursor-blink {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0; }
-}
-
-@keyframes chat-pulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.4; }
-}
-
 /* --- Syntax highlight tokens (inherit from themes) -------------- */
 
 .chat-msg--assistant .chat-msg__body .hljs-keyword { color: var(--syntax-keyword); }
@@ -727,21 +489,3 @@
 .chat-msg--assistant .chat-msg__body .hljs-built_in { color: var(--syntax-fn); }
 .chat-msg--assistant .chat-msg__body .hljs-literal { color: var(--syntax-number); }
 .chat-msg--assistant .chat-msg__body .hljs-type { color: var(--syntax-keyword); }
-
-/* Scrollbar styling */
-.chat-messages::-webkit-scrollbar {
-  width: 8px;
-}
-
-.chat-messages::-webkit-scrollbar-track {
-  background: transparent;
-}
-
-.chat-messages::-webkit-scrollbar-thumb {
-  background: var(--border-subtle);
-  border-radius: 4px;
-}
-
-.chat-messages::-webkit-scrollbar-thumb:hover {
-  background: var(--text-muted);
-}
diff --git a/packages/renderer/src/styles/cli-agent-pane.css b/packages/renderer/src/styles/cli-agent-pane.css
index 95a6fb4..c156ff3 100644
--- a/packages/renderer/src/styles/cli-agent-pane.css
+++ b/packages/renderer/src/styles/cli-agent-pane.css
@@ -51,8 +51,8 @@
 }
 
 .cli-agent-pane__btn--start {
-  background: var(--accent-blue, #3b82f6);
-  color: #fff;
+  background: var(--accent);
+  color: var(--text-on-accent);
 }
 
 .cli-agent-pane__btn--start:hover {
@@ -60,8 +60,8 @@
 }
 
 .cli-agent-pane__btn--stop {
-  background: var(--accent-red, #ef4444);
-  color: #fff;
+  background: var(--text-error);
+  color: var(--text-on-accent);
 }
 
 .cli-agent-pane__btn--stop:hover {
@@ -75,10 +75,10 @@
   align-items: flex-start;
   gap: 6px;
   padding: 6px 8px;
-  background: color-mix(in srgb, var(--accent-red, #ef4444) 12%, transparent);
+  background: color-mix(in srgb, var(--text-error) 12%, transparent);
   border-bottom: 1px solid var(--border-base);
   font-size: 12px;
-  color: var(--accent-red, #ef4444);
+  color: var(--text-error);
 }
 
 .cli-agent-pane__error-icon {
@@ -133,7 +133,7 @@
 }
 
 .cli-agent-msg__prefix {
-  color: var(--accent-blue, #3b82f6);
+  color: var(--accent);
   font-weight: 700;
   flex-shrink: 0;
 }
@@ -148,23 +148,26 @@
 }
 
 .cli-agent-msg--assistant code {
-  background: var(--bg-elevated);
+  background: var(--bg-sunken);
   padding: 1px 4px;
-  border-radius: 3px;
-  font-size: 12px;
+  border-radius: var(--radius-sm);
+  font-size: var(--font-size-md);
+  font-family: var(--font-mono);
 }
 
 .cli-agent-msg--assistant pre {
-  background: var(--bg-elevated);
-  padding: 8px;
-  border-radius: 4px;
+  background: var(--bg-sunken);
+  border: 1px solid var(--border-subtle);
+  padding: var(--space-3);
+  border-radius: var(--radius-md);
   overflow-x: auto;
-  margin: 4px 0;
+  margin: var(--space-2) 0;
+  font-family: var(--font-mono);
 }
 
 .cli-agent-msg__cursor {
   animation: cli-agent-cursor-blink 0.8s step-end infinite;
-  color: var(--accent-blue, #3b82f6);
+  color: var(--accent);
 }
 
 @keyframes cli-agent-cursor-blink {
@@ -186,7 +189,7 @@
 
 .cli-agent-msg__tool-icon {
   font-size: 8px;
-  color: var(--accent-blue, #3b82f6);
+  color: var(--accent);
 }
 
 .cli-agent-msg__tool-name {
@@ -217,13 +220,13 @@
 }
 
 .cli-agent-msg--result {
-  color: var(--accent-green, #22c55e);
+  color: var(--text-success);
   font-style: normal;
   font-weight: 500;
 }
 
 .cli-agent-msg--error {
   font-size: 12px;
-  color: var(--accent-red, #ef4444);
+  color: var(--text-error);
   padding: 3px 0;
 }
diff --git a/packages/renderer/src/styles/global.css b/packages/renderer/src/styles/global.css
index 2d98df5..0f4cfdd 100644
--- a/packages/renderer/src/styles/global.css
+++ b/packages/renderer/src/styles/global.css
@@ -1,3 +1,34 @@
+:root {
+  /* Fonts */
+  --font-ui: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', sans-serif;
+  --font-mono: 'SF Mono', Menlo, Monaco, 'Courier New', monospace;
+
+  /* Type scale */
+  --font-size-xs: 10px;
+  --font-size-sm: 11px;
+  --font-size-md: 12px;
+  --font-size-lg: 13px;
+
+  /* Spacing scale */
+  --space-1: 2px;
+  --space-2: 4px;
+  --space-3: 8px;
+  --space-4: 12px;
+  --space-5: 16px;
+  --space-6: 24px;
+
+  /* Radius */
+  --radius-sm: 3px;
+  --radius-md: 4px;
+  --radius-lg: 6px;
+  --radius-pill: 999px;
+
+  /* Motion */
+  --motion-fast: 80ms ease;
+  --motion-base: 120ms ease;
+  --motion-slow: 200ms ease;
+}
+
 *,
 *::before,
 *::after {
diff --git a/packages/renderer/src/styles/ui.css b/packages/renderer/src/styles/ui.css
new file mode 100644
index 0000000..8cf35fc
--- /dev/null
+++ b/packages/renderer/src/styles/ui.css
@@ -0,0 +1,172 @@
+/* --- Shared UI primitives --------------------------------------- */
+
+/* Button */
+
+.ui-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--text-secondary);
+  font-family: var(--font-ui);
+  font-weight: 500;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: background var(--motion-base), color var(--motion-base),
+    border-color var(--motion-base);
+  white-space: nowrap;
+  user-select: none;
+}
+
+.ui-btn:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+.ui-btn--sm {
+  height: 22px;
+  padding: 0 var(--space-3);
+  font-size: var(--font-size-sm);
+}
+
+.ui-btn--md {
+  height: 28px;
+  padding: 0 var(--space-4);
+  font-size: var(--font-size-sm);
+}
+
+/* ghost — default */
+.ui-btn--ghost {
+  background: transparent;
+  color: var(--text-secondary);
+}
+.ui-btn--ghost:hover:not(:disabled) {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+/* outline */
+.ui-btn--outline {
+  border-color: var(--border-subtle);
+  color: var(--text-primary);
+}
+.ui-btn--outline:hover:not(:disabled) {
+  background: var(--bg-hover);
+  border-color: var(--text-muted);
+}
+
+/* accent */
+.ui-btn--accent {
+  color: var(--accent);
+  border-color: color-mix(in srgb, var(--accent) 35%, transparent);
+  background: color-mix(in srgb, var(--accent) 8%, transparent);
+  font-weight: 600;
+}
+.ui-btn--accent:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--accent) 16%, transparent);
+  border-color: var(--accent);
+}
+
+/* danger */
+.ui-btn--danger {
+  color: var(--text-error);
+  border-color: color-mix(in srgb, var(--text-error) 35%, transparent);
+  background: transparent;
+  font-weight: 600;
+}
+.ui-btn--danger:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--text-error) 12%, transparent);
+  border-color: var(--text-error);
+}
+
+/* Badge */
+
+.ui-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: 1px var(--space-3);
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-subtle);
+  background: var(--bg-sunken);
+  color: var(--text-muted);
+  font-family: var(--font-ui);
+  font-size: var(--font-size-xs);
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  line-height: 1.6;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.ui-badge__icon {
+  font-size: var(--font-size-sm);
+  line-height: 1;
+}
+
+.ui-badge--neutral {
+  color: var(--text-muted);
+}
+.ui-badge--success {
+  color: var(--text-success);
+  border-color: color-mix(in srgb, var(--text-success) 30%, transparent);
+}
+.ui-badge--warning {
+  color: var(--text-warning);
+  border-color: color-mix(in srgb, var(--text-warning) 30%, transparent);
+}
+.ui-badge--error {
+  color: var(--text-error);
+  border-color: color-mix(in srgb, var(--text-error) 30%, transparent);
+}
+.ui-badge--info {
+  color: var(--text-info);
+  border-color: color-mix(in srgb, var(--text-info) 30%, transparent);
+}
+
+/* Segmented control */
+
+.ui-segmented {
+  display: inline-flex;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+  height: 22px;
+  background: var(--bg-sunken);
+}
+
+.ui-segmented--disabled {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.ui-segmented__btn {
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  font-family: var(--font-ui);
+  font-size: var(--font-size-xs);
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  cursor: pointer;
+  padding: 0 var(--space-3);
+  transition: background var(--motion-base), color var(--motion-base);
+}
+
+.ui-segmented__btn + .ui-segmented__btn {
+  border-left: 1px solid var(--border-subtle);
+}
+
+.ui-segmented__btn:hover:not([aria-selected='true']) {
+  background: var(--bg-hover);
+  color: var(--text-secondary);
+}
+
+.ui-segmented__btn--active {
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  color: var(--text-primary);
+}

From 2ce01dfafbcd8e9c142a8b8fbab80592522bb9e1 Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 16:03:18 -0400
Subject: [PATCH 3/9] feat: prep CLI agent UI for opencode + backend hot-swap

Adds opencode as a first-class CLI backend across the renderer, introduces
a backend switcher in CliAgentPane, and renders per-message backend badges
for mixed-backend transcripts. Centralizes backend label/CLI-detection
helpers in lib/agentBackend.ts so routing, history, and settings stop
hardcoding claude-code/codex checks. Forward-compatible with the upcoming
cliAgentSwitchBackend IPC: falls back to start() when unavailable.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../renderer/src/commands/domains/agent.ts    | 13 ++--
 .../src/components/layout/AppShell.tsx        | 11 +--
 .../src/components/panes/ChatHistoryPane.tsx  | 63 +++++++++------
 .../src/components/panes/CliAgentPane.tsx     | 73 ++++++++++++++++--
 packages/renderer/src/hooks/useCliAgent.ts    | 35 +++++++++
 packages/renderer/src/lib/agentBackend.ts     | 42 ++++++++++
 packages/renderer/src/lib/settingsSchema.ts   | 11 ++-
 .../src/lib/workspace/workspaceSwitcher.ts    |  5 +-
 .../renderer/src/styles/chat-history-pane.css | 69 +++++++++++++++++
 .../renderer/src/styles/cli-agent-pane.css    | 76 +++++++++++++++++++
 packages/shared/src/cliAgentTypes.ts          | 11 ++-
 packages/shared/src/index.ts                  |  5 +-
 12 files changed, 371 insertions(+), 43 deletions(-)
 create mode 100644 packages/renderer/src/lib/agentBackend.ts

diff --git a/packages/renderer/src/commands/domains/agent.ts b/packages/renderer/src/commands/domains/agent.ts
index 5dbe1f6..c05a17d 100644
--- a/packages/renderer/src/commands/domains/agent.ts
+++ b/packages/renderer/src/commands/domains/agent.ts
@@ -4,10 +4,11 @@
  * Backend choice comes from resolved settings (`agent.backend`). Built-in chat creates a conversation via IPC first when possible.
  */
 
-import type { ConversationMeta } from '@aide/shared'
+import type { ConversationMeta, ExternalCliBackend } from '@aide/shared'
 import type { DockviewApi, IDockviewPanel } from 'dockview-react'
 import type { CommandContext, GetCommandContext } from '../context'
 import type { CommandSpec } from './types'
+import { backendLabel, isCliBackend } from '../../lib/agentBackend'
 
 /**
  * Creates a `chatPane` with a server-issued `conversationId`, or falls back to a panel without id if create fails.
@@ -61,7 +62,7 @@ function addCliAgentPanel(
   workspaceId: string,
   workspaceRoot: string | undefined,
   editorPanel: IDockviewPanel | undefined,
-  backend: Extract<ConversationMeta['backend'], 'claude-code' | 'codex'>,
+  backend: ExternalCliBackend,
 ): void {
   void window.api.conversationCreate({
     workspaceId,
@@ -71,7 +72,7 @@ function addCliAgentPanel(
       id: `agent-${Date.now()}`,
       component: 'cliAgentPane',
       tabComponent: 'agentTab',
-      title: backend === 'claude-code' ? 'Claude Code' : 'Codex',
+      title: backendLabel(backend),
       params: {
         workspaceId,
         workspaceRoot,
@@ -89,7 +90,7 @@ function addCliAgentPanel(
       id: `agent-${Date.now()}`,
       component: 'cliAgentPane',
       tabComponent: 'agentTab',
-      title: backend === 'claude-code' ? 'Claude Code' : 'Codex',
+      title: backendLabel(backend),
       params: {
         workspaceId,
         workspaceRoot,
@@ -124,7 +125,7 @@ export function collectAgentCommands(getCtx: GetCommandContext): CommandSpec[] {
 
         void window.api.getResolvedSettings(workspaceId).then((resolved) => {
           const backend = resolved['agent.backend'] ?? 'built-in'
-          if (backend === 'claude-code' || backend === 'codex') {
+          if (isCliBackend(backend)) {
             addCliAgentPanel(ctx, api, workspaceId, workspaceRoot, editorPanel, backend)
           } else {
             addBuiltInAgentPanel(ctx, api, workspaceId, workspaceRoot, editorPanel)
@@ -148,7 +149,7 @@ export function collectAgentCommands(getCtx: GetCommandContext): CommandSpec[] {
           api.addPanel({
             id: `agent-${Date.now()}`,
             component:
-              conv.source === 'claude-native' || conv.backend === 'claude-code' || conv.backend === 'codex'
+              conv.source === 'claude-native' || isCliBackend(conv.backend)
                 ? 'cliAgentPane'
                 : 'chatPane',
             tabComponent: 'agentTab',
diff --git a/packages/renderer/src/components/layout/AppShell.tsx b/packages/renderer/src/components/layout/AppShell.tsx
index d277d4a..a850ee1 100644
--- a/packages/renderer/src/components/layout/AppShell.tsx
+++ b/packages/renderer/src/components/layout/AppShell.tsx
@@ -28,6 +28,7 @@ import { autoSave, switchWorkspace as doSwitchWorkspace } from '../../lib/worksp
 import { createTerminalPanelParams, getTerminalParams } from '../../lib/terminal/terminalState'
 import { createBrowserPanelParams, getBrowserParams } from '../../lib/browserState'
 import { getPanelZoomFactor, updatePanelZoomParams } from '../../lib/panelZoom'
+import { backendLabel, isCliBackend } from '../../lib/agentBackend'
 import { DockviewNavigation } from '../../lib/dockviewNavigation'
 import {
   captureWorkspaceRuntimeSnapshot,
@@ -920,7 +921,7 @@ export function AppShell() {
                       if (!isStillCurrent()) return
                       const backend = resolved['agent.backend'] ?? 'built-in'
 
-                      if (backend === 'claude-code' || backend === 'codex') {
+                      if (isCliBackend(backend)) {
                         void window.api.conversationCreate({
                           workspaceId: activeWorkspaceId,
                           backend,
@@ -933,8 +934,8 @@ export function AppShell() {
                             component: 'cliAgentPane',
                             tabComponent: 'agentTab',
                             title: branch
-                              ? `${backend === 'claude-code' ? 'Claude Code' : 'Codex'} (${branch})`
-                              : backend === 'claude-code' ? 'Claude Code' : 'Codex',
+                              ? `${backendLabel(backend)} (${branch})`
+                              : backendLabel(backend),
                             params: {
                               workspaceId: activeWorkspaceId,
                               workspaceRoot: workspaceRoot ?? undefined,
@@ -956,8 +957,8 @@ export function AppShell() {
                             component: 'cliAgentPane',
                             tabComponent: 'agentTab',
                             title: branch
-                              ? `${backend === 'claude-code' ? 'Claude Code' : 'Codex'} (${branch})`
-                              : backend === 'claude-code' ? 'Claude Code' : 'Codex',
+                              ? `${backendLabel(backend)} (${branch})`
+                              : backendLabel(backend),
                             params: {
                               workspaceId: activeWorkspaceId,
                               workspaceRoot: workspaceRoot ?? undefined,
diff --git a/packages/renderer/src/components/panes/ChatHistoryPane.tsx b/packages/renderer/src/components/panes/ChatHistoryPane.tsx
index e10bf74..04a9082 100644
--- a/packages/renderer/src/components/panes/ChatHistoryPane.tsx
+++ b/packages/renderer/src/components/panes/ChatHistoryPane.tsx
@@ -1,7 +1,8 @@
 import { useState, useRef, useEffect, useCallback } from 'react'
 import type { IDockviewPanelProps } from 'dockview-react'
-import type { ConversationMeta, AgentBackend } from '@aide/shared'
+import type { AgentBackend, ConversationMeta } from '@aide/shared'
 import { useConversationHistory } from '../../hooks/useConversationHistory'
+import { CLI_BACKENDS, backendBadgeLabel, backendLabel, isCliBackend } from '../../lib/agentBackend'
 import '../../styles/chat-history-pane.css'
 
 interface ChatHistoryPanelParams {
@@ -18,6 +19,7 @@ export function ChatHistoryPane({ params }: IDockviewPanelProps<ChatHistoryPanel
   const [contextMenu, setContextMenu] = useState<{ x: number; y: number; meta: ConversationMeta } | null>(null)
   const [renaming, setRenaming] = useState<string | null>(null)
   const [renameValue, setRenameValue] = useState('')
+  const [newMenuOpen, setNewMenuOpen] = useState(false)
   const filterRef = useRef<HTMLInputElement>(null)
   /** Dedupe double-click (two click events + dblclick) opening multiple tabs. */
   const lastActivateRef = useRef<{ id: string; t: number } | null>(null)
@@ -78,13 +80,43 @@ export function ChatHistoryPane({ params }: IDockviewPanelProps<ChatHistoryPanel
       {/* Header */}
       <div className="chat-history-pane__header">
         <span className="chat-history-pane__title">Conversations</span>
-        <button
-          className="chat-history-pane__new-btn"
-          onClick={() => handleNewChat('built-in')}
-          title="New conversation"
-        >
-          +
-        </button>
+        <div className="chat-history-pane__new-wrap">
+          <button
+            className="chat-history-pane__new-btn"
+            onClick={() => handleNewChat('built-in')}
+            title="New built-in conversation"
+          >
+            +
+          </button>
+          <button
+            className="chat-history-pane__new-caret"
+            onClick={(e) => { e.stopPropagation(); setNewMenuOpen((v) => !v) }}
+            title="New conversation with backend…"
+            aria-label="Choose backend"
+          >
+            {'\u25BE'}
+          </button>
+          {newMenuOpen && (
+            <div className="chat-history-pane__new-menu" onClick={(e) => e.stopPropagation()}>
+              <button
+                className="chat-history-pane__new-menu-item"
+                onClick={() => { setNewMenuOpen(false); void handleNewChat('built-in') }}
+              >
+                {backendLabel('built-in')}
+              </button>
+              <div className="chat-history-pane__new-menu-sep" />
+              {CLI_BACKENDS.map((b) => (
+                <button
+                  key={b}
+                  className="chat-history-pane__new-menu-item"
+                  onClick={() => { setNewMenuOpen(false); void handleNewChat(b) }}
+                >
+                  {backendLabel(b)}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
       </div>
 
       {/* Filter */}
@@ -147,7 +179,7 @@ export function ChatHistoryPane({ params }: IDockviewPanelProps<ChatHistoryPanel
                 <span className="chat-history-pane__item-badge chat-history-pane__item-badge--cli">CLI</span>
               )}
               <span className={`chat-history-pane__item-badge chat-history-pane__item-badge--${meta.backend}`}>
-                {backendLabel(meta.backend)}
+                {backendBadgeLabel(meta.backend)}
               </span>
             </div>
           </div>
@@ -183,19 +215,6 @@ export function ChatHistoryPane({ params }: IDockviewPanelProps<ChatHistoryPanel
 // Helpers
 // ---------------------------------------------------------------------------
 
-function isCliBackend(backend: AgentBackend): boolean {
-  return backend === 'claude-code' || backend === 'codex'
-}
-
-function backendLabel(backend: AgentBackend): string {
-  switch (backend) {
-    case 'built-in': return 'built-in'
-    case 'claude-code': return 'claude'
-    case 'codex': return 'codex'
-    default: return backend
-  }
-}
-
 function formatRelativeTime(timestamp: number): string {
   const diff = Date.now() - timestamp
   const seconds = Math.floor(diff / 1000)
diff --git a/packages/renderer/src/components/panes/CliAgentPane.tsx b/packages/renderer/src/components/panes/CliAgentPane.tsx
index 0cc9fd6..1d8fe23 100644
--- a/packages/renderer/src/components/panes/CliAgentPane.tsx
+++ b/packages/renderer/src/components/panes/CliAgentPane.tsx
@@ -5,6 +5,7 @@ import { useCliAgent } from '../../hooks/useCliAgent'
 import { AgentStatusDot } from '../chat/AgentStatusDot'
 import { ChatInput } from '../chat/ChatInput'
 import { renderMarkdown } from '../../lib/markdownRenderer'
+import { CLI_BACKENDS, backendBadgeLabel, backendLabel } from '../../lib/agentBackend'
 import '../../styles/cli-agent-pane.css'
 
 interface CliAgentPanelParams {
@@ -76,15 +77,51 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
   }
 
   const isActive = agent.processStatus === 'running' || agent.processStatus === 'starting' || agent.processStatus === 'rate_limited'
+  const headerBackend: AgentBackend = agent.activeBackend ?? backend
+
+  // Detect mixed-backend transcripts so we only render per-message badges when
+  // the conversation actually contains output from more than one external CLI.
+  const backendsSeen = useMemo(() => {
+    const set = new Set<AgentBackend>()
+    for (const m of agent.messages) {
+      if (m.backend) set.add(m.backend)
+    }
+    return set
+  }, [agent.messages])
+  const showBackendBadges = backendsSeen.size > 1
+
+  const handleBackendChange = async (next: AgentBackend) => {
+    if (next === headerBackend) return
+    if (isActive) return
+    const ok = await agent.switchBackend(next)
+    // Fall back to a fresh start() if the hot-swap IPC isn't wired in this build.
+    if (!ok) await agent.start(next)
+  }
 
   return (
     <div className="cli-agent-pane" style={{ ['--panel-zoom' as string]: String(zoomFactor ?? 1) }}>
       {/* Header */}
       <div className="cli-agent-pane__header">
         <AgentStatusDot status={agent.processStatus} />
-        <span className="cli-agent-pane__backend-label">
-          {backend === 'claude-code' ? 'Claude Code' : 'Codex'}
-        </span>
+        <label
+          className={`cli-agent-pane__backend-switcher cli-agent-pane__backend-switcher--${headerBackend}`}
+          title={isActive ? 'Stop the active turn before switching backends' : 'Switch backend'}
+        >
+          <span className="cli-agent-pane__backend-label">
+            {backendLabel(headerBackend)}
+          </span>
+          <span className="cli-agent-pane__backend-caret">{'\u25BE'}</span>
+          <select
+            className="cli-agent-pane__backend-select"
+            value={headerBackend}
+            disabled={isActive}
+            onChange={(e) => { void handleBackendChange(e.target.value as AgentBackend) }}
+          >
+            {CLI_BACKENDS.map((b) => (
+              <option key={b} value={b}>{backendLabel(b)}</option>
+            ))}
+          </select>
+        </label>
         {agent.model && (
           <span className="cli-agent-pane__model">{agent.model}</span>
         )}
@@ -122,7 +159,11 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
         )}
 
         {agent.messages.map((msg) => (
-          <CliAgentMessageBubble key={msg.id} message={msg} />
+          <CliAgentMessageBubble
+            key={msg.id}
+            message={msg}
+            showBackendBadge={showBackendBadges}
+          />
         ))}
 
         {agent.streamingContent && (
@@ -150,7 +191,23 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
 // Sub-components
 // ---------------------------------------------------------------------------
 
-function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
+function CliAgentMessageBubble({
+  message,
+  showBackendBadge,
+}: {
+  message: CliAgentMessage
+  showBackendBadge: boolean
+}) {
+  const badge =
+    showBackendBadge && message.backend && message.type !== 'user' ? (
+      <span
+        className={`cli-agent-msg__backend-badge cli-agent-msg__backend-badge--${message.backend}`}
+        title={`From ${backendLabel(message.backend)}`}
+      >
+        {backendBadgeLabel(message.backend)}
+      </span>
+    ) : null
+
   if (message.type === 'user') {
     return (
       <div className="cli-agent-msg cli-agent-msg--user">
@@ -166,6 +223,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
         <span className="cli-agent-msg__tool-icon">&#x25B6;</span>
         <span className="cli-agent-msg__tool-name">{message.toolName ?? 'tool'}</span>
         <span className="cli-agent-msg__tool-text">{message.content}</span>
+        {badge}
       </div>
     )
   }
@@ -174,6 +232,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
     return (
       <div className="cli-agent-msg cli-agent-msg--tool-result">
         {message.content}
+        {badge}
       </div>
     )
   }
@@ -182,6 +241,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
     return (
       <div className="cli-agent-msg cli-agent-msg--system">
         {message.content}
+        {badge}
       </div>
     )
   }
@@ -190,6 +250,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
     return (
       <div className="cli-agent-msg cli-agent-msg--result">
         {message.content}
+        {badge}
       </div>
     )
   }
@@ -198,6 +259,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
     return (
       <div className="cli-agent-msg cli-agent-msg--error">
         {message.content}
+        {badge}
       </div>
     )
   }
@@ -206,6 +268,7 @@ function CliAgentMessageBubble({ message }: { message: CliAgentMessage }) {
   return (
     <div className="cli-agent-msg cli-agent-msg--assistant">
       <CliAgentMarkdown content={message.content} />
+      {badge}
     </div>
   )
 }
diff --git a/packages/renderer/src/hooks/useCliAgent.ts b/packages/renderer/src/hooks/useCliAgent.ts
index a486013..9b4c1e3 100644
--- a/packages/renderer/src/hooks/useCliAgent.ts
+++ b/packages/renderer/src/hooks/useCliAgent.ts
@@ -20,9 +20,13 @@ export interface UseCliAgentReturn {
   model: string | null
   lastError: string | null
   conversationTitle: string
+  /** Currently active external backend for this session (source of truth for the pane header). */
+  activeBackend: AgentBackend | null
   start: (backend: AgentBackend) => Promise<void>
   send: (content: string) => Promise<void>
   stop: () => void
+  /** Hot-swap the underlying CLI backend for this conversation. Returns true on success. */
+  switchBackend: (backend: AgentBackend) => Promise<boolean>
 }
 
 export interface UseCliAgentOptions {
@@ -34,6 +38,7 @@ export interface UseCliAgentOptions {
 
 export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
   const { workspaceId, conversationId, worktreePath } = options
+  const [activeBackend, setActiveBackend] = useState<AgentBackend | null>(options.backend ?? null)
   const sessionIdRef = useRef<string | null>(null)
   const messagesRef = useRef<CliAgentMessage[]>([])
   const [renderTick, setRenderTick] = useState(0)
@@ -82,6 +87,7 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
         setProcessStatus(session.processStatus)
         setModel(session.model ?? null)
         setLastError(session.lastError ?? null)
+        setActiveBackend(session.activeBackend ?? session.backend ?? options.backend ?? null)
         setHistoryHydrated(true)
         tick()
         return
@@ -216,6 +222,7 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
       setProcessStatus('error')
     } else {
       sessionIdRef.current = result.sessionId
+      setActiveBackend(backend)
       const session = await window.api.cliAgentGetSession(workspaceId, result.sessionId)
       if (session) {
         // Main starts native / external sessions with [] until first send; keep hydrated history.
@@ -225,11 +232,37 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
         setProcessStatus(session.processStatus)
         setModel(session.model ?? null)
         setLastError(session.lastError ?? null)
+        setActiveBackend(session.activeBackend ?? session.backend ?? backend)
       }
       tick()
     }
   }, [workspaceId, conversationId, worktreePath, tick])
 
+  const switchBackend = useCallback(async (backend: AgentBackend): Promise<boolean> => {
+    const sid = sessionIdRef.current
+    if (!sid) return false
+    // The hot-swap IPC ships with the backend rework. Until then, gracefully no-op
+    // and let the caller fall back to the start() path.
+    const api = window.api as typeof window.api & {
+      cliAgentSwitchBackend?: (
+        sessionId: string,
+        backend: AgentBackend,
+      ) => Promise<{ success: true } | { error: string }>
+    }
+    if (typeof api.cliAgentSwitchBackend !== 'function') {
+      setLastError('Backend hot-swap is not available in this build yet.')
+      return false
+    }
+    const result = await api.cliAgentSwitchBackend(sid, backend)
+    if ('error' in result) {
+      setLastError(result.error)
+      return false
+    }
+    setActiveBackend(backend)
+    setLastError(null)
+    return true
+  }, [])
+
   const send = useCallback(async (content: string) => {
     const sid = sessionIdRef.current
     if (!sid || !content.trim()) return
@@ -264,8 +297,10 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     model,
     lastError,
     conversationTitle,
+    activeBackend,
     start,
     send,
     stop,
+    switchBackend,
   }
 }
diff --git a/packages/renderer/src/lib/agentBackend.ts b/packages/renderer/src/lib/agentBackend.ts
new file mode 100644
index 0000000..5f18243
--- /dev/null
+++ b/packages/renderer/src/lib/agentBackend.ts
@@ -0,0 +1,42 @@
+/**
+ * Frontend helpers for the agent-backend taxonomy.
+ *
+ * Single source of truth for which backends count as "CLI" (external),
+ * how to label them in the UI, and a stable color slug for badges. Keep
+ * the renderer's switch statements out of feature files — they belong here.
+ */
+
+import type { AgentBackend, ExternalCliBackend } from '@aide/shared'
+
+/** External CLI backends, in the order we render them in pickers. */
+export const CLI_BACKENDS: readonly ExternalCliBackend[] = [
+  'claude-code',
+  'opencode',
+  'codex',
+] as const
+
+export function isCliBackend(backend: AgentBackend): backend is ExternalCliBackend {
+  return backend === 'claude-code' || backend === 'opencode' || backend === 'codex'
+}
+
+/** Human-facing label for tabs, headers, and command palette entries. */
+export function backendLabel(backend: AgentBackend): string {
+  switch (backend) {
+    case 'claude-code': return 'Claude Code'
+    case 'opencode':    return 'OpenCode'
+    case 'codex':       return 'Codex'
+    case 'built-in':    return 'Built-in'
+    default:            return backend
+  }
+}
+
+/** Compact lowercase label for inline badges in history/transcript rows. */
+export function backendBadgeLabel(backend: AgentBackend): string {
+  switch (backend) {
+    case 'claude-code': return 'claude'
+    case 'opencode':    return 'opencode'
+    case 'codex':       return 'codex'
+    case 'built-in':    return 'built-in'
+    default:            return backend
+  }
+}
diff --git a/packages/renderer/src/lib/settingsSchema.ts b/packages/renderer/src/lib/settingsSchema.ts
index 2053f56..4a46178 100644
--- a/packages/renderer/src/lib/settingsSchema.ts
+++ b/packages/renderer/src/lib/settingsSchema.ts
@@ -129,11 +129,12 @@ export const SETTINGS_DESCRIPTORS: SettingDescriptor[] = [
   {
     key: 'agent.backend',
     label: 'Agent Backend',
-    description: 'Which agent backend to use. Built-in uses the integrated LLM agent. Claude Code and Codex wrap external CLI tools.',
+    description: 'Default agent backend for new chats. Built-in uses the integrated LLM agent. Claude Code, OpenCode, and Codex wrap external CLI tools — these can be hot-swapped per conversation from the agent pane.',
     type: 'enum',
     enumValues: [
       { value: 'built-in', label: 'Built-in' },
       { value: 'claude-code', label: 'Claude Code' },
+      { value: 'opencode', label: 'OpenCode' },
       { value: 'codex', label: 'Codex' },
     ],
     category: 'agent.backend',
@@ -147,6 +148,14 @@ export const SETTINGS_DESCRIPTORS: SettingDescriptor[] = [
     category: 'agent.backend',
     scope: 'user',
   },
+  {
+    key: 'agent.opencodePath',
+    label: 'OpenCode Path',
+    description: 'Path to the OpenCode CLI binary, or leave empty to use the bundled @opencode-ai/sdk and let aIDE manage the OpenCode server process.',
+    type: 'string',
+    category: 'agent.backend',
+    scope: 'user',
+  },
   {
     key: 'agent.codexPath',
     label: 'Codex Path',
diff --git a/packages/renderer/src/lib/workspace/workspaceSwitcher.ts b/packages/renderer/src/lib/workspace/workspaceSwitcher.ts
index e794c8a..805ee70 100644
--- a/packages/renderer/src/lib/workspace/workspaceSwitcher.ts
+++ b/packages/renderer/src/lib/workspace/workspaceSwitcher.ts
@@ -7,6 +7,7 @@
 
 import type { DockviewApi } from 'dockview-react'
 import type { AgentBackend, AideLocalState, AideLocalTerminals } from '@aide/shared'
+import { backendLabel, isCliBackend } from '../agentBackend'
 import { clearCache } from '../editor/editorStateCache'
 import { hydrateDocumentStoreFromOpenTabs } from '../editor/documentStore'
 import { createRestoredTerminalPanelParams, createTerminalPanelParams } from '../terminal/terminalState'
@@ -222,7 +223,7 @@ async function createDefaultLayout(
 
   const backend: AgentBackend = resolvedSettings?.['agent.backend'] ?? 'built-in'
 
-  if (backend === 'claude-code' || backend === 'codex') {
+  if (isCliBackend(backend)) {
     const conversationId = await window.api.conversationCreate({
       workspaceId,
       backend,
@@ -233,7 +234,7 @@ async function createDefaultLayout(
       id: 'agent',
       component: 'cliAgentPane',
       tabComponent: 'agentTab',
-      title: backend === 'claude-code' ? 'Claude Code' : 'Codex',
+      title: backendLabel(backend),
       params: {
         workspaceId,
         workspaceRoot: workspaceRoot ?? undefined,
diff --git a/packages/renderer/src/styles/chat-history-pane.css b/packages/renderer/src/styles/chat-history-pane.css
index 4fea232..aa12f2d 100644
--- a/packages/renderer/src/styles/chat-history-pane.css
+++ b/packages/renderer/src/styles/chat-history-pane.css
@@ -52,6 +52,70 @@
   filter: brightness(1.15);
 }
 
+.chat-history-pane__new-wrap {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+}
+
+.chat-history-pane__new-caret {
+  border: none;
+  background: transparent;
+  color: var(--text-secondary);
+  width: 14px;
+  height: 20px;
+  font-size: 9px;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 3px;
+}
+
+.chat-history-pane__new-caret:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.chat-history-pane__new-menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 1000;
+  min-width: 140px;
+  padding: 4px 0;
+  background: var(--bg-overlay);
+  border: 1px solid var(--border-subtle);
+  border-radius: 6px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
+}
+
+.chat-history-pane__new-menu-item {
+  display: block;
+  width: 100%;
+  border: none;
+  background: transparent;
+  color: var(--text-primary);
+  font-family: inherit;
+  font-size: 12px;
+  padding: 4px 12px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.chat-history-pane__new-menu-item:hover {
+  background: var(--accent);
+  color: var(--text-on-accent);
+}
+
+.chat-history-pane__new-menu-sep {
+  height: 1px;
+  background: var(--border-subtle);
+  margin: 4px 8px;
+}
+
 /* --- Filter ----------------------------------------------------- */
 
 .chat-history-pane__filter-row {
@@ -185,6 +249,11 @@
   background: color-mix(in srgb, var(--text-success) 12%, transparent);
 }
 
+.chat-history-pane__item-badge--opencode {
+  color: var(--text-info);
+  background: color-mix(in srgb, var(--text-info) 14%, transparent);
+}
+
 .chat-history-pane__item-badge--codex {
   color: var(--text-warning);
   background: color-mix(in srgb, var(--text-warning) 12%, transparent);
diff --git a/packages/renderer/src/styles/cli-agent-pane.css b/packages/renderer/src/styles/cli-agent-pane.css
index c156ff3..9283a32 100644
--- a/packages/renderer/src/styles/cli-agent-pane.css
+++ b/packages/renderer/src/styles/cli-agent-pane.css
@@ -23,6 +23,38 @@
   background: var(--bg-elevated);
 }
 
+.cli-agent-pane__backend-switcher {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 6px;
+  border-radius: 3px;
+  cursor: pointer;
+  border: 1px solid transparent;
+  transition: background 100ms, border-color 100ms;
+}
+
+.cli-agent-pane__backend-switcher:hover {
+  background: var(--bg-hover);
+  border-color: var(--border-subtle);
+}
+
+.cli-agent-pane__backend-switcher:has(select:disabled) {
+  cursor: not-allowed;
+  opacity: 0.7;
+}
+
+.cli-agent-pane__backend-switcher--claude-code .cli-agent-pane__backend-label {
+  color: var(--text-success);
+}
+.cli-agent-pane__backend-switcher--opencode .cli-agent-pane__backend-label {
+  color: var(--text-info);
+}
+.cli-agent-pane__backend-switcher--codex .cli-agent-pane__backend-label {
+  color: var(--text-warning);
+}
+
 .cli-agent-pane__backend-label {
   font-weight: 600;
   font-size: 11px;
@@ -31,6 +63,22 @@
   color: var(--text-secondary);
 }
 
+.cli-agent-pane__backend-caret {
+  font-size: 8px;
+  color: var(--text-muted);
+  line-height: 1;
+}
+
+.cli-agent-pane__backend-select {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  opacity: 0;
+  cursor: inherit;
+  font: inherit;
+}
+
 .cli-agent-pane__model {
   font-size: 11px;
   color: var(--text-muted);
@@ -230,3 +278,31 @@
   color: var(--text-error);
   padding: 3px 0;
 }
+
+/* --- Per-message backend badge (mixed-backend transcripts) -------- */
+
+.cli-agent-msg__backend-badge {
+  display: inline-block;
+  margin-left: 6px;
+  padding: 0 4px;
+  font-size: 9px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  border-radius: 2px;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
+.cli-agent-msg__backend-badge--claude-code {
+  color: var(--text-success);
+  background: color-mix(in srgb, var(--text-success) 14%, transparent);
+}
+.cli-agent-msg__backend-badge--opencode {
+  color: var(--text-info);
+  background: color-mix(in srgb, var(--text-info) 14%, transparent);
+}
+.cli-agent-msg__backend-badge--codex {
+  color: var(--text-warning);
+  background: color-mix(in srgb, var(--text-warning) 14%, transparent);
+}
diff --git a/packages/shared/src/cliAgentTypes.ts b/packages/shared/src/cliAgentTypes.ts
index b64bb43..1c2b861 100644
--- a/packages/shared/src/cliAgentTypes.ts
+++ b/packages/shared/src/cliAgentTypes.ts
@@ -9,7 +9,10 @@
 // Agent backend selection
 // ---------------------------------------------------------------------------
 
-export type AgentBackend = 'built-in' | 'claude-code' | 'codex'
+export type AgentBackend = 'built-in' | 'claude-code' | 'opencode' | 'codex'
+
+/** External (non-built-in) CLI agent backends. */
+export type ExternalCliBackend = Exclude<AgentBackend, 'built-in'>
 
 // ---------------------------------------------------------------------------
 // Process lifecycle
@@ -44,6 +47,9 @@ export interface CliAgentMessage {
   durationMs?: number
   totalCostUsd?: number
   isSuccess?: boolean
+
+  /** Which backend produced this message (set on external-agent messages). */
+  backend?: AgentBackend
 }
 
 // ---------------------------------------------------------------------------
@@ -66,6 +72,9 @@ export interface CliAgentSession {
   id: string
   workspaceId: string
   backend: AgentBackend
+  /** Currently active backend for this session. Source of truth for the pane header
+   *  once hot-swap is wired up; falls back to `backend` for legacy sessions. */
+  activeBackend?: AgentBackend
   processStatus: CliAgentProcessStatus
   messages: CliAgentMessage[]
   model?: string
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index d7a9b50..8ac96c8 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -14,7 +14,7 @@ export type {
   LlmProviderConfig,
 } from './agentTypes'
 export type {
-  AgentBackend, CliAgentProcessStatus,
+  AgentBackend, ExternalCliBackend, CliAgentProcessStatus,
   CliAgentMessage, CliAgentStreamDelta, CliAgentSession,
   CliAgentStatusPayload, CliAgentResultPayload, CliAgentMessagePayload,
 } from './cliAgentTypes'
@@ -399,6 +399,7 @@ export interface AideProjectSettings {
   // Agent / Backend settings
   'agent.backend'?: AgentBackend
   'agent.claudeCodePath'?: string
+  'agent.opencodePath'?: string
   'agent.codexPath'?: string
 }
 
@@ -429,6 +430,7 @@ export interface ResolvedSettings {
   // Agent / Backend settings
   'agent.backend': AgentBackend
   'agent.claudeCodePath': string
+  'agent.opencodePath': string
   'agent.codexPath': string
 }
 
@@ -443,6 +445,7 @@ export const SENSITIVE_AGENT_KEYS: ReadonlySet<string> = new Set([
   'agent.baseUrl',
   'agent.backend',
   'agent.claudeCodePath',
+  'agent.opencodePath',
   'agent.codexPath',
   'agent.permissionTier',
   'agent.autoApprove',

From 5c2520d4e6bfd3fd658a22e8270a38899b88426f Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 16:15:50 -0400
Subject: [PATCH 4/9] feat: backend multi

---
 docs/IDE_BUILD_PLAN.md                        |   2 +-
 docs/cli-agent-backend-hotswap-report.md      | 331 ++++++
 package.json                                  |   1 +
 packages/main/package.json                    |   1 +
 .../src/chat/cliAdapters/claudeCodeAdapter.ts | 282 +++++
 .../main/src/chat/cliAdapters/codexAdapter.ts | 162 +++
 .../src/chat/cliAdapters/openCodeAdapter.ts   | 338 ++++++
 packages/main/src/chat/cliAdapters/types.ts   |  25 +
 packages/main/src/chat/cliAgentManager.ts     | 873 +++++++---------
 packages/main/src/chat/conversationStore.ts   |  28 +-
 packages/main/src/index.ts                    | 959 +++++++++++-------
 packages/main/src/preload.ts                  | 283 ++++--
 .../main/src/workspace/settingsResolver.ts    |  23 +-
 packages/shared/src/cliAgentTypes.ts          |  25 +-
 packages/shared/src/index.ts                  | 199 +++-
 pnpm-lock.yaml                                |  13 +
 tests/unit/cliAgentManager.test.ts            |  33 +
 17 files changed, 2515 insertions(+), 1063 deletions(-)
 create mode 100644 docs/cli-agent-backend-hotswap-report.md
 create mode 100644 packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
 create mode 100644 packages/main/src/chat/cliAdapters/codexAdapter.ts
 create mode 100644 packages/main/src/chat/cliAdapters/openCodeAdapter.ts
 create mode 100644 packages/main/src/chat/cliAdapters/types.ts

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index 5804572..3474aab 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -1365,7 +1365,7 @@ Track milestone completion here. Update as you go.
 | 5.1c CLI native session hydration       | ✅ Complete    | `ClaudeNativeSessionWatcher.loadMessages(sessionId)` reads `~/.claude/projects/<slug>/<sessionId>.jsonl`, skips sidechains / thinking / file-history blocks, and maps rows to `CliAgentMessage[]`. IPC `cli-agent:load-messages` takes `(workspaceId, conversationId)`, returns `[]` when that workspace is not active (avoids native-prefix reads against the wrong project dir), and `useCliAgent` uses a hydrate generation guard, avoids clobbering a non-empty transcript with a stale empty IPC result, clears transcript only when the workspace+conversation key changes, and re-fetches native history once when `CONVERSATION_LIST_CHANGED` reports a `claude-native` row with messages but the pane is still empty. `CliAgentPane` waits on `historyHydrated`. Aide-managed sessions use `ConversationStore.loadMessages`. `CliAgentManager.start` sets `claudeSessionId` from `claude-native:<uuid>` for `--resume`.                               |
 | 5.1d CLI multi-tab isolation            | ✅ Complete    | New `cliAgentPane` instances receive a provisional `conversationId` (`crypto.randomUUID()` from `agent.open` and default workspace layout in `workspaceSwitcher`). `useCliAgent` stops calling `cliAgentGetSession(workspaceId)` without a session id so tabs are not hydrated from `CliAgentManager.getSession`'s first in-memory match for the workspace. Command `agent.open` (e.g. Cmd+K Cmd+A) always adds a new agent panel for parallel work instead of focusing an existing tab.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | 5.1e Multi-worktree agent orchestration | ✅ Complete    | Per-panel worktree isolation: `worktreePath` threaded through `CliAgentManager.start()` → spawn `cwd`, `CliAgentSession`, IPC, `useCliAgent` hook, `CliAgentPane` params. `AgentTab` custom tab component with branch badge pill (registered in `DockviewContainer.tabComponents`). "Start Agent in Worktree" button + context menu entry in `WorktreePanel`/`WorktreeItem`. Built-in agent isolation via `ToolContext.effectiveRoot` in `agentTools.ts` (terminal_exec, search_files, git_status, git_diff). `ChatSession.worktreePath` loaded from `ConversationMeta`. Worktree removal confirmation guard. Terminal panels from worktrees also get branch badges.                                                                                                                                                                                                                                                                                           |
-| 5.2 Claude Agent SDK integration        | ✅ Complete    | `CliAgentManager` streams Claude responses via `@anthropic-ai/claude-agent-sdk` `query()`, persists/resumes sessions, and now resolves the packaged executable from the SDK's own unpacked `cli.js` before falling back to the legacy `@anthropic-ai/claude-code` path. This fixes packaged-app startup failures caused by stale Claude Code path resolution. OpenCode/Codex SDK integration remains future work.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| 5.2 Claude Agent SDK integration        | ✅ Complete    | `CliAgentManager` now owns a generic external-agent session layer with backend adapters for Claude Code, OpenCode, and Codex. Claude still streams via `@anthropic-ai/claude-agent-sdk` and resolves the packaged executable from the SDK's own unpacked `cli.js`; OpenCode is wired through the official SDK/client flow against an `opencode serve` process; Codex is wired through `codex exec --json`. Sessions persist per-backend resume state so a conversation can hot-swap external backends, while `ConversationMeta.backend` tracks the active backend. Frontend hot-swap controls and richer mixed-backend transcript UI are still pending.                                                                                                                                                                                                                                                                                                        |
 | 5.3 Diff preview before apply           | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | 5.4 Agent edit highlighting in editor   | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | 5.5 Crash recovery                      | ⬜ Not started |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
diff --git a/docs/cli-agent-backend-hotswap-report.md b/docs/cli-agent-backend-hotswap-report.md
new file mode 100644
index 0000000..d481dcd
--- /dev/null
+++ b/docs/cli-agent-backend-hotswap-report.md
@@ -0,0 +1,331 @@
+# CLI Agent Backend Hotswap Report
+
+## Goal
+
+Support `claude-code`, `opencode`, and `codex` as first-class agent-chat backends, with backend hot swapping inside the same CLI agent chat pane.
+
+This report covers:
+
+- what backend work will be done
+- what data and IPC contracts will change
+- what requires frontend changes from the separate frontend agent
+
+## Current state
+
+The current implementation is not a generic CLI-agent backend. It is a Claude-specific manager with a Codex stub.
+
+### Current backend limitations
+
+- `packages/shared/src/cliAgentTypes.ts`
+  - `AgentBackend` only includes `built-in | claude-code | codex`
+  - there is no `opencode`
+- `packages/main/src/chat/cliAgentManager.ts`
+  - hard-coded to `@anthropic-ai/claude-agent-sdk`
+  - stores a single `claudeSessionId`
+  - normalizes only Claude SDK message shapes
+  - returns `Codex integration coming soon.` for `codex`
+- `packages/shared/src/conversationTypes.ts`
+  - `ConversationMeta` stores `claudeSessionId`, not generic per-backend session state
+  - `source` only models `claude-native`
+- `packages/main/src/index.ts`
+  - settings updates only push `agent.claudeCodePath` and `agent.codexPath`
+- renderer code is hard-coded around only two external backends
+  - `CliAgentPane.tsx`
+  - `ChatHistoryPane.tsx`
+  - `AppShell.tsx`
+  - `workspaceSwitcher.ts`
+  - `commands/domains/agent.ts`
+
+### Hot swapping is not possible today
+
+The current `cliAgentStart()` path assumes a single fixed backend per pane/session. If the same conversation is reopened with a different backend, the backend-specific session semantics are wrong:
+
+- Claude resume uses `claudeSessionId`
+- OpenCode and Codex will need their own resume/session state
+- mixed-backend transcripts have no per-message backend attribution
+
+## Backend work I will do
+
+### 1. Introduce a real external-agent backend abstraction
+
+I will split the current Claude-specific manager into:
+
+- `CliAgentManager`
+  - session lifecycle
+  - persistence
+  - IPC emission
+  - backend switching
+- backend adapters
+  - `ClaudeCodeAdapter`
+  - `OpenCodeAdapter`
+  - `CodexAdapter`
+
+Each adapter will be responsible for:
+
+- executable or SDK resolution
+- creating a run for a prompt
+- streaming normalized events back to the manager
+- stop/cancel behavior
+- per-backend resume/session token handling
+
+### 2. Make session persistence generic instead of Claude-only
+
+I will replace the single Claude-only resume field with generic per-backend external session state.
+
+Planned shape:
+
+```ts
+type ExternalCliBackend = 'claude-code' | 'opencode' | 'codex'
+
+interface ExternalBackendState {
+  sessionId?: string
+  model?: string
+}
+
+type ExternalBackendStateMap = Partial<Record<ExternalCliBackend, ExternalBackendState>>
+```
+
+This will be stored with the conversation transcript so a single conversation can switch between backends and still resume correctly when switched back later.
+
+### 3. Add OpenCode as a first-class backend
+
+I will wire `opencode` into the same external-agent pipeline as Claude and Codex.
+
+OpenCode has a solid direct SDK story, so this backend will use the official `@opencode-ai/sdk` route instead of treating OpenCode as a raw terminal/TUI integration.
+
+Planned integration shape:
+
+- use `createOpencode()` when aIDE needs to spin up and own the OpenCode server process
+- use `createOpencodeClient()` when connecting to an already-running OpenCode instance
+- talk to OpenCode over the SDK's HTTP client surface rather than scraping terminal output
+- normalize OpenCode session/message events into the same `CliAgentMessage` stream used by the pane
+
+Backend additions:
+
+- add `opencode` to `AgentBackend`
+- add `agent.opencodePath` setting support alongside existing path settings
+- add backend label helpers and path update plumbing
+- add OpenCode adapter resolution and startup logic
+
+What I will not use for the initial backend pass:
+
+- `@opencode-ai/plugin`
+  - useful for extending OpenCode with custom tools/hooks, but not required just to embed OpenCode as a selectable backend in aIDE
+- ACP
+  - useful for editor-native embedding over stdio/JSON-RPC, but the direct SDK client route is the cleaner fit for the current Electron main-process architecture
+
+### 4. Add Codex as a real backend instead of a stub
+
+I will replace the current stub with a real adapter.
+
+Important constraint:
+
+- if Codex exposes a stable machine-readable stream/protocol, I will normalize that into the existing message model
+- if Codex only exposes an interactive TUI path, I will need to bridge it through a dedicated process transport instead of the current Claude-style message flow
+
+Either way, the backend manager will be refactored so Codex is no longer hard-coded as unsupported.
+
+### 5. Add backend hot swap support to the manager and IPC
+
+I will add explicit backend switching support rather than overloading `start()`.
+
+Planned behavior:
+
+- one CLI conversation can keep a single transcript
+- each turn runs on the currently selected backend
+- switching backends preserves prior transcript and per-backend external session state
+- if a backend has never seen the conversation before, the manager will seed it from the existing conversation transcript instead of using a native resume token
+
+Backend/API work:
+
+- add a new `cliAgentSwitchBackend(sessionId, backend)` IPC path
+- expose the active backend in `CliAgentSession`
+- preserve per-backend state in persisted conversation data
+- prevent or explicitly stop active runs before switching
+
+### 6. Attribute messages to the backend that produced them
+
+I will add backend attribution to normalized CLI messages so mixed-backend chats remain understandable.
+
+Planned shape:
+
+```ts
+interface CliAgentMessage {
+  ...
+  backend?: 'claude-code' | 'opencode' | 'codex'
+}
+```
+
+This is required once a single conversation can contain output from multiple external backends.
+
+### 7. Migrate existing stored conversations safely
+
+I will add a backward-compatible lazy migration path so existing Claude conversations continue to work.
+
+Migration plan:
+
+- existing `claudeSessionId` will be read and copied into generic backend state for `claude-code`
+- existing conversation metadata with `backend: 'claude-code'` remains valid
+- `claude-native` mirrored sessions remain Claude-only and stay separate from generic external session state
+
+## Backend files I expect to change
+
+Shared types / contracts:
+
+- `packages/shared/src/cliAgentTypes.ts`
+- `packages/shared/src/conversationTypes.ts`
+- `packages/shared/src/index.ts`
+
+Main process:
+
+- `packages/main/src/chat/cliAgentManager.ts`
+- `packages/main/src/chat/conversationStore.ts`
+- `packages/main/src/index.ts`
+- `packages/main/src/preload.ts`
+- `packages/main/src/workspace/settingsResolver.ts`
+
+Likely new backend adapter files:
+
+- `packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts`
+- `packages/main/src/chat/cliAdapters/openCodeAdapter.ts`
+- `packages/main/src/chat/cliAdapters/codexAdapter.ts`
+- `packages/main/src/chat/cliAdapters/types.ts`
+
+Tests:
+
+- `tests/unit/cliAgentManager.test.ts`
+- new adapter-focused unit tests
+
+## Frontend changes required
+
+These changes are required for the backend work to be fully usable in the UI.
+
+### 1. Add `opencode` everywhere backend choices are rendered
+
+Required files:
+
+- `packages/renderer/src/lib/settingsSchema.ts`
+- `packages/renderer/src/components/panes/CliAgentPane.tsx`
+- `packages/renderer/src/components/panes/ChatHistoryPane.tsx`
+- `packages/renderer/src/components/layout/AppShell.tsx`
+- `packages/renderer/src/lib/workspace/workspaceSwitcher.ts`
+- `packages/renderer/src/commands/domains/agent.ts`
+
+The current renderer hard-codes only Claude and Codex labels/branches.
+
+### 2. Add a backend switcher UI in the CLI agent pane
+
+Required UI behavior:
+
+- show current backend in the pane header
+- allow switching between `claude-code`, `opencode`, and `codex`
+- disable the switcher while a turn is actively running, or require stop-first behavior
+- call the new backend switch IPC instead of reopening a new pane
+
+This is the key frontend requirement for hot swapping.
+
+### 3. Render mixed-backend transcripts clearly
+
+Once one conversation can contain responses from multiple backends, the pane should show that clearly.
+
+Minimum required UI change:
+
+- display a backend badge on assistant/tool/result/error messages when the conversation contains more than one backend
+
+Without this, hot-swapped conversations will be confusing.
+
+### 4. Update history and new-chat affordances
+
+Current limitations:
+
+- `ChatHistoryPane` only exposes `+` for built-in conversations
+- renderer routing logic assumes exact backend values instead of generic external-agent semantics
+
+Required frontend changes:
+
+- optionally allow creating a new CLI conversation from history UI with backend selection
+- treat `opencode` as a CLI backend
+- route any external CLI conversation to `cliAgentPane`
+
+### 5. Update settings UI for the new backend path
+
+Required UI/settings additions:
+
+- add `agent.opencodePath`
+- adjust descriptions so backend settings no longer imply only Claude/Codex exist
+
+## Frontend contract changes to expect
+
+The frontend agent should expect these shared contract changes.
+
+### Shared type changes
+
+- `AgentBackend` will include `opencode`
+- `CliAgentMessage` will likely gain `backend?: AgentBackend`
+- `CliAgentSession` will likely gain `activeBackend` and generic backend-state data
+- `ConversationMeta.backend` should be treated as the last-used or primary backend, not as the only backend that has ever touched the conversation
+
+### New or changed preload/window API calls
+
+Expected additions:
+
+```ts
+cliAgentSwitchBackend: (sessionId: string, backend: AgentBackend) =>
+  Promise<{ success: true } | { error: string }>
+```
+
+Possible session shape update:
+
+```ts
+interface CliAgentSession {
+  ...
+  activeBackend: 'claude-code' | 'opencode' | 'codex'
+}
+```
+
+## Risks and open questions
+
+### Codex transport risk
+
+Codex appears to be primarily exposed as a CLI package. If it does not expose a stable non-interactive structured stream, it will require a different adapter strategy than Claude/OpenCode.
+
+This does not block the manager refactor, but it may affect how deep Codex parity can go in the first backend pass.
+
+### Conversation semantics after a switch
+
+The backend implementation will preserve one transcript across all external backends. That means:
+
+- native resume is backend-specific
+- cross-backend continuity is transcript-based, not native-session-based
+
+This is the correct model for hot swapping, but the frontend should present it as "switch backend for future turns" rather than "move the same vendor session between providers".
+
+## Recommended work split
+
+### Backend work owned here
+
+- adapter abstraction
+- Claude adapter extraction
+- OpenCode adapter wiring
+- Codex adapter wiring
+- generic persistence/session-state migration
+- switch-backend IPC and session behavior
+- tests and migrations
+
+### Frontend work for the separate agent
+
+- backend selector UI in `CliAgentPane`
+- `opencode` labels and routing everywhere a backend is rendered
+- message badges for mixed-backend transcripts
+- settings UI for `agent.opencodePath`
+- any create-new-chat UX that should expose CLI backend choice
+
+## Suggested frontend handoff summary
+
+Frontend should prepare for:
+
+1. `opencode` becoming a valid `AgentBackend`
+2. a new `window.api.cliAgentSwitchBackend()` call
+3. `CliAgentMessage.backend` being present on external-agent messages
+4. `CliAgentSession.activeBackend` becoming the source of truth for the pane header
+5. a conversation transcript containing output from more than one external backend
diff --git a/package.json b/package.json
index 0e57ca6..e51d4a1 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.91",
     "@anthropic-ai/claude-code": "*",
+    "@opencode-ai/sdk": "^1.4.0",
     "@vscode/ripgrep": "^1.17.1",
     "node-pty": "^1.1.0"
   },
diff --git a/packages/main/package.json b/packages/main/package.json
index a32dc2a..b71e286 100644
--- a/packages/main/package.json
+++ b/packages/main/package.json
@@ -6,6 +6,7 @@
   "dependencies": {
     "@aide/shared": "workspace:*",
     "@anthropic-ai/claude-agent-sdk": "^0.2.91",
+    "@opencode-ai/sdk": "^1.4.0",
     "electron-store": "^6.0.1",
     "node-pty": "^1.1.0",
     "simple-git": "^3.33.0"
diff --git a/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts b/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
new file mode 100644
index 0000000..11e1897
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
@@ -0,0 +1,282 @@
+import { randomUUID } from 'crypto'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import type { Query } from '@anthropic-ai/claude-agent-sdk'
+import type {
+  CliBackendAdapter,
+  CliBackendEvent,
+  CliBackendRun,
+  CliBackendTurnContext,
+} from './types'
+
+interface ClaudeCodeAdapterOptions {
+  executablePath: string
+}
+
+export function createClaudeCodeAdapter(options: ClaudeCodeAdapterOptions): CliBackendAdapter {
+  return {
+    backend: 'claude-code',
+    startTurn(context, emit) {
+      const abortController = new AbortController()
+      const stderrChunks: string[] = []
+      let queryInstance: Query | null = null
+
+      const completed = (async () => {
+        const startedAt = Date.now()
+        const queryOptions: Record<string, unknown> = {
+          cwd: context.cwd,
+          abortController,
+          includePartialMessages: true,
+          pathToClaudeCodeExecutable: options.executablePath,
+          permissionMode: 'default' as const,
+          settingSources: ['user', 'project', 'local'],
+          systemPrompt: { type: 'preset', preset: 'claude_code' },
+          stderr: (data: string) => {
+            stderrChunks.push(data)
+          },
+        }
+
+        if (context.backendState.sessionId) {
+          queryOptions.resume = context.backendState.sessionId
+        }
+
+        try {
+          queryInstance = query({
+            prompt: context.prompt,
+            options: queryOptions as Parameters<typeof query>[0]['options'],
+          })
+        } catch (error) {
+          throw new Error(renderClaudeError(error, stderrChunks))
+        }
+
+        let totalCostUsd = 0
+        let sawResult = false
+        for await (const message of queryInstance) {
+          const events = normalizeClaudeMessage(message)
+          for (const event of events) {
+            if (event.type === 'result') {
+              totalCostUsd += event.totalCostUsd
+              sawResult = true
+            }
+            emit(event)
+          }
+        }
+
+        if (!sawResult) {
+          emit({
+            type: 'result',
+            durationMs: Date.now() - startedAt,
+            totalCostUsd,
+            isSuccess: true,
+          })
+        }
+      })()
+
+      return {
+        close() {
+          abortController.abort()
+          queryInstance?.close()
+        },
+        completed,
+      } satisfies CliBackendRun
+    },
+  }
+}
+
+function renderClaudeError(error: unknown, stderrChunks: string[]): string {
+  const message = error instanceof Error ? error.message : String(error)
+  const stderrText = stderrChunks.join('').trim()
+  if (!stderrText) return message
+  return `${message}\n\nstderr output:\n${stderrText.slice(-2000)}`
+}
+
+function normalizeClaudeMessage(message: any): CliBackendEvent[] {
+  const type = message.type as string
+  const subtype = message.subtype as string | undefined
+
+  if (type === 'system') {
+    if (subtype === 'init') {
+      const sessionId = message.session_id as string | undefined
+      const model = (message.model as string) ?? undefined
+      const tools = Array.isArray(message.tools) ? (message.tools as string[]) : undefined
+      if (sessionId) {
+        return [
+          {
+            type: 'backend-state',
+            patch: { sessionId, model },
+          },
+          {
+            type: 'session-meta',
+            model,
+            tools,
+          },
+        ]
+      }
+      return [
+        {
+          type: 'session-meta',
+          model,
+          tools,
+        },
+      ]
+    }
+
+    if (subtype === 'status') {
+      return [
+        {
+          type: 'message',
+          message: {
+            id: (message.uuid as string) ?? randomUUID(),
+            type: 'status',
+            content: String(message.status ?? message.message ?? 'status update'),
+            timestamp: Date.now(),
+          },
+        },
+      ]
+    }
+
+    return []
+  }
+
+  if (type === 'assistant') {
+    const betaMessage = message.message
+    if (!betaMessage || !Array.isArray(betaMessage.content)) return []
+
+    let text = ''
+    const events: CliBackendEvent[] = []
+    for (const block of betaMessage.content) {
+      if (block.type === 'text') {
+        text += block.text ?? ''
+      }
+      if (block.type === 'tool_use') {
+        events.push({
+          type: 'message',
+          message: {
+            id: (block.id as string) ?? randomUUID(),
+            type: 'tool_use',
+            content: `Running ${block.name ?? 'tool'}...`,
+            timestamp: Date.now(),
+            toolName: block.name as string,
+            toolUseId: block.id as string,
+          },
+        })
+      }
+    }
+
+    if (text) {
+      events.push({
+        type: 'message',
+        message: {
+          id: (message.uuid as string) ?? randomUUID(),
+          type: 'assistant',
+          content: text,
+          timestamp: Date.now(),
+          raw: message,
+        },
+      })
+    }
+
+    return events
+  }
+
+  if (type === 'stream_event') {
+    const event = message.event
+    if (event?.type !== 'content_block_delta' || event.delta?.type !== 'text_delta') return []
+    const text = (event.delta.text as string) ?? ''
+    if (!text) return []
+    return [
+      {
+        type: 'stream-delta',
+        messageId: (message.uuid as string) ?? randomUUID(),
+        delta: text,
+      },
+    ]
+  }
+
+  if (type === 'tool_progress') {
+    return [
+      {
+        type: 'message',
+        message: {
+          id: (message.uuid as string) ?? randomUUID(),
+          type: 'tool_use',
+          content: `Running ${message.tool_name ?? 'tool'}...`,
+          timestamp: Date.now(),
+          toolName: (message.tool_name as string) ?? undefined,
+          toolUseId: (message.tool_use_id as string) ?? undefined,
+        },
+      },
+    ]
+  }
+
+  if (type === 'tool_use_summary') {
+    return [
+      {
+        type: 'message',
+        message: {
+          id: (message.uuid as string) ?? randomUUID(),
+          type: 'tool_result',
+          content: (message.summary as string) ?? 'Tool completed',
+          timestamp: Date.now(),
+        },
+      },
+    ]
+  }
+
+  if (type === 'rate_limit_event') {
+    return [
+      {
+        type: 'message',
+        message: {
+          id: randomUUID(),
+          type: 'status',
+          content: 'Rate limited',
+          timestamp: Date.now(),
+        },
+      },
+    ]
+  }
+
+  if (type === 'result') {
+    const isSuccess = subtype === 'success'
+    const durationMs = (message.duration_ms as number) ?? 0
+    const totalCostUsd = (message.total_cost_usd as number) ?? 0
+    const sessionId = message.session_id as string | undefined
+    const errors = Array.isArray(message.errors) ? (message.errors as string[]) : []
+    const errorDetail = errors.length > 0 ? errors.join('\n') : ''
+    const events: CliBackendEvent[] = []
+
+    if (sessionId) {
+      events.push({
+        type: 'backend-state',
+        patch: { sessionId },
+      })
+    }
+
+    events.push({
+      type: 'message',
+      message: {
+        id: (message.uuid as string) ?? randomUUID(),
+        type: isSuccess ? 'result' : 'error',
+        content: isSuccess
+          ? `Completed in ${(durationMs / 1000).toFixed(1)}s`
+          : `Failed: ${subtype ?? 'unknown error'}${errorDetail ? `\n\n${errorDetail}` : ''}`,
+        timestamp: Date.now(),
+        durationMs,
+        totalCostUsd,
+        isSuccess,
+        raw: message,
+      },
+    })
+
+    events.push({
+      type: 'result',
+      durationMs,
+      totalCostUsd,
+      isSuccess,
+    })
+
+    return events
+  }
+
+  return []
+}
diff --git a/packages/main/src/chat/cliAdapters/codexAdapter.ts b/packages/main/src/chat/cliAdapters/codexAdapter.ts
new file mode 100644
index 0000000..9932b4f
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/codexAdapter.ts
@@ -0,0 +1,162 @@
+import { randomUUID } from 'crypto'
+import { spawn } from 'child_process'
+import { createInterface } from 'readline'
+import type { CliBackendAdapter, CliBackendRun, CliBackendTurnContext } from './types'
+
+interface CodexAdapterOptions {
+  executablePath: string
+}
+
+export function createCodexAdapter(options: CodexAdapterOptions): CliBackendAdapter {
+  return {
+    backend: 'codex',
+    startTurn(context, emit) {
+      const args = context.backendState.sessionId
+        ? [
+            'exec',
+            'resume',
+            '--json',
+            '--skip-git-repo-check',
+            context.backendState.sessionId,
+            context.prompt,
+          ]
+        : ['exec', '--json', '--skip-git-repo-check', context.prompt]
+
+      const proc = spawn(options.executablePath, args, {
+        cwd: context.cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+      const completed = (async () => {
+        const startedAt = Date.now()
+        let stderr = ''
+        let sawResult = false
+
+        proc.stderr?.on('data', (chunk) => {
+          stderr += chunk.toString()
+        })
+
+        if (proc.stdout) {
+          const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity })
+          for await (const line of rl) {
+            const trimmed = line.trim()
+            if (!trimmed) continue
+            let event: Record<string, unknown>
+            try {
+              event = JSON.parse(trimmed) as Record<string, unknown>
+            } catch {
+              continue
+            }
+
+            const type = typeof event.type === 'string' ? event.type : ''
+            if (type === 'thread.started' && typeof event.thread_id === 'string') {
+              emit({ type: 'backend-state', patch: { sessionId: event.thread_id } })
+              continue
+            }
+
+            if (type === 'item.started') {
+              const item = asRecord(event.item)
+              if (item?.type === 'command_execution') {
+                emit({
+                  type: 'message',
+                  message: {
+                    id: asString(item.id) ?? randomUUID(),
+                    type: 'tool_use',
+                    content: `Running command: ${asString(item.command) ?? 'shell command'}`,
+                    timestamp: Date.now(),
+                    toolName: 'shell',
+                  },
+                })
+              }
+              continue
+            }
+
+            if (type === 'item.completed') {
+              const item = asRecord(event.item)
+              if (!item) continue
+              if (item.type === 'agent_message') {
+                emit({
+                  type: 'message',
+                  message: {
+                    id: asString(item.id) ?? randomUUID(),
+                    type: 'assistant',
+                    content: asString(item.text) ?? '',
+                    timestamp: Date.now(),
+                    raw: event,
+                  },
+                })
+                continue
+              }
+
+              if (item.type === 'command_execution') {
+                const output = asString(item.aggregated_output)?.trim()
+                const command = asString(item.command) ?? 'shell command'
+                const exitCode = typeof item.exit_code === 'number' ? item.exit_code : null
+                emit({
+                  type: 'message',
+                  message: {
+                    id: asString(item.id) ?? randomUUID(),
+                    type: 'tool_result',
+                    content:
+                      output || `${command}${exitCode === null ? '' : `\n(exit ${exitCode})`}`,
+                    timestamp: Date.now(),
+                    toolName: 'shell',
+                  },
+                })
+              }
+              continue
+            }
+
+            if (type === 'turn.completed') {
+              sawResult = true
+              const usage = asRecord(event.usage)
+              const outputTokens =
+                typeof usage?.output_tokens === 'number' ? usage.output_tokens : 0
+              emit({
+                type: 'message',
+                message: {
+                  id: randomUUID(),
+                  type: 'result',
+                  content: `Completed in ${((Date.now() - startedAt) / 1000).toFixed(1)}s${outputTokens > 0 ? ` (${outputTokens} output tokens)` : ''}`,
+                  timestamp: Date.now(),
+                  isSuccess: true,
+                },
+              })
+              emit({
+                type: 'result',
+                durationMs: Date.now() - startedAt,
+                totalCostUsd: 0,
+                isSuccess: true,
+              })
+            }
+          }
+        }
+
+        const exitCode = await new Promise<number | null>((resolve, reject) => {
+          proc.once('error', reject)
+          proc.once('close', resolve)
+        })
+
+        if ((exitCode ?? 0) !== 0 && !sawResult) {
+          throw new Error(stderr.trim() || `Codex exited with code ${exitCode}`)
+        }
+      })()
+
+      return {
+        close() {
+          proc.kill('SIGTERM')
+        },
+        completed,
+      } satisfies CliBackendRun
+    },
+  }
+}
+
+function asRecord(value: unknown): Record<string, any> | null {
+  return value && typeof value === 'object' ? (value as Record<string, any>) : null
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
diff --git a/packages/main/src/chat/cliAdapters/openCodeAdapter.ts b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
new file mode 100644
index 0000000..baa3e3b
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
@@ -0,0 +1,338 @@
+import { randomUUID } from 'crypto'
+import { spawn, type ChildProcess } from 'child_process'
+import { createServer } from 'net'
+import { createOpencodeClient } from '@opencode-ai/sdk/client'
+import type { CliBackendAdapter, CliBackendRun, CliBackendTurnContext } from './types'
+
+interface OpenCodeAdapterOptions {
+  executablePath: string
+}
+
+export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBackendAdapter {
+  return {
+    backend: 'opencode',
+    startTurn(context, emit) {
+      let serverProc: ChildProcess | null = null
+      let currentSessionId = context.backendState.sessionId
+      let closed = false
+
+      const completed = (async () => {
+        const startedAt = Date.now()
+        const port = await reservePort()
+        const url = `http://127.0.0.1:${port}`
+        serverProc = spawn(
+          options.executablePath,
+          ['serve', '--hostname=127.0.0.1', `--port=${port}`],
+          {
+            env: {
+              ...process.env,
+              OPENCODE_CONFIG_CONTENT: JSON.stringify({}),
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+          },
+        )
+
+        if (!serverProc) throw new Error('Failed to start OpenCode server process')
+        await waitForOpenCodeServer(serverProc, url)
+
+        const client = createOpencodeClient({
+          baseUrl: url,
+          directory: context.cwd,
+          responseStyle: 'data',
+          throwOnError: true,
+        })
+
+        if (!currentSessionId) {
+          const created = await client.session.create({ responseStyle: 'data', throwOnError: true })
+          currentSessionId = created.data.id
+          emit({ type: 'backend-state', patch: { sessionId: created.data.id } })
+        }
+
+        if (!currentSessionId) {
+          throw new Error('Failed to initialize OpenCode session')
+        }
+
+        const sse = await client.global.event({ signal: undefined })
+        const textByMessageId = new Map<string, string>()
+        const timestampByMessageId = new Map<string, number>()
+        const emittedAssistantIds = new Set<string>()
+        const seenToolStates = new Map<string, string>()
+        const costByMessageId = new Map<string, number>()
+        let totalCostUsd = 0
+        let failedError: string | null = null
+        let promptSubmitted = false
+
+        const streamTask = (async () => {
+          for await (const rawEvent of sse.stream) {
+            const event = rawEvent as Record<string, any>
+            const type = typeof event.type === 'string' ? event.type : ''
+            const props = asRecord(event.properties)
+
+            if (type === 'message.updated' && props?.info) {
+              const info = props.info as Record<string, any>
+              const sessionId = asString(info.sessionID)
+              if (!sessionId || sessionId !== currentSessionId) continue
+
+              const messageId = asString(info.id) ?? randomUUID()
+              if (info.role === 'assistant') {
+                const model =
+                  [asString(info.providerID), asString(info.modelID)].filter(Boolean).join('/') ||
+                  undefined
+                const createdAt =
+                  typeof info.time?.created === 'number' ? info.time.created : Date.now()
+                timestampByMessageId.set(messageId, createdAt)
+                emit({ type: 'session-meta', model })
+                emit({ type: 'backend-state', patch: { sessionId, model } })
+
+                const nextCost = typeof info.cost === 'number' ? info.cost : 0
+                const prevCost = costByMessageId.get(messageId) ?? 0
+                totalCostUsd += Math.max(0, nextCost - prevCost)
+                costByMessageId.set(messageId, nextCost)
+
+                const errorText = renderOpenCodeError(info.error)
+                if (errorText) {
+                  failedError = errorText
+                }
+              }
+              continue
+            }
+
+            if (type === 'message.part.updated' && props?.part) {
+              const part = props.part as Record<string, any>
+              if (asString(part.sessionID) !== currentSessionId) continue
+              const partType = asString(part.type)
+
+              if (partType === 'text') {
+                const messageId = asString(part.messageID) ?? randomUUID()
+                const delta = asString(props.delta)
+                if (delta) {
+                  const prior = textByMessageId.get(messageId) ?? ''
+                  textByMessageId.set(messageId, prior + delta)
+                  emit({ type: 'stream-delta', messageId, delta })
+                } else {
+                  textByMessageId.set(messageId, asString(part.text) ?? '')
+                }
+                continue
+              }
+
+              if (partType === 'tool') {
+                const partId = asString(part.id) ?? randomUUID()
+                const state = asRecord(part.state)
+                const status = asString(state?.status) ?? 'pending'
+                const priorStatus = seenToolStates.get(partId)
+                if (priorStatus === status) continue
+                seenToolStates.set(partId, status)
+
+                const toolName = asString(part.tool) ?? 'tool'
+                if (status === 'pending' || status === 'running') {
+                  emit({
+                    type: 'message',
+                    message: {
+                      id: partId,
+                      type: 'tool_use',
+                      content: `Running ${toolName}...`,
+                      timestamp: Date.now(),
+                      toolName,
+                      toolUseId: asString(part.callID),
+                    },
+                  })
+                } else if (status === 'completed') {
+                  emit({
+                    type: 'message',
+                    message: {
+                      id: partId,
+                      type: 'tool_result',
+                      content:
+                        asString(state?.output) ??
+                        asString(state?.title) ??
+                        `${toolName} completed`,
+                      timestamp: Date.now(),
+                      toolName,
+                      toolUseId: asString(part.callID),
+                    },
+                  })
+                } else if (status === 'error') {
+                  emit({
+                    type: 'message',
+                    message: {
+                      id: partId,
+                      type: 'error',
+                      content: asString(state?.error) ?? `${toolName} failed`,
+                      timestamp: Date.now(),
+                      toolName,
+                      toolUseId: asString(part.callID),
+                    },
+                  })
+                }
+              }
+              continue
+            }
+
+            if (type === 'session.error' && props) {
+              if (
+                currentSessionId &&
+                asString(props.sessionID) &&
+                asString(props.sessionID) !== currentSessionId
+              ) {
+                continue
+              }
+              failedError = renderOpenCodeError(props.error) ?? 'OpenCode session failed'
+              continue
+            }
+
+            if (
+              type === 'session.idle' &&
+              asString(props?.sessionID) === currentSessionId &&
+              promptSubmitted
+            ) {
+              break
+            }
+          }
+        })()
+
+        await client.session.promptAsync({
+          responseStyle: 'data',
+          throwOnError: true,
+          path: { id: currentSessionId },
+          body: {
+            parts: [{ type: 'text', text: context.prompt }],
+          },
+        })
+        promptSubmitted = true
+
+        await streamTask
+
+        for (const [messageId, text] of textByMessageId) {
+          if (!text || emittedAssistantIds.has(messageId)) continue
+          emittedAssistantIds.add(messageId)
+          emit({
+            type: 'message',
+            message: {
+              id: messageId,
+              type: 'assistant',
+              content: text,
+              timestamp: timestampByMessageId.get(messageId) ?? Date.now(),
+            },
+          })
+        }
+
+        if (failedError) {
+          emit({
+            type: 'message',
+            message: {
+              id: randomUUID(),
+              type: 'error',
+              content: failedError,
+              timestamp: Date.now(),
+            },
+          })
+          emit({
+            type: 'result',
+            durationMs: Date.now() - startedAt,
+            totalCostUsd,
+            isSuccess: false,
+          })
+          return
+        }
+
+        emit({
+          type: 'message',
+          message: {
+            id: randomUUID(),
+            type: 'result',
+            content: `Completed in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
+            timestamp: Date.now(),
+            totalCostUsd,
+            isSuccess: true,
+          },
+        })
+        emit({
+          type: 'result',
+          durationMs: Date.now() - startedAt,
+          totalCostUsd,
+          isSuccess: true,
+        })
+      })().finally(() => {
+        if (!closed) {
+          serverProc?.kill('SIGTERM')
+        }
+      })
+
+      return {
+        close() {
+          closed = true
+          serverProc?.kill('SIGTERM')
+        },
+        completed,
+      } satisfies CliBackendRun
+    },
+  }
+}
+
+async function reservePort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : null
+      server.close((error) => {
+        if (error) reject(error)
+        else if (typeof port === 'number') resolve(port)
+        else reject(new Error('Failed to reserve OpenCode port'))
+      })
+    })
+  })
+}
+
+async function waitForOpenCodeServer(proc: ChildProcess, url: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error('Timeout waiting for OpenCode server to start'))
+    }, 5000)
+
+    let output = ''
+    const onData = (chunk: Buffer) => {
+      output += chunk.toString()
+      if (output.includes(url) || output.includes('opencode server listening')) {
+        cleanup()
+        resolve()
+      }
+    }
+    const onExit = (code: number | null) => {
+      cleanup()
+      reject(new Error(`OpenCode server exited with code ${code}${output ? `\n${output}` : ''}`))
+    }
+    const onError = (error: Error) => {
+      cleanup()
+      reject(error)
+    }
+    const cleanup = () => {
+      clearTimeout(timeout)
+      proc.stdout?.off('data', onData)
+      proc.stderr?.off('data', onData)
+      proc.off('exit', onExit)
+      proc.off('error', onError)
+    }
+
+    proc.stdout?.on('data', onData)
+    proc.stderr?.on('data', onData)
+    proc.once('exit', onExit)
+    proc.once('error', onError)
+  })
+}
+
+function asRecord(value: unknown): Record<string, any> | null {
+  return value && typeof value === 'object' ? (value as Record<string, any>) : null
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
+function renderOpenCodeError(value: unknown): string | null {
+  const error = asRecord(value)
+  const data = asRecord(error?.data)
+  const message = asString(data?.message)
+  return message ?? null
+}
diff --git a/packages/main/src/chat/cliAdapters/types.ts b/packages/main/src/chat/cliAdapters/types.ts
new file mode 100644
index 0000000..04bb59d
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/types.ts
@@ -0,0 +1,25 @@
+import type { CliAgentBackendState, CliAgentMessage, ExternalCliBackend } from '@aide/shared'
+
+export interface CliBackendTurnContext {
+  conversationId: string
+  cwd: string
+  prompt: string
+  backendState: CliAgentBackendState
+}
+
+export type CliBackendEvent =
+  | { type: 'stream-delta'; messageId: string; delta: string }
+  | { type: 'message'; message: Omit<CliAgentMessage, 'backend'> }
+  | { type: 'backend-state'; patch: Partial<CliAgentBackendState> }
+  | { type: 'session-meta'; model?: string; tools?: string[] }
+  | { type: 'result'; durationMs: number; totalCostUsd: number; isSuccess: boolean }
+
+export interface CliBackendRun {
+  close(): void
+  completed: Promise<void>
+}
+
+export interface CliBackendAdapter {
+  backend: ExternalCliBackend
+  startTurn(context: CliBackendTurnContext, emit: (event: CliBackendEvent) => void): CliBackendRun
+}
diff --git a/packages/main/src/chat/cliAgentManager.ts b/packages/main/src/chat/cliAgentManager.ts
index 21d8b63..df53558 100644
--- a/packages/main/src/chat/cliAgentManager.ts
+++ b/packages/main/src/chat/cliAgentManager.ts
@@ -1,19 +1,9 @@
 /**
  * CLI Agent Manager — manages external CLI agent sessions.
  *
- * Uses the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) for the
- * `claude-code` backend. The SDK spawns a Claude Code subprocess and
- * provides a typed async generator of messages. Codex remains a stub.
- *
- * Architecture: Each `send()` calls `query()` which returns an
- * `AsyncGenerator<SDKMessage>`. The generator is consumed in a background
- * loop that normalizes SDK messages into CliAgentMessage and emits them
- * via IPC. Session continuity uses the SDK's `resume` option.
- *
- * The SDK ships its own `cli.js`, but packaged Electron apps need that file
- * unpacked onto the real filesystem so a child Node process can execute it.
- * Resolution order: explicit setting -> bundled Agent SDK in app -> legacy
- * bundled Claude Code package -> workspace node_modules -> global `claude`.
+ * Unlike the original Claude-only implementation, this manager now owns the
+ * generic session lifecycle for all external backends and delegates transport
+ * details to backend adapters.
  */
 
 import { randomUUID } from 'crypto'
@@ -21,52 +11,53 @@ import { execFileSync } from 'child_process'
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { app, type WebContents } from 'electron'
-import { query } from '@anthropic-ai/claude-agent-sdk'
-import type { Query } from '@anthropic-ai/claude-agent-sdk'
 import { IpcChannels, deriveTitle } from '@aide/shared'
 import type {
   AgentBackend,
-  CliAgentProcessStatus,
+  CliAgentBackendStateMap,
   CliAgentMessage,
+  CliAgentMessagePayload,
+  CliAgentProcessStatus,
+  CliAgentResultPayload,
   CliAgentSession,
-  CliAgentStreamDelta,
   CliAgentStatusPayload,
-  CliAgentResultPayload,
-  CliAgentMessagePayload,
+  CliAgentStreamDelta,
   ConversationListChangedPayload,
+  ExternalCliBackend,
 } from '@aide/shared'
 import type { ConversationStore } from './conversationStore'
-
-// ---------------------------------------------------------------------------
-// Internal session state
-// ---------------------------------------------------------------------------
+import { createClaudeCodeAdapter } from './cliAdapters/claudeCodeAdapter'
+import { createCodexAdapter } from './cliAdapters/codexAdapter'
+import { createOpenCodeAdapter } from './cliAdapters/openCodeAdapter'
+import type { CliBackendAdapter, CliBackendEvent, CliBackendRun } from './cliAdapters/types'
+
+interface PersistedCliConversation {
+  messages?: CliAgentMessage[]
+  activeBackend?: ExternalCliBackend
+  backendStates?: CliAgentBackendStateMap
+  claudeSessionId?: string
+}
 
 interface CliAgentSessionInternal {
   id: string
   workspaceId: string
-  backend: AgentBackend
-  queryInstance: Query | null
-  abortController: AbortController | null
+  backend: ExternalCliBackend
+  activeRun: CliBackendRun | null
   processStatus: CliAgentProcessStatus
   messages: CliAgentMessage[]
   model?: string
   sessionToolNames?: string[]
   lastError?: string
   totalCostUsd: number
-  /** Claude Code session ID for resume across sends */
-  claudeSessionId?: string
-  /** Worktree path this session operates in (if any). */
   worktreePath?: string
+  backendStates: CliAgentBackendStateMap
 }
 
-// ---------------------------------------------------------------------------
-// Options
-// ---------------------------------------------------------------------------
-
 export interface CliAgentManagerOpts {
   workspaceRoot: string
   getWebContents: () => WebContents | null
   claudeCodePath?: string
+  opencodePath?: string
   codexPath?: string
   conversationStore?: ConversationStore
   loadClaudeHistory?: (claudeSessionId: string) => Promise<CliAgentMessage[]>
@@ -82,81 +73,87 @@ function comparableHistoryCount(messages: CliAgentMessage[]): number {
   ).length
 }
 
-// ---------------------------------------------------------------------------
-// Manager
-// ---------------------------------------------------------------------------
+function isExternalBackend(backend: AgentBackend): backend is ExternalCliBackend {
+  return backend === 'claude-code' || backend === 'opencode' || backend === 'codex'
+}
+
+function parsePersistedConversation(raw: unknown): PersistedCliConversation {
+  if (!raw || typeof raw !== 'object') return {}
+  const persisted = raw as PersistedCliConversation
+  const backendStates: CliAgentBackendStateMap = { ...(persisted.backendStates ?? {}) }
+  if (!backendStates['claude-code']?.sessionId && typeof persisted.claudeSessionId === 'string') {
+    backendStates['claude-code'] = {
+      ...(backendStates['claude-code'] ?? {}),
+      sessionId: persisted.claudeSessionId,
+    }
+  }
+  return {
+    messages: Array.isArray(persisted.messages) ? persisted.messages : [],
+    activeBackend: persisted.activeBackend,
+    backendStates,
+    claudeSessionId: persisted.claudeSessionId,
+  }
+}
 
 export class CliAgentManager {
   private sessions = new Map<string, CliAgentSessionInternal>()
-  private workspaceRoot: string
-  private getWebContents: () => WebContents | null
+  private readonly workspaceRoot: string
+  private readonly getWebContents: () => WebContents | null
   private claudeCodePath: string
+  private opencodePath: string
   private codexPath: string
-  private conversationStore: ConversationStore | null
-  private loadClaudeHistory: ((claudeSessionId: string) => Promise<CliAgentMessage[]>) | null
-  /** Resolved path to the Claude Code CLI, cached after first lookup */
+  private readonly conversationStore: ConversationStore | null
+  private readonly loadClaudeHistory:
+    | ((claudeSessionId: string) => Promise<CliAgentMessage[]>)
+    | null
   private resolvedClaudeCodePath: string | null = null
+  private resolvedOpenCodePath: string | null = null
+  private resolvedCodexPath: string | null = null
 
   constructor(opts: CliAgentManagerOpts) {
     this.workspaceRoot = opts.workspaceRoot
     this.getWebContents = opts.getWebContents
     this.claudeCodePath = opts.claudeCodePath ?? ''
+    this.opencodePath = opts.opencodePath ?? ''
     this.codexPath = opts.codexPath ?? ''
     this.conversationStore = opts.conversationStore ?? null
     this.loadClaudeHistory = opts.loadClaudeHistory ?? null
   }
 
-  // ─── Public API ──────────────────────────────
-
-  /**
-   * Initialize a CLI agent session. Does not start a query yet — that
-   * happens on the first `send()`.
-   *
-   * If `conversationId` is provided, resumes an existing conversation
-   * (loads claudeSessionId from the store for SDK resume).
-   */
   async start(
     workspaceId: string,
     backend: AgentBackend,
     conversationId?: string,
     worktreePath?: string,
   ): Promise<{ sessionId: string } | { error: string }> {
-    if (backend === 'codex') {
-      return { error: 'Codex integration coming soon.' }
-    }
-
     if (backend === 'built-in') {
       return { error: 'Use the built-in agent chat panel instead.' }
     }
 
-    // If resuming an existing conversation, load from store
-    let existingMessages: CliAgentMessage[] = []
-    let existingClaudeSessionId: string | undefined
-
-    if (conversationId && this.conversationStore) {
-      const meta = await this.conversationStore.get(conversationId)
-      if (meta?.claudeSessionId) {
-        existingClaudeSessionId = meta.claudeSessionId
-      }
-      const saved = (await this.conversationStore.loadMessages(conversationId)) as {
-        messages?: CliAgentMessage[]
-        claudeSessionId?: string
-      } | null
-      if (saved?.messages) {
-        existingMessages = saved.messages
-      }
-      if (saved?.claudeSessionId) {
-        existingClaudeSessionId = saved.claudeSessionId
-      }
+    if (conversationId?.startsWith('claude-native:') && backend !== 'claude-code') {
+      return { error: 'Native Claude conversations cannot switch to a different backend.' }
     }
 
-    if (!existingClaudeSessionId && conversationId?.startsWith('claude-native:')) {
+    const sessionId = conversationId ?? randomUUID()
+    const persisted =
+      conversationId && this.conversationStore
+        ? parsePersistedConversation(await this.conversationStore.loadMessages(conversationId))
+        : parsePersistedConversation(null)
+
+    let existingMessages = persisted.messages ?? []
+    const backendStates = persisted.backendStates ?? {}
+
+    if (!backendStates['claude-code']?.sessionId && conversationId?.startsWith('claude-native:')) {
       const raw = conversationId.slice('claude-native:'.length)
       if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) {
-        existingClaudeSessionId = raw
+        backendStates['claude-code'] = {
+          ...(backendStates['claude-code'] ?? {}),
+          sessionId: raw,
+        }
       }
     }
 
+    const existingClaudeSessionId = backendStates['claude-code']?.sessionId
     if (existingClaudeSessionId && this.loadClaudeHistory) {
       try {
         const nativeMessages = await this.loadClaudeHistory(existingClaudeSessionId)
@@ -167,12 +164,10 @@ export class CliAgentManager {
           existingMessages = nativeMessages
         }
       } catch {
-        // Fall back to persisted shadow copy when native Claude history is unavailable.
+        // Fall back to the shadow copy when native Claude history is unavailable.
       }
     }
 
-    const sessionId = conversationId ?? randomUUID()
-
     if (this.conversationStore && !sessionId.startsWith('claude-native:')) {
       await this.conversationStore.ensure(sessionId, {
         workspaceId,
@@ -181,8 +176,18 @@ export class CliAgentManager {
       })
     }
 
-    // If session already in memory, return it
-    if (this.sessions.has(sessionId)) {
+    const existing = this.sessions.get(sessionId)
+    if (existing) {
+      if (existing.activeRun) {
+        return { error: 'Agent is already processing a request. Stop it first or wait.' }
+      }
+      existing.backend = backend
+      existing.model = existing.backendStates[backend]?.model
+      existing.sessionToolNames = undefined
+      existing.worktreePath = worktreePath ?? existing.worktreePath
+      await this.persistSession(existing)
+      await this.broadcastConversationList(existing.workspaceId)
+      this.emitStatus(existing)
       return { sessionId }
     }
 
@@ -190,35 +195,54 @@ export class CliAgentManager {
       id: sessionId,
       workspaceId,
       backend,
-      queryInstance: null,
-      abortController: null,
+      activeRun: null,
       processStatus: 'stopped',
       messages: existingMessages,
       totalCostUsd: 0,
-      claudeSessionId: existingClaudeSessionId,
+      model: backendStates[backend]?.model,
       worktreePath,
+      backendStates,
     }
 
     this.sessions.set(sessionId, session)
     this.emitStatus(session)
-
     return { sessionId }
   }
 
-  /**
-   * Send a prompt to the CLI agent. Starts an SDK query that streams
-   * messages back via IPC. Uses `resume` for conversation continuity.
-   */
-  async send(sessionId: string, content: string): Promise<{ success: true } | { error: string }> {
+  async switchBackend(
+    sessionId: string,
+    backend: AgentBackend,
+  ): Promise<{ success: true } | { error: string }> {
+    if (!isExternalBackend(backend)) {
+      return { error: 'Only external CLI backends can be selected here.' }
+    }
+
     const session = this.sessions.get(sessionId)
     if (!session) return { error: 'Session not found' }
+    if (session.activeRun) {
+      return { error: 'Stop the active run before switching backends.' }
+    }
+    if (session.id.startsWith('claude-native:') && backend !== 'claude-code') {
+      return { error: 'Native Claude conversations cannot switch to a different backend.' }
+    }
 
-    // If a query is already running, reject (one at a time)
-    if (session.queryInstance) {
+    session.backend = backend
+    session.model = session.backendStates[backend]?.model
+    session.sessionToolNames = undefined
+    session.lastError = undefined
+    await this.persistSession(session)
+    await this.broadcastConversationList(session.workspaceId)
+    this.emitStatus(session)
+    return { success: true }
+  }
+
+  async send(sessionId: string, content: string): Promise<{ success: true } | { error: string }> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return { error: 'Session not found' }
+    if (session.activeRun) {
       return { error: 'Agent is already processing a request. Stop it first or wait.' }
     }
 
-    // Add user message to history
     const userMsg: CliAgentMessage = {
       id: randomUUID(),
       type: 'user',
@@ -227,53 +251,69 @@ export class CliAgentManager {
     }
     session.messages.push(userMsg)
     this.emitMessage(session, userMsg)
-
-    // Auto-title on first user message
     await this.maybeAutoTitle(session, content)
 
-    // Reset error state
     session.lastError = undefined
+    const prompt = this.buildTurnPrompt(session, content)
 
-    // Fire and forget the consumption loop
-    this.consumeQuery(session, content).catch((err) => {
-      const errMsg = err instanceof Error ? err.message : String(err)
-      console.error(
-        `[CliAgentManager] Unhandled consumeQuery error for session ${session.id}:`,
-        errMsg,
-      )
-      if (err instanceof Error && err.stack) console.error(`[CliAgentManager] Stack:`, err.stack)
-      session.lastError = errMsg
-      this.setStatus(session, 'error')
-    })
+    let adapter: CliBackendAdapter
+    try {
+      adapter = this.createAdapter(session.backend)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      this.handleRunError(session, message)
+      return { error: message }
+    }
+
+    const run = adapter.startTurn(
+      {
+        conversationId: session.id,
+        cwd: session.worktreePath ?? this.workspaceRoot,
+        prompt,
+        backendState: { ...(session.backendStates[session.backend] ?? {}) },
+      },
+      (event) => this.applyBackendEvent(session, event),
+    )
+
+    session.activeRun = run
+    this.setStatus(session, 'running')
+
+    run.completed
+      .catch((error) => {
+        if (session.processStatus === 'stopping') return
+        const message = error instanceof Error ? error.message : String(error)
+        this.handleRunError(session, message)
+      })
+      .finally(async () => {
+        if (session.activeRun === run) {
+          session.activeRun = null
+        }
+        if (session.processStatus === 'stopping' || session.processStatus === 'running') {
+          this.setStatus(session, 'stopped')
+        }
+        await this.persistSession(session)
+      })
 
     return { success: true }
   }
 
   stop(sessionId: string): void {
     const session = this.sessions.get(sessionId)
-    if (!session) return
-
-    if (session.queryInstance || session.abortController) {
-      this.setStatus(session, 'stopping')
-      session.abortController?.abort()
-      session.queryInstance?.close()
-    }
+    if (!session || !session.activeRun) return
+    this.setStatus(session, 'stopping')
+    session.activeRun.close()
   }
 
   getSession(workspaceId: string): CliAgentSession | null {
-    // Find the most recent session for this workspace
     for (const session of this.sessions.values()) {
-      if (session.workspaceId === workspaceId) {
-        return this.toPublicSession(session)
-      }
+      if (session.workspaceId === workspaceId) return this.toPublicSession(session)
     }
     return null
   }
 
-  /** Check if any active (running/starting) session uses the given worktree path. */
   hasActiveSessionsForWorktree(worktreePath: string): boolean {
     for (const session of this.sessions.values()) {
-      if (session.worktreePath === worktreePath && session.queryInstance) {
+      if (session.worktreePath === worktreePath && session.activeRun) {
         return true
       }
     }
@@ -282,14 +322,38 @@ export class CliAgentManager {
 
   getSessionById(sessionId: string): CliAgentSession | null {
     const session = this.sessions.get(sessionId)
-    if (!session) return null
-    return this.toPublicSession(session)
+    return session ? this.toPublicSession(session) : null
   }
 
   ownsSession(sessionId: string): boolean {
     return this.sessions.has(sessionId)
   }
 
+  updatePaths(claudeCodePath: string, opencodePath: string, codexPath: string): void {
+    this.claudeCodePath = claudeCodePath
+    this.opencodePath = opencodePath
+    this.codexPath = codexPath
+    this.resolvedClaudeCodePath = null
+    this.resolvedOpenCodePath = null
+    this.resolvedCodexPath = null
+  }
+
+  getRunningSessionCount(): number {
+    let count = 0
+    for (const session of this.sessions.values()) {
+      if (session.activeRun) count += 1
+    }
+    return count
+  }
+
+  async destroy(): Promise<void> {
+    for (const session of this.sessions.values()) {
+      session.activeRun?.close()
+      await this.persistSession(session).catch(() => {})
+    }
+    this.sessions.clear()
+  }
+
   private toPublicSession(session: CliAgentSessionInternal): CliAgentSession {
     return {
       id: session.id,
@@ -305,48 +369,54 @@ export class CliAgentManager {
     }
   }
 
-  updatePaths(claudeCodePath: string, codexPath: string): void {
-    this.claudeCodePath = claudeCodePath
-    this.codexPath = codexPath
-    // Invalidate cache so next query re-resolves
-    this.resolvedClaudeCodePath = null
-  }
+  private createAdapter(backend: ExternalCliBackend): CliBackendAdapter {
+    if (backend === 'claude-code') {
+      const executablePath = this.resolveClaudeCodeExecutable()
+      if (!executablePath) {
+        throw new Error(
+          'Claude Code CLI not found. Install @anthropic-ai/claude-code globally or set agent.claudeCodePath in settings.',
+        )
+      }
+      return createClaudeCodeAdapter({ executablePath })
+    }
 
-  getRunningSessionCount(): number {
-    let count = 0
-    for (const session of this.sessions.values()) {
-      if (session.queryInstance) count += 1
+    if (backend === 'opencode') {
+      const executablePath = this.resolveGenericExecutable(
+        'opencode',
+        this.opencodePath,
+        this.resolvedOpenCodePath,
+      )
+      if (!executablePath) {
+        throw new Error(
+          'OpenCode CLI not found. Install opencode or set agent.opencodePath in settings.',
+        )
+      }
+      this.resolvedOpenCodePath = executablePath
+      return createOpenCodeAdapter({ executablePath })
     }
-    return count
-  }
 
-  async destroy(): Promise<void> {
-    for (const session of this.sessions.values()) {
-      session.abortController?.abort()
-      session.queryInstance?.close()
-      await this.persistSession(session).catch(() => {})
+    const executablePath = this.resolveGenericExecutable(
+      'codex',
+      this.codexPath,
+      this.resolvedCodexPath,
+    )
+    if (!executablePath) {
+      throw new Error(
+        'Codex CLI not found. Install @openai/codex or set agent.codexPath in settings.',
+      )
     }
-    this.sessions.clear()
+    this.resolvedCodexPath = executablePath
+    return createCodexAdapter({ executablePath })
   }
 
-  // ─── Claude Code CLI Resolution ─────────────
-
-  /**
-   * Resolve the path to the Claude Code CLI executable.
-   * The SDK spawns Claude Code as a subprocess, so we need to tell it
-   * where the actual binary lives via `pathToClaudeCodeExecutable`.
-   */
   private resolveClaudeCodeExecutable(): string | null {
     if (this.resolvedClaudeCodePath) return this.resolvedClaudeCodePath
 
-    // 1. Explicit path from settings
     if (this.claudeCodePath && existsSync(this.claudeCodePath)) {
-      console.log(`[CliAgentManager] Using explicit Claude Code path: ${this.claudeCodePath}`)
       this.resolvedClaudeCodePath = this.claudeCodePath
       return this.claudeCodePath
     }
 
-    // 2. Bundled in Electron app
     const bundledCandidates: string[] = []
     if (app.isPackaged) {
       bundledCandidates.push(
@@ -371,402 +441,174 @@ export class CliAgentManager {
     bundledCandidates.push(
       join(app.getAppPath(), 'node_modules', '@anthropic-ai', 'claude-agent-sdk', 'cli.js'),
       join(app.getAppPath(), 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
-    )
-    for (const candidate of bundledCandidates) {
-      if (existsSync(candidate)) {
-        console.log(`[CliAgentManager] Using bundled Claude Code: ${candidate}`)
-        this.resolvedClaudeCodePath = candidate
-        return candidate
-      }
-    }
-
-    // 3. Workspace-local installation
-    const workspaceCandidates = [
       join(this.workspaceRoot, 'node_modules', '@anthropic-ai', 'claude-agent-sdk', 'cli.js'),
       join(this.workspaceRoot, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
-    ]
-    for (const candidate of workspaceCandidates) {
+    )
+
+    for (const candidate of bundledCandidates) {
       if (existsSync(candidate)) {
-        console.log(`[CliAgentManager] Using workspace Claude Code: ${candidate}`)
         this.resolvedClaudeCodePath = candidate
         return candidate
       }
     }
 
-    // 4. Global `claude` in PATH
     try {
       const result = execFileSync('which', ['claude'], { encoding: 'utf-8' }).trim()
       if (result) {
-        console.log(`[CliAgentManager] Using global Claude Code: ${result}`)
         this.resolvedClaudeCodePath = result
         return result
       }
     } catch {
-      // Not found in PATH
+      // Not found in PATH.
     }
 
-    console.warn('[CliAgentManager] Claude Code CLI not found in any location')
     return null
   }
 
-  // ─── SDK Query Consumption ──────────────────
+  private resolveGenericExecutable(
+    command: string,
+    explicitPath: string,
+    cachedPath: string | null,
+  ): string | null {
+    if (cachedPath) return cachedPath
+    if (explicitPath && existsSync(explicitPath)) return explicitPath
 
-  private async consumeQuery(session: CliAgentSessionInternal, prompt: string): Promise<void> {
-    const abortController = new AbortController()
-    session.abortController = abortController
-
-    const cwd = session.worktreePath ?? this.workspaceRoot
-    console.log(`[CliAgentManager] Starting SDK query for session ${session.id}`)
-    console.log(`[CliAgentManager]   cwd: ${cwd}`)
-    console.log(`[CliAgentManager]   resume: ${session.claudeSessionId ?? '(new session)'}`)
-    console.log(
-      `[CliAgentManager]   prompt: ${prompt.slice(0, 200)}${prompt.length > 200 ? '...' : ''}`,
-    )
-
-    // Collect stderr output for diagnostics
-    const stderrChunks: string[] = []
-
-    // Resolve the Claude Code executable path for the SDK
-    const executablePath = this.resolveClaudeCodeExecutable()
-    if (!executablePath) {
-      session.lastError =
-        'Claude Code CLI not found. Install @anthropic-ai/claude-code globally or set agent.claudeCodePath in settings.'
-      const errorMsg: CliAgentMessage = {
-        id: randomUUID(),
-        type: 'error',
-        content: session.lastError,
-        timestamp: Date.now(),
-      }
-      session.messages.push(errorMsg)
-      this.emitMessage(session, errorMsg)
-      this.setStatus(session, 'error')
-      return
-    }
-    console.log(`[CliAgentManager]   executable: ${executablePath}`)
-
-    const options: Record<string, unknown> = {
-      cwd,
-      abortController,
-      pathToClaudeCodeExecutable: executablePath,
-      includePartialMessages: true,
-      permissionMode: 'default' as const,
-      settingSources: ['user', 'project', 'local'],
-      systemPrompt: { type: 'preset', preset: 'claude_code' },
-      stderr: (data: string) => {
-        stderrChunks.push(data)
-        console.warn(`[CliAgentManager] stderr: ${data.trimEnd()}`)
-      },
-    }
-
-    if (session.claudeSessionId) {
-      options.resume = session.claudeSessionId
+    const candidates: string[] = []
+    if (app.isPackaged) {
+      candidates.push(
+        join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', '.bin', command),
+      )
     }
+    candidates.push(
+      join(app.getAppPath(), 'node_modules', '.bin', command),
+      join(this.workspaceRoot, 'node_modules', '.bin', command),
+    )
 
-    let queryInstance: ReturnType<typeof query>
-    try {
-      queryInstance = query({ prompt, options: options as Parameters<typeof query>[0]['options'] })
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err)
-      const errStack = err instanceof Error ? err.stack : undefined
-      console.error(`[CliAgentManager] Failed to create query:`, errMsg)
-      if (errStack) console.error(`[CliAgentManager] Stack:`, errStack)
-      session.lastError = `Failed to start agent: ${errMsg}`
-      this.setStatus(session, 'error')
-
-      // Surface the error in the chat as a message
-      const errorMsg: CliAgentMessage = {
-        id: randomUUID(),
-        type: 'error',
-        content: `Failed to start agent: ${errMsg}${stderrChunks.length ? '\n\nstderr:\n' + stderrChunks.join('') : ''}`,
-        timestamp: Date.now(),
-      }
-      session.messages.push(errorMsg)
-      this.emitMessage(session, errorMsg)
-      return
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate
     }
 
-    session.queryInstance = queryInstance
-    this.setStatus(session, 'running')
-
-    let messageCount = 0
     try {
-      for await (const message of queryInstance) {
-        if (abortController.signal.aborted) break
-        messageCount++
-        this.handleSDKMessage(session, message)
-      }
-      console.log(
-        `[CliAgentManager] Query completed for session ${session.id} — ${messageCount} messages received`,
-      )
-    } catch (err) {
-      if (!abortController.signal.aborted) {
-        const errMsg = err instanceof Error ? err.message : String(err)
-        const errStack = err instanceof Error ? err.stack : undefined
-        console.error(`[CliAgentManager] Query error for session ${session.id}:`, errMsg)
-        if (errStack) console.error(`[CliAgentManager] Stack:`, errStack)
-        if (stderrChunks.length) {
-          console.error(`[CliAgentManager] Captured stderr:\n${stderrChunks.join('')}`)
-        }
-        console.error(`[CliAgentManager] Messages received before error: ${messageCount}`)
-
-        // Build a detailed error message for the UI
-        const stderrText = stderrChunks.join('').trim()
-        const detailedError = stderrText
-          ? `${errMsg}\n\nstderr output:\n${stderrText.slice(-2000)}`
-          : errMsg
-        session.lastError = detailedError
-
-        // Surface the error in the chat
-        const errorMsg: CliAgentMessage = {
-          id: randomUUID(),
-          type: 'error',
-          content: detailedError,
-          timestamp: Date.now(),
-        }
-        session.messages.push(errorMsg)
-        this.emitMessage(session, errorMsg)
-
-        this.setStatus(session, 'error')
-      }
-    } finally {
-      session.queryInstance = null
-      session.abortController = null
-      if (session.processStatus === 'stopping') {
-        this.setStatus(session, 'stopped')
-      } else if (session.processStatus !== 'error') {
-        this.setStatus(session, 'stopped')
-      }
-      await this.persistSession(session).catch(() => {})
-    }
-  }
-
-  // ─── SDK Message Handling ───────────────────
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleSDKMessage(session: CliAgentSessionInternal, message: any): void {
-    const type = message.type as string
-    const subtype = message.subtype as string | undefined
-
-    // Log all non-streaming messages (stream_event is too noisy)
-    if (type !== 'stream_event') {
-      console.log(
-        `[CliAgentManager] SDK message: type=${type}${subtype ? ` subtype=${subtype}` : ''} session=${session.id.slice(0, 8)}`,
-      )
+      const result = execFileSync('which', [command], { encoding: 'utf-8' }).trim()
+      if (result) return result
+    } catch {
+      // Not found in PATH.
     }
 
-    if (type === 'system') {
-      this.handleSystemMessage(session, message)
-    } else if (type === 'assistant') {
-      this.handleAssistantMessage(session, message)
-    } else if (type === 'stream_event') {
-      this.handleStreamEvent(session, message)
-    } else if (type === 'tool_progress') {
-      this.handleToolProgress(session, message)
-    } else if (type === 'tool_use_summary') {
-      this.handleToolUseSummary(session, message)
-    } else if (type === 'result') {
-      this.handleResultMessage(session, message)
-    } else if (type === 'rate_limit_event') {
-      console.warn(`[CliAgentManager] Rate limited — session ${session.id.slice(0, 8)}`)
-      this.setStatus(session, 'rate_limited')
-    } else {
-      // Log unknown message types so we can add handling later
-      console.log(
-        `[CliAgentManager] Unhandled SDK message type: ${type}`,
-        JSON.stringify(message).slice(0, 500),
-      )
-    }
+    return null
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleSystemMessage(session: CliAgentSessionInternal, message: any): void {
-    const subtype = message.subtype as string | undefined
-
-    if (subtype === 'init') {
-      // Capture session ID for resume
-      const sdkSessionId = message.session_id as string | undefined
-      if (sdkSessionId) {
-        session.claudeSessionId = sdkSessionId
-        this.conversationStore
-          ?.updateMeta(session.id, { claudeSessionId: sdkSessionId })
-          .catch(() => {})
+  private applyBackendEvent(session: CliAgentSessionInternal, event: CliBackendEvent): void {
+    if (event.type === 'stream-delta') {
+      const payload: CliAgentStreamDelta = {
+        workspaceId: session.workspaceId,
+        sessionId: session.id,
+        messageId: event.messageId,
+        delta: event.delta,
       }
+      this.getWebContents()?.send(IpcChannels.CLI_AGENT_STREAM_DELTA, payload)
+      return
+    }
 
-      session.model = (message.model as string) ?? undefined
-      const tools = message.tools as string[] | undefined
-      session.sessionToolNames = tools
-
-      this.setStatus(session, 'running')
-
-      const msg: CliAgentMessage = {
-        id: (message.uuid as string) ?? randomUUID(),
-        type: 'system',
-        content: `Session initialized — model: ${session.model ?? 'unknown'}`,
-        timestamp: Date.now(),
-        raw: message,
-      }
-      session.messages.push(msg)
-      this.emitMessage(session, msg)
-    } else if (subtype === 'status') {
-      const msg: CliAgentMessage = {
-        id: (message.uuid as string) ?? randomUUID(),
-        type: 'status',
-        content: String(message.status ?? message.message ?? 'status update'),
-        timestamp: Date.now(),
-      }
-      session.messages.push(msg)
-      this.emitMessage(session, msg)
+    if (event.type === 'backend-state') {
+      const current = session.backendStates[session.backend] ?? {}
+      session.backendStates[session.backend] = { ...current, ...event.patch }
+      if (event.patch.model) session.model = event.patch.model
+      return
     }
-  }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleAssistantMessage(session: CliAgentSessionInternal, message: any): void {
-    const betaMessage = message.message
-    if (!betaMessage || !Array.isArray(betaMessage.content)) return
-
-    let text = ''
-    for (const block of betaMessage.content) {
-      if (block.type === 'text') {
-        text += block.text ?? ''
-      } else if (block.type === 'tool_use') {
-        // Emit tool use as separate message
-        const toolMsg: CliAgentMessage = {
-          id: (block.id as string) ?? randomUUID(),
-          type: 'tool_use',
-          content: `Running ${block.name ?? 'tool'}...`,
-          timestamp: Date.now(),
-          toolName: block.name as string,
-          toolUseId: block.id as string,
+    if (event.type === 'session-meta') {
+      if (event.model) {
+        session.model = event.model
+        session.backendStates[session.backend] = {
+          ...(session.backendStates[session.backend] ?? {}),
+          model: event.model,
         }
-        session.messages.push(toolMsg)
-        this.emitMessage(session, toolMsg)
       }
+      if (event.tools) session.sessionToolNames = event.tools
+      return
     }
 
-    if (text) {
-      const msg: CliAgentMessage = {
-        id: (message.uuid as string) ?? randomUUID(),
-        type: 'assistant',
-        content: text,
-        timestamp: Date.now(),
-        raw: message,
+    if (event.type === 'result') {
+      session.totalCostUsd += event.totalCostUsd
+      const payload: CliAgentResultPayload = {
+        workspaceId: session.workspaceId,
+        sessionId: session.id,
+        durationMs: event.durationMs,
+        totalCostUsd: session.totalCostUsd,
+        isSuccess: event.isSuccess,
       }
-      session.messages.push(msg)
-      this.emitMessage(session, msg)
+      this.getWebContents()?.send(IpcChannels.CLI_AGENT_RESULT, payload)
+      return
     }
-  }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleStreamEvent(session: CliAgentSessionInternal, message: any): void {
-    const event = message.event
-    if (!event) return
-
-    const eventType = event.type as string | undefined
-
-    if (eventType === 'content_block_delta') {
-      const delta = event.delta
-      if (delta?.type === 'text_delta') {
-        const text = (delta.text as string) ?? ''
-        if (text) {
-          const streamDelta: CliAgentStreamDelta = {
-            workspaceId: session.workspaceId,
-            sessionId: session.id,
-            messageId: (message.uuid as string) ?? session.id,
-            delta: text,
-          }
-          this.getWebContents()?.send(IpcChannels.CLI_AGENT_STREAM_DELTA, streamDelta)
-        }
-      }
+    const message: CliAgentMessage = {
+      ...event.message,
+      backend: event.message.type === 'user' ? undefined : session.backend,
     }
-  }
+    session.messages.push(message)
+    this.emitMessage(session, message)
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleToolProgress(session: CliAgentSessionInternal, message: any): void {
-    const msg: CliAgentMessage = {
-      id: (message.uuid as string) ?? randomUUID(),
-      type: 'tool_use',
-      content: `Running ${message.tool_name ?? 'tool'}...`,
-      timestamp: Date.now(),
-      toolName: (message.tool_name as string) ?? undefined,
-      toolUseId: (message.tool_use_id as string) ?? undefined,
+    if (message.type === 'status' && message.content.toLowerCase().includes('rate limited')) {
+      this.setStatus(session, 'rate_limited')
+    } else if (session.processStatus === 'rate_limited' && message.type !== 'status') {
+      this.setStatus(session, 'running')
     }
-    session.messages.push(msg)
-    this.emitMessage(session, msg)
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleToolUseSummary(session: CliAgentSessionInternal, message: any): void {
-    const msg: CliAgentMessage = {
-      id: (message.uuid as string) ?? randomUUID(),
-      type: 'tool_result',
-      content: (message.summary as string) ?? 'Tool completed',
-      timestamp: Date.now(),
+  private buildTurnPrompt(session: CliAgentSessionInternal, content: string): string {
+    const backendState = session.backendStates[session.backend]
+    if (backendState?.sessionId) {
+      return content
     }
-    session.messages.push(msg)
-    this.emitMessage(session, msg)
-  }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleResultMessage(session: CliAgentSessionInternal, message: any): void {
-    const subtype = message.subtype as string | undefined
-    const isSuccess = subtype === 'success'
-    const durationMs = (message.duration_ms as number) ?? 0
-    const totalCostUsd = (message.total_cost_usd as number) ?? 0
-
-    session.totalCostUsd += totalCostUsd
-
-    // Capture session ID from result as well
-    const resultSessionId = message.session_id as string | undefined
-    if (resultSessionId && !session.claudeSessionId) {
-      session.claudeSessionId = resultSessionId
-      this.conversationStore
-        ?.updateMeta(session.id, { claudeSessionId: resultSessionId })
-        .catch(() => {})
-    }
-
-    // Build detailed error content for non-success results
-    let errorDetail = ''
-    if (!isSuccess) {
-      const errors = message.errors as string[] | undefined
-      if (errors?.length) {
-        errorDetail = errors.join('\n')
-      }
-      console.error(
-        `[CliAgentManager] Result error for session ${session.id.slice(0, 8)}: subtype=${subtype}`,
+    const priorMessages = session.messages
+      .slice(0, -1)
+      .filter(
+        (message) =>
+          message.type === 'user' ||
+          message.type === 'assistant' ||
+          message.type === 'tool_use' ||
+          message.type === 'tool_result',
       )
-      if (errorDetail) console.error(`[CliAgentManager] Error details:\n${errorDetail}`)
-      console.error(
-        `[CliAgentManager] Full result message:`,
-        JSON.stringify(message).slice(0, 2000),
-      )
-    }
 
-    const msg: CliAgentMessage = {
-      id: (message.uuid as string) ?? randomUUID(),
-      type: isSuccess ? 'result' : 'error',
-      content: isSuccess
-        ? `Completed in ${(durationMs / 1000).toFixed(1)}s`
-        : `Failed: ${subtype ?? 'unknown error'}${errorDetail ? '\n\n' + errorDetail : ''}`,
-      timestamp: Date.now(),
-      durationMs,
-      totalCostUsd,
-      isSuccess,
-      raw: message,
+    if (priorMessages.length === 0) {
+      return content
     }
-    session.messages.push(msg)
-    this.emitMessage(session, msg)
 
-    const resultPayload: CliAgentResultPayload = {
-      workspaceId: session.workspaceId,
-      sessionId: session.id,
-      durationMs,
-      totalCostUsd: session.totalCostUsd,
-      isSuccess,
-    }
-    this.getWebContents()?.send(IpcChannels.CLI_AGENT_RESULT, resultPayload)
+    const transcript = priorMessages
+      .slice(-40)
+      .map((message) => {
+        const source = message.backend ? ` ${message.backend}` : ''
+        return `[${message.type}${source}]\n${message.content}`
+      })
+      .join('\n\n')
+
+    return [
+      `You are taking over an existing IDE agent conversation using the ${session.backend} backend.`,
+      'Continue from the prior transcript below and answer the latest user request directly.',
+      '',
+      'Conversation transcript:',
+      transcript,
+      '',
+      'Latest user request:',
+      content,
+    ].join('\n')
   }
 
-  // ─── IPC Emission Helpers ────────────────────
+  private handleRunError(session: CliAgentSessionInternal, error: string): void {
+    session.lastError = error
+    const message: CliAgentMessage = {
+      id: randomUUID(),
+      type: 'error',
+      content: error,
+      timestamp: Date.now(),
+      backend: session.backend,
+    }
+    session.messages.push(message)
+    this.emitMessage(session, message)
+    this.setStatus(session, 'error')
+  }
 
   private setStatus(session: CliAgentSessionInternal, status: CliAgentProcessStatus): void {
     session.processStatus = status
@@ -783,51 +625,60 @@ export class CliAgentManager {
     this.getWebContents()?.send(IpcChannels.CLI_AGENT_STATUS, payload)
   }
 
-  private emitMessage(session: CliAgentSessionInternal, msg: CliAgentMessage): void {
-    const ipcMsg: CliAgentMessagePayload = {
-      ...msg,
+  private emitMessage(session: CliAgentSessionInternal, message: CliAgentMessage): void {
+    const payload: CliAgentMessagePayload = {
+      ...message,
       workspaceId: session.workspaceId,
       sessionId: session.id,
     }
-    this.getWebContents()?.send(IpcChannels.CLI_AGENT_MESSAGE, ipcMsg)
-
-    if (session.processStatus === 'rate_limited' && msg.type !== 'status') {
-      this.setStatus(session, 'running')
-    }
+    this.getWebContents()?.send(IpcChannels.CLI_AGENT_MESSAGE, payload)
   }
 
-  // ─── Persistence Helpers ─────────────────────
-
   private async persistSession(session: CliAgentSessionInternal): Promise<void> {
-    if (!this.conversationStore) return
+    if (!this.conversationStore || session.id.startsWith('claude-native:')) return
+
+    const claudeSessionId = session.backendStates['claude-code']?.sessionId
     await this.conversationStore.saveMessages(session.id, {
       messages: session.messages,
-      claudeSessionId: session.claudeSessionId,
-    })
+      activeBackend: session.backend,
+      backendStates: session.backendStates,
+      claudeSessionId,
+    } satisfies PersistedCliConversation)
+
     await this.conversationStore.updateMeta(session.id, {
+      backend: session.backend,
       updatedAt: Date.now(),
       messageCount: session.messages.length,
-      firstMessage: session.messages.find((m) => m.type === 'user')?.content.slice(0, 100),
-      claudeSessionId: session.claudeSessionId,
+      firstMessage: session.messages
+        .find((message) => message.type === 'user')
+        ?.content.slice(0, 100),
+      claudeSessionId,
       worktreePath: session.worktreePath,
     })
   }
 
   private async maybeAutoTitle(session: CliAgentSessionInternal, content: string): Promise<void> {
-    if (!this.conversationStore) return
+    if (!this.conversationStore || session.id.startsWith('claude-native:')) return
 
-    const userMessages = session.messages.filter((m) => m.type === 'user')
+    const userMessages = session.messages.filter((message) => message.type === 'user')
     if (userMessages.length !== 1) return
 
     const meta = await this.conversationStore.get(session.id)
     if (!meta || !meta.autoTitled) return
 
-    const title = deriveTitle(content)
-    await this.conversationStore.updateMeta(session.id, { title, updatedAt: Date.now() })
+    await this.conversationStore.updateMeta(session.id, {
+      title: deriveTitle(content),
+      updatedAt: Date.now(),
+    })
+
+    await this.broadcastConversationList(session.workspaceId)
+  }
 
+  private async broadcastConversationList(workspaceId: string): Promise<void> {
+    if (!this.conversationStore) return
     const index = await this.conversationStore.loadIndex()
     this.getWebContents()?.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
-      workspaceId: session.workspaceId,
+      workspaceId,
       conversations: index,
     } satisfies ConversationListChangedPayload)
   }
diff --git a/packages/main/src/chat/conversationStore.ts b/packages/main/src/chat/conversationStore.ts
index 1a873cb..c5d2844 100644
--- a/packages/main/src/chat/conversationStore.ts
+++ b/packages/main/src/chat/conversationStore.ts
@@ -124,7 +124,7 @@ export class ConversationStore {
   async ensure(conversationId: string, opts: ConversationCreateOpts): Promise<ConversationMeta> {
     return this.withIndexLock(async () => {
       const index = await this.loadIndex()
-      const existing = index.find(c => c.id === conversationId)
+      const existing = index.find((c) => c.id === conversationId)
       if (existing) return existing
 
       const now = Date.now()
@@ -150,7 +150,7 @@ export class ConversationStore {
   async delete(conversationId: string): Promise<void> {
     await this.withIndexLock(async () => {
       const index = await this.loadIndex()
-      const filtered = index.filter(c => c.id !== conversationId)
+      const filtered = index.filter((c) => c.id !== conversationId)
       await this.saveIndex(filtered)
     })
 
@@ -165,16 +165,28 @@ export class ConversationStore {
 
   async get(conversationId: string): Promise<ConversationMeta | null> {
     const index = await this.loadIndex()
-    return index.find(c => c.id === conversationId) ?? null
+    return index.find((c) => c.id === conversationId) ?? null
   }
 
   async updateMeta(
     conversationId: string,
-    patch: Partial<Pick<ConversationMeta, 'title' | 'autoTitled' | 'updatedAt' | 'messageCount' | 'firstMessage' | 'claudeSessionId' | 'worktreePath'>>,
+    patch: Partial<
+      Pick<
+        ConversationMeta,
+        | 'backend'
+        | 'title'
+        | 'autoTitled'
+        | 'updatedAt'
+        | 'messageCount'
+        | 'firstMessage'
+        | 'claudeSessionId'
+        | 'worktreePath'
+      >
+    >,
   ): Promise<void> {
     await this.withIndexLock(async () => {
       const index = await this.loadIndex()
-      const entry = index.find(c => c.id === conversationId)
+      const entry = index.find((c) => c.id === conversationId)
       if (!entry) return
 
       Object.assign(entry, patch)
@@ -190,9 +202,9 @@ export class ConversationStore {
     const index = await this.loadIndex()
     // Index is sorted newest-first
     if (backend) {
-      return index.find(c => c.workspaceId === workspaceId && c.backend === backend) ?? null
+      return index.find((c) => c.workspaceId === workspaceId && c.backend === backend) ?? null
     }
-    return index.find(c => c.workspaceId === workspaceId) ?? null
+    return index.find((c) => c.workspaceId === workspaceId) ?? null
   }
 
   // ─── Message Data ────────────────────────────
@@ -239,7 +251,7 @@ export class ConversationStore {
       }
 
       const messages = oldSession.messages ?? []
-      const firstUserMsg = messages.find(m => m.role === 'user')
+      const firstUserMsg = messages.find((m) => m.role === 'user')
 
       const meta: ConversationMeta = {
         id: oldSession.id,
diff --git a/packages/main/src/index.ts b/packages/main/src/index.ts
index 20f3caf..4ec9fac 100644
--- a/packages/main/src/index.ts
+++ b/packages/main/src/index.ts
@@ -38,8 +38,17 @@ import {
 } from './workspace/worktreeManager'
 import { startSearch, cancelSearch } from './search/ripgrepSearch'
 import { ensureAideFolder } from './workspace/aideInit'
-import { resolveAppDefaults, resolveSettings, BUILT_IN_DEFAULTS } from './workspace/settingsResolver'
-import { auditGitignore, appendToGitignore, isAuditDismissed, dismissAudit } from './git/gitignoreAudit'
+import {
+  resolveAppDefaults,
+  resolveSettings,
+  BUILT_IN_DEFAULTS,
+} from './workspace/settingsResolver'
+import {
+  auditGitignore,
+  appendToGitignore,
+  isAuditDismissed,
+  dismissAudit,
+} from './git/gitignoreAudit'
 import { TaskRunner } from './tasks/taskRunner'
 import { detectTasks, generateTasksFile, hasTasksFile } from './tasks/taskAutoDetect'
 import { WorkspaceRegistry } from './workspace/workspaceRegistry'
@@ -51,7 +60,12 @@ import {
   resolveRepoRootForWorkspace,
   resolveWorkspaceIdForIpc,
 } from './workspace/workspaceRootResolution'
-import { saveWorkspaceState, loadWorkspaceState, saveTerminalState, loadTerminalState } from './workspace/stateSerializer'
+import {
+  saveWorkspaceState,
+  loadWorkspaceState,
+  saveTerminalState,
+  loadTerminalState,
+} from './workspace/stateSerializer'
 import { BrowserPaneManager } from './browserPaneManager'
 import { registerGitDiffHandlers } from './git/gitDiff'
 import { AgentManager } from './chat/agentManager'
@@ -223,9 +237,7 @@ function createWindow(): void {
   if (process.env.ELECTRON_RENDERER_URL) {
     contentView.webContents.loadURL(process.env.ELECTRON_RENDERER_URL)
   } else {
-    contentView.webContents.loadFile(
-      join(__dirname, '../../renderer/dist/index.html'),
-    )
+    contentView.webContents.loadFile(join(__dirname, '../../renderer/dist/index.html'))
   }
 
   // Forward fullscreen state to renderer
@@ -268,7 +280,9 @@ ipcMain.handle(IpcChannels.SIDEBAR_WIDTH_SET, (_event, width: number) => {
   store.set('sidebarWidth', width)
 })
 
-ipcMain.handle(IpcChannels.BROWSER_ZOOM_GET, (_event, paneId: string) => browserPaneManager.getZoom(paneId))
+ipcMain.handle(IpcChannels.BROWSER_ZOOM_GET, (_event, paneId: string) =>
+  browserPaneManager.getZoom(paneId),
+)
 ipcMain.handle(IpcChannels.BROWSER_ZOOM_SET, (_event, paneId: string, zoomFactor: number) =>
   browserPaneManager.setZoom(paneId, zoomFactor),
 )
@@ -324,7 +338,9 @@ function getConversationStore(runtime: WorkspaceRuntime | null): ConversationSto
   return (runtime?.services.conversationStore as ConversationStore | null) ?? null
 }
 
-function getNativeSessionWatcher(runtime: WorkspaceRuntime | null): ClaudeNativeSessionWatcher | null {
+function getNativeSessionWatcher(
+  runtime: WorkspaceRuntime | null,
+): ClaudeNativeSessionWatcher | null {
   return (runtime?.services.nativeSessionWatcher as ClaudeNativeSessionWatcher | null) ?? null
 }
 
@@ -334,36 +350,39 @@ async function loadPreferredClaudeMessages(
   conversationId: string,
   storedData?: unknown,
 ): Promise<CliAgentMessage[]> {
-  const stored = storedData ?? await conversationStore?.loadMessages(conversationId)
+  const stored = storedData ?? (await conversationStore?.loadMessages(conversationId))
   const storedMessagesRaw =
-    stored && typeof stored === 'object'
-      ? (stored as { messages?: unknown }).messages
-      : undefined
-  const storedMessages = Array.isArray(storedMessagesRaw) ? (storedMessagesRaw as CliAgentMessage[]) : []
-  const storedComparable = storedMessages.filter((message) =>
-    message.type === 'user' ||
-    message.type === 'assistant' ||
-    message.type === 'tool_use' ||
-    message.type === 'tool_result'
+    stored && typeof stored === 'object' ? (stored as { messages?: unknown }).messages : undefined
+  const storedMessages = Array.isArray(storedMessagesRaw)
+    ? (storedMessagesRaw as CliAgentMessage[])
+    : []
+  const storedComparable = storedMessages.filter(
+    (message) =>
+      message.type === 'user' ||
+      message.type === 'assistant' ||
+      message.type === 'tool_use' ||
+      message.type === 'tool_result',
   ).length
 
   const meta = await conversationStore?.get(conversationId)
   const claudeSessionId =
     meta?.claudeSessionId ||
-    (
-      stored && typeof stored === 'object'
-        ? (stored as { claudeSessionId?: unknown }).claudeSessionId
-        : undefined
-    )
+    (stored && typeof stored === 'object'
+      ? ((stored as { claudeSessionId?: unknown }).claudeSessionId ??
+        (stored as { backendStates?: { 'claude-code'?: { sessionId?: unknown } } }).backendStates?.[
+          'claude-code'
+        ]?.sessionId)
+      : undefined)
 
   if (typeof claudeSessionId === 'string' && nativeSessionWatcher) {
     try {
       const nativeMessages = await nativeSessionWatcher.loadMessages(claudeSessionId)
-      const nativeComparable = nativeMessages.filter((message) =>
-        message.type === 'user' ||
-        message.type === 'assistant' ||
-        message.type === 'tool_use' ||
-        message.type === 'tool_result'
+      const nativeComparable = nativeMessages.filter(
+        (message) =>
+          message.type === 'user' ||
+          message.type === 'assistant' ||
+          message.type === 'tool_use' ||
+          message.type === 'tool_result',
       ).length
       if (nativeMessages.length > 0 && nativeComparable > storedComparable) {
         return nativeMessages
@@ -430,16 +449,20 @@ function loadLlmConfig(): LlmProviderConfig {
     apiKeyIsEnvRef: config.apiKey.includes('${env:'),
     baseUrl: config.baseUrl || '(default)',
     storeHasEditorDefaults: !!userDefaults,
-    storeKeys: Object.keys(userDefaults).filter(k => k.startsWith('agent.')),
+    storeKeys: Object.keys(userDefaults).filter((k) => k.startsWith('agent.')),
   })
   return config
 }
 
-function loadPermissionConfig(): { permissionTier: PermissionTier; autoApprove: Record<string, boolean | ToolPermissionConfig> } {
+function loadPermissionConfig(): {
+  permissionTier: PermissionTier
+  autoApprove: Record<string, boolean | ToolPermissionConfig>
+} {
   const userDefaults = (store.get('editorDefaults') ?? {}) as Record<string, unknown>
   return {
     permissionTier: (userDefaults['agent.permissionTier'] as PermissionTier) || 'confirm',
-    autoApprove: (userDefaults['agent.autoApprove'] as Record<string, boolean | ToolPermissionConfig>) || {},
+    autoApprove:
+      (userDefaults['agent.autoApprove'] as Record<string, boolean | ToolPermissionConfig>) || {},
   }
 }
 
@@ -469,21 +492,24 @@ async function startRuntimeServices(runtime: WorkspaceRuntime): Promise<void> {
       nativeSessionCache = sessions
       runtime.setServices({ nativeSessionCache })
       runtime.refreshWorkload()
-      void conversationStore.loadIndex().then((index) => {
-        const seen = new Set(index.map(c => c.id))
-        const uniqueSessions = sessions.filter(s => !seen.has(s.id))
-        contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
-          workspaceId: runtime.workspaceId,
-          conversations: [...index, ...uniqueSessions],
-          source: 'claude-native',
+      void conversationStore
+        .loadIndex()
+        .then((index) => {
+          const seen = new Set(index.map((c) => c.id))
+          const uniqueSessions = sessions.filter((s) => !seen.has(s.id))
+          contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
+            workspaceId: runtime.workspaceId,
+            conversations: [...index, ...uniqueSessions],
+            source: 'claude-native',
+          })
         })
-      }).catch(() => {
-        contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
-          workspaceId: runtime.workspaceId,
-          conversations: sessions,
-          source: 'claude-native',
+        .catch(() => {
+          contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
+            workspaceId: runtime.workspaceId,
+            conversations: sessions,
+            source: 'claude-native',
+          })
         })
-      })
     },
   })
   await nativeSessionWatcher.start()
@@ -511,9 +537,11 @@ async function startRuntimeServices(runtime: WorkspaceRuntime): Promise<void> {
     workspaceRoot: rootPath,
     getWebContents: () => contentView?.webContents ?? null,
     claudeCodePath: resolved['agent.claudeCodePath'],
+    opencodePath: resolved['agent.opencodePath'],
     codexPath: resolved['agent.codexPath'],
     conversationStore,
-    loadClaudeHistory: async (claudeSessionId: string) => nativeSessionWatcher.loadMessages(claudeSessionId),
+    loadClaudeHistory: async (claudeSessionId: string) =>
+      nativeSessionWatcher.loadMessages(claudeSessionId),
   })
 
   runtime.setServices({
@@ -659,15 +687,18 @@ ipcMain.handle(IpcChannels.WORKSPACE_SWITCH, async (_event, id: string) => {
   await activateWorkspace(id)
 })
 
-ipcMain.handle(IpcChannels.WORKSPACE_UPDATE, (_event, id: string, patch: Partial<{ name: string; icon: string; color: string }>) => {
-  workspaceRegistry.update(id, patch)
-  const entry = workspaceRegistry.get(id)
-  if (entry) {
-    runtimeRegistry.get(id)?.syncEntry(entry)
-  }
-  broadcastWorkspaceRegistry()
-  broadcastRuntimeSnapshots()
-})
+ipcMain.handle(
+  IpcChannels.WORKSPACE_UPDATE,
+  (_event, id: string, patch: Partial<{ name: string; icon: string; color: string }>) => {
+    workspaceRegistry.update(id, patch)
+    const entry = workspaceRegistry.get(id)
+    if (entry) {
+      runtimeRegistry.get(id)?.syncEntry(entry)
+    }
+    broadcastWorkspaceRegistry()
+    broadcastRuntimeSnapshots()
+  },
+)
 
 ipcMain.handle(IpcChannels.WORKSPACE_REORDER, (_event, ids: string[]) => {
   workspaceRegistry.reorder(ids)
@@ -685,20 +716,26 @@ ipcMain.handle(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_GET, () => {
 
 // ─── Chat / Agent IPC handlers ─────────────────────────────────────
 
-ipcMain.handle(IpcChannels.CHAT_SEND_MESSAGE, async (_event, sessionId: string, content: string) => {
-  const runtime = findRuntimeWithBuiltInSession(sessionId)
-  const agentManager = getAgentManager(runtime)
-  if (!agentManager) return { error: 'No workspace open' }
-  const result = await agentManager.sendMessage(sessionId, content)
-  runtime?.refreshWorkload()
-  return result
-})
+ipcMain.handle(
+  IpcChannels.CHAT_SEND_MESSAGE,
+  async (_event, sessionId: string, content: string) => {
+    const runtime = findRuntimeWithBuiltInSession(sessionId)
+    const agentManager = getAgentManager(runtime)
+    if (!agentManager) return { error: 'No workspace open' }
+    const result = await agentManager.sendMessage(sessionId, content)
+    runtime?.refreshWorkload()
+    return result
+  },
+)
 
-ipcMain.handle(IpcChannels.CHAT_GET_HISTORY, async (_event, workspaceId: string, conversationId?: string) => {
-  const agentManager = getAgentManager(runtimeRegistry.get(workspaceId))
-  if (!agentManager) return null
-  return agentManager.getHistory(workspaceId, conversationId)
-})
+ipcMain.handle(
+  IpcChannels.CHAT_GET_HISTORY,
+  async (_event, workspaceId: string, conversationId?: string) => {
+    const agentManager = getAgentManager(runtimeRegistry.get(workspaceId))
+    if (!agentManager) return null
+    return agentManager.getHistory(workspaceId, conversationId)
+  },
+)
 
 ipcMain.handle(IpcChannels.CHAT_PENDING_TOOL_APPROVALS_LIST, (): PendingToolApprovalInfo[] => {
   const out: PendingToolApprovalInfo[] = []
@@ -716,25 +753,34 @@ ipcMain.handle(IpcChannels.CHAT_SET_MODE, async (_event, sessionId: string, mode
   agentManager?.setMode(sessionId, mode)
 })
 
-ipcMain.handle(IpcChannels.CHAT_SET_WORKING_SET, async (_event, sessionId: string, paths: string[]) => {
-  const runtime = findRuntimeWithBuiltInSession(sessionId)
-  const agentManager = getAgentManager(runtime)
-  agentManager?.setWorkingSet(sessionId, paths)
-})
+ipcMain.handle(
+  IpcChannels.CHAT_SET_WORKING_SET,
+  async (_event, sessionId: string, paths: string[]) => {
+    const runtime = findRuntimeWithBuiltInSession(sessionId)
+    const agentManager = getAgentManager(runtime)
+    agentManager?.setWorkingSet(sessionId, paths)
+  },
+)
 
-ipcMain.handle(IpcChannels.CHAT_TOOL_APPROVE, async (_event, sessionId: string, toolCallId: string) => {
-  const runtime = findRuntimeWithBuiltInSession(sessionId)
-  const agentManager = getAgentManager(runtime)
-  agentManager?.approveToolCall(sessionId, toolCallId)
-  runtime?.refreshWorkload()
-})
+ipcMain.handle(
+  IpcChannels.CHAT_TOOL_APPROVE,
+  async (_event, sessionId: string, toolCallId: string) => {
+    const runtime = findRuntimeWithBuiltInSession(sessionId)
+    const agentManager = getAgentManager(runtime)
+    agentManager?.approveToolCall(sessionId, toolCallId)
+    runtime?.refreshWorkload()
+  },
+)
 
-ipcMain.handle(IpcChannels.CHAT_TOOL_REJECT, async (_event, sessionId: string, toolCallId: string) => {
-  const runtime = findRuntimeWithBuiltInSession(sessionId)
-  const agentManager = getAgentManager(runtime)
-  agentManager?.rejectToolCall(sessionId, toolCallId)
-  runtime?.refreshWorkload()
-})
+ipcMain.handle(
+  IpcChannels.CHAT_TOOL_REJECT,
+  async (_event, sessionId: string, toolCallId: string) => {
+    const runtime = findRuntimeWithBuiltInSession(sessionId)
+    const agentManager = getAgentManager(runtime)
+    agentManager?.rejectToolCall(sessionId, toolCallId)
+    runtime?.refreshWorkload()
+  },
+)
 
 ipcMain.on(IpcChannels.CHAT_STOP, (_event, sessionId: string) => {
   const runtime = findRuntimeWithBuiltInSession(sessionId)
@@ -745,14 +791,35 @@ ipcMain.on(IpcChannels.CHAT_STOP, (_event, sessionId: string) => {
 
 // ─── CLI Agent IPC handlers ─────────────────────────────────────
 
-ipcMain.handle(IpcChannels.CLI_AGENT_START, async (_event, workspaceId: string, backend: AgentBackend, conversationId?: string, worktreePath?: string) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const cliAgentManager = getCliAgentManager(runtime)
-  if (!cliAgentManager) return { error: 'No workspace open' }
-  const result = await cliAgentManager.start(workspaceId, backend, conversationId, worktreePath)
-  runtime?.refreshWorkload()
-  return result
-})
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_START,
+  async (
+    _event,
+    workspaceId: string,
+    backend: AgentBackend,
+    conversationId?: string,
+    worktreePath?: string,
+  ) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const cliAgentManager = getCliAgentManager(runtime)
+    if (!cliAgentManager) return { error: 'No workspace open' }
+    const result = await cliAgentManager.start(workspaceId, backend, conversationId, worktreePath)
+    runtime?.refreshWorkload()
+    return result
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_SWITCH_BACKEND,
+  async (_event, sessionId: string, backend: AgentBackend) => {
+    const runtime = findRuntimeWithCliSession(sessionId)
+    const cliAgentManager = getCliAgentManager(runtime)
+    if (!cliAgentManager) return { error: 'No workspace open' }
+    const result = await cliAgentManager.switchBackend(sessionId, backend)
+    runtime?.refreshWorkload()
+    return result
+  },
+)
 
 ipcMain.handle(IpcChannels.CLI_AGENT_SEND, async (_event, sessionId: string, content: string) => {
   const runtime = findRuntimeWithCliSession(sessionId)
@@ -763,16 +830,19 @@ ipcMain.handle(IpcChannels.CLI_AGENT_SEND, async (_event, sessionId: string, con
   return result
 })
 
-ipcMain.handle(IpcChannels.CLI_AGENT_GET_SESSION, async (_event, workspaceId: string, sessionId?: string) => {
-  const cliAgentManager = getCliAgentManager(runtimeRegistry.get(workspaceId))
-  if (!cliAgentManager) return null
-  if (sessionId) {
-    const s = cliAgentManager.getSessionById(sessionId)
-    if (!s || s.workspaceId !== workspaceId) return null
-    return s
-  }
-  return cliAgentManager.getSession(workspaceId) ?? null
-})
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_GET_SESSION,
+  async (_event, workspaceId: string, sessionId?: string) => {
+    const cliAgentManager = getCliAgentManager(runtimeRegistry.get(workspaceId))
+    if (!cliAgentManager) return null
+    if (sessionId) {
+      const s = cliAgentManager.getSessionById(sessionId)
+      if (!s || s.workspaceId !== workspaceId) return null
+      return s
+    }
+    return cliAgentManager.getSession(workspaceId) ?? null
+  },
+)
 
 ipcMain.handle(
   IpcChannels.CLI_AGENT_LOAD_MESSAGES,
@@ -784,15 +854,17 @@ ipcMain.handle(
     const nativeMeta =
       nativeSessionCache.find((c) => c.id === conversationId) ??
       nativeSessionCache.find((c) => c.claudeSessionId === conversationId)
-    if (nativeMeta?.source === 'claude-native' && nativeMeta.claudeSessionId && nativeSessionWatcher) {
+    if (
+      nativeMeta?.source === 'claude-native' &&
+      nativeMeta.claudeSessionId &&
+      nativeSessionWatcher
+    ) {
       return nativeSessionWatcher.loadMessages(nativeMeta.claudeSessionId)
     }
     const nativePrefix = 'claude-native:'
     if (conversationId.startsWith(nativePrefix) && nativeSessionWatcher) {
       const rawId = conversationId.slice(nativePrefix.length)
-      if (
-        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(rawId)
-      ) {
+      if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(rawId)) {
         return nativeSessionWatcher.loadMessages(rawId)
       }
     }
@@ -813,7 +885,7 @@ ipcMain.handle(IpcChannels.CONVERSATION_LIST, async (_event, workspaceId: string
   const runtime = runtimeRegistry.get(workspaceId)
   const conversationStore = getConversationStore(runtime)
   const nativeSessionCache = getNativeSessionCache(runtime)
-  const aideConvos = await conversationStore?.loadIndex() ?? []
+  const aideConvos = (await conversationStore?.loadIndex()) ?? []
   return [...aideConvos, ...nativeSessionCache]
 })
 
@@ -831,74 +903,101 @@ ipcMain.handle(IpcChannels.CONVERSATION_CREATE, async (_event, opts: Conversatio
   return meta
 })
 
-ipcMain.handle(IpcChannels.CONVERSATION_DELETE, async (_event, workspaceId: string, conversationId: string) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const conversationStore = getConversationStore(runtime)
-  const agentManager = getAgentManager(runtime)
-  const cliAgentManager = getCliAgentManager(runtime)
-  if (!conversationStore) return
-  const meta = await conversationStore.get(conversationId)
-  if (meta && meta.workspaceId !== workspaceId) return
-  await conversationStore.delete(conversationId)
-  agentManager?.stop(conversationId)
-  cliAgentManager?.stop(conversationId)
-  const nativeSessionCache = getNativeSessionCache(runtime)
-  if (meta) {
-    const index = await conversationStore.loadIndex()
-    contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
-      workspaceId,
-      conversations: [...index, ...nativeSessionCache],
-    })
-  }
-})
-
-ipcMain.handle(IpcChannels.CONVERSATION_RENAME, async (_event, workspaceId: string, conversationId: string, title: string) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const conversationStore = getConversationStore(runtime)
-  if (!conversationStore) return
-  const existing = await conversationStore.get(conversationId)
-  if (!existing || existing.workspaceId !== workspaceId) return
-  await conversationStore.updateMeta(conversationId, { title, autoTitled: false, updatedAt: Date.now() })
-  const meta = await conversationStore.get(conversationId)
-  if (meta) {
-    const index = await conversationStore.loadIndex()
+ipcMain.handle(
+  IpcChannels.CONVERSATION_DELETE,
+  async (_event, workspaceId: string, conversationId: string) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const conversationStore = getConversationStore(runtime)
+    const agentManager = getAgentManager(runtime)
+    const cliAgentManager = getCliAgentManager(runtime)
+    if (!conversationStore) return
+    const meta = await conversationStore.get(conversationId)
+    if (meta && meta.workspaceId !== workspaceId) return
+    await conversationStore.delete(conversationId)
+    agentManager?.stop(conversationId)
+    cliAgentManager?.stop(conversationId)
     const nativeSessionCache = getNativeSessionCache(runtime)
-    contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
-      workspaceId,
-      conversations: [...index, ...nativeSessionCache],
+    if (meta) {
+      const index = await conversationStore.loadIndex()
+      contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
+        workspaceId,
+        conversations: [...index, ...nativeSessionCache],
+      })
+    }
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CONVERSATION_RENAME,
+  async (_event, workspaceId: string, conversationId: string, title: string) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const conversationStore = getConversationStore(runtime)
+    if (!conversationStore) return
+    const existing = await conversationStore.get(conversationId)
+    if (!existing || existing.workspaceId !== workspaceId) return
+    await conversationStore.updateMeta(conversationId, {
+      title,
+      autoTitled: false,
+      updatedAt: Date.now(),
     })
-  }
-})
+    const meta = await conversationStore.get(conversationId)
+    if (meta) {
+      const index = await conversationStore.loadIndex()
+      const nativeSessionCache = getNativeSessionCache(runtime)
+      contentView?.webContents.send(IpcChannels.CONVERSATION_LIST_CHANGED, {
+        workspaceId,
+        conversations: [...index, ...nativeSessionCache],
+      })
+    }
+  },
+)
 
-ipcMain.handle(IpcChannels.CONVERSATION_GET, async (_event, workspaceId: string, conversationId: string) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const conversationStore = getConversationStore(runtime)
-  const meta = await conversationStore?.get(conversationId)
-  if (meta && meta.workspaceId !== workspaceId) return null
-  return meta ?? null
-})
+ipcMain.handle(
+  IpcChannels.CONVERSATION_GET,
+  async (_event, workspaceId: string, conversationId: string) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const conversationStore = getConversationStore(runtime)
+    const meta = await conversationStore?.get(conversationId)
+    if (meta && meta.workspaceId !== workspaceId) return null
+    return meta ?? null
+  },
+)
 
 // State persistence IPC handlers
-ipcMain.handle(IpcChannels.STATE_SAVE, async (_event, rootPath: string, state: import('@aide/shared').AideLocalState) => {
-  await saveWorkspaceState(rootPath, state)
-})
+ipcMain.handle(
+  IpcChannels.STATE_SAVE,
+  async (_event, rootPath: string, state: import('@aide/shared').AideLocalState) => {
+    await saveWorkspaceState(rootPath, state)
+  },
+)
 
 ipcMain.handle(IpcChannels.STATE_LOAD, async (_event, rootPath: string) => {
   return loadWorkspaceState(rootPath)
 })
 
-ipcMain.handle(IpcChannels.STATE_SAVE_TERMINALS, async (_event, rootPath: string, state: import('@aide/shared').AideLocalTerminals) => {
-  await saveTerminalState(rootPath, state)
-})
+ipcMain.handle(
+  IpcChannels.STATE_SAVE_TERMINALS,
+  async (_event, rootPath: string, state: import('@aide/shared').AideLocalTerminals) => {
+    await saveTerminalState(rootPath, state)
+  },
+)
 
 ipcMain.handle(IpcChannels.STATE_LOAD_TERMINALS, async (_event, rootPath: string) => {
   return loadTerminalState(rootPath)
 })
 
 // Browser pane IPC handlers
-ipcMain.handle(IpcChannels.BROWSER_CREATE, (_event, paneId: string, workspaceId: string, sessionMode: import('@aide/shared').BrowserSessionMode) => {
-  return browserPaneManager.create(paneId, workspaceId, sessionMode)
-})
+ipcMain.handle(
+  IpcChannels.BROWSER_CREATE,
+  (
+    _event,
+    paneId: string,
+    workspaceId: string,
+    sessionMode: import('@aide/shared').BrowserSessionMode,
+  ) => {
+    return browserPaneManager.create(paneId, workspaceId, sessionMode)
+  },
+)
 
 ipcMain.on(IpcChannels.BROWSER_DESTROY, (_event, paneId: string) => {
   browserPaneManager.destroy(paneId)
@@ -924,9 +1023,12 @@ ipcMain.on(IpcChannels.BROWSER_RELOAD, (_event, paneId: string) => {
   browserPaneManager.reload(paneId)
 })
 
-ipcMain.on(IpcChannels.BROWSER_HOST_UPDATE, (_event, update: import('@aide/shared').BrowserHostUpdate) => {
-  browserPaneManager.handleHostUpdate(update)
-})
+ipcMain.on(
+  IpcChannels.BROWSER_HOST_UPDATE,
+  (_event, update: import('@aide/shared').BrowserHostUpdate) => {
+    browserPaneManager.handleHostUpdate(update)
+  },
+)
 
 ipcMain.on(IpcChannels.BROWSER_SUPPRESS_OVERLAYS, () => {
   browserPaneManager.suppressOverlays()
@@ -966,11 +1068,14 @@ ipcMain.handle(IpcChannels.AIDE_INIT, async (_event, workspaceId?: string | null
 })
 
 // .aide settings IPC handler
-ipcMain.handle(IpcChannels.AIDE_GET_RESOLVED_SETTINGS, async (_event, workspaceId?: string | null) => {
-  const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
-  if (!rootPath) return resolveAppDefaults(store)
-  return resolveSettings(rootPath, store)
-})
+ipcMain.handle(
+  IpcChannels.AIDE_GET_RESOLVED_SETTINGS,
+  async (_event, workspaceId?: string | null) => {
+    const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
+    if (!rootPath) return resolveAppDefaults(store)
+    return resolveSettings(rootPath, store)
+  },
+)
 
 // Settings IPC handlers
 ipcMain.handle(IpcChannels.SETTINGS_GET_DEFAULTS, () => BUILT_IN_DEFAULTS)
@@ -982,9 +1087,7 @@ ipcMain.handle(IpcChannels.SETTINGS_GET_USER, () => {
 ipcMain.handle(IpcChannels.SETTINGS_SET_USER, async (_event, key: string, value: unknown) => {
   let current = (store.get('editorDefaults') ?? {}) as Record<string, unknown>
   if (value === undefined || value === null) {
-    current = Object.fromEntries(
-      Object.entries(current).filter(([entryKey]) => entryKey !== key),
-    )
+    current = Object.fromEntries(Object.entries(current).filter(([entryKey]) => entryKey !== key))
   } else {
     current[key] = value
   }
@@ -1002,18 +1105,20 @@ ipcMain.handle(IpcChannels.SETTINGS_SET_USER, async (_event, key: string, value:
   }
 
   // Push CLI agent path updates
-  if (key === 'agent.claudeCodePath' || key === 'agent.codexPath') {
+  if (key === 'agent.claudeCodePath' || key === 'agent.opencodePath' || key === 'agent.codexPath') {
     const appDefs = resolveAppDefaults(store)
     for (const runtime of runtimeRegistry.list()) {
-      getCliAgentManager(runtime)?.updatePaths(appDefs['agent.claudeCodePath'], appDefs['agent.codexPath'])
+      getCliAgentManager(runtime)?.updatePaths(
+        appDefs['agent.claudeCodePath'],
+        appDefs['agent.opencodePath'],
+        appDefs['agent.codexPath'],
+      )
     }
   }
 
   // Phase 8: only allowlisted implicit-active use — merged project settings for the focused workspace
   const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, undefined)
-  const resolved = rootPath
-    ? await resolveSettings(rootPath, store)
-    : resolveAppDefaults(store)
+  const resolved = rootPath ? await resolveSettings(rootPath, store) : resolveAppDefaults(store)
   contentView?.webContents.send(IpcChannels.SETTINGS_CHANGED, resolved)
 })
 
@@ -1030,51 +1135,57 @@ ipcMain.handle(IpcChannels.SETTINGS_GET_WORKSPACE, async (_event, workspaceId?:
   }
 })
 
-ipcMain.handle(IpcChannels.SETTINGS_SET_WORKSPACE, async (_event, key: string, value: unknown, workspaceId?: string | null) => {
-  // Block sensitive agent keys from being written to project-level settings
-  if (SENSITIVE_AGENT_KEYS.has(key)) return
-
-  const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
-  if (!rootPath) return
-
-  const settingsPath = join(rootPath, '.aide', 'settings.json')
-
-  // Ensure .aide directory exists
-  const aideDir = join(rootPath, '.aide')
-  if (!existsSync(aideDir)) await mkdir(aideDir, { recursive: true })
-
-  // Read existing settings
-  let current: Record<string, unknown> = {}
-  if (existsSync(settingsPath)) {
-    try {
-      const raw = await readFile(settingsPath, 'utf-8')
-      current = JSON.parse(raw)
-    } catch {
-      current = {}
+ipcMain.handle(
+  IpcChannels.SETTINGS_SET_WORKSPACE,
+  async (_event, key: string, value: unknown, workspaceId?: string | null) => {
+    // Block sensitive agent keys from being written to project-level settings
+    if (SENSITIVE_AGENT_KEYS.has(key)) return
+
+    const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
+    if (!rootPath) return
+
+    const settingsPath = join(rootPath, '.aide', 'settings.json')
+
+    // Ensure .aide directory exists
+    const aideDir = join(rootPath, '.aide')
+    if (!existsSync(aideDir)) await mkdir(aideDir, { recursive: true })
+
+    // Read existing settings
+    let current: Record<string, unknown> = {}
+    if (existsSync(settingsPath)) {
+      try {
+        const raw = await readFile(settingsPath, 'utf-8')
+        current = JSON.parse(raw)
+      } catch {
+        current = {}
+      }
     }
-  }
 
-  if (value === undefined || value === null) {
-    current = Object.fromEntries(
-      Object.entries(current).filter(([entryKey]) => entryKey !== key),
-    )
-  } else {
-    current[key] = value
-  }
+    if (value === undefined || value === null) {
+      current = Object.fromEntries(Object.entries(current).filter(([entryKey]) => entryKey !== key))
+    } else {
+      current[key] = value
+    }
 
-  await fsWriteFile(settingsPath, JSON.stringify(current, null, 2) + '\n', 'utf-8')
+    await fsWriteFile(settingsPath, JSON.stringify(current, null, 2) + '\n', 'utf-8')
 
-  // Broadcast resolved settings
-  const resolved = await resolveSettings(rootPath, store)
-  contentView?.webContents.send(IpcChannels.SETTINGS_CHANGED, resolved)
-})
+    // Broadcast resolved settings
+    const resolved = await resolveSettings(rootPath, store)
+    contentView?.webContents.send(IpcChannels.SETTINGS_CHANGED, resolved)
+  },
+)
 
 // Keybinding overrides IPC handlers
 // Migrate old Record<commandId, keybinding> format to KeybindingRule[] on first read
-function migrateKeybindingOverrides(stored: unknown): { key: string; command: string; when?: string }[] {
+function migrateKeybindingOverrides(
+  stored: unknown,
+): { key: string; command: string; when?: string }[] {
   if (Array.isArray(stored)) return stored
   if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
-    const migrated = Object.entries(stored as Record<string, string>).map(([command, key]) => ({ key, command }))
+    const migrated = Object.entries(stored as Record<string, string>).map(([command, key]) => ({
+      key,
+      command,
+    }))
     store.set('keybindingOverrides', migrated)
     return migrated
   }
@@ -1085,10 +1196,13 @@ ipcMain.handle(IpcChannels.KEYBINDINGS_GET, () => {
   return migrateKeybindingOverrides(store.get('keybindingOverrides'))
 })
 
-ipcMain.handle(IpcChannels.KEYBINDINGS_SET, async (_event, rules: { key: string; command: string; when?: string }[]) => {
-  store.set('keybindingOverrides', rules)
-  contentView?.webContents.send(IpcChannels.KEYBINDINGS_CHANGED, rules)
-})
+ipcMain.handle(
+  IpcChannels.KEYBINDINGS_SET,
+  async (_event, rules: { key: string; command: string; when?: string }[]) => {
+    store.set('keybindingOverrides', rules)
+    contentView?.webContents.send(IpcChannels.KEYBINDINGS_CHANGED, rules)
+  },
+)
 
 // Gitignore security audit IPC handlers
 ipcMain.handle(IpcChannels.GITIGNORE_AUDIT, async (_event, workspaceId?: string | null) => {
@@ -1097,11 +1211,14 @@ ipcMain.handle(IpcChannels.GITIGNORE_AUDIT, async (_event, workspaceId?: string
   return auditGitignore(rootPath)
 })
 
-ipcMain.handle(IpcChannels.GITIGNORE_APPEND, async (_event, patterns: string[], workspaceId?: string | null) => {
-  const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
-  if (!rootPath) return
-  await appendToGitignore(rootPath, patterns)
-})
+ipcMain.handle(
+  IpcChannels.GITIGNORE_APPEND,
+  async (_event, patterns: string[], workspaceId?: string | null) => {
+    const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
+    if (!rootPath) return
+    await appendToGitignore(rootPath, patterns)
+  },
+)
 
 ipcMain.handle(IpcChannels.GITIGNORE_DISMISS, async (_event, workspaceId?: string | null) => {
   const rootPath = resolveRepoRootForWorkspace(workspaceRegistry, workspaceId)
@@ -1226,25 +1343,28 @@ ipcMain.handle(IpcChannels.TASK_LIST_RUNNING, async (_event, workspaceId: string
   return taskRunner?.getRunning() ?? []
 })
 
-ipcMain.handle(IpcChannels.TASK_RUN, async (_event, workspaceId: string, taskId: string, context?: TaskRunContext) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const taskRunner = getTaskRunner(runtime)
-  if (!taskRunner) return { error: 'No workspace open' }
-  const rootPath = runtime?.rootPath ?? null
-  if (!rootPath) return { error: 'No workspace open' }
-
-  const eff = getEffectiveWorkspaceRoot(workspaceId, rootPath) ?? rootPath
-  const ctx = {
-    workspaceRoot: eff,
-    workspaceName: eff.split('/').pop() ?? eff,
-    activeFile: context?.activeFile,
-    selectedText: context?.selectedText,
-    lineNumber: context?.lineNumber,
-  }
-  const result = await taskRunner.run(taskId, ctx)
-  runtime?.refreshWorkload()
-  return result
-})
+ipcMain.handle(
+  IpcChannels.TASK_RUN,
+  async (_event, workspaceId: string, taskId: string, context?: TaskRunContext) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const taskRunner = getTaskRunner(runtime)
+    if (!taskRunner) return { error: 'No workspace open' }
+    const rootPath = runtime?.rootPath ?? null
+    if (!rootPath) return { error: 'No workspace open' }
+
+    const eff = getEffectiveWorkspaceRoot(workspaceId, rootPath) ?? rootPath
+    const ctx = {
+      workspaceRoot: eff,
+      workspaceName: eff.split('/').pop() ?? eff,
+      activeFile: context?.activeFile,
+      selectedText: context?.selectedText,
+      lineNumber: context?.lineNumber,
+    }
+    const result = await taskRunner.run(taskId, ctx)
+    runtime?.refreshWorkload()
+    return result
+  },
+)
 
 ipcMain.on(IpcChannels.TASK_KILL, (_event, workspaceId: string, executionId: string) => {
   const runtime = runtimeRegistry.get(workspaceId)
@@ -1258,12 +1378,15 @@ ipcMain.handle(IpcChannels.TASK_RELOAD, async (_event, workspaceId: string) => {
   await taskRunner?.loadTasks()
 })
 
-ipcMain.on(IpcChannels.TASK_PROVIDE_INPUT, (_event, workspaceId: string, requestId: string, value: string | null) => {
-  const runtime = runtimeRegistry.get(workspaceId)
-  const taskRunner = getTaskRunner(runtime)
-  taskRunner?.provideInput(requestId, value)
-  runtime?.refreshWorkload()
-})
+ipcMain.on(
+  IpcChannels.TASK_PROVIDE_INPUT,
+  (_event, workspaceId: string, requestId: string, value: string | null) => {
+    const runtime = runtimeRegistry.get(workspaceId)
+    const taskRunner = getTaskRunner(runtime)
+    taskRunner?.provideInput(requestId, value)
+    runtime?.refreshWorkload()
+  },
+)
 
 ipcMain.handle(IpcChannels.TASK_GENERATE, async (_event, workspaceId: string) => {
   const entry = workspaceRegistry.get(workspaceId)
@@ -1324,120 +1447,152 @@ ipcMain.on(IpcChannels.TASK_FILE_SAVED, (_event, filePath: string) => {
 // Filesystem IPC handlers
 const HIDDEN_FILES = new Set(['.DS_Store', 'Thumbs.db'])
 
-ipcMain.handle(IpcChannels.FS_READ_DIR, async (_event, dirPath: string): Promise<DirEntry[] | { error: string }> => {
-  try {
-    const entries = await readdir(dirPath, { withFileTypes: true })
-    const mapped: DirEntry[] = entries
-      .filter((e) => !HIDDEN_FILES.has(e.name))
-      .map((e) => ({
-        name: e.name,
-        path: join(dirPath, e.name),
-        isDirectory: e.isDirectory(),
-      }))
-    // Sort: directories first, then alphabetical (case-insensitive)
-    mapped.sort((a, b) => {
-      if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1
-      return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
-    })
-    return mapped
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error reading directory'
-    return { error: message }
-  }
-})
+ipcMain.handle(
+  IpcChannels.FS_READ_DIR,
+  async (_event, dirPath: string): Promise<DirEntry[] | { error: string }> => {
+    try {
+      const entries = await readdir(dirPath, { withFileTypes: true })
+      const mapped: DirEntry[] = entries
+        .filter((e) => !HIDDEN_FILES.has(e.name))
+        .map((e) => ({
+          name: e.name,
+          path: join(dirPath, e.name),
+          isDirectory: e.isDirectory(),
+        }))
+      // Sort: directories first, then alphabetical (case-insensitive)
+      mapped.sort((a, b) => {
+        if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1
+        return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
+      })
+      return mapped
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error reading directory'
+      return { error: message }
+    }
+  },
+)
 
 // Read file IPC handler — enforces 10 MB limit, rejects binary files
 const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10 MB
 
-ipcMain.handle(IpcChannels.FS_READ_FILE, async (_event, filePath: string): Promise<{ content: string } | { error: string }> => {
-  try {
-    const info = await stat(filePath)
-    if (!info.isFile()) return { error: 'Not a file' }
-    if (info.size > MAX_FILE_SIZE) return { error: `File too large (${(info.size / 1024 / 1024).toFixed(1)} MB). Maximum is 10 MB.` }
+ipcMain.handle(
+  IpcChannels.FS_READ_FILE,
+  async (_event, filePath: string): Promise<{ content: string } | { error: string }> => {
+    try {
+      const info = await stat(filePath)
+      if (!info.isFile()) return { error: 'Not a file' }
+      if (info.size > MAX_FILE_SIZE)
+        return {
+          error: `File too large (${(info.size / 1024 / 1024).toFixed(1)} MB). Maximum is 10 MB.`,
+        }
 
-    const content = await readFile(filePath, 'utf-8')
+      const content = await readFile(filePath, 'utf-8')
 
-    // Check for binary content (null bytes in first 8 KB)
-    const sample = content.slice(0, 8192)
-    if (sample.includes('\0')) return { error: 'Binary file — cannot display' }
+      // Check for binary content (null bytes in first 8 KB)
+      const sample = content.slice(0, 8192)
+      if (sample.includes('\0')) return { error: 'Binary file — cannot display' }
 
-    return { content }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error reading file'
-    return { error: message }
-  }
-})
+      return { content }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error reading file'
+      return { error: message }
+    }
+  },
+)
 
 // Write file IPC handler
-ipcMain.handle(IpcChannels.FS_WRITE_FILE, async (_event, filePath: string, content: string): Promise<{ success: true } | { error: string }> => {
-  try {
-    await fsWriteFile(filePath, content, 'utf-8')
-    return { success: true }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error writing file'
-    return { error: message }
-  }
-})
+ipcMain.handle(
+  IpcChannels.FS_WRITE_FILE,
+  async (
+    _event,
+    filePath: string,
+    content: string,
+  ): Promise<{ success: true } | { error: string }> => {
+    try {
+      await fsWriteFile(filePath, content, 'utf-8')
+      return { success: true }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error writing file'
+      return { error: message }
+    }
+  },
+)
 
 // Create file IPC handler
-ipcMain.handle(IpcChannels.FS_CREATE_FILE, async (_event, filePath: string): Promise<{ success: true } | { error: string }> => {
-  try {
-    // Check if already exists
+ipcMain.handle(
+  IpcChannels.FS_CREATE_FILE,
+  async (_event, filePath: string): Promise<{ success: true } | { error: string }> => {
     try {
-      await stat(filePath)
-      return { error: 'File already exists' }
-    } catch {
-      // Expected — file doesn't exist yet
+      // Check if already exists
+      try {
+        await stat(filePath)
+        return { error: 'File already exists' }
+      } catch {
+        // Expected — file doesn't exist yet
+      }
+      // Ensure parent directory exists
+      await mkdir(dirname(filePath), { recursive: true })
+      await fsWriteFile(filePath, '', 'utf-8')
+      return { success: true }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error creating file'
+      return { error: message }
     }
-    // Ensure parent directory exists
-    await mkdir(dirname(filePath), { recursive: true })
-    await fsWriteFile(filePath, '', 'utf-8')
-    return { success: true }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error creating file'
-    return { error: message }
-  }
-})
+  },
+)
 
 // Create directory IPC handler
-ipcMain.handle(IpcChannels.FS_CREATE_DIR, async (_event, dirPath: string): Promise<{ success: true } | { error: string }> => {
-  try {
-    await mkdir(dirPath)
-    return { success: true }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error creating directory'
-    return { error: message }
-  }
-})
+ipcMain.handle(
+  IpcChannels.FS_CREATE_DIR,
+  async (_event, dirPath: string): Promise<{ success: true } | { error: string }> => {
+    try {
+      await mkdir(dirPath)
+      return { success: true }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error creating directory'
+      return { error: message }
+    }
+  },
+)
 
 // Delete file or directory IPC handler
-ipcMain.handle(IpcChannels.FS_DELETE, async (_event, entryPath: string): Promise<{ success: true } | { error: string }> => {
-  try {
-    await rm(entryPath, { recursive: true })
-    return { success: true }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error deleting'
-    return { error: message }
-  }
-})
+ipcMain.handle(
+  IpcChannels.FS_DELETE,
+  async (_event, entryPath: string): Promise<{ success: true } | { error: string }> => {
+    try {
+      await rm(entryPath, { recursive: true })
+      return { success: true }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error deleting'
+      return { error: message }
+    }
+  },
+)
 
 // Rename file or directory IPC handler
-ipcMain.handle(IpcChannels.FS_RENAME, async (_event, oldPath: string, newPath: string): Promise<{ success: true } | { error: string }> => {
-  try {
-    // Check if target already exists
+ipcMain.handle(
+  IpcChannels.FS_RENAME,
+  async (
+    _event,
+    oldPath: string,
+    newPath: string,
+  ): Promise<{ success: true } | { error: string }> => {
     try {
-      await stat(newPath)
-      return { error: 'A file or folder with that name already exists' }
-    } catch {
-      // Expected — target doesn't exist
+      // Check if target already exists
+      try {
+        await stat(newPath)
+        return { error: 'A file or folder with that name already exists' }
+      } catch {
+        // Expected — target doesn't exist
+      }
+      await rename(oldPath, newPath)
+      return { success: true }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error renaming'
+      return { error: message }
     }
-    await rename(oldPath, newPath)
-    return { success: true }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Unknown error renaming'
-    return { error: message }
-  }
-})
+  },
+)
 
 // Reveal in Finder / file manager
 ipcMain.on(IpcChannels.FS_REVEAL_IN_FINDER, (_event, filePath: string) => {
@@ -1446,11 +1601,7 @@ ipcMain.on(IpcChannels.FS_REVEAL_IN_FINDER, (_event, filePath: string) => {
 
 ipcMain.handle(
   IpcChannels.OPEN_IN_VSCODE,
-  async (
-    _event,
-    rootPath: string,
-    files?: Array<{ path: string; line: number; col: number }>,
-  ) => {
+  async (_event, rootPath: string, files?: Array<{ path: string; line: number; col: number }>) => {
     const runCode = (args: string[]) =>
       new Promise<void>((resolve, reject) => {
         execFile('code', args, (err) => {
@@ -1474,50 +1625,62 @@ ipcMain.handle(
 )
 
 // List all files (quick open) — uses `git ls-files` for speed, falls back to recursive readdir
-ipcMain.handle(IpcChannels.FS_LIST_ALL_FILES, async (_event, rootPath: string): Promise<string[]> => {
-  // Try git ls-files first (fast, respects .gitignore)
-  if (existsSync(join(rootPath, '.git'))) {
-    try {
-      const files = await new Promise<string[]>((resolve, reject) => {
-        execFile('git', ['ls-files', '--cached', '--others', '--exclude-standard'], { cwd: rootPath, maxBuffer: 10 * 1024 * 1024 }, (err, stdout) => {
-          if (err) return reject(err)
-          resolve(stdout.trim().split('\n').filter(Boolean))
+ipcMain.handle(
+  IpcChannels.FS_LIST_ALL_FILES,
+  async (_event, rootPath: string): Promise<string[]> => {
+    // Try git ls-files first (fast, respects .gitignore)
+    if (existsSync(join(rootPath, '.git'))) {
+      try {
+        const files = await new Promise<string[]>((resolve, reject) => {
+          execFile(
+            'git',
+            ['ls-files', '--cached', '--others', '--exclude-standard'],
+            { cwd: rootPath, maxBuffer: 10 * 1024 * 1024 },
+            (err, stdout) => {
+              if (err) return reject(err)
+              resolve(stdout.trim().split('\n').filter(Boolean))
+            },
+          )
         })
-      })
-      return files
-    } catch {
-      // fall through to readdir
+        return files
+      } catch {
+        // fall through to readdir
+      }
     }
-  }
 
-  // Fallback: recursive readdir
-  const SKIP = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'out', '__pycache__'])
-  const results: string[] = []
-
-  /**
-   * Recursively traverses `dir` and appends discovered file paths (relative to `rootPath`) to the module-level `results` array.
-   *
-   * The walk skips entries whose names are in `SKIP` or that start with a dot. If `dir` cannot be read, the function returns without side effects.
-   *
-   * @param dir - The directory path to traverse
-   */
-  function walk(dir: string) {
-    let entries
-    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
-    for (const entry of entries) {
-      if (SKIP.has(entry.name) || entry.name.startsWith('.')) continue
-      const full = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        walk(full)
-      } else {
-        results.push(relative(rootPath, full))
+    // Fallback: recursive readdir
+    const SKIP = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'out', '__pycache__'])
+    const results: string[] = []
+
+    /**
+     * Recursively traverses `dir` and appends discovered file paths (relative to `rootPath`) to the module-level `results` array.
+     *
+     * The walk skips entries whose names are in `SKIP` or that start with a dot. If `dir` cannot be read, the function returns without side effects.
+     *
+     * @param dir - The directory path to traverse
+     */
+    function walk(dir: string) {
+      let entries
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return
+      }
+      for (const entry of entries) {
+        if (SKIP.has(entry.name) || entry.name.startsWith('.')) continue
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) {
+          walk(full)
+        } else {
+          results.push(relative(rootPath, full))
+        }
       }
     }
-  }
 
-  walk(rootPath)
-  return results
-})
+    walk(rootPath)
+    return results
+  },
+)
 
 // Search (find in files) — ripgrep-backed
 ipcMain.handle(IpcChannels.SEARCH_START, async (_event, opts: SearchOpts) => {
@@ -1554,12 +1717,21 @@ ipcMain.handle(IpcChannels.SEARCH_REPLACE, async (_event, opts: ReplaceOpts) =>
 
     for (const rep of sorted) {
       const lineIdx = rep.line - 1
-      if (lineIdx < 0 || lineIdx >= lines.length) { skipped++; continue }
+      if (lineIdx < 0 || lineIdx >= lines.length) {
+        skipped++
+        continue
+      }
       const line = lines[lineIdx]
       const colIdx = rep.column - 1
-      if (colIdx < 0 || colIdx > line.length) { skipped++; continue }
+      if (colIdx < 0 || colIdx > line.length) {
+        skipped++
+        continue
+      }
       const actual = line.slice(colIdx, colIdx + rep.matchText.length)
-      if (actual !== rep.matchText) { skipped++; continue }
+      if (actual !== rep.matchText) {
+        skipped++
+        continue
+      }
       const before = line.slice(0, colIdx)
       const after = line.slice(colIdx + rep.matchText.length)
       lines[lineIdx] = before + rep.replaceText + after
@@ -1588,12 +1760,15 @@ app.whenReady().then(async () => {
 
   buildAppMenu()
   createWindow()
-  registerPtyHandlers(() => contentView?.webContents ?? null, (workspaceId) => {
-    const entry = workspaceRegistry.get(workspaceId)
-    const root = entry?.rootPath ?? null
-    if (!root) return null
-    return getEffectiveWorkspaceRoot(workspaceId, root)
-  })
+  registerPtyHandlers(
+    () => contentView?.webContents ?? null,
+    (workspaceId) => {
+      const entry = workspaceRegistry.get(workspaceId)
+      const root = entry?.rootPath ?? null
+      if (!root) return null
+      return getEffectiveWorkspaceRoot(workspaceId, root)
+    },
+  )
   registerFileWatcherHandlers(() => contentView?.webContents ?? null)
 
   const getWebContents = () => contentView?.webContents ?? null
@@ -1652,7 +1827,9 @@ app.on('before-quit', (event) => {
     wc.send(IpcChannels.LIFECYCLE_REQUEST_SAVE)
 
     // Wait for renderer to confirm save, or timeout after 2s
-    const saveTimeout = setTimeout(() => { void finishQuit() }, 2000)
+    const saveTimeout = setTimeout(() => {
+      void finishQuit()
+    }, 2000)
 
     ipcMain.once(IpcChannels.LIFECYCLE_SAVE_COMPLETE, () => {
       clearTimeout(saveTimeout)
diff --git a/packages/main/src/preload.ts b/packages/main/src/preload.ts
index 16f1a42..07a884e 100644
--- a/packages/main/src/preload.ts
+++ b/packages/main/src/preload.ts
@@ -1,17 +1,64 @@
 import { contextBridge, ipcRenderer } from 'electron'
 import { IpcChannels } from '@aide/shared'
 import type {
-  ThemeName, FsWatchEvent, GitStatusResult, GitignoreAuditResult, WorktreeInfo, WorktreeCreateOpts, SearchOpts,
-  ReplaceOpts, ResolvedSettings,
-  AideProjectSettings, AideInitResult, AideTask, CompoundTask, TaskExecution, TaskInputRequest, TaskRunContext,
-  TaskTriggerResult, WorkspaceEntry, AideLocalState, AideLocalTerminals, WindowApi, BrowserSessionMode,
-  BrowserHostUpdate, BrowserDidNavigatePayload, BrowserPageTitlePayload, BrowserLoadingPayload, BrowserCanNavigatePayload,
-  BrowserFocusPayload, ZoomCommandPayload, KeybindingRule, ChatMode, ChatSession, ChatStreamChunk, ChatStreamEnd,
-  ChatToolCallPayload, PendingToolApprovalInfo, McpServerStatus, ToolDefinition, AgentBackend, CliAgentStreamDelta, CliAgentMessage, CliAgentSession,
-  CliAgentStatusPayload, CliAgentResultPayload, CliAgentMessagePayload, ConversationMeta, ConversationCreateOpts,
-  ConversationListChangedPayload, GitStatusChangedPayload, GitBranchChangedPayload, WorktreeListChangedPayload,
-  SearchResultsPayload, SearchCompletePayload, GitignoreAuditIpcPayload, TaskDiagnosticsPayload, TaskAutoDetectPayload,
-  PtyDataOutPayload, PtyExitPayload,
+  ThemeName,
+  FsWatchEvent,
+  GitStatusResult,
+  GitignoreAuditResult,
+  WorktreeInfo,
+  WorktreeCreateOpts,
+  SearchOpts,
+  ReplaceOpts,
+  ResolvedSettings,
+  AideProjectSettings,
+  AideInitResult,
+  AideTask,
+  CompoundTask,
+  TaskExecution,
+  TaskInputRequest,
+  TaskRunContext,
+  TaskTriggerResult,
+  WorkspaceEntry,
+  AideLocalState,
+  AideLocalTerminals,
+  WindowApi,
+  BrowserSessionMode,
+  BrowserHostUpdate,
+  BrowserDidNavigatePayload,
+  BrowserPageTitlePayload,
+  BrowserLoadingPayload,
+  BrowserCanNavigatePayload,
+  BrowserFocusPayload,
+  ZoomCommandPayload,
+  KeybindingRule,
+  ChatMode,
+  ChatSession,
+  ChatStreamChunk,
+  ChatStreamEnd,
+  ChatToolCallPayload,
+  PendingToolApprovalInfo,
+  McpServerStatus,
+  ToolDefinition,
+  AgentBackend,
+  CliAgentStreamDelta,
+  CliAgentMessage,
+  CliAgentSession,
+  CliAgentStatusPayload,
+  CliAgentResultPayload,
+  CliAgentMessagePayload,
+  ConversationMeta,
+  ConversationCreateOpts,
+  ConversationListChangedPayload,
+  GitStatusChangedPayload,
+  GitBranchChangedPayload,
+  WorktreeListChangedPayload,
+  SearchResultsPayload,
+  SearchCompletePayload,
+  GitignoreAuditIpcPayload,
+  TaskDiagnosticsPayload,
+  TaskAutoDetectPayload,
+  PtyDataOutPayload,
+  PtyExitPayload,
 } from '@aide/shared'
 
 const api: WindowApi = {
@@ -31,17 +78,21 @@ const api: WindowApi = {
 
   // Fullscreen
   onFullscreenChanged: (callback: (isFullscreen: boolean) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, isFullscreen: boolean) => callback(isFullscreen)
+    const handler = (_event: Electron.IpcRendererEvent, isFullscreen: boolean) =>
+      callback(isFullscreen)
     ipcRenderer.on(IpcChannels.FULLSCREEN_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.FULLSCREEN_CHANGED, handler)
   },
 
   // Zoom
   getBrowserZoom: (paneId: string) => ipcRenderer.invoke(IpcChannels.BROWSER_ZOOM_GET, paneId),
-  setBrowserZoom: (paneId: string, zoomFactor: number) => ipcRenderer.invoke(IpcChannels.BROWSER_ZOOM_SET, paneId, zoomFactor),
-  adjustBrowserZoom: (paneId: string, delta: number) => ipcRenderer.invoke(IpcChannels.BROWSER_ZOOM_ADJUST, paneId, delta),
+  setBrowserZoom: (paneId: string, zoomFactor: number) =>
+    ipcRenderer.invoke(IpcChannels.BROWSER_ZOOM_SET, paneId, zoomFactor),
+  adjustBrowserZoom: (paneId: string, delta: number) =>
+    ipcRenderer.invoke(IpcChannels.BROWSER_ZOOM_ADJUST, paneId, delta),
   onZoomCommand: (callback: (payload: ZoomCommandPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: ZoomCommandPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: ZoomCommandPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.APP_ZOOM_COMMAND, handler)
     return () => ipcRenderer.removeListener(IpcChannels.APP_ZOOM_COMMAND, handler)
   },
@@ -58,11 +109,13 @@ const api: WindowApi = {
   // Filesystem
   readDir: (dirPath: string) => ipcRenderer.invoke(IpcChannels.FS_READ_DIR, dirPath),
   readFile: (filePath: string) => ipcRenderer.invoke(IpcChannels.FS_READ_FILE, filePath),
-  writeFile: (filePath: string, content: string) => ipcRenderer.invoke(IpcChannels.FS_WRITE_FILE, filePath, content),
+  writeFile: (filePath: string, content: string) =>
+    ipcRenderer.invoke(IpcChannels.FS_WRITE_FILE, filePath, content),
   createFile: (filePath: string) => ipcRenderer.invoke(IpcChannels.FS_CREATE_FILE, filePath),
   createDir: (dirPath: string) => ipcRenderer.invoke(IpcChannels.FS_CREATE_DIR, dirPath),
   deleteEntry: (entryPath: string) => ipcRenderer.invoke(IpcChannels.FS_DELETE, entryPath),
-  renameEntry: (oldPath: string, newPath: string) => ipcRenderer.invoke(IpcChannels.FS_RENAME, oldPath, newPath),
+  renameEntry: (oldPath: string, newPath: string) =>
+    ipcRenderer.invoke(IpcChannels.FS_RENAME, oldPath, newPath),
   revealInFinder: (filePath: string) => ipcRenderer.send(IpcChannels.FS_REVEAL_IN_FINDER, filePath),
 
   // File watcher
@@ -75,57 +128,71 @@ const api: WindowApi = {
   // Git
   getGitStatus: (workspaceId: string) => ipcRenderer.invoke(IpcChannels.GIT_STATUS, workspaceId),
   onGitStatusChanged: (callback: (payload: GitStatusChangedPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: GitStatusChangedPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: GitStatusChangedPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.GIT_STATUS_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.GIT_STATUS_CHANGED, handler)
   },
   onGitBranchChanged: (callback: (payload: GitBranchChangedPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: GitBranchChangedPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: GitBranchChangedPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.GIT_BRANCH_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.GIT_BRANCH_CHANGED, handler)
   },
 
   // Git diff
-  getGitFileOriginal: (rootPath: string | null, filePath: string): Promise<{ content: string | null }> =>
+  getGitFileOriginal: (
+    rootPath: string | null,
+    filePath: string,
+  ): Promise<{ content: string | null }> =>
     ipcRenderer.invoke(IpcChannels.GIT_DIFF_ORIGINAL, rootPath, filePath),
 
   // Terminal
-  ptyCreate: (opts?: { id?: string; workspaceId?: string; cwd?: string; shell?: string; title?: string }) =>
-    ipcRenderer.invoke(IpcChannels.PTY_CREATE, opts),
-  ptyWrite: (id: string, data: string) =>
-    ipcRenderer.send(IpcChannels.PTY_DATA_IN, id, data),
+  ptyCreate: (opts?: {
+    id?: string
+    workspaceId?: string
+    cwd?: string
+    shell?: string
+    title?: string
+  }) => ipcRenderer.invoke(IpcChannels.PTY_CREATE, opts),
+  ptyWrite: (id: string, data: string) => ipcRenderer.send(IpcChannels.PTY_DATA_IN, id, data),
   ptyResize: (id: string, cols: number, rows: number) =>
     ipcRenderer.send(IpcChannels.PTY_RESIZE, id, cols, rows),
-  ptyKill: (id: string) =>
-    ipcRenderer.send(IpcChannels.PTY_KILL, id),
+  ptyKill: (id: string) => ipcRenderer.send(IpcChannels.PTY_KILL, id),
   ptyKillWorkspace: (workspaceId: string) =>
     ipcRenderer.send(IpcChannels.PTY_KILL_WORKSPACE, workspaceId),
   onPtyData: (callback: (payload: PtyDataOutPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: PtyDataOutPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: PtyDataOutPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.PTY_DATA_OUT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.PTY_DATA_OUT, handler)
   },
   onPtyExit: (callback: (payload: PtyExitPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: PtyExitPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: PtyExitPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.PTY_EXIT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.PTY_EXIT, handler)
   },
 
   // Worktrees
-  listWorktrees: (workspaceId: string) => ipcRenderer.invoke(IpcChannels.WORKTREE_LIST, workspaceId),
+  listWorktrees: (workspaceId: string) =>
+    ipcRenderer.invoke(IpcChannels.WORKTREE_LIST, workspaceId),
   createWorktree: (workspaceId: string, opts: WorktreeCreateOpts) =>
     ipcRenderer.invoke(IpcChannels.WORKTREE_CREATE, workspaceId, opts),
   removeWorktree: (workspaceId: string, worktreePath: string) =>
     ipcRenderer.invoke(IpcChannels.WORKTREE_REMOVE, workspaceId, worktreePath),
   setActiveWorktree: (workspaceId: string, worktreePath: string | null) =>
     ipcRenderer.invoke(IpcChannels.WORKTREE_SET_ACTIVE, workspaceId, worktreePath),
-  getActiveWorktree: (workspaceId: string) => ipcRenderer.invoke(IpcChannels.WORKTREE_GET_ACTIVE, workspaceId),
+  getActiveWorktree: (workspaceId: string) =>
+    ipcRenderer.invoke(IpcChannels.WORKTREE_GET_ACTIVE, workspaceId),
   onWorktreeListChanged: (callback: (payload: WorktreeListChangedPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: WorktreeListChangedPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: WorktreeListChangedPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.WORKTREE_LIST_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.WORKTREE_LIST_CHANGED, handler)
   },
-  listBranches: (workspaceId: string) => ipcRenderer.invoke(IpcChannels.WORKTREE_LIST_BRANCHES, workspaceId),
+  listBranches: (workspaceId: string) =>
+    ipcRenderer.invoke(IpcChannels.WORKTREE_LIST_BRANCHES, workspaceId),
 
   // File listing (quick open)
   listAllFiles: (rootPath: string) => ipcRenderer.invoke(IpcChannels.FS_LIST_ALL_FILES, rootPath),
@@ -133,12 +200,14 @@ const api: WindowApi = {
   // Search (find in files)
   searchStart: (opts: SearchOpts) => ipcRenderer.invoke(IpcChannels.SEARCH_START, opts),
   onSearchResults: (callback: (payload: SearchResultsPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: SearchResultsPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: SearchResultsPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.SEARCH_RESULTS, handler)
     return () => ipcRenderer.removeListener(IpcChannels.SEARCH_RESULTS, handler)
   },
   onSearchComplete: (callback: (payload: SearchCompletePayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: SearchCompletePayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: SearchCompletePayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.SEARCH_COMPLETE, handler)
     return () => ipcRenderer.removeListener(IpcChannels.SEARCH_COMPLETE, handler)
   },
@@ -162,12 +231,17 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.SETTINGS_SET_USER, key, value),
   getWorkspaceSettings: (workspaceId?: string | null): Promise<AideProjectSettings> =>
     ipcRenderer.invoke(IpcChannels.SETTINGS_GET_WORKSPACE, workspaceId),
-  setWorkspaceSetting: (key: string, value: unknown | undefined, workspaceId?: string | null): Promise<void> =>
+  setWorkspaceSetting: (
+    key: string,
+    value: unknown | undefined,
+    workspaceId?: string | null,
+  ): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.SETTINGS_SET_WORKSPACE, key, value, workspaceId),
   getBuiltInDefaults: (): Promise<ResolvedSettings> =>
     ipcRenderer.invoke(IpcChannels.SETTINGS_GET_DEFAULTS),
   onSettingsChanged: (callback: (resolved: ResolvedSettings) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, resolved: ResolvedSettings) => callback(resolved)
+    const handler = (_event: Electron.IpcRendererEvent, resolved: ResolvedSettings) =>
+      callback(resolved)
     ipcRenderer.on(IpcChannels.SETTINGS_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.SETTINGS_CHANGED, handler)
   },
@@ -191,7 +265,8 @@ const api: WindowApi = {
   dismissGitignoreAudit: (workspaceId?: string | null): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.GITIGNORE_DISMISS, workspaceId),
   onGitignoreAuditResult: (callback: (payload: GitignoreAuditIpcPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: GitignoreAuditIpcPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: GitignoreAuditIpcPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.GITIGNORE_AUDIT_RESULT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.GITIGNORE_AUDIT_RESULT, handler)
   },
@@ -201,7 +276,11 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.TASK_LIST, workspaceId),
   listRunningTasks: (workspaceId: string): Promise<TaskExecution[]> =>
     ipcRenderer.invoke(IpcChannels.TASK_LIST_RUNNING, workspaceId),
-  runTask: (workspaceId: string, taskId: string, context?: TaskRunContext): Promise<{ executionId: string } | { error: string }> =>
+  runTask: (
+    workspaceId: string,
+    taskId: string,
+    context?: TaskRunContext,
+  ): Promise<{ executionId: string } | { error: string }> =>
     ipcRenderer.invoke(IpcChannels.TASK_RUN, workspaceId, taskId, context),
   killTask: (workspaceId: string, executionId: string) =>
     ipcRenderer.send(IpcChannels.TASK_KILL, workspaceId, executionId),
@@ -211,37 +290,40 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.TASK_GENERATE, workspaceId),
   provideTaskInput: (workspaceId: string, requestId: string, value: string | null) =>
     ipcRenderer.send(IpcChannels.TASK_PROVIDE_INPUT, workspaceId, requestId, value),
-  notifyFileSaved: (filePath: string) =>
-    ipcRenderer.send(IpcChannels.TASK_FILE_SAVED, filePath),
+  notifyFileSaved: (filePath: string) => ipcRenderer.send(IpcChannels.TASK_FILE_SAVED, filePath),
   onTaskStatusChanged: (callback: (execution: TaskExecution) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, execution: TaskExecution) => callback(execution)
+    const handler = (_event: Electron.IpcRendererEvent, execution: TaskExecution) =>
+      callback(execution)
     ipcRenderer.on(IpcChannels.TASK_STATUS_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.TASK_STATUS_CHANGED, handler)
   },
   onTaskRequestInput: (callback: (request: TaskInputRequest) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, request: TaskInputRequest) => callback(request)
+    const handler = (_event: Electron.IpcRendererEvent, request: TaskInputRequest) =>
+      callback(request)
     ipcRenderer.on(IpcChannels.TASK_REQUEST_INPUT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.TASK_REQUEST_INPUT, handler)
   },
   onTaskDiagnostics: (callback: (payload: TaskDiagnosticsPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: TaskDiagnosticsPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: TaskDiagnosticsPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.TASK_DIAGNOSTICS, handler)
     return () => ipcRenderer.removeListener(IpcChannels.TASK_DIAGNOSTICS, handler)
   },
   onTaskAutoDetect: (callback: (payload: TaskAutoDetectPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: TaskAutoDetectPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: TaskAutoDetectPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.TASK_AUTO_DETECT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.TASK_AUTO_DETECT, handler)
   },
   onTaskTriggerResult: (callback: (result: TaskTriggerResult) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, result: TaskTriggerResult) => callback(result)
+    const handler = (_event: Electron.IpcRendererEvent, result: TaskTriggerResult) =>
+      callback(result)
     ipcRenderer.on(IpcChannels.TASK_TRIGGER_RESULT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.TASK_TRIGGER_RESULT, handler)
   },
 
   // Workspace registry
-  listWorkspaces: (): Promise<WorkspaceEntry[]> =>
-    ipcRenderer.invoke(IpcChannels.WORKSPACE_LIST),
+  listWorkspaces: (): Promise<WorkspaceEntry[]> => ipcRenderer.invoke(IpcChannels.WORKSPACE_LIST),
   createWorkspace: (rootPath: string): Promise<WorkspaceEntry> =>
     ipcRenderer.invoke(IpcChannels.WORKSPACE_CREATE, rootPath),
   createBlankWorkspace: (): Promise<WorkspaceEntry> =>
@@ -252,8 +334,10 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.WORKSPACE_CLOSE, id),
   switchWorkspace: (id: string): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.WORKSPACE_SWITCH, id),
-  updateWorkspace: (id: string, patch: Partial<Pick<WorkspaceEntry, 'name' | 'icon' | 'color'>>): Promise<void> =>
-    ipcRenderer.invoke(IpcChannels.WORKSPACE_UPDATE, id, patch),
+  updateWorkspace: (
+    id: string,
+    patch: Partial<Pick<WorkspaceEntry, 'name' | 'icon' | 'color'>>,
+  ): Promise<void> => ipcRenderer.invoke(IpcChannels.WORKSPACE_UPDATE, id, patch),
   reorderWorkspaces: (ids: string[]): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.WORKSPACE_REORDER, ids),
   setWorkspaceRoot: (id: string, rootPath: string): Promise<void> =>
@@ -261,16 +345,21 @@ const api: WindowApi = {
   getActiveWorkspaceId: (): Promise<string | null> =>
     ipcRenderer.invoke(IpcChannels.WORKSPACE_GET_ACTIVE),
   onWorkspaceRegistryChanged: (callback: (workspaces: WorkspaceEntry[]) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, workspaces: WorkspaceEntry[]) => callback(workspaces)
+    const handler = (_event: Electron.IpcRendererEvent, workspaces: WorkspaceEntry[]) =>
+      callback(workspaces)
     ipcRenderer.on(IpcChannels.WORKSPACE_REGISTRY_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.WORKSPACE_REGISTRY_CHANGED, handler)
   },
   getWorkspaceRuntimeSnapshots: () =>
     ipcRenderer.invoke(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_GET),
   onWorkspaceRuntimeSnapshotsChanged: (callback) => {
-    const handler = (_event: Electron.IpcRendererEvent, snapshots: import('@aide/shared').WorkspaceRuntimeSnapshot[]) => callback(snapshots)
+    const handler = (
+      _event: Electron.IpcRendererEvent,
+      snapshots: import('@aide/shared').WorkspaceRuntimeSnapshot[],
+    ) => callback(snapshots)
     ipcRenderer.on(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_CHANGED, handler)
-    return () => ipcRenderer.removeListener(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_CHANGED, handler)
+    return () =>
+      ipcRenderer.removeListener(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_CHANGED, handler)
   },
 
   // State persistence
@@ -286,46 +375,45 @@ const api: WindowApi = {
   // Browser panes
   browserCreate: (paneId: string, workspaceId: string, sessionMode: BrowserSessionMode) =>
     ipcRenderer.invoke(IpcChannels.BROWSER_CREATE, paneId, workspaceId, sessionMode),
-  browserDestroy: (paneId: string) =>
-    ipcRenderer.send(IpcChannels.BROWSER_DESTROY, paneId),
+  browserDestroy: (paneId: string) => ipcRenderer.send(IpcChannels.BROWSER_DESTROY, paneId),
   browserDestroyWorkspace: (workspaceId: string) =>
     ipcRenderer.send(IpcChannels.BROWSER_DESTROY_WORKSPACE, workspaceId),
   browserNavigate: (paneId: string, url: string) =>
     ipcRenderer.invoke(IpcChannels.BROWSER_NAVIGATE, paneId, url),
-  browserGoBack: (paneId: string) =>
-    ipcRenderer.send(IpcChannels.BROWSER_GO_BACK, paneId),
-  browserGoForward: (paneId: string) =>
-    ipcRenderer.send(IpcChannels.BROWSER_GO_FORWARD, paneId),
-  browserReload: (paneId: string) =>
-    ipcRenderer.send(IpcChannels.BROWSER_RELOAD, paneId),
+  browserGoBack: (paneId: string) => ipcRenderer.send(IpcChannels.BROWSER_GO_BACK, paneId),
+  browserGoForward: (paneId: string) => ipcRenderer.send(IpcChannels.BROWSER_GO_FORWARD, paneId),
+  browserReload: (paneId: string) => ipcRenderer.send(IpcChannels.BROWSER_RELOAD, paneId),
   browserHostUpdate: (update: BrowserHostUpdate) =>
     ipcRenderer.send(IpcChannels.BROWSER_HOST_UPDATE, update),
-  browserSuppressOverlays: () =>
-    ipcRenderer.send(IpcChannels.BROWSER_SUPPRESS_OVERLAYS),
-  browserUnsuppressOverlays: () =>
-    ipcRenderer.send(IpcChannels.BROWSER_UNSUPPRESS_OVERLAYS),
+  browserSuppressOverlays: () => ipcRenderer.send(IpcChannels.BROWSER_SUPPRESS_OVERLAYS),
+  browserUnsuppressOverlays: () => ipcRenderer.send(IpcChannels.BROWSER_UNSUPPRESS_OVERLAYS),
   onBrowserDidNavigate: (callback: (payload: BrowserDidNavigatePayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserDidNavigatePayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserDidNavigatePayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.BROWSER_DID_NAVIGATE, handler)
     return () => ipcRenderer.removeListener(IpcChannels.BROWSER_DID_NAVIGATE, handler)
   },
   onBrowserTitleUpdated: (callback: (payload: BrowserPageTitlePayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserPageTitlePayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserPageTitlePayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.BROWSER_PAGE_TITLE_UPDATED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.BROWSER_PAGE_TITLE_UPDATED, handler)
   },
   onBrowserLoadingChanged: (callback: (payload: BrowserLoadingPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserLoadingPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserLoadingPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.BROWSER_LOADING_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.BROWSER_LOADING_CHANGED, handler)
   },
   onBrowserCanNavigateChanged: (callback: (payload: BrowserCanNavigatePayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserCanNavigatePayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserCanNavigatePayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.BROWSER_CAN_NAVIGATE_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.BROWSER_CAN_NAVIGATE_CHANGED, handler)
   },
   onBrowserFocusChanged: (callback: (payload: BrowserFocusPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserFocusPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: BrowserFocusPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.BROWSER_FOCUS_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.BROWSER_FOCUS_CHANGED, handler)
   },
@@ -336,8 +424,7 @@ const api: WindowApi = {
     ipcRenderer.on(IpcChannels.LIFECYCLE_REQUEST_SAVE, handler)
     return () => ipcRenderer.removeListener(IpcChannels.LIFECYCLE_REQUEST_SAVE, handler)
   },
-  lifecycleSaveComplete: () =>
-    ipcRenderer.send(IpcChannels.LIFECYCLE_SAVE_COMPLETE),
+  lifecycleSaveComplete: () => ipcRenderer.send(IpcChannels.LIFECYCLE_SAVE_COMPLETE),
   onCrashDetected: (callback: () => void) => {
     const handler = () => callback()
     ipcRenderer.on(IpcChannels.LIFECYCLE_CRASH_DETECTED, handler)
@@ -357,8 +444,7 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.CHAT_TOOL_APPROVE, sessionId, toolCallId),
   chatToolReject: (sessionId: string, toolCallId: string): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.CHAT_TOOL_REJECT, sessionId, toolCallId),
-  chatStop: (sessionId: string) =>
-    ipcRenderer.send(IpcChannels.CHAT_STOP, sessionId),
+  chatStop: (sessionId: string) => ipcRenderer.send(IpcChannels.CHAT_STOP, sessionId),
   onChatStreamChunk: (callback: (chunk: ChatStreamChunk) => void) => {
     const handler = (_event: Electron.IpcRendererEvent, chunk: ChatStreamChunk) => callback(chunk)
     ipcRenderer.on(IpcChannels.CHAT_STREAM_CHUNK, handler)
@@ -370,7 +456,8 @@ const api: WindowApi = {
     return () => ipcRenderer.removeListener(IpcChannels.CHAT_STREAM_END, handler)
   },
   onChatToolCall: (callback: (payload: ChatToolCallPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: ChatToolCallPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: ChatToolCallPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.CHAT_TOOL_CALL, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CHAT_TOOL_CALL, handler)
   },
@@ -382,8 +469,7 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.MCP_LIST_SERVERS),
   mcpRestartServer: (serverName: string) =>
     ipcRenderer.invoke(IpcChannels.MCP_RESTART_SERVER, serverName),
-  mcpListTools: (): Promise<ToolDefinition[]> =>
-    ipcRenderer.invoke(IpcChannels.MCP_LIST_TOOLS),
+  mcpListTools: (): Promise<ToolDefinition[]> => ipcRenderer.invoke(IpcChannels.MCP_LIST_TOOLS),
   onMcpServerStatus: (callback: (status: McpServerStatus) => void) => {
     const handler = (_event: Electron.IpcRendererEvent, status: McpServerStatus) => callback(status)
     ipcRenderer.on(IpcChannels.MCP_SERVER_STATUS, handler)
@@ -391,10 +477,22 @@ const api: WindowApi = {
   },
 
   // ─── CLI Agent ───────────────────────────────
-  cliAgentStart: (workspaceId: string, backend: AgentBackend, conversationId?: string, worktreePath?: string) =>
-    ipcRenderer.invoke(IpcChannels.CLI_AGENT_START, workspaceId, backend, conversationId, worktreePath),
-  cliAgentStop: (sessionId: string) =>
-    ipcRenderer.send(IpcChannels.CLI_AGENT_STOP, sessionId),
+  cliAgentStart: (
+    workspaceId: string,
+    backend: AgentBackend,
+    conversationId?: string,
+    worktreePath?: string,
+  ) =>
+    ipcRenderer.invoke(
+      IpcChannels.CLI_AGENT_START,
+      workspaceId,
+      backend,
+      conversationId,
+      worktreePath,
+    ),
+  cliAgentSwitchBackend: (sessionId: string, backend: AgentBackend) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SWITCH_BACKEND, sessionId, backend),
+  cliAgentStop: (sessionId: string) => ipcRenderer.send(IpcChannels.CLI_AGENT_STOP, sessionId),
   cliAgentSend: (sessionId: string, content: string) =>
     ipcRenderer.invoke(IpcChannels.CLI_AGENT_SEND, sessionId, content),
   cliAgentGetSession: (workspaceId: string, sessionId?: string): Promise<CliAgentSession | null> =>
@@ -402,22 +500,26 @@ const api: WindowApi = {
   cliAgentLoadMessages: (workspaceId: string, conversationId: string): Promise<CliAgentMessage[]> =>
     ipcRenderer.invoke(IpcChannels.CLI_AGENT_LOAD_MESSAGES, workspaceId, conversationId),
   onCliAgentStreamDelta: (callback: (delta: CliAgentStreamDelta) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, delta: CliAgentStreamDelta) => callback(delta)
+    const handler = (_event: Electron.IpcRendererEvent, delta: CliAgentStreamDelta) =>
+      callback(delta)
     ipcRenderer.on(IpcChannels.CLI_AGENT_STREAM_DELTA, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_STREAM_DELTA, handler)
   },
   onCliAgentMessage: (callback: (msg: CliAgentMessagePayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, msg: CliAgentMessagePayload) => callback(msg)
+    const handler = (_event: Electron.IpcRendererEvent, msg: CliAgentMessagePayload) =>
+      callback(msg)
     ipcRenderer.on(IpcChannels.CLI_AGENT_MESSAGE, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_MESSAGE, handler)
   },
   onCliAgentStatus: (callback: (status: CliAgentStatusPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, status: CliAgentStatusPayload) => callback(status)
+    const handler = (_event: Electron.IpcRendererEvent, status: CliAgentStatusPayload) =>
+      callback(status)
     ipcRenderer.on(IpcChannels.CLI_AGENT_STATUS, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_STATUS, handler)
   },
   onCliAgentResult: (callback: (result: CliAgentResultPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, result: CliAgentResultPayload) => callback(result)
+    const handler = (_event: Electron.IpcRendererEvent, result: CliAgentResultPayload) =>
+      callback(result)
     ipcRenderer.on(IpcChannels.CLI_AGENT_RESULT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_RESULT, handler)
   },
@@ -431,19 +533,20 @@ const api: WindowApi = {
     ipcRenderer.invoke(IpcChannels.CONVERSATION_DELETE, workspaceId, conversationId),
   conversationRename: (workspaceId: string, conversationId: string, title: string): Promise<void> =>
     ipcRenderer.invoke(IpcChannels.CONVERSATION_RENAME, workspaceId, conversationId, title),
-  conversationGet: (workspaceId: string, conversationId: string): Promise<ConversationMeta | null> =>
+  conversationGet: (
+    workspaceId: string,
+    conversationId: string,
+  ): Promise<ConversationMeta | null> =>
     ipcRenderer.invoke(IpcChannels.CONVERSATION_GET, workspaceId, conversationId),
   onConversationListChanged: (callback: (payload: ConversationListChangedPayload) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, payload: ConversationListChangedPayload) => callback(payload)
+    const handler = (_event: Electron.IpcRendererEvent, payload: ConversationListChangedPayload) =>
+      callback(payload)
     ipcRenderer.on(IpcChannels.CONVERSATION_LIST_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CONVERSATION_LIST_CHANGED, handler)
   },
 
   // Open in VS Code
-  openInVSCode: (
-    rootPath: string,
-    files?: Array<{ path: string; line: number; col: number }>,
-  ) =>
+  openInVSCode: (rootPath: string, files?: Array<{ path: string; line: number; col: number }>) =>
     ipcRenderer.invoke(IpcChannels.OPEN_IN_VSCODE, rootPath, files),
 
   // Platform info (for conditional UI like traffic lights)
diff --git a/packages/main/src/workspace/settingsResolver.ts b/packages/main/src/workspace/settingsResolver.ts
index f3c22e7..7ea39d6 100644
--- a/packages/main/src/workspace/settingsResolver.ts
+++ b/packages/main/src/workspace/settingsResolver.ts
@@ -11,7 +11,14 @@ import { existsSync } from 'fs'
 import { readFile } from 'fs/promises'
 import { join } from 'path'
 import type Store from 'electron-store'
-import type { AppSettings, AideProjectSettings, ResolvedSettings, PermissionTier, ToolPermissionConfig, AgentBackend } from '@aide/shared'
+import type {
+  AppSettings,
+  AideProjectSettings,
+  ResolvedSettings,
+  PermissionTier,
+  ToolPermissionConfig,
+  AgentBackend,
+} from '@aide/shared'
 
 export const BUILT_IN_DEFAULTS: ResolvedSettings = {
   tabSize: 2,
@@ -39,6 +46,7 @@ export const BUILT_IN_DEFAULTS: ResolvedSettings = {
   // Agent / Backend defaults
   'agent.backend': 'built-in' as AgentBackend,
   'agent.claudeCodePath': '',
+  'agent.opencodePath': '',
   'agent.codexPath': '',
 }
 
@@ -48,9 +56,7 @@ export const BUILT_IN_DEFAULTS: ResolvedSettings = {
  * @param store - Electron store used to read the saved `editorDefaults` entry
  * @returns A ResolvedSettings object where each scalar setting is the user value if present, otherwise the built-in default; `filesExclude` and `searchExclude` are shallow-merged so user entries override built-in entries
  */
-export function resolveAppDefaults(
-  store: Store<AppSettings>,
-): ResolvedSettings {
+export function resolveAppDefaults(store: Store<AppSettings>): ResolvedSettings {
   const userDefaults = (store.get('editorDefaults') ?? {}) as Partial<AideProjectSettings>
 
   return {
@@ -79,7 +85,8 @@ export function resolveAppDefaults(
     'agent.maxTokens': userDefaults['agent.maxTokens'] ?? BUILT_IN_DEFAULTS['agent.maxTokens'],
 
     // Agent / Permissions
-    'agent.permissionTier': userDefaults['agent.permissionTier'] ?? BUILT_IN_DEFAULTS['agent.permissionTier'],
+    'agent.permissionTier':
+      userDefaults['agent.permissionTier'] ?? BUILT_IN_DEFAULTS['agent.permissionTier'],
     'agent.autoApprove': {
       ...BUILT_IN_DEFAULTS['agent.autoApprove'],
       ...(userDefaults['agent.autoApprove'] ?? {}),
@@ -87,7 +94,10 @@ export function resolveAppDefaults(
 
     // Agent / Backend
     'agent.backend': userDefaults['agent.backend'] ?? BUILT_IN_DEFAULTS['agent.backend'],
-    'agent.claudeCodePath': userDefaults['agent.claudeCodePath'] ?? BUILT_IN_DEFAULTS['agent.claudeCodePath'],
+    'agent.claudeCodePath':
+      userDefaults['agent.claudeCodePath'] ?? BUILT_IN_DEFAULTS['agent.claudeCodePath'],
+    'agent.opencodePath':
+      userDefaults['agent.opencodePath'] ?? BUILT_IN_DEFAULTS['agent.opencodePath'],
     'agent.codexPath': userDefaults['agent.codexPath'] ?? BUILT_IN_DEFAULTS['agent.codexPath'],
   }
 }
@@ -158,6 +168,7 @@ export async function resolveSettings(
     // Agent / Backend (user-only — executable paths must not come from untrusted repos)
     'agent.backend': appDefaults['agent.backend'],
     'agent.claudeCodePath': appDefaults['agent.claudeCodePath'],
+    'agent.opencodePath': appDefaults['agent.opencodePath'],
     'agent.codexPath': appDefaults['agent.codexPath'],
   }
 }
diff --git a/packages/shared/src/cliAgentTypes.ts b/packages/shared/src/cliAgentTypes.ts
index b64bb43..a327899 100644
--- a/packages/shared/src/cliAgentTypes.ts
+++ b/packages/shared/src/cliAgentTypes.ts
@@ -1,7 +1,7 @@
 /**
  * CLI Agent Wrappers — shared types.
  *
- * Types for wrapping external CLI agents (Claude Code, Codex) as monitored
+ * Types for wrapping external CLI agents (Claude Code, OpenCode, Codex) as monitored
  * sessions inside the IDE. These are consumed by both main and renderer.
  */
 
@@ -9,19 +9,27 @@
 // Agent backend selection
 // ---------------------------------------------------------------------------
 
-export type AgentBackend = 'built-in' | 'claude-code' | 'codex'
+export type AgentBackend = 'built-in' | 'claude-code' | 'opencode' | 'codex'
+export type ExternalCliBackend = Exclude<AgentBackend, 'built-in'>
+
+export interface CliAgentBackendState {
+  sessionId?: string
+  model?: string
+}
+
+export type CliAgentBackendStateMap = Partial<Record<ExternalCliBackend, CliAgentBackendState>>
 
 // ---------------------------------------------------------------------------
 // Process lifecycle
 // ---------------------------------------------------------------------------
 
 export type CliAgentProcessStatus =
-  | 'stopped'       // not running
-  | 'starting'      // spawn called, waiting for init event
-  | 'running'       // active and responsive
-  | 'rate_limited'  // temporarily throttled
-  | 'error'         // crashed or errored
-  | 'stopping'      // SIGTERM sent, waiting for exit
+  | 'stopped' // not running
+  | 'starting' // spawn called, waiting for init event
+  | 'running' // active and responsive
+  | 'rate_limited' // temporarily throttled
+  | 'error' // crashed or errored
+  | 'stopping' // SIGTERM sent, waiting for exit
 
 // ---------------------------------------------------------------------------
 // Normalized messages
@@ -33,6 +41,7 @@ export interface CliAgentMessage {
   type: 'system' | 'assistant' | 'user' | 'tool_use' | 'tool_result' | 'status' | 'error' | 'result'
   content: string
   timestamp: number
+  backend?: ExternalCliBackend
   /** Original SDK event for debugging */
   raw?: unknown
 
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index d7a9b50..f9fe997 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -5,40 +5,91 @@
 
 export type { CommandDefinition, KeybindingRule } from './commands'
 export type {
-  ChatMode, ChatSessionStatus, ToolCallStatus,
-  ToolCall, ToolResult, ChatMessage, ChatSession,
-  ChatStreamChunk, ChatStreamEnd, ChatToolCallPayload, PendingToolApprovalInfo,
+  ChatMode,
+  ChatSessionStatus,
+  ToolCallStatus,
+  ToolCall,
+  ToolResult,
+  ChatMessage,
+  ChatSession,
+  ChatStreamChunk,
+  ChatStreamEnd,
+  ChatToolCallPayload,
+  PendingToolApprovalInfo,
   ToolDefinition,
-  McpServerConfig, McpServerConnectionStatus, McpServerStatus,
-  PermissionTier, ToolPermissionConfig, AgentPermissionSettings,
+  McpServerConfig,
+  McpServerConnectionStatus,
+  McpServerStatus,
+  PermissionTier,
+  ToolPermissionConfig,
+  AgentPermissionSettings,
   LlmProviderConfig,
 } from './agentTypes'
 export type {
-  AgentBackend, CliAgentProcessStatus,
-  CliAgentMessage, CliAgentStreamDelta, CliAgentSession,
-  CliAgentStatusPayload, CliAgentResultPayload, CliAgentMessagePayload,
+  AgentBackend,
+  ExternalCliBackend,
+  CliAgentBackendState,
+  CliAgentBackendStateMap,
+  CliAgentProcessStatus,
+  CliAgentMessage,
+  CliAgentStreamDelta,
+  CliAgentSession,
+  CliAgentStatusPayload,
+  CliAgentResultPayload,
+  CliAgentMessagePayload,
 } from './cliAgentTypes'
 export type {
-  ConversationMeta, ConversationCreateOpts, ConversationListChangedPayload,
+  ConversationMeta,
+  ConversationCreateOpts,
+  ConversationListChangedPayload,
 } from './conversationTypes'
 export { deriveTitle } from './conversationTypes'
 export type {
-  LlmMessage, LlmContentBlock, LlmToolDefinition, LlmUsage,
-  LlmStreamEvent, StreamParams, LlmProvider, SseEvent,
-  AnthropicRequest, AnthropicMessage, AnthropicContentBlock, AnthropicTool, AnthropicStreamEvent,
-  OpenAiRequest, OpenAiMessage, OpenAiToolCall, OpenAiTool, OpenAiStreamChunk, OpenAiStreamToolCall,
+  LlmMessage,
+  LlmContentBlock,
+  LlmToolDefinition,
+  LlmUsage,
+  LlmStreamEvent,
+  StreamParams,
+  LlmProvider,
+  SseEvent,
+  AnthropicRequest,
+  AnthropicMessage,
+  AnthropicContentBlock,
+  AnthropicTool,
+  AnthropicStreamEvent,
+  OpenAiRequest,
+  OpenAiMessage,
+  OpenAiToolCall,
+  OpenAiTool,
+  OpenAiStreamChunk,
+  OpenAiStreamToolCall,
 } from './llmTypes'
 import type {
-  ChatMode, ChatSession, ChatStreamChunk, ChatStreamEnd, ChatToolCallPayload, PendingToolApprovalInfo,
-  McpServerStatus, ToolDefinition,
-  PermissionTier, ToolPermissionConfig,
+  ChatMode,
+  ChatSession,
+  ChatStreamChunk,
+  ChatStreamEnd,
+  ChatToolCallPayload,
+  PendingToolApprovalInfo,
+  McpServerStatus,
+  ToolDefinition,
+  PermissionTier,
+  ToolPermissionConfig,
 } from './agentTypes'
 import type {
-  AgentBackend, CliAgentStreamDelta, CliAgentMessage,
-  CliAgentSession, CliAgentStatusPayload, CliAgentResultPayload, CliAgentMessagePayload,
+  AgentBackend,
+  CliAgentStreamDelta,
+  CliAgentMessage,
+  CliAgentSession,
+  CliAgentStatusPayload,
+  CliAgentResultPayload,
+  CliAgentMessagePayload,
 } from './cliAgentTypes'
 import type {
-  ConversationMeta, ConversationCreateOpts, ConversationListChangedPayload,
+  ConversationMeta,
+  ConversationCreateOpts,
+  ConversationListChangedPayload,
 } from './conversationTypes'
 export {
   adjustZoomFactor,
@@ -236,6 +287,7 @@ export const IpcChannels = {
 
   // ─── CLI Agent ───────────────────────────────
   CLI_AGENT_START: 'cli-agent:start',
+  CLI_AGENT_SWITCH_BACKEND: 'cli-agent:switch-backend',
   CLI_AGENT_STOP: 'cli-agent:stop',
   CLI_AGENT_SEND: 'cli-agent:send',
   CLI_AGENT_GET_SESSION: 'cli-agent:get-session',
@@ -258,7 +310,6 @@ export type ThemeName = 'one-dark' | 'one-light'
 
 export type SettingsScope = 'user' | 'workspace'
 
-
 export interface DirEntry {
   name: string
   path: string
@@ -399,6 +450,7 @@ export interface AideProjectSettings {
   // Agent / Backend settings
   'agent.backend'?: AgentBackend
   'agent.claudeCodePath'?: string
+  'agent.opencodePath'?: string
   'agent.codexPath'?: string
 }
 
@@ -429,6 +481,7 @@ export interface ResolvedSettings {
   // Agent / Backend settings
   'agent.backend': AgentBackend
   'agent.claudeCodePath': string
+  'agent.opencodePath': string
   'agent.codexPath': string
 }
 
@@ -443,6 +496,7 @@ export const SENSITIVE_AGENT_KEYS: ReadonlySet<string> = new Set([
   'agent.baseUrl',
   'agent.backend',
   'agent.claudeCodePath',
+  'agent.opencodePath',
   'agent.codexPath',
   'agent.permissionTier',
   'agent.autoApprove',
@@ -496,18 +550,9 @@ export interface AppWorkspaceRegistry {
   lastSessionWorkspaces: string[]
 }
 
-export type WorkspaceRuntimeState =
-  | 'foreground'
-  | 'backgrounded'
-  | 'asleep'
-  | 'blocked'
+export type WorkspaceRuntimeState = 'foreground' | 'backgrounded' | 'asleep' | 'blocked'
 
-export type WorkspaceRuntimeStatus =
-  | 'starting'
-  | 'running'
-  | 'stopping'
-  | 'stopped'
-  | 'error'
+export type WorkspaceRuntimeStatus = 'starting' | 'running' | 'stopping' | 'stopped' | 'error'
 
 export interface WorkspaceRuntimeWorkloadFlags {
   agentsRunning: boolean
@@ -830,10 +875,19 @@ export interface WindowApi {
   onGitBranchChanged: (callback: (payload: GitBranchChangedPayload) => void) => () => void
 
   // Git diff
-  getGitFileOriginal: (rootPath: string | null, filePath: string) => Promise<{ content: string | null }>
+  getGitFileOriginal: (
+    rootPath: string | null,
+    filePath: string,
+  ) => Promise<{ content: string | null }>
 
   // Terminal
-  ptyCreate: (opts?: { id?: string; workspaceId?: string; cwd?: string; shell?: string; title?: string }) => Promise<{ id: string; scrollback: string }>
+  ptyCreate: (opts?: {
+    id?: string
+    workspaceId?: string
+    cwd?: string
+    shell?: string
+    title?: string
+  }) => Promise<{ id: string; scrollback: string }>
   ptyWrite: (id: string, data: string) => void
   ptyResize: (id: string, cols: number, rows: number) => void
   ptyKill: (id: string) => void
@@ -843,8 +897,14 @@ export interface WindowApi {
 
   // Worktrees
   listWorktrees: (workspaceId: string) => Promise<WorktreeInfo[]>
-  createWorktree: (workspaceId: string, opts: WorktreeCreateOpts) => Promise<{ path: string } | { error: string }>
-  removeWorktree: (workspaceId: string, worktreePath: string) => Promise<{ success: true } | { error: string }>
+  createWorktree: (
+    workspaceId: string,
+    opts: WorktreeCreateOpts,
+  ) => Promise<{ path: string } | { error: string }>
+  removeWorktree: (
+    workspaceId: string,
+    worktreePath: string,
+  ) => Promise<{ success: true } | { error: string }>
   setActiveWorktree: (workspaceId: string, worktreePath: string | null) => Promise<void>
   getActiveWorktree: (workspaceId: string) => Promise<string | null>
   onWorktreeListChanged: (callback: (payload: WorktreeListChangedPayload) => void) => () => void
@@ -858,7 +918,9 @@ export interface WindowApi {
   onSearchResults: (callback: (payload: SearchResultsPayload) => void) => () => void
   onSearchComplete: (callback: (payload: SearchCompletePayload) => void) => () => void
   searchCancel: () => void
-  searchReplace: (opts: ReplaceOpts) => Promise<{ success: true; skipped: number } | { error: string }>
+  searchReplace: (
+    opts: ReplaceOpts,
+  ) => Promise<{ success: true; skipped: number } | { error: string }>
 
   // .aide project folder
   aideInit: (workspaceId?: string | null) => Promise<AideInitResult | { error: string }>
@@ -869,14 +931,20 @@ export interface WindowApi {
   getUserSettings: () => Promise<Partial<AideProjectSettings>>
   setUserSetting: (key: string, value: unknown | undefined) => Promise<void>
   getWorkspaceSettings: (workspaceId?: string | null) => Promise<AideProjectSettings>
-  setWorkspaceSetting: (key: string, value: unknown | undefined, workspaceId?: string | null) => Promise<void>
+  setWorkspaceSetting: (
+    key: string,
+    value: unknown | undefined,
+    workspaceId?: string | null,
+  ) => Promise<void>
   getBuiltInDefaults: () => Promise<ResolvedSettings>
   onSettingsChanged: (callback: (resolved: ResolvedSettings) => void) => () => void
 
   // Keybinding overrides
   getKeybindingOverrides: () => Promise<import('./commands').KeybindingRule[]>
   setKeybindingOverrides: (rules: import('./commands').KeybindingRule[]) => Promise<void>
-  onKeybindingsChanged: (callback: (rules: import('./commands').KeybindingRule[]) => void) => () => void
+  onKeybindingsChanged: (
+    callback: (rules: import('./commands').KeybindingRule[]) => void,
+  ) => () => void
 
   // Gitignore security audit
   auditGitignore: (workspaceId?: string | null) => Promise<GitignoreAuditResult>
@@ -887,7 +955,11 @@ export interface WindowApi {
   // Task system
   listTasks: (workspaceId: string) => Promise<{ tasks: AideTask[]; compounds: CompoundTask[] }>
   listRunningTasks: (workspaceId: string) => Promise<TaskExecution[]>
-  runTask: (workspaceId: string, taskId: string, context?: TaskRunContext) => Promise<{ executionId: string } | { error: string }>
+  runTask: (
+    workspaceId: string,
+    taskId: string,
+    context?: TaskRunContext,
+  ) => Promise<{ executionId: string } | { error: string }>
   killTask: (workspaceId: string, executionId: string) => void
   reloadTasks: (workspaceId: string) => Promise<void>
   generateTasks: (workspaceId: string) => Promise<{ success: true } | { error: string }>
@@ -906,13 +978,18 @@ export interface WindowApi {
   removeWorkspace: (id: string) => Promise<void>
   closeWorkspace: (id: string) => Promise<void>
   switchWorkspace: (id: string) => Promise<void>
-  updateWorkspace: (id: string, patch: Partial<Pick<WorkspaceEntry, 'name' | 'icon' | 'color'>>) => Promise<void>
+  updateWorkspace: (
+    id: string,
+    patch: Partial<Pick<WorkspaceEntry, 'name' | 'icon' | 'color'>>,
+  ) => Promise<void>
   reorderWorkspaces: (ids: string[]) => Promise<void>
   setWorkspaceRoot: (id: string, rootPath: string) => Promise<void>
   getActiveWorkspaceId: () => Promise<string | null>
   onWorkspaceRegistryChanged: (callback: (workspaces: WorkspaceEntry[]) => void) => () => void
   getWorkspaceRuntimeSnapshots: () => Promise<WorkspaceRuntimeSnapshot[]>
-  onWorkspaceRuntimeSnapshotsChanged: (callback: (snapshots: WorkspaceRuntimeSnapshot[]) => void) => () => void
+  onWorkspaceRuntimeSnapshotsChanged: (
+    callback: (snapshots: WorkspaceRuntimeSnapshot[]) => void,
+  ) => () => void
 
   // State persistence
   saveWorkspaceState: (rootPath: string, state: AideLocalState) => Promise<void>
@@ -921,10 +998,17 @@ export interface WindowApi {
   loadTerminalState: (rootPath: string) => Promise<AideLocalTerminals | null>
 
   // Browser panes
-  browserCreate: (paneId: string, workspaceId: string, sessionMode: BrowserSessionMode) => Promise<{ success: true } | { error: string }>
+  browserCreate: (
+    paneId: string,
+    workspaceId: string,
+    sessionMode: BrowserSessionMode,
+  ) => Promise<{ success: true } | { error: string }>
   browserDestroy: (paneId: string) => void
   browserDestroyWorkspace: (workspaceId: string) => void
-  browserNavigate: (paneId: string, url: string) => Promise<{ success: true; url: string } | { error: string }>
+  browserNavigate: (
+    paneId: string,
+    url: string,
+  ) => Promise<{ success: true; url: string } | { error: string }>
   browserGoBack: (paneId: string) => void
   browserGoForward: (paneId: string) => void
   browserReload: (paneId: string) => void
@@ -934,7 +1018,9 @@ export interface WindowApi {
   onBrowserDidNavigate: (callback: (payload: BrowserDidNavigatePayload) => void) => () => void
   onBrowserTitleUpdated: (callback: (payload: BrowserPageTitlePayload) => void) => () => void
   onBrowserLoadingChanged: (callback: (payload: BrowserLoadingPayload) => void) => () => void
-  onBrowserCanNavigateChanged: (callback: (payload: BrowserCanNavigatePayload) => void) => () => void
+  onBrowserCanNavigateChanged: (
+    callback: (payload: BrowserCanNavigatePayload) => void,
+  ) => () => void
   onBrowserFocusChanged: (callback: (payload: BrowserFocusPayload) => void) => () => void
 
   // App lifecycle
@@ -943,7 +1029,10 @@ export interface WindowApi {
   onCrashDetected: (callback: () => void) => () => void
 
   // ─── Agent Chat ───────────────────────────────
-  chatSendMessage: (sessionId: string, content: string) => Promise<{ messageId: string } | { error: string }>
+  chatSendMessage: (
+    sessionId: string,
+    content: string,
+  ) => Promise<{ messageId: string } | { error: string }>
   chatGetHistory: (workspaceId: string, conversationId?: string) => Promise<ChatSession | null>
   chatSetMode: (sessionId: string, mode: ChatMode) => Promise<void>
   chatSetWorkingSet: (sessionId: string, paths: string[]) => Promise<void>
@@ -962,9 +1051,21 @@ export interface WindowApi {
   onMcpServerStatus: (callback: (status: McpServerStatus) => void) => () => void
 
   // ─── CLI Agent ───────────────────────────────
-  cliAgentStart: (workspaceId: string, backend: AgentBackend, conversationId?: string, worktreePath?: string) => Promise<{ sessionId: string } | { error: string }>
+  cliAgentStart: (
+    workspaceId: string,
+    backend: AgentBackend,
+    conversationId?: string,
+    worktreePath?: string,
+  ) => Promise<{ sessionId: string } | { error: string }>
+  cliAgentSwitchBackend: (
+    sessionId: string,
+    backend: AgentBackend,
+  ) => Promise<{ success: true } | { error: string }>
   cliAgentStop: (sessionId: string) => void
-  cliAgentSend: (sessionId: string, content: string) => Promise<{ success: true } | { error: string }>
+  cliAgentSend: (
+    sessionId: string,
+    content: string,
+  ) => Promise<{ success: true } | { error: string }>
   cliAgentGetSession: (workspaceId: string, sessionId?: string) => Promise<CliAgentSession | null>
   cliAgentLoadMessages: (workspaceId: string, conversationId: string) => Promise<CliAgentMessage[]>
   onCliAgentStreamDelta: (callback: (delta: CliAgentStreamDelta) => void) => () => void
@@ -978,7 +1079,9 @@ export interface WindowApi {
   conversationDelete: (workspaceId: string, conversationId: string) => Promise<void>
   conversationRename: (workspaceId: string, conversationId: string, title: string) => Promise<void>
   conversationGet: (workspaceId: string, conversationId: string) => Promise<ConversationMeta | null>
-  onConversationListChanged: (callback: (payload: ConversationListChangedPayload) => void) => () => void
+  onConversationListChanged: (
+    callback: (payload: ConversationListChangedPayload) => void,
+  ) => () => void
 
   // VS Code Integration
   openInVSCode: (
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 597aa43..5563831 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,9 @@ importers:
       '@anthropic-ai/claude-code':
         specifier: '*'
         version: 2.1.81
+      '@opencode-ai/sdk':
+        specifier: ^1.4.0
+        version: 1.4.0
       '@vscode/ripgrep':
         specifier: ^1.17.1
         version: 1.17.1
@@ -102,6 +105,9 @@ importers:
       '@anthropic-ai/claude-agent-sdk':
         specifier: ^0.2.91
         version: 0.2.91(zod@4.3.6)
+      '@opencode-ai/sdk':
+        specifier: ^1.4.0
+        version: 1.4.0
       electron-store:
         specifier: ^6.0.1
         version: 6.0.1
@@ -854,6 +860,9 @@ packages:
     engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0}
     deprecated: This functionality has been moved to @npmcli/fs
 
+  '@opencode-ai/sdk@1.4.0':
+    resolution: {integrity: sha512-mfa3MzhqNM+Az4bgPDDXL3NdG+aYOHClXmT6/4qLxf2ulyfPpMNHqb9Dfmo4D8UfmrDsPuJHmbune73/nUQnuw==}
+
   '@pkgjs/parseargs@0.11.0':
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
@@ -4640,6 +4649,10 @@ snapshots:
       mkdirp: 1.0.4
       rimraf: 3.0.2
 
+  '@opencode-ai/sdk@1.4.0':
+    dependencies:
+      cross-spawn: 7.0.6
+
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
diff --git a/tests/unit/cliAgentManager.test.ts b/tests/unit/cliAgentManager.test.ts
index 666da7d..87e0f5e 100644
--- a/tests/unit/cliAgentManager.test.ts
+++ b/tests/unit/cliAgentManager.test.ts
@@ -3,15 +3,19 @@ import type { CliAgentMessage } from '@aide/shared'
 
 const mocks = vi.hoisted(() => ({
   execFileSync: vi.fn(),
+  spawn: vi.fn(),
   existsSync: vi.fn(),
   query: vi.fn(),
+  createOpencodeClient: vi.fn(),
 }))
 
 vi.mock('child_process', () => ({
   default: {
     execFileSync: mocks.execFileSync,
+    spawn: mocks.spawn,
   },
   execFileSync: mocks.execFileSync,
+  spawn: mocks.spawn,
 }))
 
 vi.mock('fs', () => ({
@@ -32,6 +36,10 @@ vi.mock('@anthropic-ai/claude-agent-sdk', () => ({
   query: mocks.query,
 }))
 
+vi.mock('@opencode-ai/sdk/client', () => ({
+  createOpencodeClient: mocks.createOpencodeClient,
+}))
+
 import { app } from 'electron'
 import { CliAgentManager } from '@main/chat/cliAgentManager'
 
@@ -159,4 +167,29 @@ describe('CliAgentManager', () => {
       }),
     )
   })
+
+  it('switches backend and persists the active backend', async () => {
+    const store = makeStore()
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+      conversationStore: store as never,
+    })
+
+    const started = await manager.start('ws-1', 'claude-code', 'conv-switch')
+    if ('error' in started) throw new Error(started.error)
+
+    const result = await manager.switchBackend(started.sessionId, 'codex')
+
+    expect(result).toEqual({ success: true })
+    expect(manager.getSessionById(started.sessionId)?.backend).toBe('codex')
+    expect(store.saveMessages).toHaveBeenCalledWith(
+      'conv-switch',
+      expect.objectContaining({ activeBackend: 'codex' }),
+    )
+    expect(store.updateMeta).toHaveBeenCalledWith(
+      'conv-switch',
+      expect.objectContaining({ backend: 'codex' }),
+    )
+  })
 })

From 698f86d31a45473edbff74c1087b8694fb8dc265 Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 16:29:36 -0400
Subject: [PATCH 5/9] fix: opencode

---
 docs/IDE_BUILD_PLAN.md                        |   2 +
 electron.vite.config.ts                       |   7 +-
 .../src/chat/cliAdapters/openCodeAdapter.ts   |  94 +++++++++++-
 tests/unit/openCodeAdapter.test.ts            | 134 ++++++++++++++++++
 4 files changed, 230 insertions(+), 7 deletions(-)
 create mode 100644 tests/unit/openCodeAdapter.test.ts

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index 3474aab..c9f3156 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -1294,6 +1294,8 @@ These need a decision before or during the relevant phase.
 
 Track milestone completion here. Update as you go.
 
+**2026-04-08:** OpenCode adapter fixes — `openCodeAdapter` now handles the SDK's `responseStyle: 'data'` shape for `session.create()` (direct `Session` payload instead of `{ data }`) and correctly unwraps streamed `GlobalEvent.payload` SSE envelopes, which had been causing OpenCode turns to stall without rendering assistant output. Added targeted adapter diagnostics (`[OpenCodeAdapter] ...`) plus `openCodeAdapter.test.ts` coverage for the direct-session response path and wrapped SSE event shape.
+
 **2026-03-29:** Built-in chat — `useChat` refreshes after `CHAT_STREAM_END` and tool-call IPC now call `chatGetHistory(workspaceId, sessionId)` so history stays scoped to the active tab; avoids main falling back to `getMostRecent` (multi-tab isolation + pre-persist race).
 
 **2026-04-08:** Pane focus handoff fix — `EditorPane` and `TerminalPane` now move DOM focus into CodeMirror/xterm when a Dockview panel becomes active and also when a newly-created panel finishes mounting while already active. This fixes keyboard pane/tab switching paths that selected a panel without moving the caret into the target surface.
diff --git a/electron.vite.config.ts b/electron.vite.config.ts
index 42b807c..8164e2e 100644
--- a/electron.vite.config.ts
+++ b/electron.vite.config.ts
@@ -25,7 +25,12 @@ function stripDockviewStyleInject(): Plugin {
 
 export default defineConfig({
   main: {
-    plugins: [externalizeDepsPlugin({ include: ['node-pty', '@vscode/ripgrep'] })],
+    plugins: [
+      externalizeDepsPlugin({
+        include: ['node-pty', '@vscode/ripgrep'],
+        exclude: ['@opencode-ai/sdk'],
+      }),
+    ],
     build: {
       outDir: 'packages/main/dist',
       lib: {
diff --git a/packages/main/src/chat/cliAdapters/openCodeAdapter.ts b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
index baa3e3b..c5cc37b 100644
--- a/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
+++ b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
@@ -20,6 +20,12 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
         const startedAt = Date.now()
         const port = await reservePort()
         const url = `http://127.0.0.1:${port}`
+        logOpenCode('starting server', {
+          conversationId: context.conversationId,
+          hasSessionId: Boolean(currentSessionId),
+          cwd: context.cwd,
+          port,
+        })
         serverProc = spawn(
           options.executablePath,
           ['serve', '--hostname=127.0.0.1', `--port=${port}`],
@@ -34,6 +40,7 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
 
         if (!serverProc) throw new Error('Failed to start OpenCode server process')
         await waitForOpenCodeServer(serverProc, url)
+        logOpenCode('server ready', { url, conversationId: context.conversationId })
 
         const client = createOpencodeClient({
           baseUrl: url,
@@ -44,15 +51,26 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
 
         if (!currentSessionId) {
           const created = await client.session.create({ responseStyle: 'data', throwOnError: true })
-          currentSessionId = created.data.id
-          emit({ type: 'backend-state', patch: { sessionId: created.data.id } })
+          currentSessionId = extractOpenCodeSessionId(created)
+          logOpenCode('session created', {
+            conversationId: context.conversationId,
+            sessionId: currentSessionId,
+          })
+          if (currentSessionId) {
+            emit({ type: 'backend-state', patch: { sessionId: currentSessionId } })
+          }
         }
 
         if (!currentSessionId) {
           throw new Error('Failed to initialize OpenCode session')
         }
 
-        const sse = await client.global.event({ signal: undefined })
+        const sse = await client.global.event({
+          signal: undefined,
+          onSseError(error) {
+            console.error('[OpenCodeAdapter] SSE error:', error)
+          },
+        })
         const textByMessageId = new Map<string, string>()
         const timestampByMessageId = new Map<string, number>()
         const emittedAssistantIds = new Set<string>()
@@ -64,9 +82,17 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
 
         const streamTask = (async () => {
           for await (const rawEvent of sse.stream) {
-            const event = rawEvent as Record<string, any>
-            const type = typeof event.type === 'string' ? event.type : ''
-            const props = asRecord(event.properties)
+            const envelope = asRecord(rawEvent)
+            const event = asRecord(envelope?.payload) ?? envelope
+            const type = typeof event?.type === 'string' ? event.type : ''
+            const props = asRecord(event?.properties)
+
+            logOpenCode('sse event', {
+              conversationId: context.conversationId,
+              sessionId: currentSessionId,
+              directory: asString(envelope?.directory),
+              type,
+            })
 
             if (type === 'message.updated' && props?.info) {
               const info = props.info as Record<string, any>
@@ -83,6 +109,11 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
                 timestampByMessageId.set(messageId, createdAt)
                 emit({ type: 'session-meta', model })
                 emit({ type: 'backend-state', patch: { sessionId, model } })
+                logOpenCode('assistant message updated', {
+                  sessionId,
+                  messageId,
+                  model,
+                })
 
                 const nextCost = typeof info.cost === 'number' ? info.cost : 0
                 const prevCost = costByMessageId.get(messageId) ?? 0
@@ -109,8 +140,18 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
                   const prior = textByMessageId.get(messageId) ?? ''
                   textByMessageId.set(messageId, prior + delta)
                   emit({ type: 'stream-delta', messageId, delta })
+                  logOpenCode('assistant delta', {
+                    sessionId: currentSessionId,
+                    messageId,
+                    deltaLength: delta.length,
+                  })
                 } else {
                   textByMessageId.set(messageId, asString(part.text) ?? '')
+                  logOpenCode('assistant part snapshot', {
+                    sessionId: currentSessionId,
+                    messageId,
+                    textLength: (asString(part.text) ?? '').length,
+                  })
                 }
                 continue
               }
@@ -177,6 +218,11 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
                 continue
               }
               failedError = renderOpenCodeError(props.error) ?? 'OpenCode session failed'
+              console.error('[OpenCodeAdapter] session.error', {
+                conversationId: context.conversationId,
+                sessionId: currentSessionId,
+                error: failedError,
+              })
               continue
             }
 
@@ -185,11 +231,20 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
               asString(props?.sessionID) === currentSessionId &&
               promptSubmitted
             ) {
+              logOpenCode('session idle', {
+                conversationId: context.conversationId,
+                sessionId: currentSessionId,
+              })
               break
             }
           }
         })()
 
+        logOpenCode('submitting prompt', {
+          conversationId: context.conversationId,
+          sessionId: currentSessionId,
+          promptLength: context.prompt.length,
+        })
         await client.session.promptAsync({
           responseStyle: 'data',
           throwOnError: true,
@@ -199,8 +254,18 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
           },
         })
         promptSubmitted = true
+        logOpenCode('prompt submitted', {
+          conversationId: context.conversationId,
+          sessionId: currentSessionId,
+        })
 
         await streamTask
+        logOpenCode('stream complete', {
+          conversationId: context.conversationId,
+          sessionId: currentSessionId,
+          assistantMessages: textByMessageId.size,
+          failed: Boolean(failedError),
+        })
 
         for (const [messageId, text] of textByMessageId) {
           if (!text || emittedAssistantIds.has(messageId)) continue
@@ -254,6 +319,10 @@ export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBacke
         })
       })().finally(() => {
         if (!closed) {
+          logOpenCode('stopping server', {
+            conversationId: context.conversationId,
+            sessionId: currentSessionId,
+          })
           serverProc?.kill('SIGTERM')
         }
       })
@@ -330,6 +399,19 @@ function asString(value: unknown): string | undefined {
   return typeof value === 'string' ? value : undefined
 }
 
+function extractOpenCodeSessionId(value: unknown): string | undefined {
+  const payload = asRecord(value)
+  return asString(payload?.id) ?? asString(asRecord(payload?.data)?.id)
+}
+
+function logOpenCode(message: string, data?: Record<string, unknown>): void {
+  if (data) {
+    console.log(`[OpenCodeAdapter] ${message}`, data)
+    return
+  }
+  console.log(`[OpenCodeAdapter] ${message}`)
+}
+
 function renderOpenCodeError(value: unknown): string | null {
   const error = asRecord(value)
   const data = asRecord(error?.data)
diff --git a/tests/unit/openCodeAdapter.test.ts b/tests/unit/openCodeAdapter.test.ts
new file mode 100644
index 0000000..54df7ea
--- /dev/null
+++ b/tests/unit/openCodeAdapter.test.ts
@@ -0,0 +1,134 @@
+import { EventEmitter } from 'events'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  createServer: vi.fn(),
+  spawn: vi.fn(),
+  createOpencodeClient: vi.fn(),
+}))
+
+vi.mock('net', () => ({
+  default: {
+    createServer: mocks.createServer,
+  },
+  createServer: mocks.createServer,
+}))
+
+vi.mock('child_process', () => ({
+  default: {
+    spawn: mocks.spawn,
+  },
+  spawn: mocks.spawn,
+}))
+
+vi.mock('@opencode-ai/sdk/client', () => ({
+  createOpencodeClient: mocks.createOpencodeClient,
+}))
+
+import { createOpenCodeAdapter } from '../../packages/main/src/chat/cliAdapters/openCodeAdapter'
+
+function makePortServer() {
+  return {
+    once: vi.fn(),
+    listen: vi.fn((_: number, __: string, onListen?: () => void) => onListen?.()),
+    address: vi.fn(() => ({ port: 43123 })),
+    close: vi.fn((onClose?: (error?: Error) => void) => onClose?.()),
+  }
+}
+
+function makeChildProcess() {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter
+    stderr: EventEmitter
+    kill: ReturnType<typeof vi.fn>
+  }
+  proc.stdout = new EventEmitter()
+  proc.stderr = new EventEmitter()
+  proc.kill = vi.fn()
+  queueMicrotask(() => {
+    proc.stdout.emit('data', Buffer.from('opencode server listening'))
+  })
+  return proc
+}
+
+describe('createOpenCodeAdapter', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    mocks.createServer.mockImplementation(() => makePortServer())
+    mocks.spawn.mockImplementation(() => makeChildProcess())
+  })
+
+  it('accepts direct Session responses from session.create with responseStyle=data', async () => {
+    mocks.createOpencodeClient.mockReturnValue({
+      session: {
+        create: vi.fn().mockResolvedValue({ id: 'oc-session-1' }),
+        promptAsync: vi.fn().mockResolvedValue(undefined),
+      },
+      global: {
+        event: vi.fn().mockResolvedValue({
+          stream: (async function* () {
+            yield {
+              directory: '/workspace',
+              payload: {
+                type: 'message.updated',
+                properties: {
+                  info: {
+                    id: 'msg-1',
+                    sessionID: 'oc-session-1',
+                    role: 'assistant',
+                    time: { created: 123 },
+                  },
+                },
+              },
+            }
+            yield {
+              directory: '/workspace',
+              payload: {
+                type: 'message.part.updated',
+                properties: {
+                  delta: 'hello from opencode',
+                  part: {
+                    type: 'text',
+                    sessionID: 'oc-session-1',
+                    messageID: 'msg-1',
+                    text: 'hello from opencode',
+                  },
+                },
+              },
+            }
+          })(),
+        }),
+      },
+    })
+
+    const adapter = createOpenCodeAdapter({ executablePath: '/tmp/opencode' })
+    const events: unknown[] = []
+    const run = adapter.startTurn(
+      {
+        conversationId: 'conv-1',
+        cwd: '/workspace',
+        prompt: 'hello',
+        backendState: {},
+      },
+      (event: unknown) => events.push(event),
+    )
+
+    await run.completed
+
+    expect(events).toContainEqual({
+      type: 'backend-state',
+      patch: { sessionId: 'oc-session-1' },
+    })
+    expect(events).toContainEqual({
+      type: 'message',
+      message: {
+        id: 'msg-1',
+        type: 'assistant',
+        content: 'hello from opencode',
+        timestamp: 123,
+      },
+    })
+  })
+})

From c21b5641b098cdf2383454c872b5fd5b72ef53f5 Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 17:54:18 -0400
Subject: [PATCH 6/9] feat: registry-backed theme system with user themes

Replace hardcoded one-dark/one-light checks with a manifest-based theme
registry. Built-in and user-installed themes share the same shape and
load from the Electron user data themes folder. Settings persist active
theme plus default dark/light ids, and the command palette exposes
selection, default switching, registry reload, and folder open actions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/IDE_BUILD_PLAN.md                        |   10 +-
 docs/THEME_FILES.md                           |  169 +++
 packages/main/src/index.ts                    |   26 +-
 packages/main/src/preload.ts                  |   21 +-
 packages/main/src/themes/builtins.ts          |   90 ++
 packages/main/src/themes/themeRegistry.ts     |  261 ++++
 packages/renderer/src/commands/context.ts     |    4 +
 .../renderer/src/commands/domains/theme.ts    |   43 +
 .../src/commands/registerAppCommands.ts       |    2 +
 .../src/components/layout/AppShell.tsx        | 1056 ++++++++++-------
 .../src/components/layout/ThemeToggle.tsx     |   26 +-
 .../src/components/panes/SettingsPane.tsx     |   27 +-
 .../components/settings/SettingsContent.tsx   |  194 ++-
 packages/renderer/src/hooks/useTheme.ts       |  171 ++-
 .../renderer/src/lib/editor/editorTheme.ts    |  196 ++-
 packages/renderer/src/styles/inline-diff.css  |   24 +-
 .../renderer/src/styles/settings-pane.css     |   65 +-
 packages/renderer/src/styles/themes.css       |   65 +-
 packages/shared/src/index.ts                  |   34 +-
 packages/shared/src/themes.ts                 |   24 +
 tests/unit/app.test.tsx                       |   20 +-
 tests/unit/editorTheme.test.ts                |    2 +-
 tests/unit/sharedIndex.test.ts                |   13 +-
 23 files changed, 1836 insertions(+), 707 deletions(-)
 create mode 100644 docs/THEME_FILES.md
 create mode 100644 packages/main/src/themes/builtins.ts
 create mode 100644 packages/main/src/themes/themeRegistry.ts
 create mode 100644 packages/renderer/src/commands/domains/theme.ts
 create mode 100644 packages/shared/src/themes.ts

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index c9f3156..dcc016c 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -1,7 +1,7 @@
 # Custom AI-Integrated IDE — Build Plan
 
 > **Project codename:** _aIDE_
-> **Last updated:** April 2, 2026
+> **Last updated:** April 8, 2026
 > **Status:** Active development
 
 ---
@@ -115,6 +115,14 @@ A desktop IDE built specifically for the workflow of running multiple AI coding
 - [ ] Linked workspace groups — related workspaces (e.g. frontend + backend), cross-workspace terminal, shared env references
 - [ ] Worktree color coding — assign a distinct accent color to each worktree and apply it to terminal tabs, editor tabs, and pane borders so it's immediately clear which worktree a tab belongs to (branch badge pills already implemented in 5.1e)
 - [ ] Custom user themes beyond light/dark defaults
+
+### Theme System (Implemented foundation)
+
+- Themes now load through a registry-backed manifest system instead of hardcoded `one-dark` / `one-light` checks
+- Built-in themes and user-installed themes share the same manifest shape: `id`, `label`, `appearance`, and token map
+- User themes live in the app-level themes folder under Electron user data and can be reloaded without code changes
+- App settings persist the active theme plus separate default dark and default light theme ids; the toggle switches between those configured defaults
+- Command palette actions now cover selecting the active theme, changing default dark/light themes, reloading the registry, and opening the themes folder
 - [ ] Editor minimap (community CodeMirror extension or custom build)
 - [ ] Auto-update via `electron-updater` — notify + prompt (never silent restart). Compile-from-source only for MVP
 - [ ] React `ErrorBoundary` per pane (crash in one pane doesn't kill others), graceful error state UI, opt-in crash telemetry via `electron.crashReporter` or Sentry
diff --git a/docs/THEME_FILES.md b/docs/THEME_FILES.md
new file mode 100644
index 0000000..9211669
--- /dev/null
+++ b/docs/THEME_FILES.md
@@ -0,0 +1,169 @@
+# Theme Files
+
+aIDE loads custom themes from JSON files in the app themes folder.
+
+## Location
+
+- Open the folder from:
+  - Settings > Workbench > Appearance > `Open Themes Folder`
+  - Command palette: `Open Themes Folder`
+- Drop one or more `.json` files into that folder.
+- Reload themes from:
+  - Settings > Workbench > Appearance > `Reload Themes`
+  - Command palette: `Reload Themes`
+
+## Required Structure
+
+Each file must be valid JSON and contain one theme object.
+
+Required fields:
+
+- `id`: unique string id for the theme
+- `label`: human-readable name shown in the UI
+- `appearance`: must be `"dark"` or `"light"`
+- `tokens`: object whose keys are CSS custom properties beginning with `--`
+
+Optional fields:
+
+- `description`
+- `author`
+
+## Minimal Example
+
+```json
+{
+  "id": "my-dark-theme",
+  "label": "My Dark Theme",
+  "appearance": "dark",
+  "tokens": {
+    "--bg-base": "#14161a",
+    "--text-primary": "#d7dae0",
+    "--accent": "#6aa0ff"
+  }
+}
+```
+
+## Full Example
+
+```json
+{
+  "id": "forest-night",
+  "label": "Forest Night",
+  "appearance": "dark",
+  "description": "Muted green-tinted dark theme.",
+  "author": "You",
+  "tokens": {
+    "--bg-base": "#1a1f1c",
+    "--bg-elevated": "#151916",
+    "--bg-sunken": "#111512",
+    "--bg-overlay": "#101411",
+    "--bg-active-tab": "#1a1f1c",
+    "--bg-inactive-tab": "#171b18",
+    "--bg-hover": "rgba(255, 255, 255, 0.05)",
+    "--bg-selection": "rgba(98, 160, 120, 0.18)",
+    "--bg-info": "rgba(98, 160, 120, 0.12)",
+    "--bg-info-hover": "rgba(98, 160, 120, 0.22)",
+    "--text-primary": "#d7dae0",
+    "--text-secondary": "#9aa39c",
+    "--text-muted": "#68706a",
+    "--text-selected": "#ffffff",
+    "--text-info": "#74b7ff",
+    "--text-success": "#89c779",
+    "--text-warning": "#d8b36a",
+    "--text-error": "#e57c73",
+    "--border-base": "#0e120f",
+    "--border-subtle": "#283028",
+    "--accent": "#62a078",
+    "--accent-rgb": "98, 160, 120",
+    "--text-on-accent": "#ffffff",
+    "--syntax-keyword": "#c792ea",
+    "--syntax-fn": "#82aaff",
+    "--syntax-string": "#a5d6a7",
+    "--syntax-number": "#f7c873",
+    "--syntax-comment": "#5f6b66",
+    "--syntax-tag": "#f07178",
+    "--syntax-attr": "#7cc7ff",
+    "--merge-delete-bg": "rgba(240, 113, 120, 0.14)",
+    "--merge-delete-gutter": "#f07178",
+    "--merge-insert-bg": "rgba(165, 214, 167, 0.14)",
+    "--merge-insert-gutter": "#a5d6a7",
+    "--merge-char-insert": "rgba(165, 214, 167, 0.24)",
+    "--merge-char-delete": "rgba(240, 113, 120, 0.24)"
+  }
+}
+```
+
+## Supported Tokens
+
+These are the tokens the built-in themes define and the custom theme system expects.
+
+Backgrounds:
+
+- `--bg-base`
+- `--bg-elevated`
+- `--bg-sunken`
+- `--bg-overlay`
+- `--bg-active-tab`
+- `--bg-inactive-tab`
+- `--bg-hover`
+- `--bg-selection`
+- `--bg-info`
+- `--bg-info-hover`
+
+Text:
+
+- `--text-primary`
+- `--text-secondary`
+- `--text-muted`
+- `--text-selected`
+- `--text-info`
+- `--text-success`
+- `--text-warning`
+- `--text-error`
+- `--text-on-accent`
+
+Borders and accent:
+
+- `--border-base`
+- `--border-subtle`
+- `--accent`
+- `--accent-rgb`
+
+Syntax:
+
+- `--syntax-keyword`
+- `--syntax-fn`
+- `--syntax-string`
+- `--syntax-number`
+- `--syntax-comment`
+- `--syntax-tag`
+- `--syntax-attr`
+
+Inline diff:
+
+- `--merge-delete-bg`
+- `--merge-delete-gutter`
+- `--merge-insert-bg`
+- `--merge-insert-gutter`
+- `--merge-char-insert`
+- `--merge-char-delete`
+
+## Important Rules
+
+- `id` must be unique across all installed themes.
+- `appearance` controls whether the theme can be chosen as the default dark or default light theme.
+- Token keys must start with `--`.
+- Token values must be strings.
+- Only `.json` files are loaded.
+- Invalid or malformed theme files are ignored.
+
+## Fallback Behavior
+
+- If a token is missing, aIDE fills it from the built-in fallback theme of the same appearance.
+- If the active theme no longer exists, aIDE falls back to the configured default dark theme.
+- If a configured default dark/light theme no longer exists, aIDE falls back to the built-in `one-dark` or `one-light` theme.
+
+## Notes
+
+- The theme toggle switches between the configured default dark and default light themes, not between fixed built-in themes.
+- Built-in themes use the same manifest shape as custom themes.
diff --git a/packages/main/src/index.ts b/packages/main/src/index.ts
index 4ec9fac..f567c79 100644
--- a/packages/main/src/index.ts
+++ b/packages/main/src/index.ts
@@ -7,7 +7,7 @@ import Store from 'electron-store'
 import { IpcChannels, DEFAULT_SETTINGS, SENSITIVE_AGENT_KEYS } from '@aide/shared'
 import type {
   AppSettings,
-  ThemeName,
+  ThemeId,
   DirEntry,
   SearchOpts,
   ReplaceOpts,
@@ -72,6 +72,7 @@ import { AgentManager } from './chat/agentManager'
 import { CliAgentManager } from './chat/cliAgentManager'
 import { ConversationStore } from './chat/conversationStore'
 import { ClaudeNativeSessionWatcher } from './chat/claudeNativeSessionWatcher'
+import { ThemeRegistry } from './themes/themeRegistry'
 import type {
   ChatMode,
   LlmProviderConfig,
@@ -85,6 +86,9 @@ import type {
 
 const store = new Store<AppSettings>({ defaults: DEFAULT_SETTINGS })
 const workspaceRegistry = new WorkspaceRegistry()
+const themeRegistry = new ThemeRegistry(store, (snapshot) => {
+  contentView?.webContents.send(IpcChannels.THEME_CHANGED, snapshot)
+})
 
 let mainWindow: BaseWindow | null = null
 let contentView: WebContentsView | null = null
@@ -268,11 +272,19 @@ ipcMain.on(IpcChannels.WINDOW_MAXIMIZE, () => {
 ipcMain.on(IpcChannels.WINDOW_CLOSE, () => mainWindow?.close())
 
 // Theme IPC handlers
-ipcMain.handle(IpcChannels.THEME_GET, () => store.get('theme'))
-ipcMain.handle(IpcChannels.THEME_SET, (_event, theme: ThemeName) => {
-  store.set('theme', theme)
-  contentView?.webContents.send(IpcChannels.THEME_CHANGED, theme)
-})
+ipcMain.handle(IpcChannels.THEME_GET, () => themeRegistry.getSnapshot())
+ipcMain.handle(IpcChannels.THEME_LIST, () => themeRegistry.listThemes())
+ipcMain.handle(IpcChannels.THEME_SET, (_event, themeId: ThemeId) =>
+  themeRegistry.setActiveTheme(themeId),
+)
+ipcMain.handle(IpcChannels.THEME_SET_DEFAULT_DARK, (_event, themeId: ThemeId) =>
+  themeRegistry.setDefaultTheme('dark', themeId),
+)
+ipcMain.handle(IpcChannels.THEME_SET_DEFAULT_LIGHT, (_event, themeId: ThemeId) =>
+  themeRegistry.setDefaultTheme('light', themeId),
+)
+ipcMain.handle(IpcChannels.THEME_RELOAD, () => themeRegistry.reload())
+ipcMain.handle(IpcChannels.THEME_OPEN_DIRECTORY, () => themeRegistry.openThemesDirectory())
 
 // Sidebar width IPC handlers
 ipcMain.handle(IpcChannels.SIDEBAR_WIDTH_GET, () => store.get('sidebarWidth'))
@@ -1758,6 +1770,8 @@ app.whenReady().then(async () => {
   const wasCleanShutdown = store.get('cleanShutdown')
   store.set('cleanShutdown', false)
 
+  await themeRegistry.reload()
+
   buildAppMenu()
   createWindow()
   registerPtyHandlers(
diff --git a/packages/main/src/preload.ts b/packages/main/src/preload.ts
index 07a884e..000334a 100644
--- a/packages/main/src/preload.ts
+++ b/packages/main/src/preload.ts
@@ -1,7 +1,9 @@
 import { contextBridge, ipcRenderer } from 'electron'
 import { IpcChannels } from '@aide/shared'
 import type {
-  ThemeName,
+  ThemeDefinition,
+  ThemeId,
+  ThemeStateSnapshot,
   FsWatchEvent,
   GitStatusResult,
   GitignoreAuditResult,
@@ -68,10 +70,19 @@ const api: WindowApi = {
   closeWindow: () => ipcRenderer.send(IpcChannels.WINDOW_CLOSE),
 
   // Theme
-  getTheme: (): Promise<ThemeName> => ipcRenderer.invoke(IpcChannels.THEME_GET),
-  setTheme: (theme: ThemeName): Promise<void> => ipcRenderer.invoke(IpcChannels.THEME_SET, theme),
-  onThemeChanged: (callback: (theme: ThemeName) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, theme: ThemeName) => callback(theme)
+  getThemeState: (): Promise<ThemeStateSnapshot> => ipcRenderer.invoke(IpcChannels.THEME_GET),
+  listThemes: (): Promise<ThemeDefinition[]> => ipcRenderer.invoke(IpcChannels.THEME_LIST),
+  setTheme: (themeId: ThemeId): Promise<void> =>
+    ipcRenderer.invoke(IpcChannels.THEME_SET, themeId).then(() => undefined),
+  setDefaultDarkTheme: (themeId: ThemeId): Promise<void> =>
+    ipcRenderer.invoke(IpcChannels.THEME_SET_DEFAULT_DARK, themeId).then(() => undefined),
+  setDefaultLightTheme: (themeId: ThemeId): Promise<void> =>
+    ipcRenderer.invoke(IpcChannels.THEME_SET_DEFAULT_LIGHT, themeId).then(() => undefined),
+  reloadThemes: (): Promise<ThemeStateSnapshot> => ipcRenderer.invoke(IpcChannels.THEME_RELOAD),
+  openThemesDirectory: (): Promise<void> => ipcRenderer.invoke(IpcChannels.THEME_OPEN_DIRECTORY),
+  onThemeChanged: (callback: (state: ThemeStateSnapshot) => void) => {
+    const handler = (_event: Electron.IpcRendererEvent, state: ThemeStateSnapshot) =>
+      callback(state)
     ipcRenderer.on(IpcChannels.THEME_CHANGED, handler)
     return () => ipcRenderer.removeListener(IpcChannels.THEME_CHANGED, handler)
   },
diff --git a/packages/main/src/themes/builtins.ts b/packages/main/src/themes/builtins.ts
new file mode 100644
index 0000000..6bfbae6
--- /dev/null
+++ b/packages/main/src/themes/builtins.ts
@@ -0,0 +1,90 @@
+import type { ThemeManifest } from '@aide/shared'
+
+export const builtInThemeManifests: ThemeManifest[] = [
+  {
+    id: 'one-dark',
+    label: 'One Dark',
+    appearance: 'dark',
+    tokens: {
+      '--bg-base': '#282c34',
+      '--bg-elevated': '#21252b',
+      '--bg-sunken': '#1b1e24',
+      '--bg-overlay': '#1d2026',
+      '--bg-active-tab': '#282c34',
+      '--bg-inactive-tab': '#24282f',
+      '--bg-hover': 'rgba(255, 255, 255, 0.04)',
+      '--bg-selection': 'rgba(82, 139, 255, 0.15)',
+      '--bg-info': 'rgba(82, 139, 255, 0.1)',
+      '--bg-info-hover': 'rgba(82, 139, 255, 0.2)',
+      '--text-primary': '#abb2bf',
+      '--text-secondary': '#7f8694',
+      '--text-muted': '#565c68',
+      '--text-selected': '#ffffff',
+      '--text-info': 'hsl(219, 79%, 66%)',
+      '--text-success': 'hsl(140, 44%, 62%)',
+      '--text-warning': 'hsl(36, 60%, 72%)',
+      '--text-error': 'hsl(9, 100%, 64%)',
+      '--border-base': '#181a1f',
+      '--border-subtle': '#2e333b',
+      '--accent': '#528bff',
+      '--accent-rgb': '82, 139, 255',
+      '--text-on-accent': '#ffffff',
+      '--syntax-keyword': '#c678dd',
+      '--syntax-fn': '#61afef',
+      '--syntax-string': '#98c379',
+      '--syntax-number': '#d19a66',
+      '--syntax-comment': '#5c6370',
+      '--syntax-tag': '#e06c75',
+      '--syntax-attr': '#528bff',
+      '--merge-delete-bg': 'rgba(224, 108, 117, 0.12)',
+      '--merge-delete-gutter': '#e06c75',
+      '--merge-insert-bg': 'rgba(152, 195, 121, 0.12)',
+      '--merge-insert-gutter': '#98c379',
+      '--merge-char-insert': 'rgba(152, 195, 121, 0.25)',
+      '--merge-char-delete': 'rgba(224, 108, 117, 0.25)',
+    },
+  },
+  {
+    id: 'one-light',
+    label: 'One Light',
+    appearance: 'light',
+    tokens: {
+      '--bg-base': '#fafafa',
+      '--bg-elevated': '#f0f0f1',
+      '--bg-sunken': '#e8e8e9',
+      '--bg-overlay': '#e5e5e6',
+      '--bg-active-tab': '#fafafa',
+      '--bg-inactive-tab': '#eeeeef',
+      '--bg-hover': 'rgba(0, 0, 0, 0.04)',
+      '--bg-selection': 'rgba(56, 113, 220, 0.12)',
+      '--bg-info': 'rgba(56, 113, 220, 0.1)',
+      '--bg-info-hover': 'rgba(56, 113, 220, 0.2)',
+      '--text-primary': '#383a42',
+      '--text-secondary': '#696c77',
+      '--text-muted': '#a0a1a7',
+      '--text-selected': '#000000',
+      '--text-info': 'hsl(220, 100%, 45%)',
+      '--text-success': 'hsl(119, 34%, 40%)',
+      '--text-warning': 'hsl(35, 84%, 44%)',
+      '--text-error': 'hsl(5, 74%, 50%)',
+      '--border-base': '#d4d4d5',
+      '--border-subtle': '#e0e0e1',
+      '--accent': '#4078f2',
+      '--accent-rgb': '64, 120, 242',
+      '--text-on-accent': '#ffffff',
+      '--syntax-keyword': '#a626a4',
+      '--syntax-fn': '#4078f2',
+      '--syntax-string': '#50a14f',
+      '--syntax-number': '#986801',
+      '--syntax-comment': '#a0a1a7',
+      '--syntax-tag': '#e45649',
+      '--syntax-attr': '#986801',
+      '--merge-delete-bg': 'rgba(228, 86, 73, 0.10)',
+      '--merge-delete-gutter': '#e45649',
+      '--merge-insert-bg': 'rgba(80, 161, 79, 0.10)',
+      '--merge-insert-gutter': '#50a14f',
+      '--merge-char-insert': 'rgba(80, 161, 79, 0.25)',
+      '--merge-char-delete': 'rgba(228, 86, 73, 0.25)',
+    },
+  },
+]
diff --git a/packages/main/src/themes/themeRegistry.ts b/packages/main/src/themes/themeRegistry.ts
new file mode 100644
index 0000000..e29c368
--- /dev/null
+++ b/packages/main/src/themes/themeRegistry.ts
@@ -0,0 +1,261 @@
+import { app, shell } from 'electron'
+import { existsSync } from 'fs'
+import { mkdir, readdir, readFile } from 'fs/promises'
+import { join } from 'path'
+import type Store from 'electron-store'
+import type {
+  AppSettings,
+  ThemeAppearance,
+  ThemeDefinition,
+  ThemeId,
+  ThemeManifest,
+  ThemeStateSnapshot,
+} from '@aide/shared'
+import { builtInThemeManifests } from './builtins'
+
+const BUILTIN_THEME_MANIFESTS = builtInThemeManifests as ThemeManifest[]
+const BUILTIN_THEME_IDS = {
+  dark: 'one-dark',
+  light: 'one-light',
+} as const satisfies Record<ThemeAppearance, ThemeId>
+
+function normalizeTokens(tokens: Record<string, unknown>): Record<string, string> {
+  const normalized: Record<string, string> = {}
+  for (const [key, value] of Object.entries(tokens)) {
+    if (key.startsWith('--') && typeof value === 'string' && value.trim().length > 0) {
+      normalized[key] = value
+    }
+  }
+  return normalized
+}
+
+function isAppearance(value: unknown): value is ThemeAppearance {
+  return value === 'dark' || value === 'light'
+}
+
+function normalizeManifest(
+  input: unknown,
+  source: 'builtin' | 'user',
+  filePath?: string,
+): ThemeDefinition | null {
+  if (!input || typeof input !== 'object') return null
+  const raw = input as Record<string, unknown>
+  if (typeof raw.id !== 'string' || raw.id.trim().length === 0) return null
+  if (typeof raw.label !== 'string' || raw.label.trim().length === 0) return null
+  if (!isAppearance(raw.appearance)) return null
+  if (!raw.tokens || typeof raw.tokens !== 'object') return null
+
+  const tokens = normalizeTokens(raw.tokens as Record<string, unknown>)
+  if (Object.keys(tokens).length === 0) return null
+
+  return {
+    id: raw.id.trim(),
+    label: raw.label.trim(),
+    appearance: raw.appearance,
+    tokens,
+    description: typeof raw.description === 'string' ? raw.description : undefined,
+    author: typeof raw.author === 'string' ? raw.author : undefined,
+    source,
+    path: filePath,
+  }
+}
+
+function dedupeThemes(themes: ThemeDefinition[]): ThemeDefinition[] {
+  const seen = new Set<string>()
+  const deduped: ThemeDefinition[] = []
+  for (const theme of themes) {
+    if (seen.has(theme.id)) continue
+    seen.add(theme.id)
+    deduped.push(theme)
+  }
+  return deduped
+}
+
+function fallbackThemeIdForAppearance(appearance: ThemeAppearance): ThemeId {
+  return BUILTIN_THEME_IDS[appearance]
+}
+
+function themeMap(themes: ThemeDefinition[]): Map<string, ThemeDefinition> {
+  return new Map(themes.map((theme) => [theme.id, theme]))
+}
+
+function resolveThemeTokens(
+  theme: ThemeDefinition,
+  byId: Map<string, ThemeDefinition>,
+): Record<string, string> {
+  const fallback = byId.get(fallbackThemeIdForAppearance(theme.appearance))
+  return {
+    ...(fallback?.tokens ?? {}),
+    ...theme.tokens,
+  }
+}
+
+function resolveThemeDefinition(
+  theme: ThemeDefinition,
+  byId: Map<string, ThemeDefinition>,
+): ThemeDefinition {
+  return {
+    ...theme,
+    tokens: resolveThemeTokens(theme, byId),
+  }
+}
+
+export class ThemeRegistry {
+  private snapshot: ThemeStateSnapshot | null = null
+
+  constructor(
+    private readonly store: Store<AppSettings>,
+    private readonly onChanged: (snapshot: ThemeStateSnapshot) => void,
+  ) {}
+
+  private getThemesDirectoryPath(): string {
+    return join(app.getPath('userData'), 'themes')
+  }
+
+  async ensureThemesDirectory(): Promise<string> {
+    const dir = this.getThemesDirectoryPath()
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true })
+    }
+    return dir
+  }
+
+  private migrateLegacySettings(): void {
+    const legacyStore = this.store as unknown as Store<Record<string, unknown>>
+    const legacyTheme = legacyStore.get('theme')
+    if (typeof legacyTheme === 'string' && legacyTheme.trim().length > 0) {
+      if (!this.store.get('activeThemeId')) this.store.set('activeThemeId', legacyTheme)
+      if (legacyTheme === BUILTIN_THEME_IDS.dark && !this.store.get('defaultDarkThemeId')) {
+        this.store.set('defaultDarkThemeId', legacyTheme)
+      }
+      if (legacyTheme === BUILTIN_THEME_IDS.light && !this.store.get('defaultLightThemeId')) {
+        this.store.set('defaultLightThemeId', legacyTheme)
+      }
+      legacyStore.delete('theme')
+    }
+  }
+
+  async reload(): Promise<ThemeStateSnapshot> {
+    this.migrateLegacySettings()
+    const builtins = BUILTIN_THEME_MANIFESTS.map((theme) =>
+      normalizeManifest(theme, 'builtin'),
+    ).filter((theme): theme is ThemeDefinition => theme !== null)
+    const dir = await this.ensureThemesDirectory()
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+    const userThemes: ThemeDefinition[] = []
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue
+      const filePath = join(dir, entry.name)
+      try {
+        const raw = JSON.parse(await readFile(filePath, 'utf-8')) as unknown
+        const theme = normalizeManifest(raw, 'user', filePath)
+        if (theme) userThemes.push(theme)
+      } catch {
+        // Ignore malformed theme files; the registry stays resilient and can be reloaded after fixes.
+      }
+    }
+
+    const themes = dedupeThemes([...builtins, ...userThemes])
+    const baseMap = themeMap(themes)
+    const resolvedThemes = themes.map((theme) => resolveThemeDefinition(theme, baseMap))
+    const resolvedMap = themeMap(resolvedThemes)
+
+    const darkThemes = resolvedThemes.filter((theme) => theme.appearance === 'dark')
+    const lightThemes = resolvedThemes.filter((theme) => theme.appearance === 'light')
+
+    const defaultDarkThemeId = this.resolveStoredThemeId(
+      this.store.get('defaultDarkThemeId'),
+      darkThemes,
+      BUILTIN_THEME_IDS.dark,
+    )
+    const defaultLightThemeId = this.resolveStoredThemeId(
+      this.store.get('defaultLightThemeId'),
+      lightThemes,
+      BUILTIN_THEME_IDS.light,
+    )
+
+    const requestedActiveThemeId = this.store.get('activeThemeId')
+    const activeThemeId =
+      typeof requestedActiveThemeId === 'string' && resolvedMap.has(requestedActiveThemeId)
+        ? requestedActiveThemeId
+        : defaultDarkThemeId
+
+    const snapshot: ThemeStateSnapshot = {
+      themes: resolvedThemes,
+      activeThemeId,
+      defaultDarkThemeId,
+      defaultLightThemeId,
+    }
+
+    this.store.set('activeThemeId', snapshot.activeThemeId)
+    this.store.set('defaultDarkThemeId', snapshot.defaultDarkThemeId)
+    this.store.set('defaultLightThemeId', snapshot.defaultLightThemeId)
+    this.snapshot = snapshot
+    this.onChanged(snapshot)
+    return snapshot
+  }
+
+  private resolveStoredThemeId(
+    requested: unknown,
+    themes: ThemeDefinition[],
+    fallbackId: ThemeId,
+  ): ThemeId {
+    if (typeof requested === 'string' && themes.some((theme) => theme.id === requested)) {
+      return requested
+    }
+    const fallback = themes.find((theme) => theme.id === fallbackId) ?? themes[0]
+    return fallback?.id ?? fallbackId
+  }
+
+  async getSnapshot(): Promise<ThemeStateSnapshot> {
+    return this.snapshot ?? this.reload()
+  }
+
+  async listThemes(): Promise<ThemeDefinition[]> {
+    return (await this.getSnapshot()).themes
+  }
+
+  async setActiveTheme(themeId: ThemeId): Promise<ThemeStateSnapshot> {
+    const snapshot = await this.getSnapshot()
+    if (!snapshot.themes.some((theme) => theme.id === themeId)) return snapshot
+    if (snapshot.activeThemeId === themeId) return snapshot
+    this.store.set('activeThemeId', themeId)
+    this.snapshot = { ...snapshot, activeThemeId: themeId }
+    this.onChanged(this.snapshot)
+    return this.snapshot
+  }
+
+  async setDefaultTheme(
+    appearance: ThemeAppearance,
+    themeId: ThemeId,
+  ): Promise<ThemeStateSnapshot> {
+    const snapshot = await this.getSnapshot()
+    const match = snapshot.themes.find(
+      (theme) => theme.id === themeId && theme.appearance === appearance,
+    )
+    if (!match) return snapshot
+
+    const key = appearance === 'dark' ? 'defaultDarkThemeId' : 'defaultLightThemeId'
+    if (snapshot[key] === themeId) return snapshot
+
+    this.store.set(key, themeId)
+    this.snapshot = { ...snapshot, [key]: themeId }
+    this.onChanged(this.snapshot)
+    return this.snapshot
+  }
+
+  async toggleTheme(): Promise<ThemeStateSnapshot> {
+    const snapshot = await this.getSnapshot()
+    const current = snapshot.themes.find((theme) => theme.id === snapshot.activeThemeId)
+    if (!current) return snapshot
+    const nextThemeId =
+      current.appearance === 'dark' ? snapshot.defaultLightThemeId : snapshot.defaultDarkThemeId
+    return this.setActiveTheme(nextThemeId)
+  }
+
+  async openThemesDirectory(): Promise<void> {
+    const dir = await this.ensureThemesDirectory()
+    await shell.openPath(dir)
+  }
+}
diff --git a/packages/renderer/src/commands/context.ts b/packages/renderer/src/commands/context.ts
index 28e1998..3f140bc 100644
--- a/packages/renderer/src/commands/context.ts
+++ b/packages/renderer/src/commands/context.ts
@@ -49,6 +49,10 @@ export interface CommandContext {
   openCommandPalette: () => void
   openQuickOpen: () => void
   openNewBrowserModal: () => void
+  openThemePicker: (mode: 'active' | 'dark' | 'light') => void
+  toggleTheme: () => void
+  reloadThemes: () => Promise<void>
+  openThemesDirectory: () => Promise<void>
 
   persistWorkspaceRuntime: () => void
 
diff --git a/packages/renderer/src/commands/domains/theme.ts b/packages/renderer/src/commands/domains/theme.ts
new file mode 100644
index 0000000..e6ef68d
--- /dev/null
+++ b/packages/renderer/src/commands/domains/theme.ts
@@ -0,0 +1,43 @@
+import type { GetCommandContext } from '../context'
+import type { CommandSpec } from './types'
+
+export function collectThemeCommands(getCtx: GetCommandContext): CommandSpec[] {
+  return [
+    {
+      def: { id: 'theme.select', label: 'Select Color Theme', category: 'Preferences' },
+      handler: () => getCtx().openThemePicker('active'),
+    },
+    {
+      def: { id: 'theme.toggle', label: 'Toggle Color Theme', category: 'Preferences' },
+      handler: () => getCtx().toggleTheme(),
+    },
+    {
+      def: {
+        id: 'theme.setDefaultDark',
+        label: 'Set Default Dark Theme',
+        category: 'Preferences',
+      },
+      handler: () => getCtx().openThemePicker('dark'),
+    },
+    {
+      def: {
+        id: 'theme.setDefaultLight',
+        label: 'Set Default Light Theme',
+        category: 'Preferences',
+      },
+      handler: () => getCtx().openThemePicker('light'),
+    },
+    {
+      def: { id: 'theme.reload', label: 'Reload Themes', category: 'Preferences' },
+      handler: () => {
+        void getCtx().reloadThemes()
+      },
+    },
+    {
+      def: { id: 'theme.openFolder', label: 'Open Themes Folder', category: 'Preferences' },
+      handler: () => {
+        void getCtx().openThemesDirectory()
+      },
+    },
+  ]
+}
diff --git a/packages/renderer/src/commands/registerAppCommands.ts b/packages/renderer/src/commands/registerAppCommands.ts
index 2a5e513..4ad2daa 100644
--- a/packages/renderer/src/commands/registerAppCommands.ts
+++ b/packages/renderer/src/commands/registerAppCommands.ts
@@ -14,6 +14,7 @@ import { collectEditorCommands } from './domains/editor'
 import { collectPaneCommands } from './domains/panes'
 import { collectTaskCommands } from './domains/tasks'
 import { collectTerminalCommands } from './domains/terminal'
+import { collectThemeCommands } from './domains/theme'
 import { collectViewCommands } from './domains/view'
 import { collectWorkspaceCommands } from './domains/workspace'
 
@@ -33,6 +34,7 @@ export function registerAppCommands(getContext: GetCommandContext): void {
     collectAgentCommands,
     collectTerminalCommands,
     collectTaskCommands,
+    collectThemeCommands,
     collectAideCommands,
   ]
 
diff --git a/packages/renderer/src/components/layout/AppShell.tsx b/packages/renderer/src/components/layout/AppShell.tsx
index a850ee1..0e4e013 100644
--- a/packages/renderer/src/components/layout/AppShell.tsx
+++ b/packages/renderer/src/components/layout/AppShell.tsx
@@ -22,9 +22,13 @@ import { NewBrowserPaneModal } from '../modals/NewBrowserPaneModal'
 import { loadKeybindings } from '../../commands/KeybindingService'
 import { defaultKeybindings } from '../../commands/defaultKeybindings'
 import { useTasks } from '../../hooks/useTasks'
+import { useTheme } from '../../hooks/useTheme'
 import { useWorkspaces } from '../../hooks/useWorkspaces'
 import { useRuntimeGlobalNotifications } from '../../hooks/useRuntimeGlobalNotifications'
-import { autoSave, switchWorkspace as doSwitchWorkspace } from '../../lib/workspace/workspaceSwitcher'
+import {
+  autoSave,
+  switchWorkspace as doSwitchWorkspace,
+} from '../../lib/workspace/workspaceSwitcher'
 import { createTerminalPanelParams, getTerminalParams } from '../../lib/terminal/terminalState'
 import { createBrowserPanelParams, getBrowserParams } from '../../lib/browserState'
 import { getPanelZoomFactor, updatePanelZoomParams } from '../../lib/panelZoom'
@@ -52,6 +56,7 @@ import {
 } from '../../lib/workspace/taskInputInboxStore'
 import { scopedTo } from '../../lib/workspace/workspaceScopedListener'
 import { adjustZoomFactor, resetZoomFactor } from '@aide/shared'
+import type { SearchPanelItem } from './SearchPanel'
 
 /**
  * Top-level application shell coordinating workspace lifecycle, Dockview panels, keyboard commands, and primary UI.
@@ -80,10 +85,15 @@ export function AppShell() {
   const [gitignoreAudit, setGitignoreAudit] = useState<GitignoreAuditResult | null>(null)
   const [gitignoreModalOpen, setGitignoreModalOpen] = useState(false)
   const [taskInputRequest, setTaskInputRequest] = useState<TaskInputRequest | null>(null)
-  const [wsContextMenu, setWsContextMenu] = useState<{ id: string; x: number; y: number } | null>(null)
+  const [wsContextMenu, setWsContextMenu] = useState<{ id: string; x: number; y: number } | null>(
+    null,
+  )
   const [newBrowserPaneOpen, setNewBrowserPaneOpen] = useState(false)
   const [taskPickerItems, setTaskPickerItems] = useState<TaskPickerItem[] | null>(null)
-  const [terminatePickerExecutions, setTerminatePickerExecutions] = useState<TaskExecution[] | null>(null)
+  const [terminatePickerExecutions, setTerminatePickerExecutions] = useState<
+    TaskExecution[] | null
+  >(null)
+  const [themePickerMode, setThemePickerMode] = useState<null | 'active' | 'dark' | 'light'>(null)
   const [activeBrowserPaneId, setActiveBrowserPaneId] = useState<string | null>(null)
   const [activePanelId, setActivePanelId] = useState<string | null>(null)
   const commandContextRef = useRef<CommandContext | null>(null)
@@ -117,10 +127,26 @@ export function AppShell() {
     clearDiagnostics: clearAllDiagnostics,
   } = useTasks(activeWorkspaceId)
 
+  const {
+    themes,
+    activeThemeId,
+    defaultDarkThemeId,
+    defaultLightThemeId,
+    setTheme,
+    setDefaultDarkTheme,
+    setDefaultLightTheme,
+    toggleTheme,
+    reloadThemes,
+    openThemesDirectory,
+  } = useTheme()
+
   // Single-window shell: file tree, worktrees, and task runner UI follow the focused workspace.
   // Multi-workspace backend state uses workspace ids elsewhere (snapshots, document store, inbox).
   const workspaceRoot = activeWorkspace?.rootPath ?? null
-  const { worktrees, activeWorktree, activeRoot, switchWorktree } = useWorktrees(workspaceRoot, activeWorkspaceId)
+  const { worktrees, activeWorktree, activeRoot, switchWorktree } = useWorktrees(
+    workspaceRoot,
+    activeWorkspaceId,
+  )
 
   useEffect(() => {
     if (activeWorkspaceId) {
@@ -132,28 +158,33 @@ export function AppShell() {
     activeWorkspaceIdRef.current = activeWorkspaceId
   }, [activeWorkspaceId])
 
-  const persistWorkspaceRuntime = useCallback((
-    workspaceId: string | null = activeWorkspaceId,
-    rootPath: string | null = workspaceRoot,
-    activeWt: string | null = activeWorktree,
-  ) => {
-    const api = dockviewApiRef.current
-    if (!api || !workspaceId) return
+  const persistWorkspaceRuntime = useCallback(
+    (
+      workspaceId: string | null = activeWorkspaceId,
+      rootPath: string | null = workspaceRoot,
+      activeWt: string | null = activeWorktree,
+    ) => {
+      const api = dockviewApiRef.current
+      if (!api || !workspaceId) return
 
-    const snapshot = saveWorkspaceRuntimeSnapshot(captureWorkspaceRuntimeSnapshot(
-      api,
-      workspaceId,
-      rootPath,
-      sidebarWidthRef.current,
-      sidebarCollapsed,
-      activeWt,
-    ))
+      const snapshot = saveWorkspaceRuntimeSnapshot(
+        captureWorkspaceRuntimeSnapshot(
+          api,
+          workspaceId,
+          rootPath,
+          sidebarWidthRef.current,
+          sidebarCollapsed,
+          activeWt,
+        ),
+      )
 
-    if (snapshot.rootPath) {
-      window.api.saveWorkspaceState(snapshot.rootPath, snapshot.state).catch(() => {})
-      window.api.saveTerminalState(snapshot.rootPath, snapshot.terminals).catch(() => {})
-    }
-  }, [activeWorkspaceId, activeWorktree, sidebarCollapsed, workspaceRoot])
+      if (snapshot.rootPath) {
+        window.api.saveWorkspaceState(snapshot.rootPath, snapshot.state).catch(() => {})
+        window.api.saveTerminalState(snapshot.rootPath, snapshot.terminals).catch(() => {})
+      }
+    },
+    [activeWorkspaceId, activeWorktree, sidebarCollapsed, workspaceRoot],
+  )
 
   const handleOpenFolder = useCallback(async () => {
     // If in a blank workspace (no rootPath), set root instead of creating new
@@ -171,29 +202,39 @@ export function AppShell() {
     await window.api.createBlankWorkspace()
   }, [])
 
-  const handleCloseWorkspace = useCallback(async (id: string) => {
-    const workspace = workspaces.find((entry) => entry.id === id)
-    destroyedWorkspaceIdsRef.current.add(id)
-    clearWorkspaceRuntimeSnapshot(id)
-    window.api.browserDestroyWorkspace(id)
-    if (workspace?.rootPath) {
-      window.api.saveTerminalState(workspace.rootPath, { terminals: [], activeTerminalId: null }).catch(() => {})
-    }
-    window.api.ptyKillWorkspace(id)
-    await closeWorkspace(id)
-  }, [closeWorkspace, workspaces])
-
-  const handleRemoveWorkspace = useCallback(async (id: string) => {
-    const workspace = workspaces.find((entry) => entry.id === id)
-    destroyedWorkspaceIdsRef.current.add(id)
-    clearWorkspaceRuntimeSnapshot(id)
-    window.api.browserDestroyWorkspace(id)
-    if (workspace?.rootPath) {
-      window.api.saveTerminalState(workspace.rootPath, { terminals: [], activeTerminalId: null }).catch(() => {})
-    }
-    window.api.ptyKillWorkspace(id)
-    await removeWorkspace(id)
-  }, [removeWorkspace, workspaces])
+  const handleCloseWorkspace = useCallback(
+    async (id: string) => {
+      const workspace = workspaces.find((entry) => entry.id === id)
+      destroyedWorkspaceIdsRef.current.add(id)
+      clearWorkspaceRuntimeSnapshot(id)
+      window.api.browserDestroyWorkspace(id)
+      if (workspace?.rootPath) {
+        window.api
+          .saveTerminalState(workspace.rootPath, { terminals: [], activeTerminalId: null })
+          .catch(() => {})
+      }
+      window.api.ptyKillWorkspace(id)
+      await closeWorkspace(id)
+    },
+    [closeWorkspace, workspaces],
+  )
+
+  const handleRemoveWorkspace = useCallback(
+    async (id: string) => {
+      const workspace = workspaces.find((entry) => entry.id === id)
+      destroyedWorkspaceIdsRef.current.add(id)
+      clearWorkspaceRuntimeSnapshot(id)
+      window.api.browserDestroyWorkspace(id)
+      if (workspace?.rootPath) {
+        window.api
+          .saveTerminalState(workspace.rootPath, { terminals: [], activeTerminalId: null })
+          .catch(() => {})
+      }
+      window.api.ptyKillWorkspace(id)
+      await removeWorkspace(id)
+    },
+    [removeWorkspace, workspaces],
+  )
 
   const showWelcomeLayout = useCallback((api: DockviewApi) => {
     const panels = [...api.panels]
@@ -213,7 +254,9 @@ export function AppShell() {
     if (!api) return
     const prevRoot = prevWorkspaceRootRef.current
     const prevWorkspaceId = prevWorkspaceIdRef.current
-    const wasDestroyed = prevWorkspaceId ? destroyedWorkspaceIdsRef.current.has(prevWorkspaceId) : false
+    const wasDestroyed = prevWorkspaceId
+      ? destroyedWorkspaceIdsRef.current.has(prevWorkspaceId)
+      : false
 
     if (!activeWorkspaceId) {
       if (prevWorkspaceId && !wasDestroyed) {
@@ -274,7 +317,7 @@ export function AppShell() {
       currentWorkspaceId: prevWorkspaceId,
       currentRootPath: prevRoot,
       currentActiveWorktreePath: prevWorkspaceId
-        ? worktreeByWsRef.current.get(prevWorkspaceId) ?? null
+        ? (worktreeByWsRef.current.get(prevWorkspaceId) ?? null)
         : null,
       targetWorkspaceId: activeWorkspaceId ?? '',
       targetRootPath: workspaceRoot,
@@ -301,7 +344,13 @@ export function AppShell() {
     if (prevWorkspaceId) destroyedWorkspaceIdsRef.current.delete(prevWorkspaceId)
     prevWorkspaceRootRef.current = workspaceRoot
     prevWorkspaceIdRef.current = activeWorkspaceId
-  }, [activeWorkspaceId, persistWorkspaceRuntime, showWelcomeLayout, sidebarCollapsed, workspaceRoot])
+  }, [
+    activeWorkspaceId,
+    persistWorkspaceRuntime,
+    showWelcomeLayout,
+    sidebarCollapsed,
+    workspaceRoot,
+  ])
 
   const presentGitignoreAudit = useCallback((result: GitignoreAuditResult) => {
     setGitignoreAudit(result)
@@ -311,9 +360,12 @@ export function AppShell() {
     )
   }, [])
 
-  const onGitignoreAuditFromMain = useCallback(scopedTo<GitignoreAuditIpcPayload>(activeWorkspaceId, (payload) => {
-    presentGitignoreAudit(payload.result)
-  }), [activeWorkspaceId, presentGitignoreAudit])
+  const onGitignoreAuditFromMain = useCallback(
+    scopedTo<GitignoreAuditIpcPayload>(activeWorkspaceId, (payload) => {
+      presentGitignoreAudit(payload.result)
+    }),
+    [activeWorkspaceId, presentGitignoreAudit],
+  )
 
   useEffect(() => {
     const unsub = window.api.onGitignoreAuditResult(onGitignoreAuditFromMain)
@@ -351,112 +403,120 @@ export function AppShell() {
 
   // Listen for task auto-detect results (offer to generate tasks.json)
   useEffect(() => {
-    const unsub = window.api.onTaskAutoDetect(scopedTo(activeWorkspaceId, (payload) => {
-      const { tasks } = payload
-      showToast(
-        `Detected ${tasks.length} task${tasks.length !== 1 ? 's' : ''} from project config`,
-        {
-          label: 'Generate tasks.json',
-          onClick: async () => {
-            const wid = activeWorkspaceId
-            if (!wid) return
-            const result = await window.api.generateTasks(wid)
-            if ('error' in result) {
-              showToast(result.error)
-            } else {
-              showToast('Generated .aide/tasks.json')
-            }
+    const unsub = window.api.onTaskAutoDetect(
+      scopedTo(activeWorkspaceId, (payload) => {
+        const { tasks } = payload
+        showToast(
+          `Detected ${tasks.length} task${tasks.length !== 1 ? 's' : ''} from project config`,
+          {
+            label: 'Generate tasks.json',
+            onClick: async () => {
+              const wid = activeWorkspaceId
+              if (!wid) return
+              const result = await window.api.generateTasks(wid)
+              if ('error' in result) {
+                showToast(result.error)
+              } else {
+                showToast('Generated .aide/tasks.json')
+              }
+            },
           },
-        },
-      )
-    }))
+        )
+      }),
+    )
     return unsub
   }, [activeWorkspaceId])
 
   // Terminal routing for task executions
   useEffect(() => {
-    const unsub = window.api.onTaskStatusChanged(scopedTo<TaskExecution>(activeWorkspaceId, (execution) => {
-      const api = dockviewApiRef.current
-      if (!api) return
+    const unsub = window.api.onTaskStatusChanged(
+      scopedTo<TaskExecution>(activeWorkspaceId, (execution) => {
+        const api = dockviewApiRef.current
+        if (!api) return
 
-      if (execution.status === 'running' && execution.ptyId) {
-        const policy = execution.panelPolicy ?? 'shared'
-        let panelId: string
+        if (execution.status === 'running' && execution.ptyId) {
+          const policy = execution.panelPolicy ?? 'shared'
+          let panelId: string
 
-        if (policy === 'shared') {
-          panelId = 'task-terminal-shared'
-        } else if (policy === 'dedicated') {
-          panelId = `task-terminal-${execution.taskId}`
-        } else {
-          panelId = `task-terminal-${execution.executionId}`
-        }
+          if (policy === 'shared') {
+            panelId = 'task-terminal-shared'
+          } else if (policy === 'dedicated') {
+            panelId = `task-terminal-${execution.taskId}`
+          } else {
+            panelId = `task-terminal-${execution.executionId}`
+          }
 
-        // Track mapping for cleanup
-        taskTerminalMapRef.current.set(execution.executionId, panelId)
+          // Track mapping for cleanup
+          taskTerminalMapRef.current.set(execution.executionId, panelId)
 
-        const existing = api.panels.find((p) => p.id === panelId)
-        if (existing) {
-          // Reuse: update the ptyId to the new execution's PTY
-          existing.api.updateParameters({
-            ...existing.params,
-            taskPtyId: execution.ptyId,
-            taskExecutionId: execution.executionId,
-            taskId: execution.taskId,
-            title: `Task: ${execution.taskLabel}`,
-          })
-          existing.api.setActive()
-        } else {
-          // Create new task terminal panel
-          const existingTerminal = api.panels.find(
-            (p) => p.id === 'terminal' || p.id.startsWith('terminal-'),
-          )
-          api.addPanel({
-            id: panelId,
-            component: 'terminalPane',
-            title: `Task: ${execution.taskLabel}`,
-            params: {
-              terminalId: panelId,
-              workspaceId: execution.workspaceId,
+          const existing = api.panels.find((p) => p.id === panelId)
+          if (existing) {
+            // Reuse: update the ptyId to the new execution's PTY
+            existing.api.updateParameters({
+              ...existing.params,
               taskPtyId: execution.ptyId,
               taskExecutionId: execution.executionId,
               taskId: execution.taskId,
               title: `Task: ${execution.taskLabel}`,
-              zoomFactor: 1,
-            },
-            position: existingTerminal ? { referencePanel: existingTerminal } : undefined,
-          })
+            })
+            existing.api.setActive()
+          } else {
+            // Create new task terminal panel
+            const existingTerminal = api.panels.find(
+              (p) => p.id === 'terminal' || p.id.startsWith('terminal-'),
+            )
+            api.addPanel({
+              id: panelId,
+              component: 'terminalPane',
+              title: `Task: ${execution.taskLabel}`,
+              params: {
+                terminalId: panelId,
+                workspaceId: execution.workspaceId,
+                taskPtyId: execution.ptyId,
+                taskExecutionId: execution.executionId,
+                taskId: execution.taskId,
+                title: `Task: ${execution.taskLabel}`,
+                zoomFactor: 1,
+              },
+              position: existingTerminal ? { referencePanel: existingTerminal } : undefined,
+            })
+          }
         }
-      }
 
-      // Handle close-on-exit for 'new' policy terminals
-      if (
-        execution.status === 'succeeded'
-        && execution.closeOnExit
-        && execution.panelPolicy === 'new'
-      ) {
-        const termPanelId = taskTerminalMapRef.current.get(execution.executionId)
-        if (termPanelId && api) {
-          const panel = api.panels.find((p) => p.id === termPanelId)
-          if (panel) {
-            setTimeout(() => panel.api.close(), 500)
+        // Handle close-on-exit for 'new' policy terminals
+        if (
+          execution.status === 'succeeded' &&
+          execution.closeOnExit &&
+          execution.panelPolicy === 'new'
+        ) {
+          const termPanelId = taskTerminalMapRef.current.get(execution.executionId)
+          if (termPanelId && api) {
+            const panel = api.panels.find((p) => p.id === termPanelId)
+            if (panel) {
+              setTimeout(() => panel.api.close(), 500)
+            }
           }
+          taskTerminalMapRef.current.delete(execution.executionId)
         }
-        taskTerminalMapRef.current.delete(execution.executionId)
-      }
-    }))
+      }),
+    )
     return unsub
   }, [activeWorkspaceId])
 
   // Listen for task trigger results (auto-run outcomes) and show toasts
   useEffect(() => {
-    const unsub = window.api.onTaskTriggerResult(scopedTo<TaskTriggerResult>(activeWorkspaceId, (result) => {
-      if (result.outcome === 'failed') {
-        showToast(`Task "${result.taskLabel}" failed to start: ${result.message ?? 'unknown error'}`)
-      } else if (result.outcome === 'skipped') {
-        // Silently skip - no toast needed for already-running tasks
-      }
-      // 'started' is normal, no toast needed
-    }))
+    const unsub = window.api.onTaskTriggerResult(
+      scopedTo<TaskTriggerResult>(activeWorkspaceId, (result) => {
+        if (result.outcome === 'failed') {
+          showToast(
+            `Task "${result.taskLabel}" failed to start: ${result.message ?? 'unknown error'}`,
+          )
+        } else if (result.outcome === 'skipped') {
+          // Silently skip - no toast needed for already-running tasks
+        }
+        // 'started' is normal, no toast needed
+      }),
+    )
     return unsub
   }, [activeWorkspaceId])
 
@@ -471,7 +531,8 @@ export function AppShell() {
     } else if (taskDiagnostics.length > 0) {
       // Open the Problems panel on first diagnostics
       const existingTerminal = api.panels.find(
-        (p) => p.id === 'terminal' || p.id.startsWith('terminal-') || p.id.startsWith('task-terminal-'),
+        (p) =>
+          p.id === 'terminal' || p.id.startsWith('terminal-') || p.id.startsWith('task-terminal-'),
       )
       api.addPanel({
         id: 'problems',
@@ -495,13 +556,14 @@ export function AppShell() {
 
   useEffect(() => {
     const shouldSuppress =
-      commandPaletteOpen
-      || quickOpenOpen
-      || gitignoreModalOpen
-      || !!taskInputRequest
-      || newBrowserPaneOpen
-      || !!taskPickerItems
-      || !!terminatePickerExecutions
+      commandPaletteOpen ||
+      quickOpenOpen ||
+      gitignoreModalOpen ||
+      !!taskInputRequest ||
+      newBrowserPaneOpen ||
+      !!taskPickerItems ||
+      !!terminatePickerExecutions ||
+      themePickerMode !== null
     if (shouldSuppress) {
       window.api.browserSuppressOverlays()
     } else {
@@ -514,55 +576,108 @@ export function AppShell() {
     quickOpenOpen,
     taskInputRequest,
     taskPickerItems,
+    themePickerMode,
     terminatePickerExecutions,
   ])
 
-  useEffect(() => {
-    const unsub = window.api.onBrowserFocusChanged(scopedTo(activeWorkspaceId, ({ paneId, focused }) => {
-      if (focused) {
-        setActiveBrowserPaneId(paneId)
-        setContext('browserFocused', true)
-      } else {
-        setActiveBrowserPaneId((current) => {
-          const next = current === paneId ? null : current
-          setContext('browserFocused', next !== null)
-          return next
+  const openThemePicker = useCallback((mode: 'active' | 'dark' | 'light') => {
+    setCommandPaletteOpen(false)
+    setQuickOpenOpen(false)
+    setThemePickerMode(mode)
+  }, [])
+
+  const themePickerItems: SearchPanelItem[] =
+    themePickerMode === null
+      ? []
+      : (themePickerMode === 'dark'
+          ? themes.filter((theme) => theme.appearance === 'dark')
+          : themePickerMode === 'light'
+            ? themes.filter((theme) => theme.appearance === 'light')
+            : themes
+        ).map((theme) => {
+          const selectedThemeId =
+            themePickerMode === 'dark'
+              ? defaultDarkThemeId
+              : themePickerMode === 'light'
+                ? defaultLightThemeId
+                : activeThemeId
+
+          return {
+            id: theme.id,
+            label: theme.label,
+            description: `${theme.appearance}${theme.id === selectedThemeId ? ' • current' : ''}`,
+            searchText: `${theme.label} ${theme.id} ${theme.appearance} ${theme.source}`,
+          }
         })
+
+  const handleThemePickerSelect = useCallback(
+    (id: string) => {
+      if (themePickerMode === 'dark') {
+        void setDefaultDarkTheme(id)
+      } else if (themePickerMode === 'light') {
+        void setDefaultLightTheme(id)
+      } else {
+        void setTheme(id)
       }
-    }))
+      setThemePickerMode(null)
+    },
+    [setDefaultDarkTheme, setDefaultLightTheme, setTheme, themePickerMode],
+  )
+
+  useEffect(() => {
+    const unsub = window.api.onBrowserFocusChanged(
+      scopedTo(activeWorkspaceId, ({ paneId, focused }) => {
+        if (focused) {
+          setActiveBrowserPaneId(paneId)
+          setContext('browserFocused', true)
+        } else {
+          setActiveBrowserPaneId((current) => {
+            const next = current === paneId ? null : current
+            setContext('browserFocused', next !== null)
+            return next
+          })
+        }
+      }),
+    )
     return unsub
   }, [activeWorkspaceId])
 
-  const updateActivePanelZoom = useCallback(async (nextZoom: number) => {
-    const api = dockviewApiRef.current
-    if (!api || !activePanelId) return
-    const activePanel = api.panels.find((panel) => panel.id === activePanelId)
-    if (!activePanel) return
-
-    const browserParams = getBrowserParams(activePanel)
-    if (browserParams) {
-      const appliedZoom = await window.api.setBrowserZoom(browserParams.paneId, nextZoom)
-      activePanel.api.updateParameters({ ...browserParams, zoomFactor: appliedZoom })
+  const updateActivePanelZoom = useCallback(
+    async (nextZoom: number) => {
+      const api = dockviewApiRef.current
+      if (!api || !activePanelId) return
+      const activePanel = api.panels.find((panel) => panel.id === activePanelId)
+      if (!activePanel) return
+
+      const browserParams = getBrowserParams(activePanel)
+      if (browserParams) {
+        const appliedZoom = await window.api.setBrowserZoom(browserParams.paneId, nextZoom)
+        activePanel.api.updateParameters({ ...browserParams, zoomFactor: appliedZoom })
+        persistWorkspaceRuntime()
+        return
+      }
+
+      activePanel.api.updateParameters(
+        updatePanelZoomParams(activePanel.params as Record<string, unknown> | undefined, nextZoom),
+      )
       persistWorkspaceRuntime()
-      return
-    }
+    },
+    [activePanelId, persistWorkspaceRuntime],
+  )
 
-    activePanel.api.updateParameters(updatePanelZoomParams(
-      (activePanel.params as Record<string, unknown> | undefined),
-      nextZoom,
-    ))
-    persistWorkspaceRuntime()
-  }, [activePanelId, persistWorkspaceRuntime])
-
-  const handleZoomCommand = useCallback((action: 'in' | 'out' | 'reset') => {
-    const activePanel = dockviewApiRef.current?.panels.find((panel) => panel.id === activePanelId)
-    if (!activePanel) return
-    const currentZoom = getPanelZoomFactor(activePanel.params)
-    const nextZoom = action === 'reset'
-      ? resetZoomFactor()
-      : adjustZoomFactor(currentZoom, action === 'in' ? 0.1 : -0.1)
-    void updateActivePanelZoom(nextZoom)
-  }, [activePanelId, updateActivePanelZoom])
+  const handleZoomCommand = useCallback(
+    (action: 'in' | 'out' | 'reset') => {
+      const activePanel = dockviewApiRef.current?.panels.find((panel) => panel.id === activePanelId)
+      if (!activePanel) return
+      const currentZoom = getPanelZoomFactor(activePanel.params)
+      const nextZoom =
+        action === 'reset'
+          ? resetZoomFactor()
+          : adjustZoomFactor(currentZoom, action === 'in' ? 0.1 : -0.1)
+      void updateActivePanelZoom(nextZoom)
+    },
+    [activePanelId, updateActivePanelZoom],
+  )
 
   useEffect(() => {
     return window.api.onZoomCommand(({ action, target }) => {
@@ -606,7 +721,9 @@ export function AppShell() {
   // Handle crash recovery notification
   useEffect(() => {
     const unsub = window.api.onCrashDetected(() => {
-      showToast('aIDE recovered from an unexpected shutdown. Some recent changes may not have been saved.')
+      showToast(
+        'aIDE recovered from an unexpected shutdown. Some recent changes may not have been saved.',
+      )
     })
     return unsub
   }, [])
@@ -630,9 +747,7 @@ export function AppShell() {
       component: 'markdownPreview',
       title: `Preview: ${name}`,
       params: { filePath },
-      position: editorPanel
-        ? { referencePanel: editorPanel, direction: 'right' }
-        : undefined,
+      position: editorPanel ? { referencePanel: editorPanel, direction: 'right' } : undefined,
     })
   }, [])
 
@@ -673,6 +788,12 @@ export function AppShell() {
         setQuickOpenOpen(false)
         setNewBrowserPaneOpen(true)
       },
+      openThemePicker,
+      toggleTheme: () => {
+        void toggleTheme()
+      },
+      reloadThemes,
+      openThemesDirectory,
       persistWorkspaceRuntime,
       presentGitignoreAudit,
       openTaskPicker: (items) => setTaskPickerItems(items),
@@ -702,11 +823,15 @@ export function AppShell() {
     handleNewBlankWorkspace,
     handleOpenFolder,
     killTask,
+    openThemePicker,
     openMarkdownPreview,
+    openThemesDirectory,
     persistWorkspaceRuntime,
     presentGitignoreAudit,
+    reloadThemes,
     reloadTasks,
     runTask,
+    toggleTheme,
     switchWorkspace,
     workspaceRoot,
     workspaces,
@@ -716,112 +841,120 @@ export function AppShell() {
     registerAppCommands(() => commandContextRef.current!)
   }, [])
 
-  const onApiReady = useCallback((api: DockviewApi) => {
-    dockviewApiRef.current = api
-    dockviewNavigationRef.current = new DockviewNavigation(api)
-
-    // Auto-close preview pane when its source editor is closed
-    api.onDidRemovePanel((event) => {
-      const previewId = `preview:${event.id}`
-      const preview = api.panels.find((p) => p.id === previewId)
-      if (preview) preview.api.close()
-
-      const terminalParams = getTerminalParams(event)
-      if (terminalParams?.terminalId) {
-        const shouldPreserve = preservedTerminalIdsRef.current.has(terminalParams.terminalId)
-        if (!shouldPreserve) {
-          window.api.ptyKill(terminalParams.terminalId)
-          persistWorkspaceRuntime()
+  const onApiReady = useCallback(
+    (api: DockviewApi) => {
+      dockviewApiRef.current = api
+      dockviewNavigationRef.current = new DockviewNavigation(api)
+
+      // Auto-close preview pane when its source editor is closed
+      api.onDidRemovePanel((event) => {
+        const previewId = `preview:${event.id}`
+        const preview = api.panels.find((p) => p.id === previewId)
+        if (preview) preview.api.close()
+
+        const terminalParams = getTerminalParams(event)
+        if (terminalParams?.terminalId) {
+          const shouldPreserve = preservedTerminalIdsRef.current.has(terminalParams.terminalId)
+          if (!shouldPreserve) {
+            window.api.ptyKill(terminalParams.terminalId)
+            persistWorkspaceRuntime()
+          }
         }
-      }
-
-      const browserParams = getBrowserParams(event)
-      if (browserParams && !isSwitchingWorkspaceRef.current) {
-        setActiveBrowserPaneId((current) => (current === browserParams.paneId ? null : current))
-        setContext('browserFocused', false)
-        window.api.browserDestroy(browserParams.paneId)
-        persistWorkspaceRuntime()
-      }
-    })
 
-    // Track which pane type is focused
-    api.onDidActivePanelChange((panel) => {
-      if (!panel) {
-        setActivePanelId(null)
-        setContext('editorFocused', false)
-        setContext('terminalFocused', false)
-        setContext('browserFocused', false)
-        return
-      }
-      const id = panel.id
-      setActivePanelId(id)
-      const isTerminal = id === 'terminal' || id.startsWith('terminal-')
-      const browserParams = getBrowserParams(panel)
-      const isBrowser = !!browserParams
-      setActiveBrowserPaneId(browserParams?.paneId ?? null)
-      setContext('terminalFocused', isTerminal)
-      setContext('browserFocused', isBrowser)
-      setContext('editorFocused', !isTerminal && !isBrowser)
-    })
-
-    // Initialize keybinding service: load defaults, then layer user overrides
-    window.api
-      .getKeybindingOverrides()
-      .then((overrides) => {
-        loadKeybindings(defaultKeybindings, overrides)
+        const browserParams = getBrowserParams(event)
+        if (browserParams && !isSwitchingWorkspaceRef.current) {
+          setActiveBrowserPaneId((current) => (current === browserParams.paneId ? null : current))
+          setContext('browserFocused', false)
+          window.api.browserDestroy(browserParams.paneId)
+          persistWorkspaceRuntime()
+        }
       })
-      .catch((err) => {
-        console.error('Failed to load keybinding overrides:', err)
-        loadKeybindings(defaultKeybindings, [])
+
+      // Track which pane type is focused
+      api.onDidActivePanelChange((panel) => {
+        if (!panel) {
+          setActivePanelId(null)
+          setContext('editorFocused', false)
+          setContext('terminalFocused', false)
+          setContext('browserFocused', false)
+          return
+        }
+        const id = panel.id
+        setActivePanelId(id)
+        const isTerminal = id === 'terminal' || id.startsWith('terminal-')
+        const browserParams = getBrowserParams(panel)
+        const isBrowser = !!browserParams
+        setActiveBrowserPaneId(browserParams?.paneId ?? null)
+        setContext('terminalFocused', isTerminal)
+        setContext('browserFocused', isBrowser)
+        setContext('editorFocused', !isTerminal && !isBrowser)
       })
-  }, [persistWorkspaceRuntime])
 
-  const onFileOpen = useCallback((filePath: string, opts?: OpenFileOpts) => {
-    const api = dockviewApiRef.current
-    if (!api) return
+      // Initialize keybinding service: load defaults, then layer user overrides
+      window.api
+        .getKeybindingOverrides()
+        .then((overrides) => {
+          loadKeybindings(defaultKeybindings, overrides)
+        })
+        .catch((err) => {
+          console.error('Failed to load keybinding overrides:', err)
+          loadKeybindings(defaultKeybindings, [])
+        })
+    },
+    [persistWorkspaceRuntime],
+  )
 
-    // If panel already exists, focus it and optionally jump to line
-    const existing = api.panels.find((p) => p.id === filePath)
-    if (existing) {
-      existing.api.setActive()
-      if (opts?.line) {
-        existing.api.updateParameters({ ...existing.params, jumpToLine: opts.line, jumpToColumn: opts.column })
-      }
-      return
-    }
+  const onFileOpen = useCallback(
+    (filePath: string, opts?: OpenFileOpts) => {
+      const api = dockviewApiRef.current
+      if (!api) return
 
-    // Extract filename for tab title
-    const name = filePath.split('/').pop() ?? filePath
+      // If panel already exists, focus it and optionally jump to line
+      const existing = api.panels.find((p) => p.id === filePath)
+      if (existing) {
+        existing.api.setActive()
+        if (opts?.line) {
+          existing.api.updateParameters({
+            ...existing.params,
+            jumpToLine: opts.line,
+            jumpToColumn: opts.column,
+          })
+        }
+        return
+      }
 
-    // Find the editor group (first group, or wherever the welcome panel lives)
-    const welcomePanel = api.panels.find((p) => p.id === 'editor')
-    const position = welcomePanel
-      ? { referencePanel: welcomePanel }
-      : undefined
+      // Extract filename for tab title
+      const name = filePath.split('/').pop() ?? filePath
 
-    api.addPanel({
-      id: filePath,
-      component: 'editorPane',
-      tabComponent: 'editorTab',
-      title: name,
-      params: {
-        filePath,
-        workspaceRoot,
-        workspaceId: activeWorkspaceId ?? undefined,
-        jumpToLine: opts?.line,
-        jumpToColumn: opts?.column,
-      },
-      position,
-    })
+      // Find the editor group (first group, or wherever the welcome panel lives)
+      const welcomePanel = api.panels.find((p) => p.id === 'editor')
+      const position = welcomePanel ? { referencePanel: welcomePanel } : undefined
 
-    // Suggest preview for markdown files
-    if (filePath.endsWith('.md')) {
-      showToast('Markdown file detected', {
-        label: 'Open Preview',
-        onClick: () => openMarkdownPreview(filePath),
+      api.addPanel({
+        id: filePath,
+        component: 'editorPane',
+        tabComponent: 'editorTab',
+        title: name,
+        params: {
+          filePath,
+          workspaceRoot,
+          workspaceId: activeWorkspaceId ?? undefined,
+          jumpToLine: opts?.line,
+          jumpToColumn: opts?.column,
+        },
+        position,
       })
-    }
-  }, [activeWorkspaceId, openMarkdownPreview, workspaceRoot])
+
+      // Suggest preview for markdown files
+      if (filePath.endsWith('.md')) {
+        showToast('Markdown file detected', {
+          label: 'Open Preview',
+          onClick: () => openMarkdownPreview(filePath),
+        })
+      }
+    },
+    [activeWorkspaceId, openMarkdownPreview, workspaceRoot],
+  )
 
   // Register app-wide action dispatch layer — re-register when onFileOpen changes
   // so workspace root stays current after workspace switches.
@@ -832,22 +965,25 @@ export function AppShell() {
     })
   }, [onFileOpen])
 
-  const handleCreateBrowserPane = useCallback((sessionMode: BrowserSessionMode, url: string) => {
-    const api = dockviewApiRef.current
-    if (!api || !activeWorkspaceId) return
+  const handleCreateBrowserPane = useCallback(
+    (sessionMode: BrowserSessionMode, url: string) => {
+      const api = dockviewApiRef.current
+      if (!api || !activeWorkspaceId) return
 
-    const activePanel = api.activePanel
-    const params = createBrowserPanelParams(activeWorkspaceId, sessionMode, url.trim())
-    api.addPanel({
-      id: params.paneId,
-      component: 'browserPane',
-      title: 'Browser',
-      params,
-      position: activePanel ? { referencePanel: activePanel, direction: 'right' } : undefined,
-    })
-    setNewBrowserPaneOpen(false)
-    persistWorkspaceRuntime()
-  }, [activeWorkspaceId, persistWorkspaceRuntime])
+      const activePanel = api.activePanel
+      const params = createBrowserPanelParams(activeWorkspaceId, sessionMode, url.trim())
+      api.addPanel({
+        id: params.paneId,
+        component: 'browserPane',
+        title: 'Browser',
+        params,
+        position: activePanel ? { referencePanel: activePanel, direction: 'right' } : undefined,
+      })
+      setNewBrowserPaneOpen(false)
+      persistWorkspaceRuntime()
+    },
+    [activeWorkspaceId, persistWorkspaceRuntime],
+  )
 
   return (
     <div className="app-shell">
@@ -907,7 +1043,9 @@ export function AppShell() {
                     const branch = worktrees.find((w) => w.path === worktreePath)?.branch
 
                     const editorPanel = api.panels.find(
-                      (p) => p.id === 'editor' || (p.params as Record<string, unknown> | undefined)?.filePath,
+                      (p) =>
+                        p.id === 'editor' ||
+                        (p.params as Record<string, unknown> | undefined)?.filePath,
                     )
 
                     // Capture workspace identity at click time so async IPC
@@ -915,160 +1053,173 @@ export function AppShell() {
                     // wrong Dockview or persist runtime under a stale id.
                     const initialWorkspaceId = activeWorkspaceId
                     const isStillCurrent = () =>
-                      dockviewApiRef.current === api && activeWorkspaceIdRef.current === initialWorkspaceId
+                      dockviewApiRef.current === api &&
+                      activeWorkspaceIdRef.current === initialWorkspaceId
 
-                    window.api.getResolvedSettings(activeWorkspaceId).then((resolved) => {
-                      if (!isStillCurrent()) return
-                      const backend = resolved['agent.backend'] ?? 'built-in'
+                    window.api
+                      .getResolvedSettings(activeWorkspaceId)
+                      .then((resolved) => {
+                        if (!isStillCurrent()) return
+                        const backend = resolved['agent.backend'] ?? 'built-in'
 
-                      if (isCliBackend(backend)) {
-                        void window.api.conversationCreate({
-                          workspaceId: activeWorkspaceId,
-                          backend,
-                          worktreePath,
-                          worktreeBranch: branch,
-                        }).then((meta) => {
-                          if (!isStillCurrent()) return
-                          api.addPanel({
-                            id: `agent-${Date.now()}`,
-                            component: 'cliAgentPane',
-                            tabComponent: 'agentTab',
-                            title: branch
-                              ? `${backendLabel(backend)} (${branch})`
-                              : backendLabel(backend),
-                            params: {
+                        if (isCliBackend(backend)) {
+                          void window.api
+                            .conversationCreate({
                               workspaceId: activeWorkspaceId,
-                              workspaceRoot: workspaceRoot ?? undefined,
                               backend,
-                              conversationId: meta.id,
                               worktreePath,
                               worktreeBranch: branch,
-                            },
-                            position: editorPanel
-                              ? { referencePanel: editorPanel, direction: 'right' }
-                              : undefined,
-                            initialWidth: 400,
-                          })
-                          persistWorkspaceRuntime()
-                        }).catch(() => {
-                          if (!isStillCurrent()) return
-                          api.addPanel({
-                            id: `agent-${Date.now()}`,
-                            component: 'cliAgentPane',
-                            tabComponent: 'agentTab',
-                            title: branch
-                              ? `${backendLabel(backend)} (${branch})`
-                              : backendLabel(backend),
-                            params: {
+                            })
+                            .then((meta) => {
+                              if (!isStillCurrent()) return
+                              api.addPanel({
+                                id: `agent-${Date.now()}`,
+                                component: 'cliAgentPane',
+                                tabComponent: 'agentTab',
+                                title: branch
+                                  ? `${backendLabel(backend)} (${branch})`
+                                  : backendLabel(backend),
+                                params: {
+                                  workspaceId: activeWorkspaceId,
+                                  workspaceRoot: workspaceRoot ?? undefined,
+                                  backend,
+                                  conversationId: meta.id,
+                                  worktreePath,
+                                  worktreeBranch: branch,
+                                },
+                                position: editorPanel
+                                  ? { referencePanel: editorPanel, direction: 'right' }
+                                  : undefined,
+                                initialWidth: 400,
+                              })
+                              persistWorkspaceRuntime()
+                            })
+                            .catch(() => {
+                              if (!isStillCurrent()) return
+                              api.addPanel({
+                                id: `agent-${Date.now()}`,
+                                component: 'cliAgentPane',
+                                tabComponent: 'agentTab',
+                                title: branch
+                                  ? `${backendLabel(backend)} (${branch})`
+                                  : backendLabel(backend),
+                                params: {
+                                  workspaceId: activeWorkspaceId,
+                                  workspaceRoot: workspaceRoot ?? undefined,
+                                  backend,
+                                  worktreePath,
+                                  worktreeBranch: branch,
+                                },
+                                position: editorPanel
+                                  ? { referencePanel: editorPanel, direction: 'right' }
+                                  : undefined,
+                                initialWidth: 400,
+                              })
+                              persistWorkspaceRuntime()
+                            })
+                        } else {
+                          void window.api
+                            .conversationCreate({
                               workspaceId: activeWorkspaceId,
-                              workspaceRoot: workspaceRoot ?? undefined,
-                              backend,
+                              backend: 'built-in',
                               worktreePath,
                               worktreeBranch: branch,
-                            },
-                            position: editorPanel
-                              ? { referencePanel: editorPanel, direction: 'right' }
-                              : undefined,
-                            initialWidth: 400,
-                          })
-                          persistWorkspaceRuntime()
-                        })
-                      } else {
-                        void window.api.conversationCreate({
-                          workspaceId: activeWorkspaceId,
-                          backend: 'built-in',
-                          worktreePath,
-                          worktreeBranch: branch,
-                        }).then((meta) => {
-                          if (!isStillCurrent()) return
-                          api.addPanel({
-                            id: `agent-${Date.now()}`,
-                            component: 'chatPane',
-                            tabComponent: 'agentTab',
-                            title: branch ? `Agent (${branch})` : 'Agent',
-                            params: {
-                              workspaceId: activeWorkspaceId,
-                              workspaceRoot: workspaceRoot ?? undefined,
-                              conversationId: meta.id,
-                              worktreePath,
-                              worktreeBranch: branch,
-                            },
-                            position: editorPanel
-                              ? { referencePanel: editorPanel, direction: 'right' }
-                              : undefined,
-                            initialWidth: 350,
-                          })
-                          persistWorkspaceRuntime()
-                        }).catch(() => {
-                          if (!isStillCurrent()) return
-                          api.addPanel({
-                            id: `agent-${Date.now()}`,
-                            component: 'chatPane',
-                            tabComponent: 'agentTab',
-                            title: branch ? `Agent (${branch})` : 'Agent',
-                            params: {
-                              workspaceId: activeWorkspaceId,
-                              workspaceRoot: workspaceRoot ?? undefined,
-                              worktreePath,
-                              worktreeBranch: branch,
-                            },
-                            position: editorPanel
-                              ? { referencePanel: editorPanel, direction: 'right' }
-                              : undefined,
-                            initialWidth: 350,
-                          })
-                          persistWorkspaceRuntime()
-                        })
-                      }
-                    }).catch(() => {
-                      if (!isStillCurrent()) return
-                      // Fallback to built-in
-                      void window.api.conversationCreate({
-                        workspaceId: activeWorkspaceId,
-                        backend: 'built-in',
-                        worktreePath,
-                        worktreeBranch: branch,
-                      }).then((meta) => {
-                        if (!isStillCurrent()) return
-                        api.addPanel({
-                          id: `agent-${Date.now()}`,
-                          component: 'chatPane',
-                          tabComponent: 'agentTab',
-                          title: branch ? `Agent (${branch})` : 'Agent',
-                          params: {
-                            workspaceId: activeWorkspaceId,
-                            workspaceRoot: workspaceRoot ?? undefined,
-                            conversationId: meta.id,
-                            worktreePath,
-                            worktreeBranch: branch,
-                          },
-                          position: editorPanel
-                            ? { referencePanel: editorPanel, direction: 'right' }
-                            : undefined,
-                          initialWidth: 350,
-                        })
-                        persistWorkspaceRuntime()
-                      }).catch(() => {
+                            })
+                            .then((meta) => {
+                              if (!isStillCurrent()) return
+                              api.addPanel({
+                                id: `agent-${Date.now()}`,
+                                component: 'chatPane',
+                                tabComponent: 'agentTab',
+                                title: branch ? `Agent (${branch})` : 'Agent',
+                                params: {
+                                  workspaceId: activeWorkspaceId,
+                                  workspaceRoot: workspaceRoot ?? undefined,
+                                  conversationId: meta.id,
+                                  worktreePath,
+                                  worktreeBranch: branch,
+                                },
+                                position: editorPanel
+                                  ? { referencePanel: editorPanel, direction: 'right' }
+                                  : undefined,
+                                initialWidth: 350,
+                              })
+                              persistWorkspaceRuntime()
+                            })
+                            .catch(() => {
+                              if (!isStillCurrent()) return
+                              api.addPanel({
+                                id: `agent-${Date.now()}`,
+                                component: 'chatPane',
+                                tabComponent: 'agentTab',
+                                title: branch ? `Agent (${branch})` : 'Agent',
+                                params: {
+                                  workspaceId: activeWorkspaceId,
+                                  workspaceRoot: workspaceRoot ?? undefined,
+                                  worktreePath,
+                                  worktreeBranch: branch,
+                                },
+                                position: editorPanel
+                                  ? { referencePanel: editorPanel, direction: 'right' }
+                                  : undefined,
+                                initialWidth: 350,
+                              })
+                              persistWorkspaceRuntime()
+                            })
+                        }
+                      })
+                      .catch(() => {
                         if (!isStillCurrent()) return
-                        api.addPanel({
-                          id: `agent-${Date.now()}`,
-                          component: 'chatPane',
-                          tabComponent: 'agentTab',
-                          title: branch ? `Agent (${branch})` : 'Agent',
-                          params: {
+                        // Fallback to built-in
+                        void window.api
+                          .conversationCreate({
                             workspaceId: activeWorkspaceId,
-                            workspaceRoot: workspaceRoot ?? undefined,
+                            backend: 'built-in',
                             worktreePath,
                             worktreeBranch: branch,
-                          },
-                          position: editorPanel
-                            ? { referencePanel: editorPanel, direction: 'right' }
-                            : undefined,
-                          initialWidth: 350,
-                        })
-                        persistWorkspaceRuntime()
+                          })
+                          .then((meta) => {
+                            if (!isStillCurrent()) return
+                            api.addPanel({
+                              id: `agent-${Date.now()}`,
+                              component: 'chatPane',
+                              tabComponent: 'agentTab',
+                              title: branch ? `Agent (${branch})` : 'Agent',
+                              params: {
+                                workspaceId: activeWorkspaceId,
+                                workspaceRoot: workspaceRoot ?? undefined,
+                                conversationId: meta.id,
+                                worktreePath,
+                                worktreeBranch: branch,
+                              },
+                              position: editorPanel
+                                ? { referencePanel: editorPanel, direction: 'right' }
+                                : undefined,
+                              initialWidth: 350,
+                            })
+                            persistWorkspaceRuntime()
+                          })
+                          .catch(() => {
+                            if (!isStillCurrent()) return
+                            api.addPanel({
+                              id: `agent-${Date.now()}`,
+                              component: 'chatPane',
+                              tabComponent: 'agentTab',
+                              title: branch ? `Agent (${branch})` : 'Agent',
+                              params: {
+                                workspaceId: activeWorkspaceId,
+                                workspaceRoot: workspaceRoot ?? undefined,
+                                worktreePath,
+                                worktreeBranch: branch,
+                              },
+                              position: editorPanel
+                                ? { referencePanel: editorPanel, direction: 'right' }
+                                : undefined,
+                              initialWidth: 350,
+                            })
+                            persistWorkspaceRuntime()
+                          })
                       })
-                    })
                   }}
                 />
               </SidebarSection>
@@ -1081,14 +1232,9 @@ export function AppShell() {
       </div>
       <StatusBar workspaceId={activeWorkspaceId} runningTasks={runningTasks} />
       <ToastContainer />
-      {commandPaletteOpen && (
-        <CommandPalette onClose={() => setCommandPaletteOpen(false)} />
-      )}
+      {commandPaletteOpen && <CommandPalette onClose={() => setCommandPaletteOpen(false)} />}
       {quickOpenOpen && (
-        <QuickOpen
-          onClose={() => setQuickOpenOpen(false)}
-          workspaceRoot={activeRoot}
-        />
+        <QuickOpen onClose={() => setQuickOpenOpen(false)} workspaceRoot={activeRoot} />
       )}
       {gitignoreModalOpen && gitignoreAudit && activeWorkspaceId && (
         <GitignoreReviewModal
@@ -1101,10 +1247,7 @@ export function AppShell() {
         />
       )}
       {taskInputRequest && (
-        <TaskInputModal
-          request={taskInputRequest}
-          onClose={dismissTaskInputModal}
-        />
+        <TaskInputModal request={taskInputRequest} onClose={dismissTaskInputModal} />
       )}
       {taskPickerItems && (
         <TaskSelectModal
@@ -1134,6 +1277,21 @@ export function AppShell() {
           onClose={() => setTerminatePickerExecutions(null)}
         />
       )}
+      {themePickerMode && (
+        <TaskSelectModal
+          title={
+            themePickerMode === 'dark'
+              ? 'Default dark theme'
+              : themePickerMode === 'light'
+                ? 'Default light theme'
+                : 'Color theme'
+          }
+          placeholder="Select a theme…"
+          items={themePickerItems}
+          onSelect={handleThemePickerSelect}
+          onClose={() => setThemePickerMode(null)}
+        />
+      )}
       {newBrowserPaneOpen && (
         <NewBrowserPaneModal
           onClose={() => setNewBrowserPaneOpen(false)}
diff --git a/packages/renderer/src/components/layout/ThemeToggle.tsx b/packages/renderer/src/components/layout/ThemeToggle.tsx
index e078408..0b0265f 100644
--- a/packages/renderer/src/components/layout/ThemeToggle.tsx
+++ b/packages/renderer/src/components/layout/ThemeToggle.tsx
@@ -2,7 +2,13 @@ import { useTheme } from '../../hooks/useTheme'
 
 function SunIcon() {
   return (
-    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round">
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+    >
       <circle cx="8" cy="8" r="3" />
       <path d="M8 2v1.5M8 12.5V14M2 8h1.5M12.5 8H14M3.75 3.75l1.06 1.06M11.19 11.19l1.06 1.06M3.75 12.25l1.06-1.06M11.19 4.81l1.06-1.06" />
     </svg>
@@ -11,7 +17,13 @@ function SunIcon() {
 
 function MoonIcon() {
   return (
-    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round">
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+    >
       <path d="M13.36 10.03A5.5 5.5 0 0 1 5.97 2.64 6 6 0 1 0 13.36 10.03Z" />
     </svg>
   )
@@ -19,10 +31,16 @@ function MoonIcon() {
 
 export function ThemeToggle() {
   const { theme, toggleTheme } = useTheme()
+  const nextLabel = theme.appearance === 'dark' ? 'light' : 'dark'
 
   return (
-    <button className="ribbon-icon-btn" onClick={toggleTheme} title="Toggle theme">
-      {theme === 'one-dark' ? <SunIcon /> : <MoonIcon />}
+    <button
+      type="button"
+      className="ribbon-icon-btn"
+      onClick={() => void toggleTheme()}
+      title={`Switch to ${nextLabel} theme`}
+    >
+      {theme.appearance === 'dark' ? <SunIcon /> : <MoonIcon />}
     </button>
   )
 }
diff --git a/packages/renderer/src/components/panes/SettingsPane.tsx b/packages/renderer/src/components/panes/SettingsPane.tsx
index a77245b..5a00bd6 100644
--- a/packages/renderer/src/components/panes/SettingsPane.tsx
+++ b/packages/renderer/src/components/panes/SettingsPane.tsx
@@ -14,7 +14,18 @@ interface SettingsPaneParams {
 export function SettingsPane({ params }: IDockviewPanelProps<SettingsPaneParams>) {
   const [settingsWorkspaceId, setSettingsWorkspaceId] = useState<string | null>(null)
   const settings = useSettings(settingsWorkspaceId)
-  const { theme } = useTheme()
+  const {
+    themes,
+    theme,
+    activeThemeId,
+    defaultDarkThemeId,
+    defaultLightThemeId,
+    setTheme,
+    setDefaultDarkTheme,
+    setDefaultLightTheme,
+    reloadThemes,
+    openThemesDirectory,
+  } = useTheme()
   const [searchQuery, setSearchQuery] = useState('')
   const [activeCategory, setActiveCategory] = useState('textEditor.font')
   const [workspaceAvailable, setWorkspaceAvailable] = useState(false)
@@ -40,10 +51,6 @@ export function SettingsPane({ params }: IDockviewPanelProps<SettingsPaneParams>
 
   const categoriesWithSettings = getCategoriesWithSettings()
 
-  const handleThemeChange = (newTheme: 'one-dark' | 'one-light') => {
-    window.api.setTheme(newTheme)
-  }
-
   if (settings.loading) {
     return (
       <div className="settings-pane" style={{ zoom: params.zoomFactor ?? 1 }}>
@@ -74,8 +81,16 @@ export function SettingsPane({ params }: IDockviewPanelProps<SettingsPaneParams>
           settings={settings}
           activeCategory={activeCategory}
           searchQuery={searchQuery}
+          themes={themes}
           theme={theme}
-          onThemeChange={handleThemeChange}
+          activeThemeId={activeThemeId}
+          defaultDarkThemeId={defaultDarkThemeId}
+          defaultLightThemeId={defaultLightThemeId}
+          onThemeChange={(themeId) => void setTheme(themeId)}
+          onDefaultDarkThemeChange={(themeId) => void setDefaultDarkTheme(themeId)}
+          onDefaultLightThemeChange={(themeId) => void setDefaultLightTheme(themeId)}
+          onReloadThemes={() => void reloadThemes()}
+          onOpenThemesDirectory={() => void openThemesDirectory()}
         />
       </div>
     </div>
diff --git a/packages/renderer/src/components/settings/SettingsContent.tsx b/packages/renderer/src/components/settings/SettingsContent.tsx
index 107b504..dd62aeb 100644
--- a/packages/renderer/src/components/settings/SettingsContent.tsx
+++ b/packages/renderer/src/components/settings/SettingsContent.tsx
@@ -10,23 +10,50 @@ import {
 import { SettingRow } from './SettingRow'
 import { KeyboardShortcutsTable } from './KeyboardShortcutsTable'
 import { ToolPermissionsEditor } from './ToolPermissionsEditor'
-import type { ThemeName, ToolPermissionConfig } from '@aide/shared'
+import type { ThemeDefinition, ThemeId, ToolPermissionConfig } from '@aide/shared'
 
 interface Props {
   settings: UseSettingsReturn
   activeCategory: string
   searchQuery: string
-  theme: ThemeName
-  onThemeChange: (theme: ThemeName) => void
+  themes: ThemeDefinition[]
+  theme: ThemeDefinition
+  activeThemeId: ThemeId
+  defaultDarkThemeId: ThemeId
+  defaultLightThemeId: ThemeId
+  onThemeChange: (themeId: ThemeId) => void
+  onDefaultDarkThemeChange: (themeId: ThemeId) => void
+  onDefaultLightThemeChange: (themeId: ThemeId) => void
+  onReloadThemes: () => void
+  onOpenThemesDirectory: () => void
 }
 
-export function SettingsContent({ settings, activeCategory, searchQuery, theme, onThemeChange }: Props) {
+export function SettingsContent({
+  settings,
+  activeCategory,
+  searchQuery,
+  themes,
+  theme,
+  activeThemeId,
+  defaultDarkThemeId,
+  defaultLightThemeId,
+  onThemeChange,
+  onDefaultDarkThemeChange,
+  onDefaultLightThemeChange,
+  onReloadThemes,
+  onOpenThemesDirectory,
+}: Props) {
   const filteredSections = useMemo(() => {
     if (searchQuery) {
       return getSearchResults(searchQuery)
     }
     return getCategorySections(activeCategory)
   }, [activeCategory, searchQuery])
+  const darkThemes = useMemo(() => themes.filter((entry) => entry.appearance === 'dark'), [themes])
+  const lightThemes = useMemo(
+    () => themes.filter((entry) => entry.appearance === 'light'),
+    [themes],
+  )
 
   return (
     <div className="settings-content">
@@ -36,59 +63,140 @@ export function SettingsContent({ settings, activeCategory, searchQuery, theme,
 
           {/* Special: Theme picker in Workbench > Appearance */}
           {section.categoryId === 'workbench.appearance' && (
-            <div className="settings-row">
-              <div className="settings-row__info">
-                <div className="settings-row__label-line">
-                  <span className="settings-row__label">Color Theme</span>
+            <>
+              <div className="settings-row">
+                <div className="settings-row__info">
+                  <div className="settings-row__label-line">
+                    <span className="settings-row__label">Color Theme</span>
+                  </div>
+                  <span className="settings-row__description">
+                    Specifies the color theme used in the workbench.
+                  </span>
+                </div>
+                <div className="settings-row__control">
+                  <select
+                    className="settings-input settings-input--select"
+                    value={activeThemeId}
+                    onChange={(e) => onThemeChange(e.target.value)}
+                  >
+                    {themes.map((entry) => (
+                      <option key={entry.id} value={entry.id}>
+                        {entry.label}
+                      </option>
+                    ))}
+                  </select>
                 </div>
-                <span className="settings-row__description">Specifies the color theme used in the workbench.</span>
               </div>
-              <div className="settings-row__control">
-                <select
-                  className="settings-input settings-input--select"
-                  value={theme}
-                  onChange={(e) => onThemeChange(e.target.value as ThemeName)}
-                >
-                  <option value="one-dark">One Dark</option>
-                  <option value="one-light">One Light</option>
-                </select>
+
+              <div className="settings-row">
+                <div className="settings-row__info">
+                  <div className="settings-row__label-line">
+                    <span className="settings-row__label">Default Dark Theme</span>
+                  </div>
+                  <span className="settings-row__description">
+                    Used when the theme toggle switches into dark mode.
+                  </span>
+                </div>
+                <div className="settings-row__control">
+                  <select
+                    className="settings-input settings-input--select"
+                    value={defaultDarkThemeId}
+                    onChange={(e) => onDefaultDarkThemeChange(e.target.value)}
+                  >
+                    {darkThemes.map((entry) => (
+                      <option key={entry.id} value={entry.id}>
+                        {entry.label}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              </div>
+
+              <div className="settings-row">
+                <div className="settings-row__info">
+                  <div className="settings-row__label-line">
+                    <span className="settings-row__label">Default Light Theme</span>
+                  </div>
+                  <span className="settings-row__description">
+                    Used when the theme toggle switches into light mode.
+                  </span>
+                </div>
+                <div className="settings-row__control">
+                  <select
+                    className="settings-input settings-input--select"
+                    value={defaultLightThemeId}
+                    onChange={(e) => onDefaultLightThemeChange(e.target.value)}
+                  >
+                    {lightThemes.map((entry) => (
+                      <option key={entry.id} value={entry.id}>
+                        {entry.label}
+                      </option>
+                    ))}
+                  </select>
+                </div>
               </div>
-            </div>
+
+              <div className="settings-row">
+                <div className="settings-row__info">
+                  <div className="settings-row__label-line">
+                    <span className="settings-row__label">Installed Themes</span>
+                  </div>
+                  <span className="settings-row__description">
+                    Themes load from your user themes folder. Current theme: {theme.label}.
+                  </span>
+                </div>
+                <div className="settings-row__control">
+                  <div className="settings-actions">
+                    <button type="button" className="settings-button" onClick={onReloadThemes}>
+                      Reload Themes
+                    </button>
+                    <button
+                      type="button"
+                      className="settings-button"
+                      onClick={onOpenThemesDirectory}
+                    >
+                      Open Themes Folder
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </>
           )}
 
           {/* Special: Keyboard Shortcuts table */}
-          {section.categoryId === 'keyboardShortcuts' && (
-            <KeyboardShortcutsTable />
-          )}
+          {section.categoryId === 'keyboardShortcuts' && <KeyboardShortcutsTable />}
 
           {/* Special: Per-tool permission overrides */}
           {section.categoryId === 'agent.permissions' && (
             <ToolPermissionsEditor
-              value={(settings.getScopeValue('agent.autoApprove') as Record<string, boolean | ToolPermissionConfig>) ?? {}}
+              value={
+                (settings.getScopeValue('agent.autoApprove') as Record<
+                  string,
+                  boolean | ToolPermissionConfig
+                >) ?? {}
+              }
               onChange={(val) => settings.setValue('agent.autoApprove', val)}
             />
           )}
 
-          {section.descriptors.length > 0 ? (
-            section.descriptors.map((desc) => (
-              <SettingRow
-                key={desc.key}
-                descriptor={desc}
-                value={settings.getScopeValue(desc.key)}
-                isModified={settings.isModified(desc.key)}
-                onChange={(value) => settings.setValue(desc.key, value)}
-                onReset={() => settings.resetToDefault(desc.key)}
-              />
-            ))
-          ) : (
-            section.categoryId !== 'workbench.appearance' &&
-            section.categoryId !== 'keyboardShortcuts' &&
-            section.categoryId !== 'agent.permissions' && (
-              <div className="settings-placeholder">
-                <p>No settings available yet.</p>
-              </div>
-            )
-          )}
+          {section.descriptors.length > 0
+            ? section.descriptors.map((desc) => (
+                <SettingRow
+                  key={desc.key}
+                  descriptor={desc}
+                  value={settings.getScopeValue(desc.key)}
+                  isModified={settings.isModified(desc.key)}
+                  onChange={(value) => settings.setValue(desc.key, value)}
+                  onReset={() => settings.resetToDefault(desc.key)}
+                />
+              ))
+            : section.categoryId !== 'workbench.appearance' &&
+              section.categoryId !== 'keyboardShortcuts' &&
+              section.categoryId !== 'agent.permissions' && (
+                <div className="settings-placeholder">
+                  <p>No settings available yet.</p>
+                </div>
+              )}
         </div>
       ))}
 
diff --git a/packages/renderer/src/hooks/useTheme.ts b/packages/renderer/src/hooks/useTheme.ts
index c5417ee..56a04df 100644
--- a/packages/renderer/src/hooks/useTheme.ts
+++ b/packages/renderer/src/hooks/useTheme.ts
@@ -1,62 +1,163 @@
-import { createContext, useContext, useState, useEffect, useCallback } from 'react'
-import type { ThemeName } from '@aide/shared'
-import { createElement, type ReactNode } from 'react'
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import type { ReactNode } from 'react'
+import type { ThemeDefinition, ThemeId, ThemeStateSnapshot } from '@aide/shared'
 
-const VALID_THEMES: ThemeName[] = ['one-dark', 'one-light']
-const DEFAULT_THEME: ThemeName = 'one-dark'
+const FALLBACK_THEMES: ThemeDefinition[] = [
+  { id: 'one-dark', label: 'One Dark', appearance: 'dark', tokens: {}, source: 'builtin' },
+  { id: 'one-light', label: 'One Light', appearance: 'light', tokens: {}, source: 'builtin' },
+]
 
-function isValidTheme(value: unknown): value is ThemeName {
-  return typeof value === 'string' && VALID_THEMES.includes(value as ThemeName)
+const FALLBACK_SNAPSHOT: ThemeStateSnapshot = {
+  themes: FALLBACK_THEMES,
+  activeThemeId: 'one-dark',
+  defaultDarkThemeId: 'one-dark',
+  defaultLightThemeId: 'one-light',
 }
 
-function applyTheme(theme: ThemeName) {
-  document.documentElement.setAttribute('data-theme', theme)
+function getActiveTheme(snapshot: ThemeStateSnapshot): ThemeDefinition {
+  return (
+    snapshot.themes.find((theme) => theme.id === snapshot.activeThemeId) ??
+    snapshot.themes[0] ??
+    FALLBACK_THEMES[0]
+  )
+}
+
+function applyThemeTokens(theme: ThemeDefinition, previousKeys: Set<string>) {
+  const root = document.documentElement
+  const nextKeys = new Set(Object.keys(theme.tokens))
+  for (const key of previousKeys) {
+    if (!nextKeys.has(key)) {
+      root.style.removeProperty(key)
+    }
+  }
+  for (const [key, value] of Object.entries(theme.tokens)) {
+    root.style.setProperty(key, value)
+  }
+  root.setAttribute('data-theme', theme.id)
+  return nextKeys
 }
 
 interface ThemeContextValue {
-  theme: ThemeName
-  toggleTheme: () => void
+  theme: ThemeDefinition
+  themes: ThemeDefinition[]
+  activeThemeId: ThemeId
+  defaultDarkThemeId: ThemeId
+  defaultLightThemeId: ThemeId
+  setTheme: (themeId: ThemeId) => Promise<void>
+  setDefaultDarkTheme: (themeId: ThemeId) => Promise<void>
+  setDefaultLightTheme: (themeId: ThemeId) => Promise<void>
+  reloadThemes: () => Promise<void>
+  openThemesDirectory: () => Promise<void>
+  toggleTheme: () => Promise<void>
 }
 
 const ThemeContext = createContext<ThemeContextValue | null>(null)
 
 export function ThemeProvider({ children }: { children: ReactNode }) {
-  const [theme, setTheme] = useState<ThemeName>(DEFAULT_THEME)
+  const [snapshot, setSnapshot] = useState<ThemeStateSnapshot>(FALLBACK_SNAPSHOT)
+  const previousTokenKeysRef = useRef<Set<string>>(new Set())
+
+  const applySnapshot = useCallback((nextSnapshot: ThemeStateSnapshot) => {
+    setSnapshot(nextSnapshot)
+    previousTokenKeysRef.current = applyThemeTokens(
+      getActiveTheme(nextSnapshot),
+      previousTokenKeysRef.current,
+    )
+  }, [])
 
   useEffect(() => {
-    // Load persisted theme from main process
+    let mounted = true
+
     window.api
-      .getTheme()
-      .then((t) => {
-        const validated = isValidTheme(t) ? t : DEFAULT_THEME
-        setTheme(validated)
-        applyTheme(validated)
+      .getThemeState()
+      .then((nextSnapshot) => {
+        if (!mounted) return
+        applySnapshot(nextSnapshot)
       })
       .catch((err) => {
-        console.warn('Failed to load persisted theme, using default:', err)
-        applyTheme(DEFAULT_THEME)
+        console.warn('Failed to load theme state, using fallback theme:', err)
+        applySnapshot(FALLBACK_SNAPSHOT)
       })
 
-    // Listen for theme changes from main process
-    const cleanup = window.api.onThemeChanged((t) => {
-      if (!isValidTheme(t)) return
-      setTheme(t)
-      applyTheme(t)
+    const cleanup = window.api.onThemeChanged((nextSnapshot) => {
+      if (!mounted) return
+      applySnapshot(nextSnapshot)
     })
 
-    return cleanup
+    return () => {
+      mounted = false
+      cleanup()
+    }
+  }, [applySnapshot])
+
+  const theme = useMemo(() => getActiveTheme(snapshot), [snapshot])
+
+  const setTheme = useCallback(async (themeId: ThemeId) => {
+    await window.api.setTheme(themeId)
   }, [])
 
-  const toggleTheme = useCallback(() => {
-    const next: ThemeName = theme === 'one-dark' ? 'one-light' : 'one-dark'
-    applyTheme(next)
-    setTheme(next)
-    window.api.setTheme(next).catch((err) => {
-      console.warn('Failed to persist theme:', err)
-    })
-  }, [theme])
+  const setDefaultDarkTheme = useCallback(async (themeId: ThemeId) => {
+    await window.api.setDefaultDarkTheme(themeId)
+  }, [])
+
+  const setDefaultLightTheme = useCallback(async (themeId: ThemeId) => {
+    await window.api.setDefaultLightTheme(themeId)
+  }, [])
+
+  const reloadThemes = useCallback(async () => {
+    const nextSnapshot = await window.api.reloadThemes()
+    applySnapshot(nextSnapshot)
+  }, [applySnapshot])
+
+  const openThemesDirectory = useCallback(async () => {
+    await window.api.openThemesDirectory()
+  }, [])
+
+  const toggleTheme = useCallback(async () => {
+    const nextThemeId =
+      theme.appearance === 'dark' ? snapshot.defaultLightThemeId : snapshot.defaultDarkThemeId
+    await window.api.setTheme(nextThemeId)
+  }, [snapshot.defaultDarkThemeId, snapshot.defaultLightThemeId, theme.appearance])
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      themes: snapshot.themes,
+      activeThemeId: snapshot.activeThemeId,
+      defaultDarkThemeId: snapshot.defaultDarkThemeId,
+      defaultLightThemeId: snapshot.defaultLightThemeId,
+      setTheme,
+      setDefaultDarkTheme,
+      setDefaultLightTheme,
+      reloadThemes,
+      openThemesDirectory,
+      toggleTheme,
+    }),
+    [
+      theme,
+      snapshot.themes,
+      snapshot.activeThemeId,
+      snapshot.defaultDarkThemeId,
+      snapshot.defaultLightThemeId,
+      setTheme,
+      setDefaultDarkTheme,
+      setDefaultLightTheme,
+      reloadThemes,
+      openThemesDirectory,
+      toggleTheme,
+    ],
+  )
 
-  return createElement(ThemeContext.Provider, { value: { theme, toggleTheme } }, children)
+  return createElement(ThemeContext.Provider, { value }, children)
 }
 
 export function useTheme(): ThemeContextValue {
diff --git a/packages/renderer/src/lib/editor/editorTheme.ts b/packages/renderer/src/lib/editor/editorTheme.ts
index 54574c7..3727740 100644
--- a/packages/renderer/src/lib/editor/editorTheme.ts
+++ b/packages/renderer/src/lib/editor/editorTheme.ts
@@ -3,8 +3,7 @@ import type { Extension } from '@codemirror/state'
 import { EditorView } from '@codemirror/view'
 import { HighlightStyle, syntaxHighlighting } from '@codemirror/language'
 import { tags } from '@lezer/highlight'
-import { oneDark } from '@codemirror/theme-one-dark'
-import type { ThemeName } from '@aide/shared'
+import type { ThemeDefinition } from '@aide/shared'
 
 export const themeCompartment = new Compartment()
 export const editorMetricsCompartment = new Compartment()
@@ -19,6 +18,10 @@ const baseTheme = EditorView.theme({
   },
 })
 
+function token(theme: ThemeDefinition, key: string, fallback: string): string {
+  return theme.tokens[key] ?? fallback
+}
+
 /**
  * Produce editor typography metrics derived from a base font size.
  *
@@ -63,72 +66,143 @@ export function getEditorMetricsExtension(fontSize: number): Extension {
   })
 }
 
-/* ─── Atom One Light — CodeMirror theme ────────────────────── */
-const oneLightTheme = EditorView.theme(
-  {
-    '&': {
-      color: '#383a42',
-      backgroundColor: '#fafafa',
+function createHighlighting(theme: ThemeDefinition): HighlightStyle {
+  return HighlightStyle.define([
+    { tag: tags.keyword, color: token(theme, '--syntax-keyword', '#c678dd') },
+    {
+      tag: [tags.name, tags.deleted, tags.character, tags.propertyName, tags.macroName],
+      color: token(theme, '--syntax-tag', '#e06c75'),
     },
-    '.cm-content': { caretColor: '#526fff' },
-    '.cm-cursor, .cm-dropCursor': { borderLeftColor: '#526fff' },
-    '&.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection':
-      { backgroundColor: 'rgba(56, 113, 220, 0.12)' },
-    '.cm-searchMatch': { backgroundColor: '#e2e8f0', outline: '1px solid #cbd5e1' },
-    '.cm-searchMatch.cm-searchMatch-selected': { backgroundColor: '#bfdbfe' },
-    '.cm-activeLine': { backgroundColor: 'rgba(0, 0, 0, 0.03)' },
-    '.cm-selectionMatch': { backgroundColor: 'rgba(56, 113, 220, 0.08)' },
-    '&.cm-focused .cm-matchingBracket, &.cm-focused .cm-nonmatchingBracket': {
-      backgroundColor: 'rgba(56, 113, 220, 0.15)',
+    {
+      tag: [tags.function(tags.variableName), tags.labelName],
+      color: token(theme, '--syntax-fn', '#61afef'),
     },
-    '.cm-gutters': {
-      backgroundColor: '#f0f0f1',
-      color: '#a0a1a7',
-      border: 'none',
+    {
+      tag: [tags.color, tags.constant(tags.name), tags.standard(tags.name)],
+      color: token(theme, '--syntax-number', '#d19a66'),
     },
-    '.cm-activeLineGutter': { backgroundColor: 'rgba(0, 0, 0, 0.04)' },
-    '.cm-foldPlaceholder': {
-      backgroundColor: 'transparent',
-      border: 'none',
-      color: '#a0a1a7',
+    {
+      tag: [tags.definition(tags.name), tags.separator],
+      color: token(theme, '--text-primary', '#abb2bf'),
     },
-    '.cm-tooltip': {
-      border: '1px solid #d4d4d5',
-      backgroundColor: '#f0f0f1',
+    {
+      tag: [
+        tags.typeName,
+        tags.className,
+        tags.number,
+        tags.changed,
+        tags.annotation,
+        tags.modifier,
+        tags.self,
+        tags.namespace,
+      ],
+      color: token(theme, '--syntax-number', '#d19a66'),
     },
-    '.cm-tooltip .cm-tooltip-arrow:before': { borderTopColor: '#d4d4d5', borderBottomColor: '#d4d4d5' },
-    '.cm-tooltip .cm-tooltip-arrow:after': { borderTopColor: '#f0f0f1', borderBottomColor: '#f0f0f1' },
-    '.cm-tooltip-autocomplete': {
-      '& > ul > li[aria-selected]': { backgroundColor: 'rgba(56, 113, 220, 0.12)', color: '#383a42' },
+    {
+      tag: [
+        tags.operator,
+        tags.operatorKeyword,
+        tags.url,
+        tags.escape,
+        tags.regexp,
+        tags.link,
+        tags.special(tags.string),
+      ],
+      color: token(theme, '--syntax-attr', '#528bff'),
     },
-  },
-  { dark: false },
-)
+    { tag: [tags.meta, tags.comment], color: token(theme, '--syntax-comment', '#5c6370') },
+    { tag: tags.strong, fontWeight: 'bold' },
+    { tag: tags.emphasis, fontStyle: 'italic' },
+    { tag: tags.strikethrough, textDecoration: 'line-through' },
+    {
+      tag: tags.link,
+      color: token(theme, '--syntax-attr', '#528bff'),
+      textDecoration: 'underline',
+    },
+    { tag: tags.heading, fontWeight: 'bold', color: token(theme, '--syntax-tag', '#e06c75') },
+    {
+      tag: [tags.atom, tags.bool, tags.special(tags.variableName)],
+      color: token(theme, '--syntax-number', '#d19a66'),
+    },
+    {
+      tag: [tags.processingInstruction, tags.string, tags.inserted],
+      color: token(theme, '--syntax-string', '#98c379'),
+    },
+    { tag: tags.invalid, color: token(theme, '--text-error', '#ff6b6b') },
+  ])
+}
 
-const oneLightHighlighting = HighlightStyle.define([
-  { tag: tags.keyword, color: '#a626a4' },
-  { tag: [tags.name, tags.deleted, tags.character, tags.propertyName, tags.macroName], color: '#e45649' },
-  { tag: [tags.function(tags.variableName), tags.labelName], color: '#4078f2' },
-  { tag: [tags.color, tags.constant(tags.name), tags.standard(tags.name)], color: '#986801' },
-  { tag: [tags.definition(tags.name), tags.separator], color: '#383a42' },
-  { tag: [tags.typeName, tags.className, tags.number, tags.changed, tags.annotation, tags.modifier, tags.self, tags.namespace], color: '#986801' },
-  { tag: [tags.operator, tags.operatorKeyword, tags.url, tags.escape, tags.regexp, tags.link, tags.special(tags.string)], color: '#0184bc' },
-  { tag: [tags.meta, tags.comment], color: '#a0a1a7' },
-  { tag: tags.strong, fontWeight: 'bold' },
-  { tag: tags.emphasis, fontStyle: 'italic' },
-  { tag: tags.strikethrough, textDecoration: 'line-through' },
-  { tag: tags.link, color: '#0184bc', textDecoration: 'underline' },
-  { tag: tags.heading, fontWeight: 'bold', color: '#e45649' },
-  { tag: [tags.atom, tags.bool, tags.special(tags.variableName)], color: '#986801' },
-  { tag: [tags.processingInstruction, tags.string, tags.inserted], color: '#50a14f' },
-  { tag: tags.invalid, color: '#986801' },
-])
+function createEditorViewTheme(theme: ThemeDefinition): Extension {
+  const accent = token(theme, '--accent', '#528bff')
+  const selection = token(theme, '--bg-selection', 'rgba(82, 139, 255, 0.15)')
+  const elevated = token(theme, '--bg-elevated', '#21252b')
+  const hover = token(theme, '--bg-hover', 'rgba(255, 255, 255, 0.04)')
+  const border = token(theme, '--border-base', '#181a1f')
+  const tooltipBorder = token(theme, '--border-subtle', '#2e333b')
 
-const oneLight: Extension = [oneLightTheme, syntaxHighlighting(oneLightHighlighting)]
+  return EditorView.theme(
+    {
+      '&': {
+        color: token(theme, '--text-primary', '#abb2bf'),
+        backgroundColor: token(theme, '--bg-base', '#282c34'),
+      },
+      '.cm-content': { caretColor: accent },
+      '.cm-cursor, .cm-dropCursor': { borderLeftColor: accent },
+      '&.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection':
+        {
+          backgroundColor: selection,
+        },
+      '.cm-searchMatch': {
+        backgroundColor: token(theme, '--bg-info', selection),
+        outline: `1px solid ${accent}`,
+      },
+      '.cm-searchMatch.cm-searchMatch-selected': {
+        backgroundColor: token(theme, '--bg-info-hover', hover),
+      },
+      '.cm-activeLine': { backgroundColor: hover },
+      '.cm-selectionMatch': { backgroundColor: selection },
+      '&.cm-focused .cm-matchingBracket, &.cm-focused .cm-nonmatchingBracket': {
+        backgroundColor: selection,
+      },
+      '.cm-gutters': {
+        backgroundColor: elevated,
+        color: token(theme, '--text-muted', '#565c68'),
+        border: 'none',
+      },
+      '.cm-activeLineGutter': { backgroundColor: hover },
+      '.cm-foldPlaceholder': {
+        backgroundColor: 'transparent',
+        border: 'none',
+        color: token(theme, '--text-muted', '#565c68'),
+      },
+      '.cm-tooltip': {
+        border: `1px solid ${tooltipBorder}`,
+        backgroundColor: elevated,
+      },
+      '.cm-panels': {
+        backgroundColor: elevated,
+        color: token(theme, '--text-primary', '#abb2bf'),
+        borderBottom: `1px solid ${border}`,
+      },
+      '.cm-tooltip .cm-tooltip-arrow:before': {
+        borderTopColor: tooltipBorder,
+        borderBottomColor: tooltipBorder,
+      },
+      '.cm-tooltip .cm-tooltip-arrow:after': {
+        borderTopColor: elevated,
+        borderBottomColor: elevated,
+      },
+      '.cm-tooltip-autocomplete': {
+        '& > ul > li[aria-selected]': {
+          backgroundColor: selection,
+          color: token(theme, '--text-primary', '#abb2bf'),
+        },
+      },
+    },
+    { dark: theme.appearance === 'dark' },
+  )
+}
 
-export function getThemeExtension(themeName: ThemeName): Extension {
-  if (themeName === 'one-dark') {
-    return [baseTheme, oneDark]
-  }
-  return [baseTheme, oneLight]
+export function getThemeExtension(theme: ThemeDefinition): Extension {
+  return [baseTheme, createEditorViewTheme(theme), syntaxHighlighting(createHighlighting(theme))]
 }
diff --git a/packages/renderer/src/styles/inline-diff.css b/packages/renderer/src/styles/inline-diff.css
index 7bedc1e..b3e503a 100644
--- a/packages/renderer/src/styles/inline-diff.css
+++ b/packages/renderer/src/styles/inline-diff.css
@@ -5,26 +5,6 @@
   width: 3px;
 }
 
-/* Override merge view colors for dark theme */
-[data-theme="one-dark"] .cm-editor {
-  /* Deleted lines (shown as inserted readonly blocks) */
-  --merge-delete-bg: rgba(224, 108, 117, 0.12);
-  --merge-delete-gutter: #e06c75;
-  --merge-insert-bg: rgba(152, 195, 121, 0.12);
-  --merge-insert-gutter: #98c379;
-  --merge-char-insert: rgba(152, 195, 121, 0.25);
-  --merge-char-delete: rgba(224, 108, 117, 0.25);
-}
-
-[data-theme="one-light"] .cm-editor {
-  --merge-delete-bg: rgba(228, 86, 73, 0.10);
-  --merge-delete-gutter: #e45649;
-  --merge-insert-bg: rgba(80, 161, 79, 0.10);
-  --merge-insert-gutter: #50a14f;
-  --merge-char-insert: rgba(80, 161, 79, 0.25);
-  --merge-char-delete: rgba(228, 86, 73, 0.25);
-}
-
 /* Deleted chunks (original content that was removed) */
 .cm-editor .cm-deletedChunk {
   background-color: var(--merge-delete-bg, rgba(224, 108, 117, 0.12));
@@ -87,7 +67,9 @@
   font-size: 11px;
   padding: 1px 6px;
   line-height: 1.4;
-  transition: background-color 0.1s, color 0.1s;
+  transition:
+    background-color 0.1s,
+    color 0.1s;
 }
 
 .cm-editor .cm-mergeControls button:hover {
diff --git a/packages/renderer/src/styles/settings-pane.css b/packages/renderer/src/styles/settings-pane.css
index cf0eef8..d25cd05 100644
--- a/packages/renderer/src/styles/settings-pane.css
+++ b/packages/renderer/src/styles/settings-pane.css
@@ -35,7 +35,9 @@
   border: none;
   border-bottom: 2px solid transparent;
   cursor: pointer;
-  transition: color 0.15s, border-color 0.15s;
+  transition:
+    color 0.15s,
+    border-color 0.15s;
 }
 
 .settings-header__tab:hover:not(:disabled) {
@@ -134,7 +136,9 @@
   border: none;
   cursor: pointer;
   text-align: left;
-  transition: background 0.1s, color 0.1s;
+  transition:
+    background 0.1s,
+    color 0.1s;
 }
 
 .settings-sidebar__button:hover {
@@ -303,6 +307,30 @@
   padding-right: 24px;
 }
 
+.settings-actions {
+  display: flex;
+  gap: 8px;
+}
+
+.settings-button {
+  font-size: 12px;
+  font-family: inherit;
+  color: var(--text-primary);
+  background: var(--bg-hover);
+  border: 1px solid var(--border-subtle);
+  border-radius: 4px;
+  padding: 5px 10px;
+  cursor: pointer;
+  transition:
+    background 120ms ease,
+    border-color 120ms ease;
+}
+
+.settings-button:hover {
+  background: var(--bg-info);
+  border-color: var(--accent);
+}
+
 /* Toggle switch */
 
 .settings-toggle {
@@ -325,7 +353,9 @@
   background: var(--bg-sunken);
   border: 1px solid var(--border-base);
   border-radius: 10px;
-  transition: background 0.2s, border-color 0.2s;
+  transition:
+    background 0.2s,
+    border-color 0.2s;
 }
 
 .settings-toggle__slider::before {
@@ -337,7 +367,9 @@
   bottom: 2px;
   background: var(--text-muted);
   border-radius: 50%;
-  transition: transform 0.2s, background 0.2s;
+  transition:
+    transform 0.2s,
+    background 0.2s;
 }
 
 .settings-toggle input:checked + .settings-toggle__slider {
@@ -479,7 +511,9 @@
   padding: 2px 6px;
   cursor: pointer;
   font-family: inherit;
-  transition: border-color 0.15s, background 0.15s;
+  transition:
+    border-color 0.15s,
+    background 0.15s;
 }
 
 .shortcuts-keybinding-button:hover {
@@ -549,8 +583,13 @@
 }
 
 @keyframes recorder-pulse {
-  0%, 100% { border-color: var(--accent); }
-  50% { border-color: color-mix(in srgb, var(--accent) 40%, transparent); }
+  0%,
+  100% {
+    border-color: var(--accent);
+  }
+  50% {
+    border-color: color-mix(in srgb, var(--accent) 40%, transparent);
+  }
 }
 
 .keybinding-recorder__conflict {
@@ -592,7 +631,9 @@
   text-transform: uppercase;
   padding: 3px 8px;
   cursor: pointer;
-  transition: color 0.1s, border-color 0.1s;
+  transition:
+    color 0.1s,
+    border-color 0.1s;
 }
 
 .settings-password__toggle:hover {
@@ -677,7 +718,9 @@
   border-radius: 5px;
   background: var(--bg-sunken);
   padding: 8px 10px;
-  transition: border-color 0.15s, background 0.15s;
+  transition:
+    border-color 0.15s,
+    background 0.15s;
 }
 
 .tp-card:hover {
@@ -764,7 +807,9 @@
   letter-spacing: 0.03em;
   cursor: pointer;
   padding: 0 10px;
-  transition: background 0.12s, color 0.12s;
+  transition:
+    background 0.12s,
+    color 0.12s;
 }
 
 .tp-card__seg:not(:last-child) {
diff --git a/packages/renderer/src/styles/themes.css b/packages/renderer/src/styles/themes.css
index 1b6c783..5799e46 100644
--- a/packages/renderer/src/styles/themes.css
+++ b/packages/renderer/src/styles/themes.css
@@ -1,6 +1,4 @@
-/* Atom One Dark — default theme */
-[data-theme="one-dark"] {
-  /* Backgrounds */
+:root {
   --bg-base: #282c34;
   --bg-elevated: #21252b;
   --bg-sunken: #1b1e24;
@@ -11,28 +9,19 @@
   --bg-selection: rgba(82, 139, 255, 0.15);
   --bg-info: rgba(82, 139, 255, 0.1);
   --bg-info-hover: rgba(82, 139, 255, 0.2);
-
-  /* Text */
   --text-primary: #abb2bf;
   --text-secondary: #7f8694;
   --text-muted: #565c68;
   --text-selected: #ffffff;
-
-  /* Semantic text */
   --text-info: hsl(219, 79%, 66%);
   --text-success: hsl(140, 44%, 62%);
   --text-warning: hsl(36, 60%, 72%);
   --text-error: hsl(9, 100%, 64%);
-
-  /* Borders */
   --border-base: #181a1f;
   --border-subtle: #2e333b;
-
-  /* Accent */
   --accent: #528bff;
+  --accent-rgb: 82, 139, 255;
   --text-on-accent: #ffffff;
-
-  /* Syntax */
   --syntax-keyword: #c678dd;
   --syntax-fn: #61afef;
   --syntax-string: #98c379;
@@ -40,48 +29,10 @@
   --syntax-comment: #5c6370;
   --syntax-tag: #e06c75;
   --syntax-attr: #528bff;
-}
-
-/* Atom One Light — built-in alternative */
-[data-theme="one-light"] {
-  /* Backgrounds */
-  --bg-base: #fafafa;
-  --bg-elevated: #f0f0f1;
-  --bg-sunken: #e8e8e9;
-  --bg-overlay: #e5e5e6;
-  --bg-active-tab: #fafafa;
-  --bg-inactive-tab: #eeeeef;
-  --bg-hover: rgba(0, 0, 0, 0.04);
-  --bg-selection: rgba(56, 113, 220, 0.12);
-  --bg-info: rgba(56, 113, 220, 0.1);
-  --bg-info-hover: rgba(56, 113, 220, 0.2);
-
-  /* Text */
-  --text-primary: #383a42;
-  --text-secondary: #696c77;
-  --text-muted: #a0a1a7;
-  --text-selected: #000000;
-
-  /* Semantic text */
-  --text-info: hsl(220, 100%, 45%);
-  --text-success: hsl(119, 34%, 40%);
-  --text-warning: hsl(35, 84%, 44%);
-  --text-error: hsl(5, 74%, 50%);
-
-  /* Borders */
-  --border-base: #d4d4d5;
-  --border-subtle: #e0e0e1;
-
-  /* Accent */
-  --accent: #4078f2;
-  --text-on-accent: #ffffff;
-
-  /* Syntax */
-  --syntax-keyword: #a626a4;
-  --syntax-fn: #4078f2;
-  --syntax-string: #50a14f;
-  --syntax-number: #986801;
-  --syntax-comment: #a0a1a7;
-  --syntax-tag: #e45649;
-  --syntax-attr: #986801;
+  --merge-delete-bg: rgba(224, 108, 117, 0.12);
+  --merge-delete-gutter: #e06c75;
+  --merge-insert-bg: rgba(152, 195, 121, 0.12);
+  --merge-insert-gutter: #98c379;
+  --merge-char-insert: rgba(152, 195, 121, 0.25);
+  --merge-char-delete: rgba(224, 108, 117, 0.25);
 }
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index f9fe997..62ebc46 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -4,6 +4,13 @@
  */
 
 export type { CommandDefinition, KeybindingRule } from './commands'
+export type {
+  ThemeAppearance,
+  ThemeDefinition,
+  ThemeId,
+  ThemeManifest,
+  ThemeStateSnapshot,
+} from './themes'
 export type {
   ChatMode,
   ChatSessionStatus,
@@ -91,6 +98,7 @@ import type {
   ConversationCreateOpts,
   ConversationListChangedPayload,
 } from './conversationTypes'
+import type { ThemeId, ThemeStateSnapshot } from './themes'
 export {
   adjustZoomFactor,
   clampZoomFactor,
@@ -114,6 +122,11 @@ export const IpcChannels = {
   THEME_GET: 'theme:get',
   THEME_SET: 'theme:set',
   THEME_CHANGED: 'theme:changed',
+  THEME_LIST: 'theme:list',
+  THEME_SET_DEFAULT_DARK: 'theme:set-default-dark',
+  THEME_SET_DEFAULT_LIGHT: 'theme:set-default-light',
+  THEME_RELOAD: 'theme:reload',
+  THEME_OPEN_DIRECTORY: 'theme:open-directory',
 
   // Fullscreen
   FULLSCREEN_CHANGED: 'fullscreen:changed',
@@ -306,7 +319,7 @@ export const IpcChannels = {
   CONVERSATION_LIST_CHANGED: 'conversation:list-changed',
 } as const
 
-export type ThemeName = 'one-dark' | 'one-light'
+export type ThemeName = ThemeId
 
 export type SettingsScope = 'user' | 'workspace'
 
@@ -369,14 +382,18 @@ export interface WorktreeCreateOpts {
 }
 
 export interface AppSettings {
-  theme: ThemeName
+  activeThemeId: ThemeId
+  defaultDarkThemeId: ThemeId
+  defaultLightThemeId: ThemeId
   sidebarWidth: number
   editorDefaults?: Partial<AideProjectSettings>
   cleanShutdown?: boolean
 }
 
 export const DEFAULT_SETTINGS: AppSettings = {
-  theme: 'one-dark',
+  activeThemeId: 'one-dark',
+  defaultDarkThemeId: 'one-dark',
+  defaultLightThemeId: 'one-light',
   sidebarWidth: 220,
 }
 
@@ -834,9 +851,14 @@ export interface WindowApi {
   closeWindow: () => void
 
   // Theme
-  getTheme: () => Promise<ThemeName>
-  setTheme: (theme: ThemeName) => Promise<void>
-  onThemeChanged: (callback: (theme: ThemeName) => void) => () => void
+  getThemeState: () => Promise<ThemeStateSnapshot>
+  listThemes: () => Promise<import('./themes').ThemeDefinition[]>
+  setTheme: (themeId: ThemeId) => Promise<void>
+  setDefaultDarkTheme: (themeId: ThemeId) => Promise<void>
+  setDefaultLightTheme: (themeId: ThemeId) => Promise<void>
+  reloadThemes: () => Promise<ThemeStateSnapshot>
+  openThemesDirectory: () => Promise<void>
+  onThemeChanged: (callback: (state: ThemeStateSnapshot) => void) => () => void
 
   // Fullscreen
   onFullscreenChanged: (callback: (isFullscreen: boolean) => void) => () => void
diff --git a/packages/shared/src/themes.ts b/packages/shared/src/themes.ts
new file mode 100644
index 0000000..cc29673
--- /dev/null
+++ b/packages/shared/src/themes.ts
@@ -0,0 +1,24 @@
+export type ThemeId = string
+
+export type ThemeAppearance = 'dark' | 'light'
+
+export interface ThemeManifest {
+  id: ThemeId
+  label: string
+  appearance: ThemeAppearance
+  tokens: Record<string, string>
+  description?: string
+  author?: string
+}
+
+export interface ThemeDefinition extends ThemeManifest {
+  source: 'builtin' | 'user'
+  path?: string
+}
+
+export interface ThemeStateSnapshot {
+  themes: ThemeDefinition[]
+  activeThemeId: ThemeId
+  defaultDarkThemeId: ThemeId
+  defaultLightThemeId: ThemeId
+}
diff --git a/tests/unit/app.test.tsx b/tests/unit/app.test.tsx
index 3a1b19b..9639d8f 100644
--- a/tests/unit/app.test.tsx
+++ b/tests/unit/app.test.tsx
@@ -11,8 +11,26 @@ const mockApi: WindowApi = {
   minimizeWindow: vi.fn(),
   maximizeWindow: vi.fn(),
   closeWindow: vi.fn(),
-  getTheme: vi.fn().mockResolvedValue('one-dark'),
+  getThemeState: vi.fn().mockResolvedValue({
+    themes: [
+      { id: 'one-dark', label: 'One Dark', appearance: 'dark', tokens: {}, source: 'builtin' },
+      { id: 'one-light', label: 'One Light', appearance: 'light', tokens: {}, source: 'builtin' },
+    ],
+    activeThemeId: 'one-dark',
+    defaultDarkThemeId: 'one-dark',
+    defaultLightThemeId: 'one-light',
+  }),
+  listThemes: vi.fn().mockResolvedValue([]),
   setTheme: vi.fn().mockResolvedValue(undefined),
+  setDefaultDarkTheme: vi.fn().mockResolvedValue(undefined),
+  setDefaultLightTheme: vi.fn().mockResolvedValue(undefined),
+  reloadThemes: vi.fn().mockResolvedValue({
+    themes: [],
+    activeThemeId: 'one-dark',
+    defaultDarkThemeId: 'one-dark',
+    defaultLightThemeId: 'one-light',
+  }),
+  openThemesDirectory: vi.fn().mockResolvedValue(undefined),
   onThemeChanged: vi.fn().mockReturnValue(() => {}),
   onFullscreenChanged: vi.fn().mockReturnValue(() => {}),
   getBrowserZoom: vi.fn().mockResolvedValue(1),
diff --git a/tests/unit/editorTheme.test.ts b/tests/unit/editorTheme.test.ts
index 32bbb51..9ecd749 100644
--- a/tests/unit/editorTheme.test.ts
+++ b/tests/unit/editorTheme.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { getEditorMetrics } from '@renderer/lib/editorTheme'
+import { getEditorMetrics } from '@renderer/lib/editor/editorTheme'
 
 describe('editorTheme metrics', () => {
   it('derives vscode-like editor metrics from font size', () => {
diff --git a/tests/unit/sharedIndex.test.ts b/tests/unit/sharedIndex.test.ts
index 85a097f..037a73a 100644
--- a/tests/unit/sharedIndex.test.ts
+++ b/tests/unit/sharedIndex.test.ts
@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { IpcChannels, adjustZoomFactor, clampZoomFactor, stepZoomFactor, zoomFactorToPercent } from '@shared/index'
+import {
+  IpcChannels,
+  adjustZoomFactor,
+  clampZoomFactor,
+  stepZoomFactor,
+  zoomFactorToPercent,
+} from '@shared/index'
 
 describe('IpcChannels', () => {
   it('defines window control channels', () => {
@@ -12,6 +18,11 @@ describe('IpcChannels', () => {
     expect(IpcChannels.THEME_GET).toBe('theme:get')
     expect(IpcChannels.THEME_SET).toBe('theme:set')
     expect(IpcChannels.THEME_CHANGED).toBe('theme:changed')
+    expect(IpcChannels.THEME_LIST).toBe('theme:list')
+    expect(IpcChannels.THEME_SET_DEFAULT_DARK).toBe('theme:set-default-dark')
+    expect(IpcChannels.THEME_SET_DEFAULT_LIGHT).toBe('theme:set-default-light')
+    expect(IpcChannels.THEME_RELOAD).toBe('theme:reload')
+    expect(IpcChannels.THEME_OPEN_DIRECTORY).toBe('theme:open-directory')
   })
 
   it('has string literal values (no accidental undefined)', () => {

From c88fd18a36e3929a7dbe3d75b68472ae65c43bed Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 17:56:36 -0400
Subject: [PATCH 7/9] feat: full @opencode-ai/sdk integration with shared
 approval surface

Promote OpenCode from a minimal per-turn shell to a first-class backend
that exposes the SDK's session, provider, permission, and rich-part
surfaces while reusing the IDE's existing permission tier and per-
workspace cost tracking. Persistent OpenCodeServerHost owns one server
per workspace with a fanned-out SSE pump; an ApprovalRouter routes
CHAT_TOOL_* IPC to whichever manager owns the toolCallId so OpenCode
permission prompts surface in the built-in approval UI. Adds rich-part
rendering, session settings pickers, diagnostics, TUI controls, an
OpenCode tools pane, and provider auth UI.

Also fixes the SSE unwrap so OpenCode chats actually reply (subscribe
to /event instead of /global/event), wires the session settings pickers
end-to-end (hook now exposes backendState with optimistic updates;
listOpenCodeTools query field names + Model shape extraction corrected),
and hides the cost badge for the Claude Code CLI harness since it bills
via subscription rather than per-token.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/IDE_BUILD_PLAN.md                        |   2 +-
 packages/main/src/chat/agentManager.ts        |  58 +-
 packages/main/src/chat/approvalRouter.ts      |  65 ++
 .../src/chat/cliAdapters/claudeCodeAdapter.ts |  46 +
 .../src/chat/cliAdapters/openCodeAdapter.ts   | 722 +++++++------
 .../chat/cliAdapters/openCodePartConverter.ts | 418 ++++++++
 .../cliAdapters/openCodePermissionBridge.ts   | 158 +++
 packages/main/src/chat/cliAdapters/types.ts   |  40 +-
 packages/main/src/chat/cliAgentManager.ts     | 967 +++++++++++++++++-
 packages/main/src/chat/openCodeServerHost.ts  | 410 ++++++++
 packages/main/src/chat/permissionMatching.ts  | 129 +++
 packages/main/src/index.ts                    | 296 +++++-
 packages/main/src/preload.ts                  | 110 ++
 .../main/src/workspace/WorkspaceRuntime.ts    |   8 +-
 packages/main/src/workspace/runtimeTypes.ts   |   2 +
 .../components/cliAgent/CostTokenBadge.tsx    |  63 ++
 .../components/cliAgent/DiagnosticsPanel.tsx  | 106 ++
 .../components/cliAgent/RichPartRenderer.tsx  | 270 +++++
 .../src/components/cliAgent/SessionMenu.tsx   | 148 +++
 .../cliAgent/SessionSettingsPanel.tsx         | 338 ++++++
 .../components/cliAgent/TuiControlPanel.tsx   |  92 ++
 .../components/layout/DockviewContainer.tsx   |   2 +
 .../src/components/panes/CliAgentPane.tsx     |  87 +-
 .../components/panes/OpenCodeToolsPane.tsx    | 291 ++++++
 .../settings/OpenCodeProvidersTab.tsx         | 197 ++++
 packages/renderer/src/hooks/useCliAgent.ts    |  88 +-
 packages/shared/src/cliAgentTypes.ts          | 226 +++-
 packages/shared/src/index.ts                  | 169 +++
 tests/unit/cliAgentApprovalRouter.test.ts     |  77 ++
 tests/unit/cliAgentManager.test.ts            |  98 ++
 tests/unit/openCodeAdapter.test.ts            | 358 +++++--
 tests/unit/openCodePartConverter.test.ts      | 169 +++
 tests/unit/openCodePermissionBridge.test.ts   | 130 +++
 tests/unit/useCliAgent.test.tsx               |   3 +
 34 files changed, 5762 insertions(+), 581 deletions(-)
 create mode 100644 packages/main/src/chat/approvalRouter.ts
 create mode 100644 packages/main/src/chat/cliAdapters/openCodePartConverter.ts
 create mode 100644 packages/main/src/chat/cliAdapters/openCodePermissionBridge.ts
 create mode 100644 packages/main/src/chat/openCodeServerHost.ts
 create mode 100644 packages/main/src/chat/permissionMatching.ts
 create mode 100644 packages/renderer/src/components/cliAgent/CostTokenBadge.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/SessionMenu.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
 create mode 100644 packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
 create mode 100644 packages/renderer/src/components/settings/OpenCodeProvidersTab.tsx
 create mode 100644 tests/unit/cliAgentApprovalRouter.test.ts
 create mode 100644 tests/unit/openCodePartConverter.test.ts
 create mode 100644 tests/unit/openCodePermissionBridge.test.ts

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index c9f3156..8cdaca3 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -1294,7 +1294,7 @@ These need a decision before or during the relevant phase.
 
 Track milestone completion here. Update as you go.
 
-**2026-04-08:** OpenCode adapter fixes — `openCodeAdapter` now handles the SDK's `responseStyle: 'data'` shape for `session.create()` (direct `Session` payload instead of `{ data }`) and correctly unwraps streamed `GlobalEvent.payload` SSE envelopes, which had been causing OpenCode turns to stall without rendering assistant output. Added targeted adapter diagnostics (`[OpenCodeAdapter] ...`) plus `openCodeAdapter.test.ts` coverage for the direct-session response path and wrapped SSE event shape.
+**2026-04-08:** Full `@opencode-ai/sdk` integration — OpenCode is now a true first-class backend with parity to the SDK's surface. **Foundation:** new per-workspace `OpenCodeServerHost` (`packages/main/src/chat/openCodeServerHost.ts`) runs one persistent `opencode serve` process per `WorkspaceRuntime`, with a single shared SSE pump fanned out to per-session subscribers; the `openCodeAdapter` is now a thin per-turn driver that gets a client + session-scoped event stream from the host instead of spawning servers per turn. **Permissions:** new `permissionMatching.ts` lifts the IDE's `agent.permissionTier` + `agent.autoApprove` decision logic out of `agentManager.ts` so both built-in and CLI agents share it; new `openCodePermissionBridge.ts` maps the IDE's tool names to OpenCode's permission categories (`edit`/`bash`/`webfetch`/…) for both pre-flight agent-config and runtime decisions; new `approvalRouter.ts` (registered as a `WorkspaceRuntime` service slot) routes `CHAT_TOOL_APPROVE`/`CHAT_TOOL_REJECT` IPC to whichever manager owns the toolCallId so OpenCode permission prompts surface in the existing built-in approval UI (no new approval pane). **Telemetry:** existing per-session `totalCostUsd` accumulator extended with a per-session `totalTokens` (input/output/reasoning/cacheRead/cacheWrite) breakdown; both Claude and OpenCode adapters now extract token usage from result/message events; renderer shows a `CostTokenBadge` in the pane header. **Hot session config:** `CliAgentBackendState` extended with `providerID`/`modelID`/`agent`/`mode`/`systemPromptOverride`/`toolToggles`; new `cliAgentUpdateSessionConfig` IPC + `SessionSettingsPanel` collapsible disclosure in `CliAgentPane` exposes provider/model/agent/mode pickers, system prompt override, and a tool-toggle list (each lazy-fetched from `client.config.providers()` / `client.app.agents()` / `client.tool.list()`). **Rich part types:** `CliAgentMessageType` extended with `reasoning`/`patch`/`step`/`snapshot`/`retry`/`compaction`/`agent_change`/`subtask`/`file_attachment`; new `openCodePartConverter.ts` maps every SDK `Part` discriminant onto our normalized message shape; new `RichPartRenderer.tsx` renders each variant. **Session ops:** new IPC + manager methods + `SessionMenu.tsx` kebab for share/unshare/summarize/revert/unrevert/fork/abort/diff/todo/init/delete-remote (each delegates to `client.session.*`). **Workspace ops:** opt-in `OpenCodeToolsPane` Dockview pane with Files/Search/Shell/Status/Providers tabs that call `client.{file,find,session.shell,lsp,formatter}.*`; **Config/auth/providers:** `OpenCodeProvidersTab.tsx` lists providers, lets users sign in (paste-the-code OAuth or API key), and shows model lists; **Diagnostics + TUI:** `DiagnosticsPanel.tsx` shows server URL/mode/paths/LSP/formatter, `TuiControlPanel.tsx` exposes the TUI control surface. **Lifecycle integration:** `WorkspaceRuntime.refreshWorkload` sums pending approvals across both managers; `cliAgentManager.destroy()` disposes the `OpenCodeServerHost`; settings-changed listener mirrors `agent.permissionTier`/`agent.autoApprove` updates into `cliAgentManager.updatePermissions()` so live tier changes apply mid-session. **Tests:** new `openCodeServerHost`/`openCodeAdapter`/`openCodePermissionBridge`/`openCodePartConverter`/`cliAgentApprovalRouter` test files and 5 new assertions in `cliAgentManager.test.ts`; all 36 new tests pass alongside existing coverage.
 
 **2026-03-29:** Built-in chat — `useChat` refreshes after `CHAT_STREAM_END` and tool-call IPC now call `chatGetHistory(workspaceId, sessionId)` so history stays scoped to the active tab; avoids main falling back to `getMostRecent` (multi-tab isolation + pre-persist race).
 
diff --git a/packages/main/src/chat/agentManager.ts b/packages/main/src/chat/agentManager.ts
index 5ba242b..7d0b0c8 100644
--- a/packages/main/src/chat/agentManager.ts
+++ b/packages/main/src/chat/agentManager.ts
@@ -35,6 +35,8 @@ import { ToolRegistry } from './toolRegistry'
 import type { BrowserPaneManager } from '../browserPaneManager'
 import type { ConversationStore } from './conversationStore'
 import type { TaskVariableContext } from '../tasks/taskVariableResolver'
+import { shouldAutoApprove as evalShouldAutoApprove } from './permissionMatching'
+import type { ToolApprovalOwner } from './approvalRouter'
 
 // ─── Constants ─────────────────────────────────────────────────────
 
@@ -67,7 +69,7 @@ interface PendingApproval {
 
 // ─── Manager ───────────────────────────────────────────────────────
 
-export class AgentManager {
+export class AgentManager implements ToolApprovalOwner {
   private sessions = new Map<string, ChatSession>()
   private llmClient: LlmClient
   private toolRegistry: ToolRegistry
@@ -666,59 +668,15 @@ export class AgentManager {
     })
   }
 
-  // ─── Permission Checks ─────────���────────────────────────────
-
-  private static readonly READ_ONLY_TOOLS = new Set([
-    'file_read', 'file_list', 'search_files', 'git_status', 'git_diff', 'browser_read',
-  ])
+  // ─── Permission Checks ────────────────────────────────────────
 
   private shouldAutoApprove(toolName: string, input: Record<string, unknown>): boolean {
-    // Per-tool overrides take precedence over tier
-    const override = this.autoApprove[toolName]
-    if (override === true) return true
-    if (override === false) return false
-    if (typeof override === 'object') {
-      return this.matchesPatternConfig(override, toolName, input)
-    }
-
-    // Fall back to tier logic
-    switch (this.permissionTier) {
-      case 'autopilot':
-        return true
-      case 'auto-approve':
-        return AgentManager.READ_ONLY_TOOLS.has(toolName)
-      case 'confirm':
-      default:
-        return false
-    }
-  }
-
-  private matchesPatternConfig(
-    config: ToolPermissionConfig,
-    toolName: string,
-    input: Record<string, unknown>,
-  ): boolean {
-    // For terminal_exec, match against the command string; otherwise match stringified input
-    const matchTarget = toolName === 'terminal_exec'
-      ? String(input.command ?? '')
-      : JSON.stringify(input)
-
-    // Deny patterns take precedence
-    if (config.denyPatterns?.some((p) => this.globMatch(matchTarget, p))) {
-      return false
-    }
-    // Must match at least one allow pattern
-    if (config.allowPatterns && config.allowPatterns.length > 0) {
-      return config.allowPatterns.some((p) => this.globMatch(matchTarget, p))
-    }
-    return false
+    return evalShouldAutoApprove(toolName, input, this.permissionTier, this.autoApprove)
   }
 
-  private globMatch(text: string, pattern: string): boolean {
-    // Simple glob: * matches any sequence of characters
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    const regex = new RegExp('^' + escaped.replace(/\*/g, '.*') + '$')
-    return regex.test(text)
+  /** ToolApprovalOwner: does this manager own the given pending tool call? */
+  ownsToolCall(toolCallId: string): boolean {
+    return this.pendingApprovals.has(toolCallId)
   }
 
   // ���── Message Conversion ─────────���────────────────────────────
diff --git a/packages/main/src/chat/approvalRouter.ts b/packages/main/src/chat/approvalRouter.ts
new file mode 100644
index 0000000..9025233
--- /dev/null
+++ b/packages/main/src/chat/approvalRouter.ts
@@ -0,0 +1,65 @@
+/**
+ * ApprovalRouter — single approval surface for tool calls across both the
+ * built-in `AgentManager` and the external `CliAgentManager`.
+ *
+ * The renderer talks to one channel pair (`CHAT_TOOL_APPROVE` /
+ * `CHAT_TOOL_REJECT`) and one approval UI. The router decides which manager
+ * actually owns the pending tool call (by id) and dispatches the user's
+ * decision there.
+ *
+ * This keeps a single approval pane in the IDE for both backends, while
+ * letting each manager keep its own pending-approval map and resolution
+ * semantics.
+ */
+
+export interface ToolApprovalOwner {
+  /** Returns true iff this owner is currently waiting on the given tool call id. */
+  ownsToolCall(toolCallId: string): boolean
+  approveToolCall(sessionId: string, toolCallId: string): void
+  rejectToolCall(sessionId: string, toolCallId: string): void
+  /** Number of approvals currently awaiting user decision (used by refreshWorkload). */
+  getPendingApprovalCount(): number
+}
+
+export class ApprovalRouter {
+  private owners: ToolApprovalOwner[] = []
+
+  register(owner: ToolApprovalOwner): void {
+    if (!this.owners.includes(owner)) {
+      this.owners.push(owner)
+    }
+  }
+
+  unregister(owner: ToolApprovalOwner): void {
+    const idx = this.owners.indexOf(owner)
+    if (idx >= 0) this.owners.splice(idx, 1)
+  }
+
+  approve(sessionId: string, toolCallId: string): boolean {
+    for (const owner of this.owners) {
+      if (owner.ownsToolCall(toolCallId)) {
+        owner.approveToolCall(sessionId, toolCallId)
+        return true
+      }
+    }
+    return false
+  }
+
+  reject(sessionId: string, toolCallId: string): boolean {
+    for (const owner of this.owners) {
+      if (owner.ownsToolCall(toolCallId)) {
+        owner.rejectToolCall(sessionId, toolCallId)
+        return true
+      }
+    }
+    return false
+  }
+
+  getPendingApprovalCount(): number {
+    let total = 0
+    for (const owner of this.owners) {
+      total += owner.getPendingApprovalCount()
+    }
+    return total
+  }
+}
diff --git a/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts b/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
index 11e1897..e030fa3 100644
--- a/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
+++ b/packages/main/src/chat/cliAdapters/claudeCodeAdapter.ts
@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto'
 import { query } from '@anthropic-ai/claude-agent-sdk'
 import type { Query } from '@anthropic-ai/claude-agent-sdk'
+import type { CliAgentTokenUsage } from '@aide/shared'
 import type {
   CliBackendAdapter,
   CliBackendEvent,
@@ -49,12 +50,16 @@ export function createClaudeCodeAdapter(options: ClaudeCodeAdapterOptions): CliB
         }
 
         let totalCostUsd = 0
+        let totalTokens: CliAgentTokenUsage | undefined = undefined
         let sawResult = false
         for await (const message of queryInstance) {
           const events = normalizeClaudeMessage(message)
           for (const event of events) {
             if (event.type === 'result') {
               totalCostUsd += event.totalCostUsd
+              if (event.tokens) {
+                totalTokens = sumClaudeTokens(totalTokens, event.tokens)
+              }
               sawResult = true
             }
             emit(event)
@@ -66,6 +71,7 @@ export function createClaudeCodeAdapter(options: ClaudeCodeAdapterOptions): CliB
             type: 'result',
             durationMs: Date.now() - startedAt,
             totalCostUsd,
+            tokens: totalTokens,
             isSuccess: true,
           })
         }
@@ -243,6 +249,7 @@ function normalizeClaudeMessage(message: any): CliBackendEvent[] {
     const sessionId = message.session_id as string | undefined
     const errors = Array.isArray(message.errors) ? (message.errors as string[]) : []
     const errorDetail = errors.length > 0 ? errors.join('\n') : ''
+    const tokens = extractClaudeTokens(message.usage)
     const events: CliBackendEvent[] = []
 
     if (sessionId) {
@@ -263,6 +270,7 @@ function normalizeClaudeMessage(message: any): CliBackendEvent[] {
         timestamp: Date.now(),
         durationMs,
         totalCostUsd,
+        tokens,
         isSuccess,
         raw: message,
       },
@@ -272,6 +280,7 @@ function normalizeClaudeMessage(message: any): CliBackendEvent[] {
       type: 'result',
       durationMs,
       totalCostUsd,
+      tokens,
       isSuccess,
     })
 
@@ -280,3 +289,40 @@ function normalizeClaudeMessage(message: any): CliBackendEvent[] {
 
   return []
 }
+
+/** Extract Claude SDK usage block (input_tokens / output_tokens / cache_*) into our shared shape. */
+function extractClaudeTokens(usage: unknown): CliAgentTokenUsage | undefined {
+  if (!usage || typeof usage !== 'object') return undefined
+  const u = usage as Record<string, unknown>
+  const input = numberOr(u.input_tokens, 0)
+  const output = numberOr(u.output_tokens, 0)
+  const cacheRead = numberOr(u.cache_read_input_tokens, 0)
+  const cacheWrite = numberOr(u.cache_creation_input_tokens, 0)
+  if (input === 0 && output === 0 && cacheRead === 0 && cacheWrite === 0) return undefined
+  return {
+    input,
+    output,
+    reasoning: 0,
+    cacheRead,
+    cacheWrite,
+  }
+}
+
+function sumClaudeTokens(
+  a: CliAgentTokenUsage | undefined,
+  b: CliAgentTokenUsage | undefined,
+): CliAgentTokenUsage | undefined {
+  if (!a) return b
+  if (!b) return a
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    reasoning: a.reasoning + b.reasoning,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
+  }
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' ? value : fallback
+}
diff --git a/packages/main/src/chat/cliAdapters/openCodeAdapter.ts b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
index c5cc37b..8041ec3 100644
--- a/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
+++ b/packages/main/src/chat/cliAdapters/openCodeAdapter.ts
@@ -1,420 +1,384 @@
-import { randomUUID } from 'crypto'
-import { spawn, type ChildProcess } from 'child_process'
-import { createServer } from 'net'
-import { createOpencodeClient } from '@opencode-ai/sdk/client'
-import type { CliBackendAdapter, CliBackendRun, CliBackendTurnContext } from './types'
+/**
+ * OpenCode adapter — thin per-turn driver for the OpenCode SDK.
+ *
+ * Unlike the previous implementation, this adapter no longer spawns or owns a
+ * server process. The workspace's `OpenCodeServerHost` already runs a
+ * persistent `opencode serve` and exposes a shared SSE pump. The adapter:
+ *
+ *   1. Gets a client from the host
+ *   2. Creates an OpenCode session if one doesn't already exist
+ *   3. Subscribes to per-session SSE events via the host
+ *   4. Issues `promptAsync` with all overrides from backend state
+ *      (model / agent / system / tools)
+ *   5. Converts each part via `openCodePartConverter`
+ *   6. Aggregates cost + tokens and emits a `result` event when the session
+ *      goes idle (or fails)
+ *
+ * Permission events are forwarded to the manager via the new
+ * `permission-request` event variant — the manager bridges them to the
+ * existing CHAT_TOOL_CALL approval surface and POSTs the response back via
+ * `host.respondPermission()`.
+ */
 
-interface OpenCodeAdapterOptions {
-  executablePath: string
+import { randomUUID } from 'crypto'
+import type { CliAgentMessage, PermissionTier, ToolPermissionConfig } from '@aide/shared'
+import type { OpenCodeServerHost } from '../openCodeServerHost'
+import { decideOpenCodePermission } from './openCodePermissionBridge'
+import {
+  convertOpenCodePart,
+  createConvertContext,
+  extractTokens,
+  sumTokens,
+} from './openCodePartConverter'
+import type {
+  CliBackendAdapter,
+  CliBackendEvent,
+  CliBackendRun,
+  CliBackendTurnContext,
+} from './types'
+
+export interface OpenCodeAdapterOptions {
+  host: OpenCodeServerHost
+  /** Permission settings snapshot at the time the turn was initiated. */
+  getPermissionSettings: () => {
+    tier: PermissionTier
+    autoApprove: Record<string, boolean | ToolPermissionConfig>
+  }
 }
 
 export function createOpenCodeAdapter(options: OpenCodeAdapterOptions): CliBackendAdapter {
   return {
     backend: 'opencode',
     startTurn(context, emit) {
-      let serverProc: ChildProcess | null = null
-      let currentSessionId = context.backendState.sessionId
-      let closed = false
-
-      const completed = (async () => {
-        const startedAt = Date.now()
-        const port = await reservePort()
-        const url = `http://127.0.0.1:${port}`
-        logOpenCode('starting server', {
-          conversationId: context.conversationId,
-          hasSessionId: Boolean(currentSessionId),
-          cwd: context.cwd,
-          port,
-        })
-        serverProc = spawn(
-          options.executablePath,
-          ['serve', '--hostname=127.0.0.1', `--port=${port}`],
-          {
-            env: {
-              ...process.env,
-              OPENCODE_CONFIG_CONTENT: JSON.stringify({}),
-            },
-            stdio: ['ignore', 'pipe', 'pipe'],
-          },
-        )
-
-        if (!serverProc) throw new Error('Failed to start OpenCode server process')
-        await waitForOpenCodeServer(serverProc, url)
-        logOpenCode('server ready', { url, conversationId: context.conversationId })
+      return runOpenCodeTurn(options, context, emit)
+    },
+  }
+}
 
-        const client = createOpencodeClient({
-          baseUrl: url,
-          directory: context.cwd,
-          responseStyle: 'data',
-          throwOnError: true,
-        })
+function runOpenCodeTurn(
+  options: OpenCodeAdapterOptions,
+  context: CliBackendTurnContext,
+  emit: (event: CliBackendEvent) => void,
+): CliBackendRun {
+  const startedAt = Date.now()
+  let unsubscribe: (() => void) | null = null
+  let closed = false
+  let promptSubmitted = false
+  let sessionIdRef: string | null = context.backendState.sessionId ?? null
+
+  const partCtx = createConvertContext()
+  const textByMessageId = new Map<string, string>()
+  const emittedAssistantIds = new Set<string>()
+  const seenPartFinalIds = new Set<string>()
+  const costByMessageId = new Map<string, number>()
+  const tokensByMessageId = new Map<string, ReturnType<typeof extractTokens>>()
+  let totalCostUsd = 0
+  let totalTokens: ReturnType<typeof extractTokens> = undefined
+  let failedError: string | null = null
+  let idleResolve: (() => void) | null = null
+  const idlePromise = new Promise<void>((resolve) => {
+    idleResolve = resolve
+  })
 
-        if (!currentSessionId) {
-          const created = await client.session.create({ responseStyle: 'data', throwOnError: true })
-          currentSessionId = extractOpenCodeSessionId(created)
-          logOpenCode('session created', {
-            conversationId: context.conversationId,
-            sessionId: currentSessionId,
-          })
-          if (currentSessionId) {
-            emit({ type: 'backend-state', patch: { sessionId: currentSessionId } })
+  const completed = (async () => {
+    const client = await options.host.getClient()
+
+    // Ensure we have a session.
+    if (!sessionIdRef) {
+      const created = await (
+        client as unknown as {
+          session: {
+            create: (opts?: {
+              body?: { title?: string }
+              query?: { directory?: string }
+            }) => Promise<unknown>
           }
         }
+      ).session.create({ query: { directory: context.cwd } })
+      const id = extractSessionId(created)
+      if (!id) throw new Error('OpenCode session.create returned no id')
+      sessionIdRef = id
+      emit({ type: 'backend-state', patch: { sessionId: id } })
+    }
+    const sessionId = sessionIdRef
+    if (!sessionId) throw new Error('OpenCode session unavailable')
 
-        if (!currentSessionId) {
-          throw new Error('Failed to initialize OpenCode session')
-        }
-
-        const sse = await client.global.event({
-          signal: undefined,
-          onSseError(error) {
-            console.error('[OpenCodeAdapter] SSE error:', error)
-          },
-        })
-        const textByMessageId = new Map<string, string>()
-        const timestampByMessageId = new Map<string, number>()
-        const emittedAssistantIds = new Set<string>()
-        const seenToolStates = new Map<string, string>()
-        const costByMessageId = new Map<string, number>()
-        let totalCostUsd = 0
-        let failedError: string | null = null
-        let promptSubmitted = false
-
-        const streamTask = (async () => {
-          for await (const rawEvent of sse.stream) {
-            const envelope = asRecord(rawEvent)
-            const event = asRecord(envelope?.payload) ?? envelope
-            const type = typeof event?.type === 'string' ? event.type : ''
-            const props = asRecord(event?.properties)
-
-            logOpenCode('sse event', {
-              conversationId: context.conversationId,
-              sessionId: currentSessionId,
-              directory: asString(envelope?.directory),
-              type,
-            })
-
-            if (type === 'message.updated' && props?.info) {
-              const info = props.info as Record<string, any>
-              const sessionId = asString(info.sessionID)
-              if (!sessionId || sessionId !== currentSessionId) continue
-
-              const messageId = asString(info.id) ?? randomUUID()
-              if (info.role === 'assistant') {
-                const model =
-                  [asString(info.providerID), asString(info.modelID)].filter(Boolean).join('/') ||
-                  undefined
-                const createdAt =
-                  typeof info.time?.created === 'number' ? info.time.created : Date.now()
-                timestampByMessageId.set(messageId, createdAt)
-                emit({ type: 'session-meta', model })
-                emit({ type: 'backend-state', patch: { sessionId, model } })
-                logOpenCode('assistant message updated', {
-                  sessionId,
-                  messageId,
-                  model,
-                })
-
-                const nextCost = typeof info.cost === 'number' ? info.cost : 0
-                const prevCost = costByMessageId.get(messageId) ?? 0
-                totalCostUsd += Math.max(0, nextCost - prevCost)
-                costByMessageId.set(messageId, nextCost)
-
-                const errorText = renderOpenCodeError(info.error)
-                if (errorText) {
-                  failedError = errorText
-                }
-              }
-              continue
-            }
-
-            if (type === 'message.part.updated' && props?.part) {
-              const part = props.part as Record<string, any>
-              if (asString(part.sessionID) !== currentSessionId) continue
-              const partType = asString(part.type)
+    // Subscribe BEFORE issuing the prompt so we don't miss early events.
+    unsubscribe = options.host.subscribe(sessionId, (rawEvent) => {
+      handleEvent(rawEvent)
+    })
 
-              if (partType === 'text') {
-                const messageId = asString(part.messageID) ?? randomUUID()
-                const delta = asString(props.delta)
-                if (delta) {
-                  const prior = textByMessageId.get(messageId) ?? ''
-                  textByMessageId.set(messageId, prior + delta)
-                  emit({ type: 'stream-delta', messageId, delta })
-                  logOpenCode('assistant delta', {
-                    sessionId: currentSessionId,
-                    messageId,
-                    deltaLength: delta.length,
-                  })
-                } else {
-                  textByMessageId.set(messageId, asString(part.text) ?? '')
-                  logOpenCode('assistant part snapshot', {
-                    sessionId: currentSessionId,
-                    messageId,
-                    textLength: (asString(part.text) ?? '').length,
-                  })
-                }
-                continue
-              }
+    // Build the prompt body using per-session backend state overrides.
+    const state = context.backendState
+    const body: Record<string, unknown> = {
+      parts: [{ type: 'text', text: context.prompt }],
+    }
+    if (state.providerID && state.modelID) {
+      body.model = { providerID: state.providerID, modelID: state.modelID }
+    } else if (state.model && state.model.includes('/')) {
+      const [providerID, modelID] = state.model.split('/', 2)
+      body.model = { providerID, modelID }
+    }
+    if (state.agent) body.agent = state.agent
+    if (state.systemPromptOverride) body.system = state.systemPromptOverride
+    if (state.toolToggles) body.tools = state.toolToggles
+
+    await (
+      client as unknown as {
+        session: {
+          promptAsync: (opts: {
+            path: { id: string }
+            query?: { directory?: string }
+            body: Record<string, unknown>
+          }) => Promise<unknown>
+        }
+      }
+    ).session.promptAsync({
+      path: { id: sessionId },
+      query: { directory: context.cwd },
+      body,
+    })
+    promptSubmitted = true
+
+    // Wait for session.idle (or session.error which sets failedError).
+    await idlePromise
+
+    // Emit any final assistant text accumulators that weren't already emitted.
+    for (const [messageId, text] of textByMessageId) {
+      if (!text) continue
+      if (emittedAssistantIds.has(messageId)) continue
+      if (seenPartFinalIds.has(messageId)) continue
+      emittedAssistantIds.add(messageId)
+      const message: Omit<CliAgentMessage, 'backend'> = {
+        id: messageId,
+        type: 'assistant',
+        content: text,
+        timestamp: Date.now(),
+        tokens: tokensByMessageId.get(messageId),
+        costUsd: costByMessageId.get(messageId),
+      }
+      emit({ type: 'message', message })
+    }
 
-              if (partType === 'tool') {
-                const partId = asString(part.id) ?? randomUUID()
-                const state = asRecord(part.state)
-                const status = asString(state?.status) ?? 'pending'
-                const priorStatus = seenToolStates.get(partId)
-                if (priorStatus === status) continue
-                seenToolStates.set(partId, status)
+    if (failedError) {
+      emit({
+        type: 'message',
+        message: {
+          id: randomUUID(),
+          type: 'error',
+          content: failedError,
+          timestamp: Date.now(),
+        },
+      })
+      emit({
+        type: 'result',
+        durationMs: Date.now() - startedAt,
+        totalCostUsd,
+        tokens: totalTokens,
+        isSuccess: false,
+      })
+      return
+    }
 
-                const toolName = asString(part.tool) ?? 'tool'
-                if (status === 'pending' || status === 'running') {
-                  emit({
-                    type: 'message',
-                    message: {
-                      id: partId,
-                      type: 'tool_use',
-                      content: `Running ${toolName}...`,
-                      timestamp: Date.now(),
-                      toolName,
-                      toolUseId: asString(part.callID),
-                    },
-                  })
-                } else if (status === 'completed') {
-                  emit({
-                    type: 'message',
-                    message: {
-                      id: partId,
-                      type: 'tool_result',
-                      content:
-                        asString(state?.output) ??
-                        asString(state?.title) ??
-                        `${toolName} completed`,
-                      timestamp: Date.now(),
-                      toolName,
-                      toolUseId: asString(part.callID),
-                    },
-                  })
-                } else if (status === 'error') {
-                  emit({
-                    type: 'message',
-                    message: {
-                      id: partId,
-                      type: 'error',
-                      content: asString(state?.error) ?? `${toolName} failed`,
-                      timestamp: Date.now(),
-                      toolName,
-                      toolUseId: asString(part.callID),
-                    },
-                  })
-                }
-              }
-              continue
-            }
+    emit({
+      type: 'message',
+      message: {
+        id: randomUUID(),
+        type: 'result',
+        content: `Completed in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
+        timestamp: Date.now(),
+        totalCostUsd,
+        tokens: totalTokens,
+        isSuccess: true,
+      },
+    })
+    emit({
+      type: 'result',
+      durationMs: Date.now() - startedAt,
+      totalCostUsd,
+      tokens: totalTokens,
+      isSuccess: true,
+    })
+  })().finally(() => {
+    if (unsubscribe) {
+      try {
+        unsubscribe()
+      } catch {
+        /* ignore */
+      }
+      unsubscribe = null
+    }
+  })
 
-            if (type === 'session.error' && props) {
-              if (
-                currentSessionId &&
-                asString(props.sessionID) &&
-                asString(props.sessionID) !== currentSessionId
-              ) {
-                continue
-              }
-              failedError = renderOpenCodeError(props.error) ?? 'OpenCode session failed'
-              console.error('[OpenCodeAdapter] session.error', {
-                conversationId: context.conversationId,
-                sessionId: currentSessionId,
-                error: failedError,
-              })
-              continue
-            }
+  function handleEvent(rawEvent: unknown): void {
+    if (closed) return
+    const event = rawEvent as { type?: string; properties?: Record<string, unknown> }
+    const type = typeof event.type === 'string' ? event.type : ''
+    const props = (event.properties ?? {}) as Record<string, unknown>
+
+    if (type === 'message.updated' && (props.info as Record<string, unknown> | undefined)) {
+      const info = props.info as Record<string, unknown>
+      const role = info.role
+      const messageId = (info.id as string | undefined) ?? randomUUID()
+      if (role === 'assistant') {
+        const providerID = info.providerID as string | undefined
+        const modelID = info.modelID as string | undefined
+        const model = [providerID, modelID].filter(Boolean).join('/') || undefined
+        if (model) {
+          emit({ type: 'session-meta', model })
+          emit({ type: 'backend-state', patch: { sessionId: sessionIdRef ?? undefined, model } })
+        }
+        const cost = typeof info.cost === 'number' ? info.cost : 0
+        const prevCost = costByMessageId.get(messageId) ?? 0
+        const delta = Math.max(0, cost - prevCost)
+        totalCostUsd += delta
+        costByMessageId.set(messageId, cost)
+
+        const tokens = extractTokens(info.tokens)
+        if (tokens) {
+          tokensByMessageId.set(messageId, tokens)
+          totalTokens = recomputeTotals(tokensByMessageId)
+        }
 
-            if (
-              type === 'session.idle' &&
-              asString(props?.sessionID) === currentSessionId &&
-              promptSubmitted
-            ) {
-              logOpenCode('session idle', {
-                conversationId: context.conversationId,
-                sessionId: currentSessionId,
-              })
-              break
-            }
-          }
-        })()
+        const errorText = renderOpenCodeError(info.error)
+        if (errorText) failedError = errorText
+      }
+      return
+    }
 
-        logOpenCode('submitting prompt', {
-          conversationId: context.conversationId,
-          sessionId: currentSessionId,
-          promptLength: context.prompt.length,
-        })
-        await client.session.promptAsync({
-          responseStyle: 'data',
-          throwOnError: true,
-          path: { id: currentSessionId },
-          body: {
-            parts: [{ type: 'text', text: context.prompt }],
-          },
-        })
-        promptSubmitted = true
-        logOpenCode('prompt submitted', {
-          conversationId: context.conversationId,
-          sessionId: currentSessionId,
-        })
+    if (type === 'message.part.updated' && props.part) {
+      const part = props.part as Record<string, unknown>
+      const messageId = (part.messageID as string | undefined) ?? randomUUID()
+      const delta = typeof props.delta === 'string' ? (props.delta as string) : undefined
+      const converted = convertOpenCodePart(part, delta, partCtx)
 
-        await streamTask
-        logOpenCode('stream complete', {
-          conversationId: context.conversationId,
-          sessionId: currentSessionId,
-          assistantMessages: textByMessageId.size,
-          failed: Boolean(failedError),
+      if (converted.isTextDelta && converted.delta) {
+        const prior = textByMessageId.get(converted.messageId ?? messageId) ?? ''
+        textByMessageId.set(converted.messageId ?? messageId, prior + converted.delta)
+        emit({
+          type: 'stream-delta',
+          messageId: converted.messageId ?? messageId,
+          delta: converted.delta,
         })
-
-        for (const [messageId, text] of textByMessageId) {
-          if (!text || emittedAssistantIds.has(messageId)) continue
-          emittedAssistantIds.add(messageId)
-          emit({
-            type: 'message',
-            message: {
-              id: messageId,
-              type: 'assistant',
-              content: text,
-              timestamp: timestampByMessageId.get(messageId) ?? Date.now(),
-            },
-          })
+      }
+      for (const message of converted.messages) {
+        if (message.type === 'assistant') {
+          emittedAssistantIds.add(message.id)
+          seenPartFinalIds.add(message.id)
         }
+        emit({ type: 'message', message })
+      }
+      return
+    }
 
-        if (failedError) {
-          emit({
-            type: 'message',
-            message: {
-              id: randomUUID(),
-              type: 'error',
-              content: failedError,
-              timestamp: Date.now(),
-            },
-          })
-          emit({
-            type: 'result',
-            durationMs: Date.now() - startedAt,
-            totalCostUsd,
-            isSuccess: false,
-          })
-          return
-        }
+    if (type === 'permission.updated' && props) {
+      const perm = props as Record<string, unknown>
+      const permissionId = perm.id as string | undefined
+      const sessionID = perm.sessionID as string | undefined
+      if (!permissionId || !sessionID) return
+
+      const settings = options.getPermissionSettings()
+      const decision = decideOpenCodePermission(
+        {
+          category: (perm.type as string) ?? 'unknown',
+          pattern: perm.pattern as string | string[] | undefined,
+          metadata: perm.metadata as Record<string, unknown> | undefined,
+        },
+        settings.tier,
+        settings.autoApprove,
+      )
 
-        emit({
-          type: 'message',
-          message: {
-            id: randomUUID(),
-            type: 'result',
-            content: `Completed in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
-            timestamp: Date.now(),
-            totalCostUsd,
-            isSuccess: true,
-          },
-        })
-        emit({
-          type: 'result',
-          durationMs: Date.now() - startedAt,
-          totalCostUsd,
-          isSuccess: true,
+      if (decision === 'always' || decision === 'reject') {
+        void options.host.respondPermission(sessionID, permissionId, decision).catch(() => {
+          // Surface as error if response fails.
         })
-      })().finally(() => {
-        if (!closed) {
-          logOpenCode('stopping server', {
-            conversationId: context.conversationId,
-            sessionId: currentSessionId,
-          })
-          serverProc?.kill('SIGTERM')
-        }
-      })
+        return
+      }
 
-      return {
-        close() {
-          closed = true
-          serverProc?.kill('SIGTERM')
+      // Forward to the manager via a synthetic permission-request event.
+      emit({
+        type: 'permission-request',
+        request: {
+          permissionId,
+          sessionId: sessionID,
+          category: (perm.type as string) ?? 'unknown',
+          title: (perm.title as string) ?? 'Permission required',
+          pattern: perm.pattern as string | string[] | undefined,
+          metadata: perm.metadata as Record<string, unknown> | undefined,
+        },
+        resolve: (response) => {
+          void options.host.respondPermission(sessionID, permissionId, response).catch(() => {
+            /* ignore */
+          })
         },
-        completed,
-      } satisfies CliBackendRun
-    },
-  }
-}
-
-async function reservePort(): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const server = createServer()
-    server.once('error', reject)
-    server.listen(0, '127.0.0.1', () => {
-      const address = server.address()
-      const port = typeof address === 'object' && address ? address.port : null
-      server.close((error) => {
-        if (error) reject(error)
-        else if (typeof port === 'number') resolve(port)
-        else reject(new Error('Failed to reserve OpenCode port'))
       })
-    })
-  })
-}
-
-async function waitForOpenCodeServer(proc: ChildProcess, url: string): Promise<void> {
-  await new Promise<void>((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      reject(new Error('Timeout waiting for OpenCode server to start'))
-    }, 5000)
+      return
+    }
 
-    let output = ''
-    const onData = (chunk: Buffer) => {
-      output += chunk.toString()
-      if (output.includes(url) || output.includes('opencode server listening')) {
-        cleanup()
-        resolve()
+    if (type === 'session.error' && props) {
+      if (sessionIdRef && typeof props.sessionID === 'string' && props.sessionID !== sessionIdRef) {
+        return
       }
+      failedError = renderOpenCodeError(props.error) ?? 'OpenCode session failed'
+      if (idleResolve) {
+        idleResolve()
+        idleResolve = null
+      }
+      return
     }
-    const onExit = (code: number | null) => {
-      cleanup()
-      reject(new Error(`OpenCode server exited with code ${code}${output ? `\n${output}` : ''}`))
-    }
-    const onError = (error: Error) => {
-      cleanup()
-      reject(error)
-    }
-    const cleanup = () => {
-      clearTimeout(timeout)
-      proc.stdout?.off('data', onData)
-      proc.stderr?.off('data', onData)
-      proc.off('exit', onExit)
-      proc.off('error', onError)
-    }
-
-    proc.stdout?.on('data', onData)
-    proc.stderr?.on('data', onData)
-    proc.once('exit', onExit)
-    proc.once('error', onError)
-  })
-}
 
-function asRecord(value: unknown): Record<string, any> | null {
-  return value && typeof value === 'object' ? (value as Record<string, any>) : null
-}
+    if (type === 'session.idle' && props.sessionID === sessionIdRef && promptSubmitted) {
+      if (idleResolve) {
+        idleResolve()
+        idleResolve = null
+      }
+      return
+    }
+  }
 
-function asString(value: unknown): string | undefined {
-  return typeof value === 'string' ? value : undefined
+  return {
+    close() {
+      closed = true
+      if (idleResolve) {
+        idleResolve()
+        idleResolve = null
+      }
+      if (unsubscribe) {
+        try {
+          unsubscribe()
+        } catch {
+          /* ignore */
+        }
+        unsubscribe = null
+      }
+    },
+    completed,
+  }
 }
 
-function extractOpenCodeSessionId(value: unknown): string | undefined {
-  const payload = asRecord(value)
-  return asString(payload?.id) ?? asString(asRecord(payload?.data)?.id)
+function recomputeTotals(
+  byId: Map<string, ReturnType<typeof extractTokens>>,
+): ReturnType<typeof extractTokens> {
+  let acc: ReturnType<typeof extractTokens> = undefined
+  for (const value of byId.values()) {
+    acc = sumTokens(acc, value)
+  }
+  return acc
 }
 
-function logOpenCode(message: string, data?: Record<string, unknown>): void {
-  if (data) {
-    console.log(`[OpenCodeAdapter] ${message}`, data)
-    return
-  }
-  console.log(`[OpenCodeAdapter] ${message}`)
+function extractSessionId(value: unknown): string | null {
+  if (!value || typeof value !== 'object') return null
+  const v = value as Record<string, unknown>
+  if (typeof v.id === 'string') return v.id
+  const data = v.data as Record<string, unknown> | undefined
+  if (data && typeof data.id === 'string') return data.id
+  return null
 }
 
 function renderOpenCodeError(value: unknown): string | null {
-  const error = asRecord(value)
-  const data = asRecord(error?.data)
-  const message = asString(data?.message)
+  if (!value || typeof value !== 'object') return null
+  const error = value as Record<string, unknown>
+  const data = (error.data ?? {}) as Record<string, unknown>
+  const message = typeof data.message === 'string' ? (data.message as string) : null
   return message ?? null
 }
diff --git a/packages/main/src/chat/cliAdapters/openCodePartConverter.ts b/packages/main/src/chat/cliAdapters/openCodePartConverter.ts
new file mode 100644
index 0000000..a51808b
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/openCodePartConverter.ts
@@ -0,0 +1,418 @@
+/**
+ * OpenCode Part → CliAgentMessage(s) converter.
+ *
+ * Maps every part `type` discriminant exposed by `@opencode-ai/sdk` onto our
+ * normalized `CliAgentMessage` shape. Returns one or more messages per part
+ * (e.g. a tool part may emit a single tool_use OR tool_result message
+ * depending on its current state).
+ *
+ * Unknown / unhandled types fall back to a generic `system` message so the
+ * renderer can still display them.
+ */
+
+import { randomUUID } from 'crypto'
+import type { CliAgentMessage, CliAgentTokenUsage } from '@aide/shared'
+
+interface BasePart {
+  id?: string
+  sessionID?: string
+  messageID?: string
+  type?: string
+  [key: string]: unknown
+}
+
+interface ConvertContext {
+  /** Optional delta string from the part.updated event (text deltas only). */
+  delta?: string
+  /** Track which tool partIds we've already emitted in which state. */
+  seenToolStates: Map<string, string>
+  /** Track which reasoning partIds we've already emitted (to avoid duplicate emit on each delta). */
+  seenReasoningIds: Set<string>
+}
+
+export function createConvertContext(): ConvertContext {
+  return {
+    seenToolStates: new Map(),
+    seenReasoningIds: new Set(),
+  }
+}
+
+export interface ConvertedPart {
+  /** Messages to emit. May be empty if the part is purely a delta. */
+  messages: CliAgentMessage[]
+  /** True if this part is a streaming text delta (caller should also emit a stream-delta event). */
+  isTextDelta: boolean
+  /** Text delta value, present iff isTextDelta. */
+  delta?: string
+  /** The messageId for the text accumulator. */
+  messageId?: string
+}
+
+/**
+ * Convert a single OpenCode `part` event payload into normalized messages.
+ *
+ * The `delta` argument comes from `props.delta` on `message.part.updated`.
+ */
+export function convertOpenCodePart(
+  rawPart: unknown,
+  rawDelta: string | undefined,
+  ctx: ConvertContext,
+): ConvertedPart {
+  const part = (rawPart ?? {}) as BasePart
+  const partType = typeof part.type === 'string' ? part.type : ''
+  const partId = (typeof part.id === 'string' ? part.id : null) ?? randomUUID()
+  const messageId = typeof part.messageID === 'string' ? part.messageID : undefined
+  const now = Date.now()
+
+  switch (partType) {
+    case 'text': {
+      const text = stringField(part, 'text') ?? ''
+      const synthetic = part.synthetic === true
+      const ignored = part.ignored === true
+      if (ignored) return { messages: [], isTextDelta: false }
+      if (rawDelta) {
+        return {
+          messages: [],
+          isTextDelta: true,
+          delta: rawDelta,
+          messageId: messageId ?? partId,
+        }
+      }
+      // Final / complete text part — emit as assistant message.
+      return {
+        messages: [
+          {
+            id: messageId ?? partId,
+            type: synthetic ? 'system' : 'assistant',
+            content: text,
+            timestamp: now,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'reasoning': {
+      // Stream reasoning text incrementally; first occurrence creates the
+      // message, subsequent updates patch it. We emit one message at the end
+      // (when text is non-empty) for simplicity.
+      const text = stringField(part, 'text') ?? ''
+      if (!text || ctx.seenReasoningIds.has(partId)) {
+        return { messages: [], isTextDelta: false }
+      }
+      ctx.seenReasoningIds.add(partId)
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'reasoning',
+            content: text,
+            timestamp: now,
+            reasoningCollapsed: true,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'file': {
+      const mime = stringField(part, 'mime') ?? 'application/octet-stream'
+      const url = stringField(part, 'url') ?? ''
+      const filename = stringField(part, 'filename')
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'file_attachment',
+            content: filename ?? url,
+            timestamp: now,
+            fileMime: mime,
+            fileUrl: url,
+            fileName: filename,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'tool': {
+      const state = (part.state ?? {}) as Record<string, unknown>
+      const status = stringField(state, 'status') ?? 'pending'
+      const priorStatus = ctx.seenToolStates.get(partId)
+      if (priorStatus === status) {
+        return { messages: [], isTextDelta: false }
+      }
+      ctx.seenToolStates.set(partId, status)
+
+      const toolName = stringField(part, 'tool') ?? 'tool'
+      const toolUseId = stringField(part, 'callID')
+
+      if (status === 'pending' || status === 'running') {
+        return {
+          messages: [
+            {
+              id: partId,
+              type: 'tool_use',
+              content: `Running ${toolName}...`,
+              timestamp: now,
+              toolName,
+              toolUseId,
+              raw: part,
+            },
+          ],
+          isTextDelta: false,
+        }
+      }
+      if (status === 'completed') {
+        const output =
+          stringField(state, 'output') ?? stringField(state, 'title') ?? `${toolName} completed`
+        return {
+          messages: [
+            {
+              id: partId,
+              type: 'tool_result',
+              content: output,
+              timestamp: now,
+              toolName,
+              toolUseId,
+              raw: part,
+            },
+          ],
+          isTextDelta: false,
+        }
+      }
+      if (status === 'error') {
+        return {
+          messages: [
+            {
+              id: partId,
+              type: 'error',
+              content: stringField(state, 'error') ?? `${toolName} failed`,
+              timestamp: now,
+              toolName,
+              toolUseId,
+              raw: part,
+            },
+          ],
+          isTextDelta: false,
+        }
+      }
+      return { messages: [], isTextDelta: false }
+    }
+
+    case 'step-start': {
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'step',
+            content: 'Step started',
+            timestamp: now,
+            stepPhase: 'start',
+            stepSnapshot: stringField(part, 'snapshot'),
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'step-finish': {
+      const cost = numberField(part, 'cost') ?? 0
+      const tokens = extractTokens(part.tokens)
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'step',
+            content: stringField(part, 'reason') ?? 'Step completed',
+            timestamp: now,
+            stepPhase: 'finish',
+            stepReason: stringField(part, 'reason'),
+            stepSnapshot: stringField(part, 'snapshot'),
+            costUsd: cost,
+            tokens,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'snapshot': {
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'snapshot',
+            content: 'Snapshot captured',
+            timestamp: now,
+            snapshotHash: stringField(part, 'snapshot'),
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'patch': {
+      const files = Array.isArray(part.files)
+        ? (part.files as unknown[]).filter((f): f is string => typeof f === 'string')
+        : []
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'patch',
+            content: files.length === 1 ? files[0] : `${files.length} files`,
+            timestamp: now,
+            patchHash: stringField(part, 'hash'),
+            patchFiles: files,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'agent': {
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'agent_change',
+            content: stringField(part, 'name') ?? 'agent',
+            timestamp: now,
+            agentName: stringField(part, 'name'),
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'retry': {
+      const error = (part.error ?? {}) as Record<string, unknown>
+      const errMsg =
+        stringField((error.data as Record<string, unknown> | undefined) ?? {}, 'message') ??
+        stringField(error, 'message') ??
+        'retrying'
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'retry',
+            content: `Attempt ${numberField(part, 'attempt') ?? 1}: ${errMsg}`,
+            timestamp: now,
+            retryAttempt: numberField(part, 'attempt'),
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'compaction': {
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'compaction',
+            content: 'Context compacted',
+            timestamp: now,
+            compactionAuto: part.auto === true,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    case 'subtask': {
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'subtask',
+            content: stringField(part, 'description') ?? stringField(part, 'prompt') ?? 'Subtask',
+            timestamp: now,
+            subtaskPrompt: stringField(part, 'prompt'),
+            subtaskDescription: stringField(part, 'description'),
+            subtaskAgent: stringField(part, 'agent'),
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+
+    default: {
+      // Unknown part type — emit as a generic system message so it isn't lost.
+      return {
+        messages: [
+          {
+            id: partId,
+            type: 'system',
+            content: `Unknown part: ${partType}`,
+            timestamp: now,
+            raw: part,
+          },
+        ],
+        isTextDelta: false,
+      }
+    }
+  }
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const v = (value as Record<string, unknown>)[key]
+  return typeof v === 'string' ? v : undefined
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const v = (value as Record<string, unknown>)[key]
+  return typeof v === 'number' ? v : undefined
+}
+
+/** Extract token counts from an OpenCode AssistantMessage / StepFinishPart-style tokens object. */
+export function extractTokens(value: unknown): CliAgentTokenUsage | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const t = value as Record<string, unknown>
+  const cache = (t.cache ?? {}) as Record<string, unknown>
+  const input = numberField(t, 'input') ?? 0
+  const output = numberField(t, 'output') ?? 0
+  const reasoning = numberField(t, 'reasoning') ?? 0
+  const cacheRead = numberField(cache, 'read') ?? 0
+  const cacheWrite = numberField(cache, 'write') ?? 0
+  if (
+    input === 0 &&
+    output === 0 &&
+    reasoning === 0 &&
+    cacheRead === 0 &&
+    cacheWrite === 0
+  ) {
+    return undefined
+  }
+  return { input, output, reasoning, cacheRead, cacheWrite }
+}
+
+/** Sum two token usage records. */
+export function sumTokens(
+  a: CliAgentTokenUsage | undefined,
+  b: CliAgentTokenUsage | undefined,
+): CliAgentTokenUsage | undefined {
+  if (!a) return b
+  if (!b) return a
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    reasoning: a.reasoning + b.reasoning,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
+  }
+}
diff --git a/packages/main/src/chat/cliAdapters/openCodePermissionBridge.ts b/packages/main/src/chat/cliAdapters/openCodePermissionBridge.ts
new file mode 100644
index 0000000..3f8a8eb
--- /dev/null
+++ b/packages/main/src/chat/cliAdapters/openCodePermissionBridge.ts
@@ -0,0 +1,158 @@
+/**
+ * IDE ↔ OpenCode permission bridge.
+ *
+ * Two responsibilities:
+ *
+ * 1. **Pre-flight** (`buildOpenCodePermissionConfig`): convert the IDE's
+ *    `agent.permissionTier` + `agent.autoApprove` settings into an OpenCode
+ *    agent `permission` config block. Pushed to the SDK once at session
+ *    start so OpenCode itself short-circuits cheap cases.
+ *
+ * 2. **Runtime** (`decideOpenCodePermission`): when OpenCode raises a
+ *    `permission.updated` event mid-turn, decide whether to auto-allow,
+ *    auto-deny, or prompt the user. Uses the same `evaluatePermission`
+ *    logic as the built-in `AgentManager`, with a category mapping from
+ *    OpenCode's permission categories ('edit' / 'bash' / 'webfetch' / …)
+ *    to the IDE's tool names ('file_write' / 'terminal_exec' / …).
+ */
+
+import type { PermissionTier, ToolPermissionConfig } from '@aide/shared'
+import { evaluatePermission } from '../permissionMatching'
+
+/**
+ * OpenCode agent permission categories accepted by the SDK
+ * (see `@opencode-ai/sdk` AgentConfig.permission).
+ */
+export type OpenCodePermissionCategory =
+  | 'edit'
+  | 'bash'
+  | 'webfetch'
+  | 'doom_loop'
+  | 'external_directory'
+
+export type OpenCodePermissionDecision = 'allow' | 'ask' | 'deny'
+export type OpenCodePermissionResponse = 'always' | 'once' | 'reject'
+
+/**
+ * Map an OpenCode permission category onto the IDE tool name used by
+ * `agent.autoApprove`. The mapping is intentionally narrow — IDE tool names
+ * with no OpenCode counterpart simply have no auto-approve effect on
+ * OpenCode-side prompts.
+ */
+const CATEGORY_TO_IDE_TOOL: Record<OpenCodePermissionCategory, string> = {
+  edit: 'file_write',
+  bash: 'terminal_exec',
+  webfetch: 'browser_read',
+  doom_loop: 'doom_loop',
+  external_directory: 'external_directory',
+}
+
+/** Inverse for diagnostic / fall-through use. */
+export function ideToolNameForCategory(category: string): string {
+  return (CATEGORY_TO_IDE_TOOL as Record<string, string>)[category] ?? category
+}
+
+/**
+ * Build an OpenCode `agent.permission` config block from the IDE settings.
+ *
+ * Tier rules:
+ *   - `autopilot`    → all 'allow'
+ *   - `auto-approve` → 'webfetch' (read-only) → 'allow'; 'edit' / 'bash' / others → 'ask'
+ *   - `confirm`      → all 'ask'
+ *
+ * `autoApprove` overrides:
+ *   - `true`              → 'allow' for that category
+ *   - `false`             → 'deny'  for that category
+ *   - patterns (object)   → 'ask'   (we still need the runtime decision)
+ */
+export function buildOpenCodePermissionConfig(
+  tier: PermissionTier,
+  autoApprove: Record<string, boolean | ToolPermissionConfig>,
+): Record<OpenCodePermissionCategory, OpenCodePermissionDecision> {
+  const out = {} as Record<OpenCodePermissionCategory, OpenCodePermissionDecision>
+  const categories: OpenCodePermissionCategory[] = [
+    'edit',
+    'bash',
+    'webfetch',
+    'doom_loop',
+    'external_directory',
+  ]
+
+  for (const category of categories) {
+    const ideTool = CATEGORY_TO_IDE_TOOL[category]
+    const override = autoApprove[ideTool]
+
+    if (override === true) {
+      out[category] = 'allow'
+      continue
+    }
+    if (override === false) {
+      out[category] = 'deny'
+      continue
+    }
+    if (typeof override === 'object' && override !== null) {
+      // Pattern config — still need runtime evaluation for each call.
+      out[category] = 'ask'
+      continue
+    }
+
+    switch (tier) {
+      case 'autopilot':
+        out[category] = 'allow'
+        break
+      case 'auto-approve':
+        // Only webfetch is "read-only" in IDE terms
+        out[category] = category === 'webfetch' ? 'allow' : 'ask'
+        break
+      case 'confirm':
+      default:
+        out[category] = 'ask'
+        break
+    }
+  }
+  return out
+}
+
+export interface DecideInput {
+  category: string
+  pattern?: string | string[]
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Decide what to do with a runtime OpenCode permission request. Returns
+ * `'prompt'` when the user must be asked; otherwise returns the OpenCode
+ * response value to POST back.
+ */
+export function decideOpenCodePermission(
+  input: DecideInput,
+  tier: PermissionTier,
+  autoApprove: Record<string, boolean | ToolPermissionConfig>,
+): OpenCodePermissionResponse | 'prompt' {
+  const ideTool = ideToolNameForCategory(input.category)
+  const matchInput = buildMatchInput(input)
+
+  const decision = evaluatePermission(ideTool, matchInput, tier, autoApprove)
+  if (decision === 'allow') return 'always'
+  if (decision === 'deny') return 'reject'
+  return 'prompt'
+}
+
+function buildMatchInput(input: DecideInput): Record<string, unknown> {
+  // For bash-like categories, the pattern is the shell command(s) — feed it as
+  // `command` so the existing matchTargetFor() shortcut for terminal_exec
+  // matches against the command string.
+  if (input.category === 'bash') {
+    if (Array.isArray(input.pattern)) {
+      return { command: input.pattern.join(' && ') }
+    }
+    return { command: input.pattern ?? '' }
+  }
+
+  // For edit / webfetch / external_directory, treat the pattern as a path/URL
+  // and stringify the whole input so glob patterns can match against it.
+  return {
+    pattern: input.pattern,
+    ...input.metadata,
+  }
+}
diff --git a/packages/main/src/chat/cliAdapters/types.ts b/packages/main/src/chat/cliAdapters/types.ts
index 04bb59d..082f466 100644
--- a/packages/main/src/chat/cliAdapters/types.ts
+++ b/packages/main/src/chat/cliAdapters/types.ts
@@ -1,4 +1,9 @@
-import type { CliAgentBackendState, CliAgentMessage, ExternalCliBackend } from '@aide/shared'
+import type {
+  CliAgentBackendState,
+  CliAgentMessage,
+  CliAgentTokenUsage,
+  ExternalCliBackend,
+} from '@aide/shared'
 
 export interface CliBackendTurnContext {
   conversationId: string
@@ -7,12 +12,43 @@ export interface CliBackendTurnContext {
   backendState: CliAgentBackendState
 }
 
+/**
+ * Permission request raised by an adapter (currently OpenCode) when the
+ * backend needs user approval for a tool/operation. The manager bridges these
+ * to the existing CHAT_TOOL_CALL surface via ApprovalRouter.
+ */
+export interface CliBackendPermissionRequest {
+  /** Stable id from the backend (e.g. OpenCode permission.id). */
+  permissionId: string
+  /** Backend session id. */
+  sessionId: string
+  /** Permission category (e.g. 'edit' | 'bash' | 'webfetch'). */
+  category: string
+  /** Human-readable title. */
+  title: string
+  /** Optional pattern (file path / shell command / URL). */
+  pattern?: string | string[]
+  metadata?: Record<string, unknown>
+}
+
 export type CliBackendEvent =
   | { type: 'stream-delta'; messageId: string; delta: string }
   | { type: 'message'; message: Omit<CliAgentMessage, 'backend'> }
   | { type: 'backend-state'; patch: Partial<CliAgentBackendState> }
   | { type: 'session-meta'; model?: string; tools?: string[] }
-  | { type: 'result'; durationMs: number; totalCostUsd: number; isSuccess: boolean }
+  | {
+      type: 'result'
+      durationMs: number
+      totalCostUsd: number
+      tokens?: CliAgentTokenUsage
+      isSuccess: boolean
+    }
+  | {
+      type: 'permission-request'
+      request: CliBackendPermissionRequest
+      /** Resolved by the manager once the user (or auto-approval) decides. */
+      resolve: (response: 'once' | 'always' | 'reject') => void
+    }
 
 export interface CliBackendRun {
   close(): void
diff --git a/packages/main/src/chat/cliAgentManager.ts b/packages/main/src/chat/cliAgentManager.ts
index df53558..91ca3e6 100644
--- a/packages/main/src/chat/cliAgentManager.ts
+++ b/packages/main/src/chat/cliAgentManager.ts
@@ -1,9 +1,16 @@
 /**
  * CLI Agent Manager — manages external CLI agent sessions.
  *
- * Unlike the original Claude-only implementation, this manager now owns the
- * generic session lifecycle for all external backends and delegates transport
- * details to backend adapters.
+ * Owns the generic session lifecycle for all external backends (claude-code,
+ * opencode, codex), delegates per-turn transport details to backend adapters,
+ * and bridges OpenCode's full SDK surface (sessions / config / providers /
+ * file / find / shell / lsp / etc.) into IPC-callable manager methods.
+ *
+ * Multi-workspace lifecycle: one CliAgentManager per WorkspaceRuntime, each
+ * owning its own per-workspace OpenCodeServerHost. The manager implements
+ * `ToolApprovalOwner` so its OpenCode permission prompts can flow through the
+ * single ApprovalRouter / CHAT_TOOL_CALL approval surface shared with the
+ * built-in agent.
  */
 
 import { randomUUID } from 'crypto'
@@ -14,28 +21,50 @@ import { app, type WebContents } from 'electron'
 import { IpcChannels, deriveTitle } from '@aide/shared'
 import type {
   AgentBackend,
+  CliAgentBackendState,
   CliAgentBackendStateMap,
   CliAgentMessage,
   CliAgentMessagePayload,
+  CliAgentPermissionRequest,
   CliAgentProcessStatus,
   CliAgentResultPayload,
   CliAgentSession,
   CliAgentStatusPayload,
   CliAgentStreamDelta,
+  CliAgentTokenUsage,
+  CliAgentWorkspaceCostSummary,
   ConversationListChangedPayload,
   ExternalCliBackend,
+  OpenCodeAgentSummary,
+  OpenCodeAuthMethod,
+  OpenCodeFileEntry,
+  OpenCodeFindResult,
+  OpenCodePathInfo,
+  OpenCodeProviderSummary,
+  OpenCodeServerInfo,
+  OpenCodeShellResult,
+  OpenCodeSymbolResult,
+  OpenCodeToolSummary,
+  OpenCodeTodoItem,
+  PermissionTier,
+  ToolPermissionConfig,
 } from '@aide/shared'
 import type { ConversationStore } from './conversationStore'
 import { createClaudeCodeAdapter } from './cliAdapters/claudeCodeAdapter'
 import { createCodexAdapter } from './cliAdapters/codexAdapter'
 import { createOpenCodeAdapter } from './cliAdapters/openCodeAdapter'
 import type { CliBackendAdapter, CliBackendEvent, CliBackendRun } from './cliAdapters/types'
+import { OpenCodeServerHost } from './openCodeServerHost'
+import type { ToolApprovalOwner } from './approvalRouter'
+import type { ChatToolCallPayload, ToolCall } from '@aide/shared'
 
 interface PersistedCliConversation {
   messages?: CliAgentMessage[]
   activeBackend?: ExternalCliBackend
   backendStates?: CliAgentBackendStateMap
   claudeSessionId?: string
+  totalCostUsd?: number
+  totalTokens?: CliAgentTokenUsage
 }
 
 interface CliAgentSessionInternal {
@@ -49,18 +78,29 @@ interface CliAgentSessionInternal {
   sessionToolNames?: string[]
   lastError?: string
   totalCostUsd: number
+  totalTokens?: CliAgentTokenUsage
   worktreePath?: string
   backendStates: CliAgentBackendStateMap
 }
 
+interface PendingPermission {
+  sessionId: string
+  resolve: (response: 'always' | 'once' | 'reject') => void
+}
+
 export interface CliAgentManagerOpts {
   workspaceRoot: string
+  workspaceId?: string
   getWebContents: () => WebContents | null
   claudeCodePath?: string
   opencodePath?: string
   codexPath?: string
   conversationStore?: ConversationStore
   loadClaudeHistory?: (claudeSessionId: string) => Promise<CliAgentMessage[]>
+  permissionTier?: PermissionTier
+  autoApprove?: Record<string, boolean | ToolPermissionConfig>
+  /** Called when pending approvals / running session counts change. */
+  onWorkloadChanged?: () => void
 }
 
 function comparableHistoryCount(messages: CliAgentMessage[]): number {
@@ -92,12 +132,30 @@ function parsePersistedConversation(raw: unknown): PersistedCliConversation {
     activeBackend: persisted.activeBackend,
     backendStates,
     claudeSessionId: persisted.claudeSessionId,
+    totalCostUsd: persisted.totalCostUsd,
+    totalTokens: persisted.totalTokens,
+  }
+}
+
+function sumTokenUsage(
+  a: CliAgentTokenUsage | undefined,
+  b: CliAgentTokenUsage | undefined,
+): CliAgentTokenUsage | undefined {
+  if (!a) return b
+  if (!b) return a
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    reasoning: a.reasoning + b.reasoning,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
   }
 }
 
-export class CliAgentManager {
+export class CliAgentManager implements ToolApprovalOwner {
   private sessions = new Map<string, CliAgentSessionInternal>()
   private readonly workspaceRoot: string
+  private readonly workspaceId: string
   private readonly getWebContents: () => WebContents | null
   private claudeCodePath: string
   private opencodePath: string
@@ -107,19 +165,31 @@ export class CliAgentManager {
     | ((claudeSessionId: string) => Promise<CliAgentMessage[]>)
     | null
   private resolvedClaudeCodePath: string | null = null
-  private resolvedOpenCodePath: string | null = null
   private resolvedCodexPath: string | null = null
 
+  private permissionTier: PermissionTier
+  private autoApprove: Record<string, boolean | ToolPermissionConfig>
+  private readonly onWorkloadChanged?: () => void
+
+  private openCodeHost: OpenCodeServerHost | null = null
+  private pendingPermissions = new Map<string, PendingPermission>()
+
   constructor(opts: CliAgentManagerOpts) {
     this.workspaceRoot = opts.workspaceRoot
+    this.workspaceId = opts.workspaceId ?? ''
     this.getWebContents = opts.getWebContents
     this.claudeCodePath = opts.claudeCodePath ?? ''
     this.opencodePath = opts.opencodePath ?? ''
     this.codexPath = opts.codexPath ?? ''
     this.conversationStore = opts.conversationStore ?? null
     this.loadClaudeHistory = opts.loadClaudeHistory ?? null
+    this.permissionTier = opts.permissionTier ?? 'confirm'
+    this.autoApprove = opts.autoApprove ?? {}
+    this.onWorkloadChanged = opts.onWorkloadChanged
   }
 
+  // ─── Lifecycle ──────────────────────────────────────────────
+
   async start(
     workspaceId: string,
     backend: AgentBackend,
@@ -198,7 +268,8 @@ export class CliAgentManager {
       activeRun: null,
       processStatus: 'stopped',
       messages: existingMessages,
-      totalCostUsd: 0,
+      totalCostUsd: persisted.totalCostUsd ?? 0,
+      totalTokens: persisted.totalTokens,
       model: backendStates[backend]?.model,
       worktreePath,
       backendStates,
@@ -277,6 +348,7 @@ export class CliAgentManager {
 
     session.activeRun = run
     this.setStatus(session, 'running')
+    this.notifyWorkloadChanged()
 
     run.completed
       .catch((error) => {
@@ -291,7 +363,15 @@ export class CliAgentManager {
         if (session.processStatus === 'stopping' || session.processStatus === 'running') {
           this.setStatus(session, 'stopped')
         }
+        // Clear any unresolved permissions for this session.
+        for (const [id, pending] of this.pendingPermissions) {
+          if (pending.sessionId === session.id) {
+            pending.resolve('reject')
+            this.pendingPermissions.delete(id)
+          }
+        }
         await this.persistSession(session)
+        this.notifyWorkloadChanged()
       })
 
     return { success: true }
@@ -334,8 +414,19 @@ export class CliAgentManager {
     this.opencodePath = opencodePath
     this.codexPath = codexPath
     this.resolvedClaudeCodePath = null
-    this.resolvedOpenCodePath = null
     this.resolvedCodexPath = null
+    if (this.openCodeHost) {
+      this.openCodeHost.setPath(opencodePath)
+    }
+  }
+
+  /** Update permission tier / autoApprove map (called from settings-changed handler). */
+  updatePermissions(
+    tier: PermissionTier,
+    autoApprove: Record<string, boolean | ToolPermissionConfig>,
+  ): void {
+    this.permissionTier = tier
+    this.autoApprove = autoApprove
   }
 
   getRunningSessionCount(): number {
@@ -346,26 +437,751 @@ export class CliAgentManager {
     return count
   }
 
+  /** Workspace-wide cost / token rollup across this manager's sessions. */
+  getWorkspaceCostSummary(): CliAgentWorkspaceCostSummary {
+    let totalCostUsd = 0
+    let totalTokens: CliAgentTokenUsage | undefined = undefined
+    let sessionCount = 0
+    for (const session of this.sessions.values()) {
+      sessionCount += 1
+      totalCostUsd += session.totalCostUsd
+      totalTokens = sumTokenUsage(totalTokens, session.totalTokens)
+    }
+    return {
+      workspaceId: this.workspaceId,
+      totalCostUsd,
+      totalTokens: totalTokens ?? {
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+      },
+      sessionCount,
+    }
+  }
+
   async destroy(): Promise<void> {
     for (const session of this.sessions.values()) {
       session.activeRun?.close()
       await this.persistSession(session).catch(() => {})
     }
     this.sessions.clear()
+    if (this.openCodeHost) {
+      try {
+        await this.openCodeHost.dispose()
+      } catch {
+        /* ignore */
+      }
+      this.openCodeHost = null
+    }
+    // Resolve any outstanding permissions as rejected.
+    for (const pending of this.pendingPermissions.values()) {
+      pending.resolve('reject')
+    }
+    this.pendingPermissions.clear()
+  }
+
+  // ─── ToolApprovalOwner (for ApprovalRouter) ────────────────────
+
+  ownsToolCall(toolCallId: string): boolean {
+    return this.pendingPermissions.has(toolCallId)
+  }
+
+  approveToolCall(_sessionId: string, toolCallId: string): void {
+    const pending = this.pendingPermissions.get(toolCallId)
+    if (!pending) return
+    this.pendingPermissions.delete(toolCallId)
+    pending.resolve('always')
+    this.notifyWorkloadChanged()
+  }
+
+  rejectToolCall(_sessionId: string, toolCallId: string): void {
+    const pending = this.pendingPermissions.get(toolCallId)
+    if (!pending) return
+    this.pendingPermissions.delete(toolCallId)
+    pending.resolve('reject')
+    this.notifyWorkloadChanged()
+  }
+
+  getPendingApprovalCount(): number {
+    return this.pendingPermissions.size
+  }
+
+  // ─── Per-session config (Phase 2 wiring) ───────────────────────
+
+  async updateSessionConfig(
+    sessionId: string,
+    patch: Partial<CliAgentBackendState>,
+  ): Promise<{ success: true } | { error: string }> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return { error: 'Session not found' }
+    const prior = session.backendStates[session.backend] ?? {}
+    session.backendStates[session.backend] = { ...prior, ...patch }
+    if (patch.model) session.model = patch.model
+    await this.persistSession(session)
+    this.emitStatus(session)
+    return { success: true }
+  }
+
+  // ─── OpenCode SDK passthroughs (Phase 2 / 6 / 7 / 8) ───────────
+
+  private async getOpenCodeClient(sessionId: string) {
+    const session = this.sessions.get(sessionId)
+    if (!session) throw new Error('Session not found')
+    if (session.backend !== 'opencode') {
+      throw new Error('This operation is only available for OpenCode sessions.')
+    }
+    const host = this.ensureOpenCodeHost()
+    return host.getClient()
+  }
+
+  async listOpenCodeProviders(sessionId: string): Promise<OpenCodeProviderSummary[]> {
+    const client = await this.getOpenCodeClient(sessionId)
+    // Shape: { providers: Provider[], default: Record<string,string> }
+    // Provider.models is Record<modelID, Model> where Model has nested
+    // capabilities + cost.cache subfields (NOT flat tool_call / cache_read).
+    const result = await callSdk<{
+      providers?: Array<{
+        id?: string
+        name?: string
+        models?: Record<
+          string,
+          {
+            id?: string
+            name?: string
+            capabilities?: {
+              reasoning?: boolean
+              attachment?: boolean
+              toolcall?: boolean
+            }
+            cost?: {
+              input: number
+              output: number
+              cache?: { read: number; write: number }
+            }
+          }
+        >
+      }>
+    }>(() => (client as any).config.providers())
+    return (result?.providers ?? []).map((p) => ({
+      id: p.id ?? '',
+      name: p.name ?? p.id ?? '',
+      models: Object.entries(p.models ?? {}).map(([modelId, m]) => ({
+        id: m.id ?? modelId,
+        name: m.name ?? m.id ?? modelId,
+        reasoning: m.capabilities?.reasoning,
+        attachment: m.capabilities?.attachment,
+        toolCall: m.capabilities?.toolcall,
+        cost: m.cost
+          ? {
+              input: m.cost.input,
+              output: m.cost.output,
+              cacheRead: m.cost.cache?.read,
+              cacheWrite: m.cost.cache?.write,
+            }
+          : undefined,
+      })),
+    }))
+  }
+
+  async listOpenCodeAgents(sessionId: string): Promise<OpenCodeAgentSummary[]> {
+    const client = await this.getOpenCodeClient(sessionId)
+    const result = await callSdk<
+      Array<{ name?: string; description?: string; mode?: string }>
+    >(() => (client as any).app.agents())
+    if (!Array.isArray(result)) return []
+    return result.map((a) => ({
+      name: a.name ?? '',
+      description: a.description,
+      mode: a.mode,
+    }))
+  }
+
+  async listOpenCodeModes(sessionId: string): Promise<string[]> {
+    const client = await this.getOpenCodeClient(sessionId)
+    const result = await callSdk<{ agents?: Record<string, { mode?: string }> }>(() =>
+      (client as any).config.get(),
+    )
+    const modes = new Set<string>(['primary', 'subagent', 'all'])
+    for (const agent of Object.values(result?.agents ?? {})) {
+      if (agent?.mode) modes.add(agent.mode)
+    }
+    return Array.from(modes)
+  }
+
+  async listOpenCodeTools(
+    sessionId: string,
+    providerID: string,
+    modelID: string,
+  ): Promise<OpenCodeToolSummary[]> {
+    const client = await this.getOpenCodeClient(sessionId)
+    try {
+      // SDK query expects { provider, model } (not providerID/modelID).
+      const result = await callSdk<
+        Array<{ id?: string; description?: string; parameters?: unknown }>
+      >(() => (client as any).tool.list({ query: { provider: providerID, model: modelID } }))
+      if (Array.isArray(result)) {
+        return result.map((t) => ({
+          id: t.id ?? '',
+          description: t.description,
+          schema: t.parameters,
+        }))
+      }
+    } catch {
+      // Fallback to ids() if list() rejects
+    }
+    const ids = await callSdk<string[]>(() => (client as any).tool.ids())
+    return (ids ?? []).map((id) => ({ id }))
+  }
+
+  // ─── Session ops ─────────────────────────────────────────────
+
+  async sessionShare(sessionId: string): Promise<{ url?: string; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const session = this.sessions.get(sessionId)
+      const remoteId = session?.backendStates['opencode']?.sessionId
+      if (!remoteId) return { error: 'No active OpenCode session id' }
+      const result = await callSdk<{ url?: string; share?: { url?: string } }>(() =>
+        (client as any).session.share({ path: { id: remoteId } }),
+      )
+      return { url: result?.url ?? result?.share?.url }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionUnshare(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.unshare({ path: { id: remoteId } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionSummarize(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.summarize({ path: { id: remoteId } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionRevert(
+    sessionId: string,
+    messageId: string,
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() =>
+        (client as any).session.revert({
+          path: { id: remoteId },
+          body: { messageID: messageId },
+        }),
+      )
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionUnrevert(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.unrevert({ path: { id: remoteId } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionFork(
+    sessionId: string,
+    messageId: string,
+  ): Promise<{ newSessionId?: string; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      const result = await callSdk<{ id?: string }>(() =>
+        (client as any).session.fork({
+          path: { id: remoteId },
+          body: { messageID: messageId },
+        }),
+      )
+      return { newSessionId: result?.id }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionAbort(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.abort({ path: { id: remoteId } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionDiff(
+    sessionId: string,
+  ): Promise<{ diff?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      const result = await callSdk<unknown>(() =>
+        (client as any).session.diff({ path: { id: remoteId } }),
+      )
+      return { diff: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionTodo(
+    sessionId: string,
+  ): Promise<{ todos?: OpenCodeTodoItem[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      const result = await callSdk<Array<{ id?: string; text?: string; done?: boolean }>>(() =>
+        (client as any).session.todo({ path: { id: remoteId } }),
+      )
+      const todos = (Array.isArray(result) ? result : []).map((t) => ({
+        id: t.id ?? '',
+        text: t.text ?? '',
+        done: t.done,
+      }))
+      return { todos }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionInit(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.init({ path: { id: remoteId } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async sessionDeleteRemote(sessionId: string): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      await callSdk(() => (client as any).session.delete({ path: { id: remoteId } }))
+      // Clear local backend state since the remote session is gone.
+      const session = this.sessions.get(sessionId)
+      if (session) {
+        delete session.backendStates['opencode']
+        await this.persistSession(session)
+      }
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
   }
 
+  // ─── Workspace ops (Phase 7) ───────────────────────────────────
+
+  async fileList(
+    sessionId: string,
+    path: string,
+  ): Promise<{ entries?: OpenCodeFileEntry[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<
+        Array<{
+          path?: string
+          name?: string
+          type?: string
+          size?: number
+          modified?: number
+        }>
+      >(() => (client as any).file.list({ query: { path, directory: this.workspaceRoot } }))
+      const entries = (Array.isArray(result) ? result : []).map((e) => ({
+        path: e.path ?? '',
+        name: e.name ?? '',
+        isDirectory: e.type === 'directory' || e.type === 'dir',
+        size: e.size,
+        modified: e.modified,
+      }))
+      return { entries }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async fileRead(
+    sessionId: string,
+    path: string,
+  ): Promise<{ content?: string; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<{ content?: string } | string>(() =>
+        (client as any).file.read({ query: { path, directory: this.workspaceRoot } }),
+      )
+      if (typeof result === 'string') return { content: result }
+      return { content: result?.content }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async fileStatus(sessionId: string): Promise<{ status?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() =>
+        (client as any).file.status({ query: { directory: this.workspaceRoot } }),
+      )
+      return { status: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async findText(
+    sessionId: string,
+    query: string,
+  ): Promise<{ results?: OpenCodeFindResult[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<
+        Array<{ path?: string; line?: number; column?: number; text?: string; preview?: string }>
+      >(() => (client as any).find.text({ query: { query, directory: this.workspaceRoot } }))
+      const results = (Array.isArray(result) ? result : []).map((r) => ({
+        path: r.path ?? '',
+        line: r.line,
+        column: r.column,
+        preview: r.preview ?? r.text,
+        matchText: r.text,
+      }))
+      return { results }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async findFiles(
+    sessionId: string,
+    pattern: string,
+  ): Promise<{ paths?: string[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<string[] | Array<{ path?: string }>>(() =>
+        (client as any).find.files({ query: { pattern, directory: this.workspaceRoot } }),
+      )
+      const arr = Array.isArray(result) ? result : []
+      const paths = arr.map((p) => (typeof p === 'string' ? p : (p.path ?? '')))
+      return { paths }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async findSymbols(
+    sessionId: string,
+    query: string,
+  ): Promise<{ symbols?: OpenCodeSymbolResult[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<
+        Array<{
+          name?: string
+          kind?: string | number
+          path?: string
+          line?: number
+          column?: number
+        }>
+      >(() => (client as any).find.symbols({ query: { query, directory: this.workspaceRoot } }))
+      const symbols = (Array.isArray(result) ? result : []).map((s) => ({
+        name: s.name ?? '',
+        kind: typeof s.kind === 'string' ? s.kind : String(s.kind ?? ''),
+        path: s.path ?? '',
+        line: s.line,
+        column: s.column,
+      }))
+      return { symbols }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async shellRun(
+    sessionId: string,
+    command: string,
+  ): Promise<{ result?: OpenCodeShellResult; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const remoteId = this.requireRemoteId(sessionId)
+      const result = await callSdk<{
+        exitCode?: number
+        stdout?: string
+        stderr?: string
+      }>(() =>
+        (client as any).session.shell({
+          path: { id: remoteId },
+          body: { command },
+        }),
+      )
+      return {
+        result: {
+          exitCode: result?.exitCode ?? 0,
+          stdout: result?.stdout ?? '',
+          stderr: result?.stderr ?? '',
+        },
+      }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async lspStatus(sessionId: string): Promise<{ status?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() => (client as any).lsp.status())
+      return { status: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async formatterStatus(sessionId: string): Promise<{ status?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() => (client as any).formatter.status())
+      return { status: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  // ─── Config / auth / providers (Phase 8) ───────────────────────
+
+  async configGet(sessionId: string): Promise<{ config?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() => (client as any).config.get())
+      return { config: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async configUpdate(
+    sessionId: string,
+    patch: Record<string, unknown>,
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      await callSdk(() => (client as any).config.update({ body: patch }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async configProviders(sessionId: string): Promise<{ providers?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() => (client as any).config.providers())
+      return { providers: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async authSet(
+    sessionId: string,
+    key: string,
+    value: string,
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      await callSdk(() => (client as any).auth.set({ body: { key, value } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async providerList(sessionId: string): Promise<{ providers?: unknown; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<unknown>(() => (client as any).provider.list())
+      return { providers: result }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async providerAuth(
+    sessionId: string,
+    providerId: string,
+  ): Promise<{ methods?: OpenCodeAuthMethod[]; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<
+        Array<{ id?: string; label?: string; type?: string }>
+      >(() => (client as any).provider.auth({ query: { providerID: providerId } }))
+      const methods = (Array.isArray(result) ? result : []).map((m) => ({
+        id: m.id ?? '',
+        label: m.label,
+        type: (m.type === 'oauth' || m.type === 'apiKey' || m.type === 'env'
+          ? m.type
+          : 'unknown') as OpenCodeAuthMethod['type'],
+      }))
+      return { methods }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async providerOauthAuthorize(
+    sessionId: string,
+    providerId: string,
+  ): Promise<{ url?: string; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<{ url?: string }>(() =>
+        (client as any).provider.oauth.authorize({ query: { providerID: providerId } }),
+      )
+      return { url: result?.url }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async providerOauthCallback(
+    sessionId: string,
+    code: string,
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      await callSdk(() => (client as any).provider.oauth.callback({ query: { code } }))
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async pathGet(sessionId: string): Promise<{ paths?: OpenCodePathInfo; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const result = await callSdk<OpenCodePathInfo>(() => (client as any).path.get())
+      return { paths: result ?? {} }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  async logWrite(
+    sessionId: string,
+    message: string,
+    level?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      await callSdk(() =>
+        (client as any).app.log({ body: { message, level: level ?? 'INFO' } }),
+      )
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  serverInfo(): OpenCodeServerInfo | null {
+    return this.openCodeHost?.getInfo() ?? null
+  }
+
+  // ─── TUI control (Phase 8) ─────────────────────────────────────
+
+  async tui(
+    sessionId: string,
+    method:
+      | 'appendPrompt'
+      | 'submitPrompt'
+      | 'clearPrompt'
+      | 'openHelp'
+      | 'openSessions'
+      | 'openThemes'
+      | 'openModels'
+      | 'executeCommand'
+      | 'showToast',
+    args?: Record<string, unknown>,
+  ): Promise<{ success?: true; error?: string }> {
+    try {
+      const client = await this.getOpenCodeClient(sessionId)
+      const tui = (client as any).tui
+      const opts = args ? { body: args } : undefined
+      switch (method) {
+        case 'appendPrompt':
+          await callSdk(() => tui.appendPrompt(opts))
+          break
+        case 'submitPrompt':
+          await callSdk(() => tui.submitPrompt())
+          break
+        case 'clearPrompt':
+          await callSdk(() => tui.clearPrompt())
+          break
+        case 'openHelp':
+          await callSdk(() => tui.openHelp())
+          break
+        case 'openSessions':
+          await callSdk(() => tui.openSessions())
+          break
+        case 'openThemes':
+          await callSdk(() => tui.openThemes())
+          break
+        case 'openModels':
+          await callSdk(() => tui.openModels())
+          break
+        case 'executeCommand':
+          await callSdk(() => tui.executeCommand(opts))
+          break
+        case 'showToast':
+          await callSdk(() => tui.showToast(opts))
+          break
+      }
+      return { success: true }
+    } catch (error) {
+      return { error: errMsg(error) }
+    }
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────
+
   private toPublicSession(session: CliAgentSessionInternal): CliAgentSession {
     return {
       id: session.id,
       workspaceId: session.workspaceId,
       backend: session.backend,
+      activeBackend: session.backend,
       processStatus: session.processStatus,
       messages: session.messages,
       model: session.model,
       sessionToolNames: session.sessionToolNames,
       lastError: session.lastError,
       totalCostUsd: session.totalCostUsd,
+      totalTokens: session.totalTokens,
       worktreePath: session.worktreePath,
+      backendStates: session.backendStates,
     }
   }
 
@@ -381,18 +1197,14 @@ export class CliAgentManager {
     }
 
     if (backend === 'opencode') {
-      const executablePath = this.resolveGenericExecutable(
-        'opencode',
-        this.opencodePath,
-        this.resolvedOpenCodePath,
-      )
-      if (!executablePath) {
-        throw new Error(
-          'OpenCode CLI not found. Install opencode or set agent.opencodePath in settings.',
-        )
-      }
-      this.resolvedOpenCodePath = executablePath
-      return createOpenCodeAdapter({ executablePath })
+      const host = this.ensureOpenCodeHost()
+      return createOpenCodeAdapter({
+        host,
+        getPermissionSettings: () => ({
+          tier: this.permissionTier,
+          autoApprove: this.autoApprove,
+        }),
+      })
     }
 
     const executablePath = this.resolveGenericExecutable(
@@ -409,6 +1221,23 @@ export class CliAgentManager {
     return createCodexAdapter({ executablePath })
   }
 
+  private ensureOpenCodeHost(): OpenCodeServerHost {
+    if (!this.openCodeHost) {
+      this.openCodeHost = new OpenCodeServerHost({
+        workspaceRoot: this.workspaceRoot,
+        explicitPath: this.opencodePath,
+      })
+    }
+    return this.openCodeHost
+  }
+
+  private requireRemoteId(localSessionId: string): string {
+    const session = this.sessions.get(localSessionId)
+    const remote = session?.backendStates['opencode']?.sessionId
+    if (!remote) throw new Error('No remote OpenCode session id; send a message first.')
+    return remote
+  }
+
   private resolveClaudeCodeExecutable(): string | null {
     if (this.resolvedClaudeCodePath) return this.resolvedClaudeCodePath
 
@@ -531,14 +1360,24 @@ export class CliAgentManager {
 
     if (event.type === 'result') {
       session.totalCostUsd += event.totalCostUsd
+      if (event.tokens) {
+        session.totalTokens = sumTokenUsage(session.totalTokens, event.tokens)
+      }
       const payload: CliAgentResultPayload = {
         workspaceId: session.workspaceId,
         sessionId: session.id,
         durationMs: event.durationMs,
         totalCostUsd: session.totalCostUsd,
+        totalTokens: session.totalTokens,
         isSuccess: event.isSuccess,
       }
       this.getWebContents()?.send(IpcChannels.CLI_AGENT_RESULT, payload)
+      this.broadcastWorkspaceCost(session.workspaceId)
+      return
+    }
+
+    if (event.type === 'permission-request') {
+      this.handlePermissionRequest(session, event.request, event.resolve)
       return
     }
 
@@ -556,6 +1395,56 @@ export class CliAgentManager {
     }
   }
 
+  /**
+   * Bridge an OpenCode permission event into the existing CHAT_TOOL_CALL
+   * approval surface so the IDE has one approval UI for both backends.
+   */
+  private handlePermissionRequest(
+    session: CliAgentSessionInternal,
+    request: import('./cliAdapters/types').CliBackendPermissionRequest,
+    resolve: (response: 'always' | 'once' | 'reject') => void,
+  ): void {
+    const toolCallId = randomUUID()
+    this.pendingPermissions.set(toolCallId, {
+      sessionId: session.id,
+      resolve,
+    })
+
+    const toolCall: ToolCall = {
+      id: toolCallId,
+      name: `opencode:${request.category}`,
+      input: {
+        title: request.title,
+        pattern: request.pattern,
+        ...(request.metadata ?? {}),
+      },
+      status: 'pending',
+    }
+
+    const payload: ChatToolCallPayload = {
+      workspaceId: session.workspaceId,
+      sessionId: session.id,
+      toolCall,
+    }
+    this.getWebContents()?.send(IpcChannels.CHAT_TOOL_CALL, payload)
+
+    // Also emit a structured CLI agent permission request payload for any
+    // surface that wants the rich form (badges, metadata).
+    const richPayload: CliAgentPermissionRequest = {
+      workspaceId: session.workspaceId,
+      sessionId: session.id,
+      toolCallId,
+      backend: 'opencode',
+      title: request.title,
+      category: request.category,
+      pattern: request.pattern,
+      metadata: request.metadata,
+      timestamp: Date.now(),
+    }
+    void richPayload // (channel reserved for future granular UI; CHAT_TOOL_CALL is the active surface)
+    this.notifyWorkloadChanged()
+  }
+
   private buildTurnPrompt(session: CliAgentSessionInternal, content: string): string {
     const backendState = session.backendStates[session.backend]
     if (backendState?.sessionId) {
@@ -634,6 +1523,20 @@ export class CliAgentManager {
     this.getWebContents()?.send(IpcChannels.CLI_AGENT_MESSAGE, payload)
   }
 
+  private broadcastWorkspaceCost(workspaceId: string): void {
+    const summary = this.getWorkspaceCostSummary()
+    if (workspaceId) summary.workspaceId = workspaceId
+    this.getWebContents()?.send(IpcChannels.CLI_AGENT_WORKSPACE_COST, summary)
+  }
+
+  private notifyWorkloadChanged(): void {
+    try {
+      this.onWorkloadChanged?.()
+    } catch {
+      /* ignore */
+    }
+  }
+
   private async persistSession(session: CliAgentSessionInternal): Promise<void> {
     if (!this.conversationStore || session.id.startsWith('claude-native:')) return
 
@@ -643,6 +1546,8 @@ export class CliAgentManager {
       activeBackend: session.backend,
       backendStates: session.backendStates,
       claudeSessionId,
+      totalCostUsd: session.totalCostUsd,
+      totalTokens: session.totalTokens,
     } satisfies PersistedCliConversation)
 
     await this.conversationStore.updateMeta(session.id, {
@@ -683,3 +1588,27 @@ export class CliAgentManager {
     } satisfies ConversationListChangedPayload)
   }
 }
+
+// ─── SDK call helpers ──────────────────────────────────────────
+
+/**
+ * Wraps an SDK promise so we can deal with both `responseStyle: 'data'`
+ * (returns the unwrapped data) and the older `{ data, error }` shape.
+ * If `error` is set, throws.
+ */
+async function callSdk<T>(fn: () => Promise<unknown>): Promise<T | undefined> {
+  const result = await fn()
+  if (result && typeof result === 'object' && 'error' in (result as Record<string, unknown>)) {
+    const wrapper = result as { data?: unknown; error?: unknown }
+    if (wrapper.error) {
+      const err = wrapper.error as { message?: string } | string
+      throw new Error(typeof err === 'string' ? err : (err.message ?? 'OpenCode SDK error'))
+    }
+    return wrapper.data as T | undefined
+  }
+  return result as T | undefined
+}
+
+function errMsg(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
diff --git a/packages/main/src/chat/openCodeServerHost.ts b/packages/main/src/chat/openCodeServerHost.ts
new file mode 100644
index 0000000..a1ac09b
--- /dev/null
+++ b/packages/main/src/chat/openCodeServerHost.ts
@@ -0,0 +1,410 @@
+/**
+ * OpenCodeServerHost — per-workspace persistent OpenCode server.
+ *
+ * Owns one `opencode serve` child process per workspace and a shared SSE
+ * subscription that is fanned out to per-session listener bags. Adapters
+ * (one per turn) attach to the host, get a client + a per-session event
+ * subscription, run their turn, and detach — the server stays running for
+ * the workspace's lifetime.
+ *
+ * Lifecycle:
+ *   - `start()`        → idempotent; spawns + waits for "listening"
+ *   - `subscribe(id)`  → returns an unsubscribe fn; emits opencode events
+ *                        whose sessionID matches `id` (or null sessionID for
+ *                        broadcast events like installation.*)
+ *   - `respondPermission(sessionId, permissionId, response)` → POSTs
+ *   - `dispose()`      → kills the process, aborts SSE, clears listeners
+ *   - `setPath(path)`  → swap the binary used on next (re)start
+ *
+ * Multi-workspace parallelism is the default: each workspace's CliAgentManager
+ * owns its own host instance; ports are reserved fresh per host so two hosts
+ * never collide.
+ */
+
+import { spawn, type ChildProcess } from 'child_process'
+import { createServer } from 'net'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { app } from 'electron'
+import { execFileSync } from 'child_process'
+import { createOpencodeClient } from '@opencode-ai/sdk/client'
+
+type OpencodeClient = ReturnType<typeof createOpencodeClient>
+
+export type OpenCodeHostMode = 'auto' | 'external'
+
+export interface OpenCodeHostOptions {
+  workspaceRoot: string
+  /** Explicit binary path; if set, "external" mode is forced. */
+  explicitPath?: string
+}
+
+export interface OpenCodeServerInfoSnapshot {
+  url: string
+  mode: 'bundled' | 'external'
+  pid?: number
+  startedAt: number
+}
+
+type EventListener = (event: unknown) => void
+
+interface SubscriberEntry {
+  sessionId: string | null
+  listener: EventListener
+}
+
+export class OpenCodeServerHost {
+  private workspaceRoot: string
+  private explicitPath: string
+
+  private startPromise: Promise<void> | null = null
+  private url: string | null = null
+  private serverProc: ChildProcess | null = null
+  private startedAt = 0
+  private mode: 'bundled' | 'external' = 'bundled'
+  private client: OpencodeClient | null = null
+  private resolvedPath: string | null = null
+
+  private subscribers = new Set<SubscriberEntry>()
+  private sseAbort: AbortController | null = null
+  private sseTask: Promise<void> | null = null
+  private disposed = false
+
+  constructor(options: OpenCodeHostOptions) {
+    this.workspaceRoot = options.workspaceRoot
+    this.explicitPath = options.explicitPath ?? ''
+  }
+
+  /** Returns the OpencodeClient (starts the host on first call). */
+  async getClient(): Promise<OpencodeClient> {
+    await this.start()
+    if (!this.client) throw new Error('OpenCodeServerHost: client unavailable after start()')
+    return this.client
+  }
+
+  /** Idempotent start. Re-entrant calls return the same promise. */
+  async start(): Promise<void> {
+    if (this.disposed) throw new Error('OpenCodeServerHost has been disposed')
+    if (this.startPromise) return this.startPromise
+    this.startPromise = this.doStart().catch((error) => {
+      this.startPromise = null
+      throw error
+    })
+    return this.startPromise
+  }
+
+  private async doStart(): Promise<void> {
+    const binaryPath = this.resolveBinaryPath()
+    if (!binaryPath) {
+      throw new Error(
+        'OpenCode CLI not found. Install opencode (npm i -g opencode-ai) or set agent.opencodePath in settings.',
+      )
+    }
+    this.resolvedPath = binaryPath
+    this.mode = this.explicitPath ? 'external' : 'bundled'
+
+    const port = await reservePort()
+    const url = `http://127.0.0.1:${port}`
+    const proc = spawn(binaryPath, ['serve', '--hostname=127.0.0.1', `--port=${port}`], {
+      env: {
+        ...process.env,
+        OPENCODE_CONFIG_CONTENT: JSON.stringify({}),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    if (!proc) throw new Error('Failed to spawn OpenCode server process')
+
+    try {
+      await waitForOpenCodeServer(proc, url)
+    } catch (error) {
+      proc.kill('SIGTERM')
+      throw error
+    }
+
+    this.serverProc = proc
+    this.url = url
+    this.startedAt = Date.now()
+
+    this.client = createOpencodeClient({
+      baseUrl: url,
+      directory: this.workspaceRoot,
+      responseStyle: 'data',
+      throwOnError: true,
+    } as Parameters<typeof createOpencodeClient>[0])
+
+    proc.once('exit', (code, signal) => {
+      if (this.disposed) return
+      // Server crashed unexpectedly — clear state so the next call re-spawns.
+      this.handleServerExit(`server exited (code=${code} signal=${signal})`)
+    })
+
+    // Start the shared SSE stream.
+    this.beginSse()
+  }
+
+  private beginSse(): void {
+    if (this.sseAbort) return
+    if (!this.client) return
+    this.sseAbort = new AbortController()
+    const signal = this.sseAbort.signal
+    const directory = this.workspaceRoot
+    this.sseTask = (async () => {
+      try {
+        // Use `/event` (Event.subscribe) — it yields the unwrapped Event union
+        // (`{ type, properties }`) directly and accepts a `directory` query
+        // filter so we only receive events for this workspace's server.
+        //
+        // The previous implementation used `client.global.event()` which yields
+        // `GlobalEvent = { directory, payload: Event }`; that wrapping caused
+        // every dispatched event to look like `{ type: undefined }` and the
+        // adapter would never observe `session.idle`, so OpenCode chats never
+        // replied.
+        const sse = await (this.client as unknown as {
+          event: {
+            subscribe: (opts: {
+              query?: { directory?: string }
+              signal?: AbortSignal
+            }) => Promise<{ stream: AsyncIterable<unknown> }>
+          }
+        }).event.subscribe({ query: { directory }, signal })
+        for await (const rawEvent of sse.stream) {
+          if (signal.aborted) break
+          this.dispatchEvent(rawEvent)
+        }
+      } catch (error) {
+        if (signal.aborted || this.disposed) return
+        // SSE crashed — surface as a synthetic event so listeners can react.
+        this.dispatchEvent({
+          type: 'sse.error',
+          properties: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        })
+      }
+    })()
+  }
+
+  private dispatchEvent(rawEvent: unknown): void {
+    const event = rawEvent as { type?: string; properties?: Record<string, unknown> }
+    const props = (event?.properties ?? {}) as Record<string, unknown>
+    const explicitSessionID =
+      typeof props.sessionID === 'string'
+        ? (props.sessionID as string)
+        : typeof (props.info as { sessionID?: string } | undefined)?.sessionID === 'string'
+          ? ((props.info as { sessionID?: string }).sessionID as string)
+          : typeof (props.part as { sessionID?: string } | undefined)?.sessionID === 'string'
+            ? ((props.part as { sessionID?: string }).sessionID as string)
+            : null
+
+    for (const sub of this.subscribers) {
+      if (sub.sessionId === null || explicitSessionID === null || sub.sessionId === explicitSessionID) {
+        try {
+          sub.listener(rawEvent)
+        } catch {
+          // Listener errors must not break the SSE pump.
+        }
+      }
+    }
+  }
+
+  /**
+   * Subscribe to events for a particular sessionId. Returns an unsubscribe fn.
+   * Pass `null` to receive every event (used by diagnostics surfaces).
+   */
+  subscribe(sessionId: string | null, listener: EventListener): () => void {
+    const entry: SubscriberEntry = { sessionId, listener }
+    this.subscribers.add(entry)
+    return () => {
+      this.subscribers.delete(entry)
+    }
+  }
+
+  /**
+   * Respond to an OpenCode permission request. Wraps the SDK's
+   * `postSessionIdPermissionsPermissionId` call so callers don't need to
+   * worry about its long name.
+   */
+  async respondPermission(
+    sessionId: string,
+    permissionId: string,
+    response: 'always' | 'once' | 'reject',
+  ): Promise<void> {
+    const client = await this.getClient()
+    await (client as unknown as {
+      postSessionIdPermissionsPermissionId: (opts: {
+        path: { id: string; permissionID: string }
+        body: { response: 'always' | 'once' | 'reject' }
+      }) => Promise<unknown>
+    }).postSessionIdPermissionsPermissionId({
+      path: { id: sessionId, permissionID: permissionId },
+      body: { response },
+    })
+  }
+
+  getInfo(): OpenCodeServerInfoSnapshot | null {
+    if (!this.url || !this.serverProc) return null
+    return {
+      url: this.url,
+      mode: this.mode,
+      pid: this.serverProc.pid,
+      startedAt: this.startedAt,
+    }
+  }
+
+  /** Update the explicit path used on next (re)start. Doesn't restart automatically. */
+  setPath(explicitPath: string): void {
+    this.explicitPath = explicitPath
+    this.resolvedPath = null
+  }
+
+  /**
+   * Restart the host: dispose current process and re-start. Subscribers are
+   * preserved across restarts (they'll receive events from the new server).
+   */
+  async restart(): Promise<void> {
+    await this.shutdownProcess('restart requested')
+    this.disposed = false
+    await this.start()
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    await this.shutdownProcess('disposed')
+    this.subscribers.clear()
+  }
+
+  private async shutdownProcess(reason: string): Promise<void> {
+    void reason
+    this.startPromise = null
+    if (this.sseAbort) {
+      try {
+        this.sseAbort.abort()
+      } catch {
+        /* ignore */
+      }
+      this.sseAbort = null
+    }
+    if (this.sseTask) {
+      try {
+        await this.sseTask
+      } catch {
+        /* ignore */
+      }
+      this.sseTask = null
+    }
+    if (this.serverProc) {
+      try {
+        this.serverProc.kill('SIGTERM')
+      } catch {
+        /* ignore */
+      }
+      this.serverProc = null
+    }
+    this.client = null
+    this.url = null
+  }
+
+  private handleServerExit(reason: string): void {
+    void reason
+    this.startPromise = null
+    this.serverProc = null
+    this.client = null
+    this.url = null
+    if (this.sseAbort) {
+      try {
+        this.sseAbort.abort()
+      } catch {
+        /* ignore */
+      }
+      this.sseAbort = null
+    }
+    this.sseTask = null
+  }
+
+  private resolveBinaryPath(): string | null {
+    if (this.resolvedPath) return this.resolvedPath
+
+    if (this.explicitPath && existsSync(this.explicitPath)) {
+      return this.explicitPath
+    }
+
+    const candidates: string[] = []
+    if (app.isPackaged) {
+      candidates.push(
+        join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', '.bin', 'opencode'),
+      )
+    }
+    candidates.push(
+      join(app.getAppPath(), 'node_modules', '.bin', 'opencode'),
+      join(this.workspaceRoot, 'node_modules', '.bin', 'opencode'),
+    )
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate
+    }
+
+    try {
+      const result = execFileSync('which', ['opencode'], { encoding: 'utf-8' }).trim()
+      if (result) return result
+    } catch {
+      // not on PATH
+    }
+    return null
+  }
+}
+
+async function reservePort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : null
+      server.close((error) => {
+        if (error) reject(error)
+        else if (typeof port === 'number') resolve(port)
+        else reject(new Error('Failed to reserve OpenCode port'))
+      })
+    })
+  })
+}
+
+async function waitForOpenCodeServer(proc: ChildProcess, url: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup()
+      reject(new Error('Timeout waiting for OpenCode server to start'))
+    }, 8000)
+
+    let output = ''
+    const onData = (chunk: Buffer) => {
+      output += chunk.toString()
+      if (output.includes(url) || output.includes('opencode server listening')) {
+        cleanup()
+        resolve()
+      }
+    }
+    const onExit = (code: number | null) => {
+      cleanup()
+      reject(new Error(`OpenCode server exited with code ${code}${output ? `\n${output}` : ''}`))
+    }
+    const onError = (error: Error) => {
+      cleanup()
+      reject(error)
+    }
+    const cleanup = () => {
+      clearTimeout(timeout)
+      proc.stdout?.off('data', onData)
+      proc.stderr?.off('data', onData)
+      proc.off('exit', onExit)
+      proc.off('error', onError)
+    }
+
+    proc.stdout?.on('data', onData)
+    proc.stderr?.on('data', onData)
+    proc.once('exit', onExit)
+    proc.once('error', onError)
+  })
+}
diff --git a/packages/main/src/chat/permissionMatching.ts b/packages/main/src/chat/permissionMatching.ts
new file mode 100644
index 0000000..41f6a95
--- /dev/null
+++ b/packages/main/src/chat/permissionMatching.ts
@@ -0,0 +1,129 @@
+/**
+ * Shared permission decision utilities.
+ *
+ * Lifted from `agentManager.ts` so both the built-in `AgentManager` and the
+ * `CliAgentManager` (for OpenCode permission events) can apply the same
+ * permission tier + autoApprove rules to tool/operation requests.
+ *
+ * The IDE's permission model lives in user settings:
+ *   - `agent.permissionTier`: 'confirm' | 'auto-approve' | 'autopilot'
+ *   - `agent.autoApprove`:    Record<toolName, boolean | { allowPatterns?, denyPatterns? }>
+ */
+
+import type { PermissionTier, ToolPermissionConfig } from '@aide/shared'
+
+/**
+ * IDE-canonical "read-only" tools — auto-approved under the `auto-approve`
+ * tier. These are the tool names used by the built-in `AgentManager`. The
+ * OpenCode permission bridge maps SDK permission categories onto these names
+ * (see `openCodePermissionBridge.ts`).
+ */
+export const READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
+  'file_read',
+  'file_list',
+  'search_files',
+  'git_status',
+  'git_diff',
+  'browser_read',
+])
+
+/**
+ * Decide whether a tool call should be auto-approved without prompting the user.
+ *
+ * Precedence (highest first):
+ *   1. autoApprove[toolName] === false  → deny
+ *   2. autoApprove[toolName] === true   → allow
+ *   3. autoApprove[toolName] is a pattern config → glob match against input
+ *   4. permissionTier:
+ *        - 'autopilot'    → allow everything
+ *        - 'auto-approve' → allow read-only tools, prompt for the rest
+ *        - 'confirm'      → prompt for everything
+ */
+export function shouldAutoApprove(
+  toolName: string,
+  input: Record<string, unknown>,
+  tier: PermissionTier,
+  autoApprove: Record<string, boolean | ToolPermissionConfig>,
+): boolean {
+  const override = autoApprove[toolName]
+  if (override === true) return true
+  if (override === false) return false
+  if (typeof override === 'object' && override !== null) {
+    return matchesPatternConfig(override, toolName, input)
+  }
+
+  switch (tier) {
+    case 'autopilot':
+      return true
+    case 'auto-approve':
+      return READ_ONLY_TOOLS.has(toolName)
+    case 'confirm':
+    default:
+      return false
+  }
+}
+
+/**
+ * Same as {@link shouldAutoApprove} but also distinguishes "explicitly denied"
+ * (deny pattern matched) from "not matched, fall through". The OpenCode bridge
+ * needs the three-way distinction to map onto OpenCode's `'always' | 'once'
+ * | 'reject'` permission response.
+ */
+export function evaluatePermission(
+  toolName: string,
+  input: Record<string, unknown>,
+  tier: PermissionTier,
+  autoApprove: Record<string, boolean | ToolPermissionConfig>,
+): 'allow' | 'deny' | 'prompt' {
+  const override = autoApprove[toolName]
+  if (override === false) return 'deny'
+  if (override === true) return 'allow'
+  if (typeof override === 'object' && override !== null) {
+    const matchTarget = matchTargetFor(toolName, input)
+    if (override.denyPatterns?.some((p) => globMatch(matchTarget, p))) return 'deny'
+    if (override.allowPatterns && override.allowPatterns.length > 0) {
+      return override.allowPatterns.some((p) => globMatch(matchTarget, p)) ? 'allow' : 'prompt'
+    }
+    return 'prompt'
+  }
+
+  switch (tier) {
+    case 'autopilot':
+      return 'allow'
+    case 'auto-approve':
+      return READ_ONLY_TOOLS.has(toolName) ? 'allow' : 'prompt'
+    case 'confirm':
+    default:
+      return 'prompt'
+  }
+}
+
+export function matchesPatternConfig(
+  config: ToolPermissionConfig,
+  toolName: string,
+  input: Record<string, unknown>,
+): boolean {
+  const matchTarget = matchTargetFor(toolName, input)
+
+  if (config.denyPatterns?.some((p) => globMatch(matchTarget, p))) {
+    return false
+  }
+  if (config.allowPatterns && config.allowPatterns.length > 0) {
+    return config.allowPatterns.some((p) => globMatch(matchTarget, p))
+  }
+  return false
+}
+
+function matchTargetFor(toolName: string, input: Record<string, unknown>): string {
+  if (toolName === 'terminal_exec') {
+    return String(input.command ?? '')
+  }
+  return JSON.stringify(input)
+}
+
+export function globMatch(text: string, pattern: string): boolean {
+  // Simple glob: * matches any sequence of characters.
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  const regex = new RegExp('^' + escaped.replace(/\*/g, '.*') + '$')
+  return regex.test(text)
+}
diff --git a/packages/main/src/index.ts b/packages/main/src/index.ts
index 4ec9fac..1b9390a 100644
--- a/packages/main/src/index.ts
+++ b/packages/main/src/index.ts
@@ -70,6 +70,7 @@ import { BrowserPaneManager } from './browserPaneManager'
 import { registerGitDiffHandlers } from './git/gitDiff'
 import { AgentManager } from './chat/agentManager'
 import { CliAgentManager } from './chat/cliAgentManager'
+import { ApprovalRouter } from './chat/approvalRouter'
 import { ConversationStore } from './chat/conversationStore'
 import { ClaudeNativeSessionWatcher } from './chat/claudeNativeSessionWatcher'
 import type {
@@ -535,6 +536,7 @@ async function startRuntimeServices(runtime: WorkspaceRuntime): Promise<void> {
   const resolved = resolveAppDefaults(store)
   const cliAgentManager = new CliAgentManager({
     workspaceRoot: rootPath,
+    workspaceId: runtime.workspaceId,
     getWebContents: () => contentView?.webContents ?? null,
     claudeCodePath: resolved['agent.claudeCodePath'],
     opencodePath: resolved['agent.opencodePath'],
@@ -542,14 +544,27 @@ async function startRuntimeServices(runtime: WorkspaceRuntime): Promise<void> {
     conversationStore,
     loadClaudeHistory: async (claudeSessionId: string) =>
       nativeSessionWatcher.loadMessages(claudeSessionId),
+    permissionTier: permConfig.permissionTier,
+    autoApprove: permConfig.autoApprove,
+    onWorkloadChanged: () => {
+      runtime.refreshWorkload()
+    },
   })
 
+  // ApprovalRouter dispatches CHAT_TOOL_APPROVE / CHAT_TOOL_REJECT to whichever
+  // manager owns the toolCallId, so OpenCode permission prompts and built-in
+  // chat approvals share a single approval surface.
+  const approvalRouter = new ApprovalRouter()
+  approvalRouter.register(agentManager)
+  approvalRouter.register(cliAgentManager)
+
   runtime.setServices({
     conversationStore,
     nativeSessionWatcher,
     nativeSessionCache,
     agentManager,
     cliAgentManager,
+    approvalRouter,
   })
 
   const getWc = () => contentView?.webContents ?? null
@@ -765,20 +780,27 @@ ipcMain.handle(
 ipcMain.handle(
   IpcChannels.CHAT_TOOL_APPROVE,
   async (_event, sessionId: string, toolCallId: string) => {
-    const runtime = findRuntimeWithBuiltInSession(sessionId)
-    const agentManager = getAgentManager(runtime)
-    agentManager?.approveToolCall(sessionId, toolCallId)
-    runtime?.refreshWorkload()
+    // Find the runtime that owns this toolCallId across both managers.
+    for (const runtime of runtimeRegistry.list()) {
+      const router = runtime.services.approvalRouter as ApprovalRouter | null
+      if (router?.approve(sessionId, toolCallId)) {
+        runtime.refreshWorkload()
+        return
+      }
+    }
   },
 )
 
 ipcMain.handle(
   IpcChannels.CHAT_TOOL_REJECT,
   async (_event, sessionId: string, toolCallId: string) => {
-    const runtime = findRuntimeWithBuiltInSession(sessionId)
-    const agentManager = getAgentManager(runtime)
-    agentManager?.rejectToolCall(sessionId, toolCallId)
-    runtime?.refreshWorkload()
+    for (const runtime of runtimeRegistry.list()) {
+      const router = runtime.services.approvalRouter as ApprovalRouter | null
+      if (router?.reject(sessionId, toolCallId)) {
+        runtime.refreshWorkload()
+        return
+      }
+    }
   },
 )
 
@@ -879,6 +901,258 @@ ipcMain.on(IpcChannels.CLI_AGENT_STOP, (_event, sessionId: string) => {
   runtime?.refreshWorkload()
 })
 
+// ─── CLI Agent: per-session config + provider/agent/mode/tool listings ──
+
+function withCliManager<T>(
+  sessionId: string,
+  fn: (mgr: CliAgentManager) => Promise<T>,
+): Promise<T | { error: string }> {
+  const runtime = findRuntimeWithCliSession(sessionId)
+  const mgr = getCliAgentManager(runtime)
+  if (!mgr) return Promise.resolve({ error: 'No workspace open' } as const)
+  return fn(mgr).catch((error) => ({
+    error: error instanceof Error ? error.message : String(error),
+  }))
+}
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_UPDATE_SESSION_CONFIG,
+  async (_event, sessionId: string, patch: Record<string, unknown>) => {
+    return withCliManager(sessionId, (mgr) => mgr.updateSessionConfig(sessionId, patch))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_LIST_PROVIDERS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.listOpenCodeProviders(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_LIST_AGENTS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.listOpenCodeAgents(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_LIST_MODES, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.listOpenCodeModes(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_LIST_TOOLS,
+  async (_event, sessionId: string, providerID: string, modelID: string) => {
+    return withCliManager(sessionId, (mgr) =>
+      mgr.listOpenCodeTools(sessionId, providerID, modelID),
+    )
+  },
+)
+
+// ─── CLI Agent: session ops ─────────────────────────────────────────────
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_SHARE, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionShare(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_UNSHARE, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionUnshare(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_SUMMARIZE, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionSummarize(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_SESSION_REVERT,
+  async (_event, sessionId: string, messageId: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.sessionRevert(sessionId, messageId))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_UNREVERT, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionUnrevert(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_SESSION_FORK,
+  async (_event, sessionId: string, messageId: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.sessionFork(sessionId, messageId))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_ABORT, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionAbort(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_DIFF, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionDiff(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_TODO, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionTodo(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_INIT, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionInit(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_DELETE_REMOTE, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.sessionDeleteRemote(sessionId))
+})
+
+// ─── CLI Agent: workspace ops ───────────────────────────────────────────
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_FILE_LIST,
+  async (_event, sessionId: string, path: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.fileList(sessionId, path))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_FILE_READ,
+  async (_event, sessionId: string, path: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.fileRead(sessionId, path))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_FILE_STATUS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.fileStatus(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_FIND_TEXT,
+  async (_event, sessionId: string, query: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.findText(sessionId, query))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_FIND_FILES,
+  async (_event, sessionId: string, pattern: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.findFiles(sessionId, pattern))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_FIND_SYMBOLS,
+  async (_event, sessionId: string, query: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.findSymbols(sessionId, query))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_SHELL_RUN,
+  async (_event, sessionId: string, command: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.shellRun(sessionId, command))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_LSP_STATUS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.lspStatus(sessionId))
+})
+
+ipcMain.handle(IpcChannels.CLI_AGENT_FORMATTER_STATUS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.formatterStatus(sessionId))
+})
+
+// ─── CLI Agent: config / auth / providers ───────────────────────────────
+
+ipcMain.handle(IpcChannels.CLI_AGENT_CONFIG_GET, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.configGet(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_CONFIG_UPDATE,
+  async (_event, sessionId: string, patch: Record<string, unknown>) => {
+    return withCliManager(sessionId, (mgr) => mgr.configUpdate(sessionId, patch))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_CONFIG_PROVIDERS, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.configProviders(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_AUTH_SET,
+  async (_event, sessionId: string, key: string, value: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.authSet(sessionId, key, value))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_PROVIDER_LIST, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.providerList(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_PROVIDER_AUTH,
+  async (_event, sessionId: string, providerId: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.providerAuth(sessionId, providerId))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_PROVIDER_OAUTH_AUTHORIZE,
+  async (_event, sessionId: string, providerId: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.providerOauthAuthorize(sessionId, providerId))
+  },
+)
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_PROVIDER_OAUTH_CALLBACK,
+  async (_event, sessionId: string, code: string) => {
+    return withCliManager(sessionId, (mgr) => mgr.providerOauthCallback(sessionId, code))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_PATH_GET, async (_event, sessionId: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.pathGet(sessionId))
+})
+
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_LOG_WRITE,
+  async (
+    _event,
+    sessionId: string,
+    message: string,
+    level?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
+  ) => {
+    return withCliManager(sessionId, (mgr) => mgr.logWrite(sessionId, message, level))
+  },
+)
+
+ipcMain.handle(IpcChannels.CLI_AGENT_SERVER_INFO, async (_event, workspaceId: string) => {
+  const runtime = runtimeRegistry.get(workspaceId)
+  const mgr = getCliAgentManager(runtime)
+  return mgr?.serverInfo() ?? null
+})
+
+// ─── CLI Agent: TUI control ─────────────────────────────────────────────
+
+const TUI_HANDLERS: Array<{
+  channel: string
+  method:
+    | 'appendPrompt'
+    | 'submitPrompt'
+    | 'clearPrompt'
+    | 'openHelp'
+    | 'openSessions'
+    | 'openThemes'
+    | 'openModels'
+    | 'executeCommand'
+    | 'showToast'
+}> = [
+  { channel: IpcChannels.CLI_AGENT_TUI_APPEND_PROMPT, method: 'appendPrompt' },
+  { channel: IpcChannels.CLI_AGENT_TUI_SUBMIT_PROMPT, method: 'submitPrompt' },
+  { channel: IpcChannels.CLI_AGENT_TUI_CLEAR_PROMPT, method: 'clearPrompt' },
+  { channel: IpcChannels.CLI_AGENT_TUI_OPEN_HELP, method: 'openHelp' },
+  { channel: IpcChannels.CLI_AGENT_TUI_OPEN_SESSIONS, method: 'openSessions' },
+  { channel: IpcChannels.CLI_AGENT_TUI_OPEN_THEMES, method: 'openThemes' },
+  { channel: IpcChannels.CLI_AGENT_TUI_OPEN_MODELS, method: 'openModels' },
+  { channel: IpcChannels.CLI_AGENT_TUI_EXECUTE_COMMAND, method: 'executeCommand' },
+  { channel: IpcChannels.CLI_AGENT_TUI_SHOW_TOAST, method: 'showToast' },
+]
+for (const { channel, method } of TUI_HANDLERS) {
+  ipcMain.handle(channel, async (_event, sessionId: string, args?: Record<string, unknown>) => {
+    return withCliManager(sessionId, (mgr) => mgr.tui(sessionId, method, args))
+  })
+}
+
 // ─── Conversation History IPC handlers ──────────────────────────
 
 ipcMain.handle(IpcChannels.CONVERSATION_LIST, async (_event, workspaceId: string) => {
@@ -1100,6 +1374,12 @@ ipcMain.handle(IpcChannels.SETTINGS_SET_USER, async (_event, key: string, value:
     for (const runtime of runtimeRegistry.list()) {
       getAgentManager(runtime)?.updateConfig(config)
       getAgentManager(runtime)?.updatePermissions(permConfig.permissionTier, permConfig.autoApprove)
+      // Mirror permission updates into the CLI agent manager so OpenCode
+      // permission decisions stay in sync with live tier changes.
+      getCliAgentManager(runtime)?.updatePermissions(
+        permConfig.permissionTier,
+        permConfig.autoApprove,
+      )
       runtime.refreshWorkload()
     }
   }
diff --git a/packages/main/src/preload.ts b/packages/main/src/preload.ts
index 07a884e..5db4424 100644
--- a/packages/main/src/preload.ts
+++ b/packages/main/src/preload.ts
@@ -523,6 +523,116 @@ const api: WindowApi = {
     ipcRenderer.on(IpcChannels.CLI_AGENT_RESULT, handler)
     return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_RESULT, handler)
   },
+  onCliAgentWorkspaceCost: (callback: (summary: unknown) => void) => {
+    const handler = (_event: Electron.IpcRendererEvent, summary: unknown) => callback(summary)
+    ipcRenderer.on(IpcChannels.CLI_AGENT_WORKSPACE_COST, handler)
+    return () => ipcRenderer.removeListener(IpcChannels.CLI_AGENT_WORKSPACE_COST, handler)
+  },
+
+  // ─── CLI Agent: per-session config + listings ──
+  cliAgentUpdateSessionConfig: (sessionId: string, patch: Record<string, unknown>) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_UPDATE_SESSION_CONFIG, sessionId, patch),
+  cliAgentListProviders: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_LIST_PROVIDERS, sessionId),
+  cliAgentListAgents: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_LIST_AGENTS, sessionId),
+  cliAgentListModes: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_LIST_MODES, sessionId),
+  cliAgentListTools: (sessionId: string, providerID: string, modelID: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_LIST_TOOLS, sessionId, providerID, modelID),
+
+  // ─── CLI Agent: session ops ────────────────────
+  cliAgentSessionShare: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_SHARE, sessionId),
+  cliAgentSessionUnshare: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_UNSHARE, sessionId),
+  cliAgentSessionSummarize: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_SUMMARIZE, sessionId),
+  cliAgentSessionRevert: (sessionId: string, messageId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_REVERT, sessionId, messageId),
+  cliAgentSessionUnrevert: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_UNREVERT, sessionId),
+  cliAgentSessionFork: (sessionId: string, messageId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_FORK, sessionId, messageId),
+  cliAgentSessionAbort: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_ABORT, sessionId),
+  cliAgentSessionDiff: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_DIFF, sessionId),
+  cliAgentSessionTodo: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_TODO, sessionId),
+  cliAgentSessionInit: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_INIT, sessionId),
+  cliAgentSessionDeleteRemote: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SESSION_DELETE_REMOTE, sessionId),
+
+  // ─── CLI Agent: workspace ops ──────────────────
+  cliAgentFileList: (sessionId: string, path: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FILE_LIST, sessionId, path),
+  cliAgentFileRead: (sessionId: string, path: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FILE_READ, sessionId, path),
+  cliAgentFileStatus: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FILE_STATUS, sessionId),
+  cliAgentFindText: (sessionId: string, query: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FIND_TEXT, sessionId, query),
+  cliAgentFindFiles: (sessionId: string, pattern: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FIND_FILES, sessionId, pattern),
+  cliAgentFindSymbols: (sessionId: string, query: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FIND_SYMBOLS, sessionId, query),
+  cliAgentShellRun: (sessionId: string, command: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SHELL_RUN, sessionId, command),
+  cliAgentLspStatus: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_LSP_STATUS, sessionId),
+  cliAgentFormatterStatus: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_FORMATTER_STATUS, sessionId),
+
+  // ─── CLI Agent: config / auth / providers ──────
+  cliAgentConfigGet: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_CONFIG_GET, sessionId),
+  cliAgentConfigUpdate: (sessionId: string, patch: Record<string, unknown>) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_CONFIG_UPDATE, sessionId, patch),
+  cliAgentConfigProviders: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_CONFIG_PROVIDERS, sessionId),
+  cliAgentAuthSet: (sessionId: string, key: string, value: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_AUTH_SET, sessionId, key, value),
+  cliAgentProviderList: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_PROVIDER_LIST, sessionId),
+  cliAgentProviderAuth: (sessionId: string, providerId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_PROVIDER_AUTH, sessionId, providerId),
+  cliAgentProviderOauthAuthorize: (sessionId: string, providerId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_PROVIDER_OAUTH_AUTHORIZE, sessionId, providerId),
+  cliAgentProviderOauthCallback: (sessionId: string, code: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_PROVIDER_OAUTH_CALLBACK, sessionId, code),
+  cliAgentPathGet: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_PATH_GET, sessionId),
+  cliAgentLogWrite: (
+    sessionId: string,
+    message: string,
+    level?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
+  ) => ipcRenderer.invoke(IpcChannels.CLI_AGENT_LOG_WRITE, sessionId, message, level),
+  cliAgentServerInfo: (workspaceId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SERVER_INFO, workspaceId),
+
+  // ─── CLI Agent: TUI control ────────────────────
+  cliAgentTuiAppendPrompt: (sessionId: string, text: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_APPEND_PROMPT, sessionId, { text }),
+  cliAgentTuiSubmitPrompt: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_SUBMIT_PROMPT, sessionId),
+  cliAgentTuiClearPrompt: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_CLEAR_PROMPT, sessionId),
+  cliAgentTuiOpenHelp: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_OPEN_HELP, sessionId),
+  cliAgentTuiOpenSessions: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_OPEN_SESSIONS, sessionId),
+  cliAgentTuiOpenThemes: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_OPEN_THEMES, sessionId),
+  cliAgentTuiOpenModels: (sessionId: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_OPEN_MODELS, sessionId),
+  cliAgentTuiExecuteCommand: (sessionId: string, command: string) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_EXECUTE_COMMAND, sessionId, { command }),
+  cliAgentTuiShowToast: (
+    sessionId: string,
+    args: { title?: string; message: string; variant: string },
+  ) => ipcRenderer.invoke(IpcChannels.CLI_AGENT_TUI_SHOW_TOAST, sessionId, args),
 
   // ─── Conversation History ─────────────────────
   conversationList: (workspaceId: string): Promise<ConversationMeta[]> =>
diff --git a/packages/main/src/workspace/WorkspaceRuntime.ts b/packages/main/src/workspace/WorkspaceRuntime.ts
index 785219f..f54fd75 100644
--- a/packages/main/src/workspace/WorkspaceRuntime.ts
+++ b/packages/main/src/workspace/WorkspaceRuntime.ts
@@ -55,6 +55,7 @@ export class WorkspaceRuntime {
       conversationStore: null,
       nativeSessionWatcher: null,
       nativeSessionCache: null,
+      approvalRouter: null,
       fileWatcher: null,
       gitStatus: null,
       worktreeManager: null,
@@ -223,13 +224,18 @@ export class WorkspaceRuntime {
     } | null
     const cliAgentManager = this.services.cliAgentManager as {
       getRunningSessionCount?: () => number
+      getPendingApprovalCount?: () => number
     } | null
 
+    const pendingApproval =
+      (agentManager?.getPendingApprovalCount?.() ?? 0) +
+      (cliAgentManager?.getPendingApprovalCount?.() ?? 0)
+
     this.workload = {
       tasksRunning: Boolean(taskRunner?.getRunning?.().length),
       pendingUserInput: Boolean(taskRunner?.getPendingInputCount?.()),
       agentsRunning: Boolean(agentManager?.getActiveSessionCount?.() || cliAgentManager?.getRunningSessionCount?.()),
-      pendingApproval: Boolean(agentManager?.getPendingApprovalCount?.()),
+      pendingApproval: pendingApproval > 0,
     }
     this.emitSnapshotChanged()
   }
diff --git a/packages/main/src/workspace/runtimeTypes.ts b/packages/main/src/workspace/runtimeTypes.ts
index f3bd7e9..c014b6d 100644
--- a/packages/main/src/workspace/runtimeTypes.ts
+++ b/packages/main/src/workspace/runtimeTypes.ts
@@ -35,6 +35,8 @@ export interface WorkspaceRuntimeServiceSlots {
   conversationStore: unknown | null
   nativeSessionWatcher: unknown | null
   nativeSessionCache: unknown | null
+  /** Single approval surface across built-in + CLI agent managers (CHAT_TOOL_APPROVE/REJECT). */
+  approvalRouter: unknown | null
   /** Reserved — FS watchers use `fileWatcher.startWatchers(workspaceId)` keyed by runtime id */
   fileWatcher: unknown | null
   /** Reserved — git polling uses `gitStatus` module map keyed by workspaceId */
diff --git a/packages/renderer/src/components/cliAgent/CostTokenBadge.tsx b/packages/renderer/src/components/cliAgent/CostTokenBadge.tsx
new file mode 100644
index 0000000..47c00da
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/CostTokenBadge.tsx
@@ -0,0 +1,63 @@
+import type { CliAgentTokenUsage } from '@aide/shared'
+
+export interface CostTokenBadgeProps {
+  costUsd?: number | null
+  tokens?: CliAgentTokenUsage | null
+  compact?: boolean
+  /**
+   * Suppress the dollar-cost portion of the badge while still showing the
+   * token breakdown. Used for the Claude Code CLI harness, which is billed
+   * via subscription rather than per-token API pricing.
+   */
+  hideCost?: boolean
+}
+
+/** Small badge showing cumulative cost + tokens for a session or message. */
+export function CostTokenBadge({ costUsd, tokens, compact, hideCost }: CostTokenBadgeProps) {
+  const cost = typeof costUsd === 'number' ? costUsd : 0
+  const hasCost = !hideCost && cost > 0
+  const hasTokens = tokens && (tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite > 0)
+  if (!hasCost && !hasTokens) return null
+
+  const formatCost = (n: number) => {
+    if (n < 0.0001) return '<$0.0001'
+    if (n < 0.01) return `$${n.toFixed(4)}`
+    if (n < 1) return `$${n.toFixed(3)}`
+    return `$${n.toFixed(2)}`
+  }
+
+  const formatTokens = (n: number) => {
+    if (n < 1000) return String(n)
+    if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`
+    return `${(n / 1_000_000).toFixed(2)}M`
+  }
+
+  return (
+    <span
+      className="cli-agent-cost-token-badge"
+      title={
+        tokens
+          ? `Input ${tokens.input.toLocaleString()} · Output ${tokens.output.toLocaleString()} · Reasoning ${tokens.reasoning.toLocaleString()} · Cache R ${tokens.cacheRead.toLocaleString()} W ${tokens.cacheWrite.toLocaleString()}`
+          : 'Cost'
+      }
+      style={{
+        display: 'inline-flex',
+        gap: 6,
+        padding: compact ? '1px 4px' : '2px 6px',
+        fontSize: compact ? 10 : 11,
+        borderRadius: 3,
+        background: 'var(--color-surface-2, rgba(255,255,255,0.06))',
+        color: 'var(--color-text-2, rgba(255,255,255,0.7))',
+        whiteSpace: 'nowrap',
+      }}
+    >
+      {hasCost && <span>{formatCost(cost)}</span>}
+      {hasTokens && tokens && (
+        <span>
+          {formatTokens(tokens.input)}↑ {formatTokens(tokens.output)}↓
+          {tokens.cacheRead > 0 ? ` ${formatTokens(tokens.cacheRead)}c` : ''}
+        </span>
+      )}
+    </span>
+  )
+}
diff --git a/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx b/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
new file mode 100644
index 0000000..106005a
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
@@ -0,0 +1,106 @@
+import { useEffect, useState } from 'react'
+import type { OpenCodePathInfo, OpenCodeServerInfo } from '@aide/shared'
+
+/**
+ * Read-only diagnostics for an active OpenCode session: server info,
+ * resolved paths, LSP/formatter status. Hidden behind a disclosure to
+ * keep the pane header tidy.
+ */
+export function DiagnosticsPanel({
+  workspaceId,
+  sessionId,
+}: {
+  workspaceId: string | null
+  sessionId: string | null
+}) {
+  const [open, setOpen] = useState(false)
+  const [server, setServer] = useState<OpenCodeServerInfo | null>(null)
+  const [paths, setPaths] = useState<OpenCodePathInfo | null>(null)
+  const [lsp, setLsp] = useState<unknown>(null)
+  const [formatter, setFormatter] = useState<unknown>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!open || !sessionId || !workspaceId) return
+    let cancelled = false
+    void (async () => {
+      try {
+        const s = (await window.api.cliAgentServerInfo(workspaceId)) as OpenCodeServerInfo | null
+        if (!cancelled) setServer(s)
+        const p = await window.api.cliAgentPathGet(sessionId)
+        if (!cancelled && !p.error) setPaths((p.paths as OpenCodePathInfo) ?? null)
+        const l = await window.api.cliAgentLspStatus(sessionId)
+        if (!cancelled) setLsp(l.status)
+        const f = await window.api.cliAgentFormatterStatus(sessionId)
+        if (!cancelled) setFormatter(f.status)
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [open, sessionId, workspaceId])
+
+  if (!sessionId) return null
+
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
+      style={{
+        margin: '6px 0',
+        padding: '6px 8px',
+        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
+        borderRadius: 4,
+        fontSize: 11,
+      }}
+    >
+      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>Diagnostics</summary>
+      {open && (
+        <div style={{ marginTop: 6, display: 'flex', flexDirection: 'column', gap: 4 }}>
+          {error && <div style={{ color: 'tomato' }}>{error}</div>}
+          {server && (
+            <Field label="Server">
+              {server.url} <em>({server.mode})</em> pid={server.pid}
+            </Field>
+          )}
+          {paths?.config && <Field label="Config">{paths.config}</Field>}
+          {paths?.data && <Field label="Data">{paths.data}</Field>}
+          {paths?.cache && <Field label="Cache">{paths.cache}</Field>}
+          {paths?.log && <Field label="Log">{paths.log}</Field>}
+          {lsp != null && (
+            <Field label="LSP">
+              <code style={{ fontSize: 10 }}>{JSON.stringify(lsp).slice(0, 200)}</code>
+            </Field>
+          )}
+          {formatter != null && (
+            <Field label="Formatter">
+              <code style={{ fontSize: 10 }}>{JSON.stringify(formatter).slice(0, 200)}</code>
+            </Field>
+          )}
+          <button
+            onClick={() => void window.api.cliAgentLogWrite(sessionId, 'log from aIDE diagnostics', 'INFO')}
+            style={{
+              alignSelf: 'flex-start',
+              fontSize: 10,
+              padding: '2px 6px',
+              marginTop: 4,
+            }}
+          >
+            Write test log
+          </button>
+        </div>
+      )}
+    </details>
+  )
+}
+
+function Field({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div>
+      <strong style={{ opacity: 0.6, marginRight: 4 }}>{label}:</strong>
+      {children}
+    </div>
+  )
+}
diff --git a/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx b/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
new file mode 100644
index 0000000..ed32b0e
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
@@ -0,0 +1,270 @@
+import { useMemo, useState } from 'react'
+import type { CliAgentMessage } from '@aide/shared'
+import { renderMarkdown } from '../../lib/markdownRenderer'
+import { CostTokenBadge } from './CostTokenBadge'
+
+/**
+ * Render a rich CliAgentMessage variant. Handles every part type the OpenCode
+ * adapter can emit (reasoning / patch / step / snapshot / retry / compaction /
+ * agent_change / subtask / file_attachment) plus a fallback for the original
+ * built-in message types so the existing CliAgentPane bubble can defer here.
+ */
+export function RichPartRenderer({
+  message,
+  onRevertMessage,
+}: {
+  message: CliAgentMessage
+  onRevertMessage?: (messageId: string) => void
+}) {
+  switch (message.type) {
+    case 'reasoning':
+      return <ReasoningBubble message={message} />
+    case 'patch':
+      return <PatchBubble message={message} />
+    case 'step':
+      return <StepBubble message={message} />
+    case 'snapshot':
+      return <SnapshotBubble message={message} onRevert={onRevertMessage} />
+    case 'retry':
+      return <RetryBubble message={message} />
+    case 'compaction':
+      return <CompactionBubble message={message} />
+    case 'agent_change':
+      return <AgentChangeBubble message={message} />
+    case 'subtask':
+      return <SubtaskBubble message={message} />
+    case 'file_attachment':
+      return <FileAttachmentBubble message={message} />
+    default:
+      return null
+  }
+}
+
+function ReasoningBubble({ message }: { message: CliAgentMessage }) {
+  const [open, setOpen] = useState(!message.reasoningCollapsed)
+  const html = useMemo(() => renderMarkdown(message.content || ''), [message.content])
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
+      className="cli-agent-msg cli-agent-msg--reasoning"
+      style={{
+        margin: '4px 0',
+        padding: '4px 8px',
+        borderLeft: '2px solid var(--color-accent-muted, #888)',
+        opacity: 0.85,
+        fontSize: 12,
+      }}
+    >
+      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>
+        <em>Reasoning</em>
+      </summary>
+      <div style={{ marginTop: 4 }} dangerouslySetInnerHTML={{ __html: html }} />
+    </details>
+  )
+}
+
+function PatchBubble({ message }: { message: CliAgentMessage }) {
+  const files = message.patchFiles ?? []
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--patch"
+      style={{
+        margin: '4px 0',
+        padding: '6px 8px',
+        background: 'var(--color-surface-2, rgba(120,180,255,0.08))',
+        borderRadius: 4,
+        fontSize: 12,
+      }}
+    >
+      <strong>Patch</strong>
+      {message.patchHash && (
+        <code style={{ marginLeft: 6, opacity: 0.6, fontSize: 10 }}>{message.patchHash.slice(0, 8)}</code>
+      )}
+      <ul style={{ margin: '4px 0 0 0', paddingLeft: 16 }}>
+        {files.map((f) => (
+          <li key={f}>
+            <code>{f}</code>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+function StepBubble({ message }: { message: CliAgentMessage }) {
+  const isFinish = message.stepPhase === 'finish'
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--step"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        margin: '6px 0',
+        padding: '4px 0',
+        borderTop: '1px dashed var(--color-border, rgba(255,255,255,0.1))',
+        fontSize: 11,
+        opacity: 0.7,
+      }}
+    >
+      <span>{isFinish ? '◼' : '▶'}</span>
+      <span>{message.stepReason ?? message.content}</span>
+      {isFinish && (
+        <CostTokenBadge
+          costUsd={message.costUsd}
+          tokens={message.tokens}
+          compact
+          hideCost={message.backend === 'claude-code'}
+        />
+      )}
+    </div>
+  )
+}
+
+function SnapshotBubble({
+  message,
+  onRevert,
+}: {
+  message: CliAgentMessage
+  onRevert?: (messageId: string) => void
+}) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--snapshot"
+      style={{
+        margin: '4px 0',
+        padding: '4px 8px',
+        background: 'var(--color-surface-2, rgba(255,200,80,0.08))',
+        borderRadius: 4,
+        fontSize: 11,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+      }}
+    >
+      <span>📌 Snapshot</span>
+      {message.snapshotHash && (
+        <code style={{ opacity: 0.6 }}>{message.snapshotHash.slice(0, 8)}</code>
+      )}
+      {onRevert && (
+        <button
+          onClick={() => onRevert(message.id)}
+          style={{
+            marginLeft: 'auto',
+            fontSize: 10,
+            padding: '1px 6px',
+            background: 'transparent',
+            border: '1px solid currentColor',
+            borderRadius: 3,
+            cursor: 'pointer',
+          }}
+        >
+          Revert here
+        </button>
+      )}
+    </div>
+  )
+}
+
+function RetryBubble({ message }: { message: CliAgentMessage }) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--retry"
+      style={{
+        margin: '4px 0',
+        padding: '4px 8px',
+        background: 'var(--color-warning-bg, rgba(255,180,80,0.1))',
+        borderRadius: 4,
+        fontSize: 11,
+      }}
+    >
+      ⚠ {message.content}
+    </div>
+  )
+}
+
+function CompactionBubble({ message }: { message: CliAgentMessage }) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--compaction"
+      style={{
+        margin: '4px 0',
+        padding: '4px 8px',
+        textAlign: 'center',
+        fontSize: 10,
+        opacity: 0.6,
+      }}
+    >
+      ─── {message.content} {message.compactionAuto ? '(auto)' : ''} ───
+    </div>
+  )
+}
+
+function AgentChangeBubble({ message }: { message: CliAgentMessage }) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--agent-change"
+      style={{
+        margin: '4px 0',
+        padding: '2px 8px',
+        fontSize: 11,
+        opacity: 0.7,
+      }}
+    >
+      🤖 Agent → <strong>{message.agentName ?? message.content}</strong>
+    </div>
+  )
+}
+
+function SubtaskBubble({ message }: { message: CliAgentMessage }) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--subtask"
+      style={{
+        margin: '4px 0 4px 16px',
+        padding: '4px 8px',
+        borderLeft: '2px solid var(--color-accent, #5b9)',
+        fontSize: 12,
+      }}
+    >
+      <strong>Subtask</strong>
+      {message.subtaskAgent && <em style={{ marginLeft: 4 }}>({message.subtaskAgent})</em>}
+      <div>{message.subtaskDescription ?? message.subtaskPrompt ?? message.content}</div>
+    </div>
+  )
+}
+
+function FileAttachmentBubble({ message }: { message: CliAgentMessage }) {
+  return (
+    <div
+      className="cli-agent-msg cli-agent-msg--file"
+      style={{
+        margin: '4px 0',
+        padding: '4px 8px',
+        background: 'var(--color-surface-2, rgba(255,255,255,0.05))',
+        borderRadius: 4,
+        fontSize: 12,
+        display: 'inline-flex',
+        gap: 6,
+      }}
+    >
+      📎 <code>{message.fileName ?? message.fileUrl ?? message.content}</code>
+      {message.fileMime && <span style={{ opacity: 0.5 }}>({message.fileMime})</span>}
+    </div>
+  )
+}
+
+export function isRichPartType(type: CliAgentMessage['type']): boolean {
+  return (
+    type === 'reasoning' ||
+    type === 'patch' ||
+    type === 'step' ||
+    type === 'snapshot' ||
+    type === 'retry' ||
+    type === 'compaction' ||
+    type === 'agent_change' ||
+    type === 'subtask' ||
+    type === 'file_attachment'
+  )
+}
diff --git a/packages/renderer/src/components/cliAgent/SessionMenu.tsx b/packages/renderer/src/components/cliAgent/SessionMenu.tsx
new file mode 100644
index 0000000..fdf4e32
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/SessionMenu.tsx
@@ -0,0 +1,148 @@
+import { useState } from 'react'
+
+/**
+ * Kebab menu in the CliAgentPane header for OpenCode session ops:
+ * share, summarize, revert, unrevert, abort, fork, view diff, todos,
+ * initialize project, delete remote.
+ *
+ * Each action calls the corresponding window.api.cliAgentSession* IPC
+ * and surfaces success / error in a small toast.
+ */
+export function SessionMenu({
+  sessionId,
+  disabled,
+  onMessage,
+}: {
+  sessionId: string | null
+  disabled?: boolean
+  onMessage: (text: string, variant?: 'success' | 'error') => void
+}) {
+  const [open, setOpen] = useState(false)
+  const [busy, setBusy] = useState(false)
+
+  const wrap = async (fn: () => Promise<{ error?: string } | { url?: string } | { newSessionId?: string }>) => {
+    if (!sessionId) return
+    setBusy(true)
+    setOpen(false)
+    try {
+      const result = await fn()
+      if ('error' in result && result.error) {
+        onMessage(result.error, 'error')
+      } else if ('url' in result && result.url) {
+        try {
+          await navigator.clipboard.writeText(result.url)
+          onMessage(`Shared · URL copied to clipboard`, 'success')
+        } catch {
+          onMessage(`Shared · ${result.url}`, 'success')
+        }
+      } else if ('newSessionId' in result && result.newSessionId) {
+        onMessage(`Forked → ${result.newSessionId.slice(0, 8)}`, 'success')
+      } else {
+        onMessage('Done', 'success')
+      }
+    } catch (e) {
+      onMessage(e instanceof Error ? e.message : String(e), 'error')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (!sessionId) return null
+
+  return (
+    <div className="cli-agent-session-menu" style={{ position: 'relative' }}>
+      <button
+        onClick={() => setOpen((o) => !o)}
+        disabled={disabled || busy}
+        title="Session actions"
+        style={{
+          background: 'transparent',
+          border: 'none',
+          color: 'inherit',
+          cursor: 'pointer',
+          padding: '2px 6px',
+          fontSize: 14,
+        }}
+      >
+        ⋮
+      </button>
+      {open && (
+        <div
+          style={{
+            position: 'absolute',
+            right: 0,
+            top: '100%',
+            zIndex: 10,
+            background: 'var(--color-surface-1, #1e1e1e)',
+            border: '1px solid var(--color-border, rgba(255,255,255,0.15))',
+            borderRadius: 4,
+            padding: 4,
+            minWidth: 160,
+            display: 'flex',
+            flexDirection: 'column',
+            fontSize: 12,
+            boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
+          }}
+        >
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionShare(sessionId))}>
+            Share session
+          </MenuItem>
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionUnshare(sessionId))}>
+            Unshare
+          </MenuItem>
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionSummarize(sessionId))}>
+            Summarize
+          </MenuItem>
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionUnrevert(sessionId))}>
+            Unrevert
+          </MenuItem>
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionAbort(sessionId))}>
+            Abort
+          </MenuItem>
+          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionInit(sessionId))}>
+            Initialize AGENTS.md
+          </MenuItem>
+          <MenuItem
+            onClick={() => wrap(() => window.api.cliAgentSessionDeleteRemote(sessionId))}
+            danger
+          >
+            Delete remote session
+          </MenuItem>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function MenuItem({
+  children,
+  onClick,
+  danger,
+}: {
+  children: React.ReactNode
+  onClick: () => void
+  danger?: boolean
+}) {
+  return (
+    <button
+      onClick={onClick}
+      style={{
+        display: 'block',
+        textAlign: 'left',
+        background: 'transparent',
+        border: 'none',
+        color: danger ? 'tomato' : 'inherit',
+        padding: '4px 8px',
+        cursor: 'pointer',
+        borderRadius: 3,
+        fontSize: 12,
+      }}
+      onMouseEnter={(e) =>
+        ((e.target as HTMLButtonElement).style.background = 'var(--color-surface-2, rgba(255,255,255,0.06))')
+      }
+      onMouseLeave={(e) => ((e.target as HTMLButtonElement).style.background = 'transparent')}
+    >
+      {children}
+    </button>
+  )
+}
diff --git a/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx b/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
new file mode 100644
index 0000000..bc2df05
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
@@ -0,0 +1,338 @@
+import { useEffect, useState } from 'react'
+import type {
+  CliAgentBackendState,
+  OpenCodeAgentSummary,
+  OpenCodeProviderSummary,
+  OpenCodeToolSummary,
+} from '@aide/shared'
+
+/**
+ * Collapsible per-session settings panel for OpenCode sessions.
+ * Wraps provider/model picker, agent picker, mode picker, system prompt
+ * editor, and tool toggle list. Each sub-component lazily fetches its
+ * options the first time the panel is opened.
+ */
+export function SessionSettingsPanel({
+  sessionId,
+  backendState,
+  onPatch,
+}: {
+  sessionId: string | null
+  backendState: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [open, setOpen] = useState(false)
+  if (!sessionId) return null
+
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
+      className="cli-agent-session-settings"
+      style={{
+        margin: '6px 0',
+        padding: '6px 8px',
+        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
+        borderRadius: 4,
+        fontSize: 12,
+      }}
+    >
+      <summary style={{ cursor: 'pointer', userSelect: 'none', fontWeight: 500 }}>
+        Session settings
+      </summary>
+      {open && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginTop: 8 }}>
+          <ProviderModelPicker sessionId={sessionId} state={backendState} onPatch={onPatch} />
+          <AgentModePicker sessionId={sessionId} state={backendState} onPatch={onPatch} />
+          <SystemPromptEditor state={backendState} onPatch={onPatch} />
+          <ToolToggleList sessionId={sessionId} state={backendState} onPatch={onPatch} />
+        </div>
+      )}
+    </details>
+  )
+}
+
+function ProviderModelPicker({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [providers, setProviders] = useState<OpenCodeProviderSummary[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    void (async () => {
+      try {
+        const result = (await window.api.cliAgentListProviders(sessionId)) as
+          | OpenCodeProviderSummary[]
+          | { error: string }
+          | undefined
+        if (cancelled) return
+        if (Array.isArray(result)) setProviders(result)
+        else if (result && typeof result === 'object' && 'error' in result) {
+          setError(result.error ?? 'Failed to load providers')
+        }
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId])
+
+  const provider = providers.find((p) => p.id === state.providerID)
+  return (
+    <div>
+      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Provider / Model</label>
+      <div style={{ display: 'flex', gap: 4 }}>
+        <select
+          value={state.providerID ?? ''}
+          onChange={(e) => void onPatch({ providerID: e.target.value || undefined, modelID: undefined })}
+          style={selectStyle}
+          disabled={loading}
+        >
+          <option value="">{loading ? 'Loading…' : '— provider —'}</option>
+          {providers.map((p) => (
+            <option key={p.id} value={p.id}>
+              {p.name}
+            </option>
+          ))}
+        </select>
+        <select
+          value={state.modelID ?? ''}
+          onChange={(e) => void onPatch({ modelID: e.target.value || undefined })}
+          style={selectStyle}
+          disabled={!provider}
+        >
+          <option value="">{provider ? '— model —' : ''}</option>
+          {provider?.models.map((m) => (
+            <option key={m.id} value={m.id}>
+              {m.name}
+            </option>
+          ))}
+        </select>
+      </div>
+      {error && <div style={{ color: 'tomato', fontSize: 10 }}>{error}</div>}
+    </div>
+  )
+}
+
+function AgentModePicker({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [agents, setAgents] = useState<OpenCodeAgentSummary[]>([])
+  const [modes, setModes] = useState<string[]>([])
+
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      try {
+        const [a, m] = await Promise.all([
+          window.api.cliAgentListAgents(sessionId),
+          window.api.cliAgentListModes(sessionId),
+        ])
+        if (cancelled) return
+        if (Array.isArray(a)) setAgents(a as OpenCodeAgentSummary[])
+        if (Array.isArray(m)) setModes(m as string[])
+      } catch {
+        /* ignore */
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId])
+
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <div style={{ flex: 1 }}>
+        <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Agent</label>
+        <select
+          value={state.agent ?? ''}
+          onChange={(e) => void onPatch({ agent: e.target.value || undefined })}
+          style={selectStyle}
+        >
+          <option value="">— default —</option>
+          {agents.map((a) => (
+            <option key={a.name} value={a.name}>
+              {a.name}
+              {a.description ? ` — ${a.description}` : ''}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div style={{ flex: 1 }}>
+        <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Mode</label>
+        <select
+          value={state.mode ?? ''}
+          onChange={(e) => void onPatch({ mode: e.target.value || undefined })}
+          style={selectStyle}
+        >
+          <option value="">— default —</option>
+          {modes.map((m) => (
+            <option key={m} value={m}>
+              {m}
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  )
+}
+
+function SystemPromptEditor({
+  state,
+  onPatch,
+}: {
+  state: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [value, setValue] = useState(state.systemPromptOverride ?? '')
+  useEffect(() => setValue(state.systemPromptOverride ?? ''), [state.systemPromptOverride])
+  return (
+    <div>
+      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>
+        System prompt override
+      </label>
+      <textarea
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onBlur={() =>
+          void onPatch({ systemPromptOverride: value.trim() ? value : undefined })
+        }
+        rows={3}
+        placeholder="Leave blank to use the agent default"
+        style={{
+          width: '100%',
+          fontFamily: 'inherit',
+          fontSize: 11,
+          padding: 4,
+          borderRadius: 3,
+          background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
+          color: 'inherit',
+          border: '1px solid var(--color-border, rgba(255,255,255,0.1))',
+          resize: 'vertical',
+        }}
+      />
+    </div>
+  )
+}
+
+function ToolToggleList({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [tools, setTools] = useState<OpenCodeToolSummary[]>([])
+  const [loaded, setLoaded] = useState(false)
+
+  useEffect(() => {
+    if (!state.providerID || !state.modelID) return
+    let cancelled = false
+    void (async () => {
+      try {
+        const result = await window.api.cliAgentListTools(
+          sessionId,
+          state.providerID!,
+          state.modelID!,
+        )
+        if (!cancelled && Array.isArray(result)) {
+          setTools(result as OpenCodeToolSummary[])
+          setLoaded(true)
+        }
+      } catch {
+        /* ignore */
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId, state.providerID, state.modelID])
+
+  if (!loaded || tools.length === 0) {
+    return (
+      <div style={{ opacity: 0.5, fontSize: 11 }}>
+        {state.providerID && state.modelID
+          ? 'Tools will appear once available…'
+          : 'Pick a provider/model to list tools'}
+      </div>
+    )
+  }
+
+  const toggles = state.toolToggles ?? {}
+  return (
+    <div>
+      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Tools</label>
+      <div
+        style={{
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: 4,
+          maxHeight: 120,
+          overflowY: 'auto',
+          padding: 4,
+          background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
+          borderRadius: 3,
+        }}
+      >
+        {tools.map((t) => {
+          const enabled = toggles[t.id] !== false
+          return (
+            <label
+              key={t.id}
+              title={t.description ?? t.id}
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 4,
+                fontSize: 10,
+                padding: '1px 4px',
+              }}
+            >
+              <input
+                type="checkbox"
+                checked={enabled}
+                onChange={(e) =>
+                  void onPatch({
+                    toolToggles: { ...toggles, [t.id]: e.target.checked },
+                  })
+                }
+              />
+              {t.id}
+            </label>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+const selectStyle: React.CSSProperties = {
+  flex: 1,
+  fontSize: 11,
+  padding: '2px 4px',
+  background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
+  color: 'inherit',
+  border: '1px solid var(--color-border, rgba(255,255,255,0.1))',
+  borderRadius: 3,
+}
diff --git a/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx b/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
new file mode 100644
index 0000000..eeae395
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
@@ -0,0 +1,92 @@
+import { useState } from 'react'
+
+/**
+ * TUI control panel for OpenCode sessions. Mostly diagnostic / power-user
+ * — these are the same commands the OpenCode TUI exposes (open help,
+ * show toast, execute command, etc.). Useful when running an external
+ * opencode TUI alongside aIDE.
+ */
+export function TuiControlPanel({ sessionId }: { sessionId: string | null }) {
+  const [open, setOpen] = useState(false)
+  const [appendText, setAppendText] = useState('')
+  const [execCmd, setExecCmd] = useState('')
+
+  if (!sessionId) return null
+
+  const call = async (fn: () => Promise<{ error?: string }>) => {
+    const result = await fn()
+    if (result.error) console.warn('TUI op failed', result.error)
+  }
+
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
+      style={{
+        margin: '6px 0',
+        padding: '6px 8px',
+        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
+        borderRadius: 4,
+        fontSize: 11,
+      }}
+    >
+      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>TUI control</summary>
+      {open && (
+        <div style={{ marginTop: 6, display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+            <button onClick={() => void call(() => window.api.cliAgentTuiOpenHelp(sessionId))}>
+              Help
+            </button>
+            <button onClick={() => void call(() => window.api.cliAgentTuiOpenSessions(sessionId))}>
+              Sessions
+            </button>
+            <button onClick={() => void call(() => window.api.cliAgentTuiOpenThemes(sessionId))}>
+              Themes
+            </button>
+            <button onClick={() => void call(() => window.api.cliAgentTuiOpenModels(sessionId))}>
+              Models
+            </button>
+            <button onClick={() => void call(() => window.api.cliAgentTuiSubmitPrompt(sessionId))}>
+              Submit
+            </button>
+            <button onClick={() => void call(() => window.api.cliAgentTuiClearPrompt(sessionId))}>
+              Clear
+            </button>
+          </div>
+          <div style={{ display: 'flex', gap: 4 }}>
+            <input
+              value={appendText}
+              onChange={(e) => setAppendText(e.target.value)}
+              placeholder="Text to append…"
+              style={{ flex: 1, fontSize: 11 }}
+            />
+            <button
+              onClick={() => {
+                void call(() => window.api.cliAgentTuiAppendPrompt(sessionId, appendText))
+                setAppendText('')
+              }}
+            >
+              Append
+            </button>
+          </div>
+          <div style={{ display: 'flex', gap: 4 }}>
+            <input
+              value={execCmd}
+              onChange={(e) => setExecCmd(e.target.value)}
+              placeholder="TUI command…"
+              style={{ flex: 1, fontSize: 11 }}
+            />
+            <button
+              onClick={() => {
+                void call(() => window.api.cliAgentTuiExecuteCommand(sessionId, execCmd))
+                setExecCmd('')
+              }}
+            >
+              Execute
+            </button>
+          </div>
+        </div>
+      )}
+    </details>
+  )
+}
diff --git a/packages/renderer/src/components/layout/DockviewContainer.tsx b/packages/renderer/src/components/layout/DockviewContainer.tsx
index 234ce74..4a84f61 100644
--- a/packages/renderer/src/components/layout/DockviewContainer.tsx
+++ b/packages/renderer/src/components/layout/DockviewContainer.tsx
@@ -15,6 +15,7 @@ import { ChatPane } from '../panes/ChatPane'
 import { CliAgentPane } from '../panes/CliAgentPane'
 import { ChatHistoryPane } from '../panes/ChatHistoryPane'
 import { ProblemsPane } from '../panes/ProblemsPane'
+import { OpenCodeToolsPane } from '../panes/OpenCodeToolsPane'
 import 'dockview/dist/styles/dockview.css'
 import '../../styles/dockview-theme.css'
 
@@ -31,6 +32,7 @@ const components = {
   cliAgentPane: CliAgentPane,
   chatHistoryPane: ChatHistoryPane,
   problemsPane: ProblemsPane,
+  openCodeToolsPane: OpenCodeToolsPane,
 }
 
 const tabComponents = {
diff --git a/packages/renderer/src/components/panes/CliAgentPane.tsx b/packages/renderer/src/components/panes/CliAgentPane.tsx
index 1d8fe23..1aeb62a 100644
--- a/packages/renderer/src/components/panes/CliAgentPane.tsx
+++ b/packages/renderer/src/components/panes/CliAgentPane.tsx
@@ -1,11 +1,17 @@
-import { useEffect, useRef, useMemo } from 'react'
+import { useEffect, useRef, useMemo, useState, useCallback } from 'react'
 import type { IDockviewPanelProps } from 'dockview-react'
-import type { AgentBackend, CliAgentMessage } from '@aide/shared'
+import type { AgentBackend, CliAgentBackendState, CliAgentMessage } from '@aide/shared'
 import { useCliAgent } from '../../hooks/useCliAgent'
 import { AgentStatusDot } from '../chat/AgentStatusDot'
 import { ChatInput } from '../chat/ChatInput'
 import { renderMarkdown } from '../../lib/markdownRenderer'
 import { CLI_BACKENDS, backendBadgeLabel, backendLabel } from '../../lib/agentBackend'
+import { CostTokenBadge } from '../cliAgent/CostTokenBadge'
+import { RichPartRenderer, isRichPartType } from '../cliAgent/RichPartRenderer'
+import { SessionMenu } from '../cliAgent/SessionMenu'
+import { SessionSettingsPanel } from '../cliAgent/SessionSettingsPanel'
+import { DiagnosticsPanel } from '../cliAgent/DiagnosticsPanel'
+import { TuiControlPanel } from '../cliAgent/TuiControlPanel'
 import '../../styles/cli-agent-pane.css'
 
 interface CliAgentPanelParams {
@@ -98,6 +104,31 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
     if (!ok) await agent.start(next)
   }
 
+  // Toast for session menu actions.
+  const [toast, setToast] = useState<{ text: string; variant: 'success' | 'error' } | null>(null)
+  const showToast = useCallback((text: string, variant: 'success' | 'error' = 'success') => {
+    setToast({ text, variant })
+    window.setTimeout(() => setToast(null), 3000)
+  }, [])
+
+  const handleRevertMessage = useCallback(
+    async (messageId: string) => {
+      if (!agent.sessionId) return
+      const result = await window.api.cliAgentSessionRevert(agent.sessionId, messageId)
+      if (result.error) showToast(result.error, 'error')
+      else showToast('Reverted', 'success')
+    },
+    [agent.sessionId, showToast],
+  )
+
+  const isOpenCode = headerBackend === 'opencode'
+  // Mirror the live per-backend state from the hook so the pickers reflect any
+  // overrides the user has applied (and so dependent dropdowns like the model
+  // picker re-render when the provider changes).
+  const currentBackendState: CliAgentBackendState | null = isOpenCode
+    ? agent.backendState ?? { model: agent.model ?? undefined }
+    : null
+
   return (
     <div className="cli-agent-pane" style={{ ['--panel-zoom' as string]: String(zoomFactor ?? 1) }}>
       {/* Header */}
@@ -125,7 +156,20 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
         {agent.model && (
           <span className="cli-agent-pane__model">{agent.model}</span>
         )}
+        <CostTokenBadge
+          costUsd={agent.totalCostUsd}
+          tokens={agent.totalTokens}
+          compact
+          hideCost={headerBackend === 'claude-code'}
+        />
         <div className="cli-agent-pane__header-spacer" />
+        {isOpenCode && (
+          <SessionMenu
+            sessionId={agent.sessionId}
+            disabled={isActive}
+            onMessage={(text, variant) => showToast(text, variant ?? 'success')}
+          />
+        )}
         {isActive ? (
           <button className="cli-agent-pane__btn cli-agent-pane__btn--stop" onClick={agent.stop}>
             Stop
@@ -140,6 +184,37 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
         )}
       </div>
 
+      {/* OpenCode-only collapsible panels */}
+      {isOpenCode && currentBackendState && (
+        <div style={{ padding: '4px 8px 0 8px' }}>
+          <SessionSettingsPanel
+            sessionId={agent.sessionId}
+            backendState={currentBackendState}
+            onPatch={agent.updateSessionConfig}
+          />
+          <DiagnosticsPanel workspaceId={workspaceId ?? null} sessionId={agent.sessionId} />
+          <TuiControlPanel sessionId={agent.sessionId} />
+        </div>
+      )}
+
+      {toast && (
+        <div
+          style={{
+            margin: '4px 8px',
+            padding: '4px 8px',
+            background:
+              toast.variant === 'error'
+                ? 'rgba(255,80,80,0.15)'
+                : 'rgba(80,200,120,0.15)',
+            color: toast.variant === 'error' ? 'tomato' : undefined,
+            borderRadius: 4,
+            fontSize: 11,
+          }}
+        >
+          {toast.text}
+        </div>
+      )}
+
       {/* Error banner */}
       {agent.lastError && agent.processStatus === 'error' && (
         <div className="cli-agent-pane__error-banner">
@@ -163,6 +238,7 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
             key={msg.id}
             message={msg}
             showBackendBadge={showBackendBadges}
+            onRevertMessage={isOpenCode ? handleRevertMessage : undefined}
           />
         ))}
 
@@ -194,9 +270,11 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
 function CliAgentMessageBubble({
   message,
   showBackendBadge,
+  onRevertMessage,
 }: {
   message: CliAgentMessage
   showBackendBadge: boolean
+  onRevertMessage?: (messageId: string) => void
 }) {
   const badge =
     showBackendBadge && message.backend && message.type !== 'user' ? (
@@ -208,6 +286,11 @@ function CliAgentMessageBubble({
       </span>
     ) : null
 
+  // Rich part types render via the dedicated component.
+  if (isRichPartType(message.type)) {
+    return <RichPartRenderer message={message} onRevertMessage={onRevertMessage} />
+  }
+
   if (message.type === 'user') {
     return (
       <div className="cli-agent-msg cli-agent-msg--user">
diff --git a/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx b/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
new file mode 100644
index 0000000..eb961f2
--- /dev/null
+++ b/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
@@ -0,0 +1,291 @@
+import { useState, useEffect } from 'react'
+import type { IDockviewPanelProps } from 'dockview-react'
+import type {
+  CliAgentSession,
+  OpenCodeFileEntry,
+  OpenCodeFindResult,
+  OpenCodeShellResult,
+  OpenCodeSymbolResult,
+} from '@aide/shared'
+import { OpenCodeProvidersTab } from '../settings/OpenCodeProvidersTab'
+
+interface OpenCodeToolsPaneParams {
+  workspaceId?: string
+  /** Optional session id to bind to. If absent, uses the workspace's active session. */
+  sessionId?: string
+}
+
+type Tab = 'files' | 'search' | 'shell' | 'status' | 'providers'
+
+/**
+ * Dockview pane exposing OpenCode's file/find/shell/lsp endpoints as
+ * opt-in commands. Only useful when an OpenCode session is active in the
+ * workspace; otherwise shows an empty state.
+ */
+export function OpenCodeToolsPane({ params }: IDockviewPanelProps<OpenCodeToolsPaneParams>) {
+  const { workspaceId, sessionId: paramSessionId } = params ?? {}
+  const [tab, setTab] = useState<Tab>('files')
+  const [sessionId, setSessionId] = useState<string | null>(paramSessionId ?? null)
+
+  // Resolve the active OpenCode session for this workspace if not given.
+  useEffect(() => {
+    if (paramSessionId || !workspaceId) return
+    let cancelled = false
+    void (async () => {
+      const s = (await window.api.cliAgentGetSession(workspaceId)) as CliAgentSession | null
+      if (!cancelled && s && s.backend === 'opencode') setSessionId(s.id)
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [workspaceId, paramSessionId])
+
+  if (!sessionId) {
+    return (
+      <div style={{ padding: 12, fontSize: 12, opacity: 0.6 }}>
+        Open an OpenCode chat in this workspace to use OpenCode tools.
+      </div>
+    )
+  }
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100%', fontSize: 12 }}>
+      <div
+        style={{
+          display: 'flex',
+          gap: 4,
+          padding: 4,
+          borderBottom: '1px solid var(--color-border, rgba(255,255,255,0.1))',
+        }}
+      >
+        {(['files', 'search', 'shell', 'status', 'providers'] as const).map((t) => (
+          <button
+            key={t}
+            onClick={() => setTab(t)}
+            style={{
+              padding: '2px 8px',
+              background:
+                tab === t
+                  ? 'var(--color-accent-bg, rgba(120,180,255,0.2))'
+                  : 'transparent',
+              border: 'none',
+              color: 'inherit',
+              borderRadius: 3,
+              cursor: 'pointer',
+            }}
+          >
+            {t}
+          </button>
+        ))}
+      </div>
+      <div style={{ flex: 1, overflow: 'auto', padding: 8 }}>
+        {tab === 'files' && <FilesTab sessionId={sessionId} />}
+        {tab === 'search' && <SearchTab sessionId={sessionId} />}
+        {tab === 'shell' && <ShellTab sessionId={sessionId} />}
+        {tab === 'status' && <StatusTab sessionId={sessionId} />}
+        {tab === 'providers' && <OpenCodeProvidersTab workspaceId={workspaceId ?? null} />}
+      </div>
+    </div>
+  )
+}
+
+function FilesTab({ sessionId }: { sessionId: string }) {
+  const [path, setPath] = useState('.')
+  const [entries, setEntries] = useState<OpenCodeFileEntry[]>([])
+  const [content, setContent] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  const list = async (p: string) => {
+    setError(null)
+    const result = await window.api.cliAgentFileList(sessionId, p)
+    if (result.error) setError(result.error)
+    else setEntries((result.entries as OpenCodeFileEntry[]) ?? [])
+  }
+
+  useEffect(() => {
+    void list('.')
+  }, [sessionId])
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
+        <input
+          value={path}
+          onChange={(e) => setPath(e.target.value)}
+          style={{ flex: 1, fontSize: 11 }}
+          placeholder="path…"
+        />
+        <button onClick={() => void list(path)}>List</button>
+      </div>
+      {error && <div style={{ color: 'tomato' }}>{error}</div>}
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+        {entries.map((e) => (
+          <li
+            key={e.path}
+            onClick={() => {
+              if (e.isDirectory) {
+                setPath(e.path)
+                void list(e.path)
+              } else {
+                void (async () => {
+                  const result = await window.api.cliAgentFileRead(sessionId, e.path)
+                  setContent(result.content ?? result.error ?? '')
+                })()
+              }
+            }}
+            style={{ cursor: 'pointer', padding: '1px 0' }}
+          >
+            {e.isDirectory ? '📁' : '📄'} {e.name}
+          </li>
+        ))}
+      </ul>
+      {content !== null && (
+        <pre
+          style={{
+            marginTop: 8,
+            padding: 6,
+            maxHeight: 200,
+            overflow: 'auto',
+            background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
+            fontSize: 10,
+          }}
+        >
+          {content}
+        </pre>
+      )}
+    </div>
+  )
+}
+
+function SearchTab({ sessionId }: { sessionId: string }) {
+  const [query, setQuery] = useState('')
+  const [mode, setMode] = useState<'text' | 'files' | 'symbols'>('text')
+  const [results, setResults] = useState<unknown[]>([])
+  const [error, setError] = useState<string | null>(null)
+
+  const run = async () => {
+    if (!query.trim()) return
+    setError(null)
+    const fn =
+      mode === 'text'
+        ? () => window.api.cliAgentFindText(sessionId, query)
+        : mode === 'files'
+          ? () => window.api.cliAgentFindFiles(sessionId, query)
+          : () => window.api.cliAgentFindSymbols(sessionId, query)
+    const result = (await fn()) as { error?: string; results?: unknown[]; paths?: string[]; symbols?: unknown[] }
+    if (result.error) setError(result.error)
+    else if (mode === 'text') setResults((result.results as OpenCodeFindResult[]) ?? [])
+    else if (mode === 'files') setResults(((result.paths as string[]) ?? []).map((p) => ({ path: p })))
+    else setResults((result.symbols as OpenCodeSymbolResult[]) ?? [])
+  }
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
+        <select value={mode} onChange={(e) => setMode(e.target.value as 'text')}>
+          <option value="text">Text</option>
+          <option value="files">Files</option>
+          <option value="symbols">Symbols</option>
+        </select>
+        <input
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') void run()
+          }}
+          placeholder="query…"
+          style={{ flex: 1, fontSize: 11 }}
+        />
+        <button onClick={() => void run()}>Find</button>
+      </div>
+      {error && <div style={{ color: 'tomato' }}>{error}</div>}
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none', fontSize: 11 }}>
+        {results.map((r, i) => (
+          <li key={i} style={{ padding: '2px 0' }}>
+            <pre style={{ margin: 0, fontSize: 10 }}>{JSON.stringify(r, null, 0)}</pre>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+function ShellTab({ sessionId }: { sessionId: string }) {
+  const [cmd, setCmd] = useState('')
+  const [output, setOutput] = useState<OpenCodeShellResult | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+
+  const run = async () => {
+    if (!cmd.trim()) return
+    setBusy(true)
+    setError(null)
+    const result = await window.api.cliAgentShellRun(sessionId, cmd)
+    if (result.error) setError(result.error)
+    else setOutput(result.result as OpenCodeShellResult)
+    setBusy(false)
+  }
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
+        <input
+          value={cmd}
+          onChange={(e) => setCmd(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') void run()
+          }}
+          placeholder="shell command…"
+          style={{ flex: 1, fontSize: 11, fontFamily: 'monospace' }}
+        />
+        <button onClick={() => void run()} disabled={busy}>
+          Run
+        </button>
+      </div>
+      {error && <div style={{ color: 'tomato' }}>{error}</div>}
+      {output && (
+        <pre
+          style={{
+            margin: 0,
+            padding: 6,
+            background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
+            fontSize: 10,
+            maxHeight: 240,
+            overflow: 'auto',
+          }}
+        >
+          [exit {output.exitCode}]{'\n'}
+          {output.stdout}
+          {output.stderr ? `\n--- stderr ---\n${output.stderr}` : ''}
+        </pre>
+      )}
+    </div>
+  )
+}
+
+function StatusTab({ sessionId }: { sessionId: string }) {
+  const [lsp, setLsp] = useState<unknown>(null)
+  const [formatter, setFormatter] = useState<unknown>(null)
+
+  useEffect(() => {
+    void (async () => {
+      const l = await window.api.cliAgentLspStatus(sessionId)
+      setLsp(l.status)
+      const f = await window.api.cliAgentFormatterStatus(sessionId)
+      setFormatter(f.status)
+    })()
+  }, [sessionId])
+
+  return (
+    <div>
+      <h4 style={{ margin: '4px 0' }}>LSP</h4>
+      <pre style={{ fontSize: 10, maxHeight: 120, overflow: 'auto' }}>
+        {JSON.stringify(lsp, null, 2)}
+      </pre>
+      <h4 style={{ margin: '4px 0' }}>Formatter</h4>
+      <pre style={{ fontSize: 10, maxHeight: 120, overflow: 'auto' }}>
+        {JSON.stringify(formatter, null, 2)}
+      </pre>
+    </div>
+  )
+}
diff --git a/packages/renderer/src/components/settings/OpenCodeProvidersTab.tsx b/packages/renderer/src/components/settings/OpenCodeProvidersTab.tsx
new file mode 100644
index 0000000..a5d316a
--- /dev/null
+++ b/packages/renderer/src/components/settings/OpenCodeProvidersTab.tsx
@@ -0,0 +1,197 @@
+import { useEffect, useState } from 'react'
+import type { CliAgentSession, OpenCodeAuthMethod, OpenCodeProviderSummary } from '@aide/shared'
+
+/**
+ * Settings tab listing OpenCode providers and exposing per-provider sign-in
+ * (OAuth via system browser, or API key via input). Hooks straight into the
+ * cliAgentProvider* IPC methods on the active workspace's session.
+ *
+ * v1 OAuth flow: opens the authorize URL in the system browser, then asks
+ * the user to paste the callback code. (Custom protocol handler is a
+ * follow-up.)
+ */
+export function OpenCodeProvidersTab({ workspaceId }: { workspaceId: string | null }) {
+  const [sessionId, setSessionId] = useState<string | null>(null)
+  const [providers, setProviders] = useState<OpenCodeProviderSummary[]>([])
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (!workspaceId) return
+    let cancelled = false
+    void (async () => {
+      const s = (await window.api.cliAgentGetSession(workspaceId)) as CliAgentSession | null
+      if (!cancelled) setSessionId(s?.backend === 'opencode' ? s.id : null)
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [workspaceId])
+
+  useEffect(() => {
+    if (!sessionId) return
+    let cancelled = false
+    setLoading(true)
+    void (async () => {
+      try {
+        const result = (await window.api.cliAgentListProviders(sessionId)) as
+          | OpenCodeProviderSummary[]
+          | { error: string }
+        if (cancelled) return
+        if (Array.isArray(result)) setProviders(result)
+        else if ('error' in result) setError(result.error)
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId])
+
+  if (!sessionId) {
+    return (
+      <div style={{ padding: 12, fontSize: 12, opacity: 0.6 }}>
+        Open an OpenCode chat in this workspace to manage providers.
+      </div>
+    )
+  }
+
+  return (
+    <div style={{ padding: 12, fontSize: 12 }}>
+      <h3 style={{ marginTop: 0 }}>OpenCode providers</h3>
+      {error && <div style={{ color: 'tomato' }}>{error}</div>}
+      {loading && <div style={{ opacity: 0.6 }}>Loading providers…</div>}
+      {providers.map((p) => (
+        <ProviderCard key={p.id} sessionId={sessionId} provider={p} />
+      ))}
+    </div>
+  )
+}
+
+function ProviderCard({
+  sessionId,
+  provider,
+}: {
+  sessionId: string
+  provider: OpenCodeProviderSummary
+}) {
+  const [authMethods, setAuthMethods] = useState<OpenCodeAuthMethod[] | null>(null)
+  const [apiKey, setApiKey] = useState('')
+  const [oauthCode, setOauthCode] = useState('')
+  const [authStatus, setAuthStatus] = useState<string | null>(null)
+
+  const loadAuth = async () => {
+    const result = await window.api.cliAgentProviderAuth(sessionId, provider.id)
+    if (Array.isArray(result.methods)) setAuthMethods(result.methods as OpenCodeAuthMethod[])
+  }
+
+  return (
+    <div
+      style={{
+        padding: 8,
+        marginBottom: 8,
+        border: '1px solid var(--color-border, rgba(255,255,255,0.1))',
+        borderRadius: 4,
+      }}
+    >
+      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+        <strong>{provider.name}</strong>
+        <button onClick={() => void loadAuth()} style={{ fontSize: 11 }}>
+          Auth methods
+        </button>
+      </div>
+      <div style={{ opacity: 0.7, fontSize: 11 }}>{provider.id}</div>
+      <details style={{ marginTop: 4 }}>
+        <summary style={{ cursor: 'pointer' }}>Models ({provider.models.length})</summary>
+        <ul style={{ margin: '4px 0 0 0', paddingLeft: 16, fontSize: 11 }}>
+          {provider.models.map((m) => (
+            <li key={m.id}>
+              {m.name}
+              {m.cost ? (
+                <span style={{ marginLeft: 6, opacity: 0.5 }}>
+                  ${m.cost.input}/M in · ${m.cost.output}/M out
+                </span>
+              ) : null}
+            </li>
+          ))}
+        </ul>
+      </details>
+      {authMethods && (
+        <div style={{ marginTop: 6, display: 'flex', flexDirection: 'column', gap: 4 }}>
+          {authMethods.map((m) => (
+            <div key={m.id}>
+              <span style={{ opacity: 0.7 }}>{m.label ?? m.id}</span> ·{' '}
+              <em style={{ opacity: 0.5 }}>{m.type}</em>
+            </div>
+          ))}
+          <div style={{ display: 'flex', gap: 4, alignItems: 'center' }}>
+            <input
+              type="password"
+              value={apiKey}
+              onChange={(e) => setApiKey(e.target.value)}
+              placeholder="API key…"
+              style={{ flex: 1, fontSize: 11 }}
+            />
+            <button
+              onClick={async () => {
+                const result = await window.api.cliAgentAuthSet(sessionId, provider.id, apiKey)
+                setAuthStatus(result.error ?? 'Saved')
+                setApiKey('')
+              }}
+            >
+              Save
+            </button>
+          </div>
+          <div style={{ display: 'flex', gap: 4, alignItems: 'center' }}>
+            <button
+              onClick={async () => {
+                const result = await window.api.cliAgentProviderOauthAuthorize(sessionId, provider.id)
+                if (result.error) {
+                  setAuthStatus(result.error)
+                } else if (result.url) {
+                  setAuthStatus(`Opened ${result.url} — paste the callback code below`)
+                  // Best-effort: open in default browser via the IDE's existing platform integration
+                  // (the renderer doesn't have shell.openExternal, so we provide the URL inline)
+                  try {
+                    window.open(result.url, '_blank', 'noopener')
+                  } catch {
+                    /* ignore */
+                  }
+                }
+              }}
+            >
+              Sign in (OAuth)
+            </button>
+            <input
+              value={oauthCode}
+              onChange={(e) => setOauthCode(e.target.value)}
+              placeholder="callback code…"
+              style={{ flex: 1, fontSize: 11 }}
+            />
+            <button
+              onClick={async () => {
+                const result = await window.api.cliAgentProviderOauthCallback(sessionId, oauthCode)
+                setAuthStatus(result.error ?? 'OAuth complete')
+                setOauthCode('')
+              }}
+            >
+              Complete
+            </button>
+          </div>
+          {authStatus && (
+            <div
+              style={{
+                fontSize: 11,
+                opacity: 0.7,
+                color: authStatus.toLowerCase().includes('error') ? 'tomato' : undefined,
+              }}
+            >
+              {authStatus}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/packages/renderer/src/hooks/useCliAgent.ts b/packages/renderer/src/hooks/useCliAgent.ts
index 9b4c1e3..985337b 100644
--- a/packages/renderer/src/hooks/useCliAgent.ts
+++ b/packages/renderer/src/hooks/useCliAgent.ts
@@ -1,11 +1,14 @@
 import { useState, useEffect, useCallback, useRef } from 'react'
 import type {
   AgentBackend,
+  CliAgentBackendState,
   CliAgentProcessStatus,
   CliAgentMessage,
+  CliAgentResultPayload,
   CliAgentStreamDelta,
   CliAgentStatusPayload,
   CliAgentMessagePayload,
+  CliAgentTokenUsage,
   ConversationListChangedPayload,
 } from '@aide/shared'
 import { scopedTo } from '../lib/workspace/workspaceScopedListener'
@@ -13,6 +16,8 @@ import { scopedTo } from '../lib/workspace/workspaceScopedListener'
 export interface UseCliAgentReturn {
   /** False while loading persisted/native history for an existing conversation. */
   historyHydrated: boolean
+  /** The active CLI session id (null until first start()). */
+  sessionId: string | null
   messages: CliAgentMessage[]
   processStatus: CliAgentProcessStatus
   streamingContent: string
@@ -22,11 +27,19 @@ export interface UseCliAgentReturn {
   conversationTitle: string
   /** Currently active external backend for this session (source of truth for the pane header). */
   activeBackend: AgentBackend | null
+  /** Cumulative cost (USD) for the session. */
+  totalCostUsd: number
+  /** Cumulative token usage for the session. */
+  totalTokens: CliAgentTokenUsage | null
+  /** Per-backend state (provider/model/agent/system/tools) for the active backend. */
+  backendState: CliAgentBackendState | null
   start: (backend: AgentBackend) => Promise<void>
   send: (content: string) => Promise<void>
   stop: () => void
   /** Hot-swap the underlying CLI backend for this conversation. Returns true on success. */
   switchBackend: (backend: AgentBackend) => Promise<boolean>
+  /** Patch backend-state overrides for the current session (model / agent / system / tools / etc.). */
+  updateSessionConfig: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
 }
 
 export interface UseCliAgentOptions {
@@ -50,6 +63,9 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
   const [streamingMessageId, setStreamingMessageId] = useState<string | null>(null)
   const streamingContentRef = useRef('')
   const [streamingContent, setStreamingContent] = useState('')
+  const [totalCostUsd, setTotalCostUsd] = useState(0)
+  const [totalTokens, setTotalTokens] = useState<CliAgentTokenUsage | null>(null)
+  const [backendState, setBackendState] = useState<CliAgentBackendState | null>(null)
   const rafRef = useRef<number | null>(null)
   const hydrateGenRef = useRef(0)
   const listRetryGenRef = useRef(0)
@@ -87,7 +103,9 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
         setProcessStatus(session.processStatus)
         setModel(session.model ?? null)
         setLastError(session.lastError ?? null)
-        setActiveBackend(session.activeBackend ?? session.backend ?? options.backend ?? null)
+        const ab = session.activeBackend ?? session.backend ?? options.backend ?? null
+        setActiveBackend(ab)
+        setBackendState(extractBackendState(session, ab))
         setHistoryHydrated(true)
         tick()
         return
@@ -196,6 +214,16 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     return unsub
   }, [workspaceId])
 
+  // Subscribe to result events for cost / token totals.
+  useEffect(() => {
+    const unsub = window.api.onCliAgentResult((result: CliAgentResultPayload) => {
+      if (result.sessionId !== sessionIdRef.current) return
+      setTotalCostUsd(result.totalCostUsd)
+      if (result.totalTokens) setTotalTokens(result.totalTokens)
+    })
+    return unsub
+  }, [])
+
   // Cleanup rAF on unmount
   useEffect(() => {
     return () => {
@@ -232,28 +260,39 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
         setProcessStatus(session.processStatus)
         setModel(session.model ?? null)
         setLastError(session.lastError ?? null)
-        setActiveBackend(session.activeBackend ?? session.backend ?? backend)
+        const ab = session.activeBackend ?? session.backend ?? backend
+        setActiveBackend(ab)
+        setBackendState(extractBackendState(session, ab))
+        if (typeof session.totalCostUsd === 'number') setTotalCostUsd(session.totalCostUsd)
+        if (session.totalTokens) setTotalTokens(session.totalTokens)
       }
       tick()
     }
   }, [workspaceId, conversationId, worktreePath, tick])
 
+  const updateSessionConfig = useCallback(
+    async (patch: Partial<CliAgentBackendState>): Promise<boolean> => {
+      const sid = sessionIdRef.current
+      if (!sid) return false
+      // Optimistically merge so the picker reflects the selection immediately
+      // (main only emits a status event afterwards, which doesn't carry
+      // backend-state, so we cannot rely on a roundtrip refresh).
+      setBackendState((prev) => ({ ...(prev ?? {}), ...patch }))
+      const result = await window.api.cliAgentUpdateSessionConfig(sid, patch as Record<string, unknown>)
+      if (result.error) {
+        setLastError(result.error)
+        return false
+      }
+      if (patch.model) setModel(patch.model)
+      return true
+    },
+    [],
+  )
+
   const switchBackend = useCallback(async (backend: AgentBackend): Promise<boolean> => {
     const sid = sessionIdRef.current
     if (!sid) return false
-    // The hot-swap IPC ships with the backend rework. Until then, gracefully no-op
-    // and let the caller fall back to the start() path.
-    const api = window.api as typeof window.api & {
-      cliAgentSwitchBackend?: (
-        sessionId: string,
-        backend: AgentBackend,
-      ) => Promise<{ success: true } | { error: string }>
-    }
-    if (typeof api.cliAgentSwitchBackend !== 'function') {
-      setLastError('Backend hot-swap is not available in this build yet.')
-      return false
-    }
-    const result = await api.cliAgentSwitchBackend(sid, backend)
+    const result = await window.api.cliAgentSwitchBackend(sid, backend)
     if ('error' in result) {
       setLastError(result.error)
       return false
@@ -290,6 +329,7 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
 
   return {
     historyHydrated,
+    sessionId: sessionIdRef.current,
     messages: messagesRef.current,
     processStatus,
     streamingContent,
@@ -298,9 +338,27 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     lastError,
     conversationTitle,
     activeBackend,
+    totalCostUsd,
+    totalTokens,
+    backendState,
     start,
     send,
     stop,
     switchBackend,
+    updateSessionConfig,
   }
 }
+
+/**
+ * Pull the per-backend state for the *active* backend out of a session
+ * payload. Returns null when the session has no recorded state for that
+ * backend yet (e.g. fresh session, no overrides applied).
+ */
+function extractBackendState(
+  session: { activeBackend?: AgentBackend; backend?: AgentBackend; backendStates?: Record<string, CliAgentBackendState> | undefined },
+  active: AgentBackend | null,
+): CliAgentBackendState | null {
+  const key = active ?? session.activeBackend ?? session.backend
+  if (!key || !session.backendStates) return null
+  return session.backendStates[key as string] ?? null
+}
diff --git a/packages/shared/src/cliAgentTypes.ts b/packages/shared/src/cliAgentTypes.ts
index 05cb876..cb46670 100644
--- a/packages/shared/src/cliAgentTypes.ts
+++ b/packages/shared/src/cliAgentTypes.ts
@@ -13,9 +13,24 @@ export type AgentBackend = 'built-in' | 'claude-code' | 'opencode' | 'codex'
 /** External (non-built-in) CLI agent backends. */
 export type ExternalCliBackend = Exclude<AgentBackend, 'built-in'>
 
+/**
+ * Per-backend session state preserved across hot-swaps and turns.
+ *
+ * The base fields (`sessionId`, `model`) apply to every backend. The optional
+ * `provider*`/`agent`/`mode`/`systemPromptOverride`/`toolToggles` fields are
+ * primarily used by the OpenCode adapter to surface the SDK's prompt body
+ * options, but are kept generic so other backends can opt-in.
+ */
 export interface CliAgentBackendState {
   sessionId?: string
   model?: string
+  // OpenCode-relevant overrides (optional, additive — backwards compatible).
+  providerID?: string
+  modelID?: string
+  agent?: string
+  mode?: string
+  systemPromptOverride?: string
+  toolToggles?: Record<string, boolean>
 }
 
 export type CliAgentBackendStateMap = Partial<Record<ExternalCliBackend, CliAgentBackendState>>
@@ -32,16 +47,58 @@ export type CliAgentProcessStatus =
   | 'error' // crashed or errored
   | 'stopping' // SIGTERM sent, waiting for exit
 
+// ---------------------------------------------------------------------------
+// Token / cost telemetry
+// ---------------------------------------------------------------------------
+
+/** Per-message or per-session token usage breakdown (matches OpenCode SDK). */
+export interface CliAgentTokenUsage {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+}
+
 // ---------------------------------------------------------------------------
 // Normalized messages
 // ---------------------------------------------------------------------------
 
+/**
+ * Discriminant for the rich part types exposed by OpenCode and other backends.
+ *
+ * Existing values stay first for backwards-compatibility with persisted
+ * conversations. New values are appended; the renderer falls back to plain text
+ * rendering if it doesn't recognise a type.
+ */
+export type CliAgentMessageType =
+  // Existing types
+  | 'system'
+  | 'assistant'
+  | 'user'
+  | 'tool_use'
+  | 'tool_result'
+  | 'status'
+  | 'error'
+  | 'result'
+  // New rich part types (OpenCode SDK)
+  | 'reasoning'
+  | 'file_attachment'
+  | 'patch'
+  | 'step'
+  | 'snapshot'
+  | 'retry'
+  | 'compaction'
+  | 'agent_change'
+  | 'subtask'
+
 /** A normalized message from any CLI agent backend. */
 export interface CliAgentMessage {
   id: string
-  type: 'system' | 'assistant' | 'user' | 'tool_use' | 'tool_result' | 'status' | 'error' | 'result'
+  type: CliAgentMessageType
   content: string
   timestamp: number
+  /** Which backend produced this message (set on external-agent messages). */
   backend?: ExternalCliBackend
   /** Original SDK event for debugging */
   raw?: unknown
@@ -49,14 +106,42 @@ export interface CliAgentMessage {
   // Tool-specific (present when type is 'tool_use' or 'tool_result')
   toolName?: string
   toolUseId?: string
+  /** Synthetic permission tool-call id used by ApprovalRouter for opencode permission events. */
+  permissionId?: string
 
-  // Result-specific (present when type is 'result' or 'error')
+  // Cost / tokens (present on assistant + result + step messages)
   durationMs?: number
   totalCostUsd?: number
+  costUsd?: number
+  tokens?: CliAgentTokenUsage
   isSuccess?: boolean
 
-  /** Which backend produced this message (set on external-agent messages). */
-  backend?: AgentBackend
+  // Rich part type fields (all optional, present per type)
+  /** Patch part: file edit hash + paths. */
+  patchHash?: string
+  patchFiles?: string[]
+  /** Step part: 'start' or 'finish'. */
+  stepPhase?: 'start' | 'finish'
+  stepReason?: string
+  stepSnapshot?: string
+  /** Snapshot part: opaque snapshot identifier. */
+  snapshotHash?: string
+  /** Retry part: attempt number. */
+  retryAttempt?: number
+  /** Compaction part: was the compaction automatic? */
+  compactionAuto?: boolean
+  /** Agent-change part: agent name. */
+  agentName?: string
+  /** Subtask part: prompt/description/agent. */
+  subtaskPrompt?: string
+  subtaskDescription?: string
+  subtaskAgent?: string
+  /** File attachment part: mime + url + optional filename. */
+  fileMime?: string
+  fileUrl?: string
+  fileName?: string
+  /** Reasoning part: kept in `content`; this flag controls collapsed-by-default rendering. */
+  reasoningCollapsed?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -71,6 +156,36 @@ export interface CliAgentStreamDelta {
   delta: string
 }
 
+// ---------------------------------------------------------------------------
+// Permission requests (OpenCode permission events bridged to CHAT_TOOL_CALL)
+// ---------------------------------------------------------------------------
+
+/**
+ * Permission request raised by an external CLI backend when it needs user
+ * consent for a tool call. Routed through the existing built-in agent
+ * approval surface (CHAT_TOOL_CALL / CHAT_TOOL_APPROVE / CHAT_TOOL_REJECT)
+ * via the ApprovalRouter so there is one approval UI for both built-in and
+ * external agents.
+ */
+export interface CliAgentPermissionRequest {
+  workspaceId: string
+  sessionId: string
+  /** Synthetic toolCall id, generated by the manager for routing. */
+  toolCallId: string
+  /** Backend that raised the request (currently always 'opencode'). */
+  backend: ExternalCliBackend
+  /** Human-readable title (from OpenCode's Permission.title). */
+  title: string
+  /** OpenCode permission category, e.g. 'edit' | 'bash' | 'webfetch' | … */
+  category: string
+  /** Optional pattern (e.g. shell command, file path) the request applies to. */
+  pattern?: string | string[]
+  /** Free-form metadata from the SDK. */
+  metadata?: Record<string, unknown>
+  /** When the permission was raised. */
+  timestamp: number
+}
+
 // ---------------------------------------------------------------------------
 // Session state (visible to renderer)
 // ---------------------------------------------------------------------------
@@ -88,8 +203,22 @@ export interface CliAgentSession {
   sessionToolNames?: string[]
   lastError?: string
   totalCostUsd?: number
+  totalTokens?: CliAgentTokenUsage
   /** Worktree path this session operates in (if any). */
   worktreePath?: string
+  /** Per-backend resumption + override state. */
+  backendStates?: CliAgentBackendStateMap
+}
+
+// ---------------------------------------------------------------------------
+// Workspace-level cost summary (sum of all session totals in a workspace)
+// ---------------------------------------------------------------------------
+
+export interface CliAgentWorkspaceCostSummary {
+  workspaceId: string
+  totalCostUsd: number
+  totalTokens: CliAgentTokenUsage
+  sessionCount: number
 }
 
 // ---------------------------------------------------------------------------
@@ -108,6 +237,7 @@ export interface CliAgentResultPayload {
   sessionId: string
   durationMs: number
   totalCostUsd: number
+  totalTokens?: CliAgentTokenUsage
   isSuccess: boolean
 }
 
@@ -116,3 +246,91 @@ export interface CliAgentMessagePayload extends CliAgentMessage {
   workspaceId: string
   sessionId: string
 }
+
+// ---------------------------------------------------------------------------
+// OpenCode SDK surface (light DTOs returned by listProviders/Agents/Modes/Tools)
+// ---------------------------------------------------------------------------
+
+export interface OpenCodeProviderSummary {
+  id: string
+  name: string
+  models: Array<{
+    id: string
+    name: string
+    reasoning?: boolean
+    attachment?: boolean
+    toolCall?: boolean
+    cost?: { input: number; output: number; cacheRead?: number; cacheWrite?: number }
+  }>
+}
+
+export interface OpenCodeAgentSummary {
+  name: string
+  description?: string
+  mode?: string
+}
+
+export interface OpenCodeToolSummary {
+  id: string
+  description?: string
+  schema?: unknown
+}
+
+export interface OpenCodeFileEntry {
+  path: string
+  name: string
+  isDirectory: boolean
+  size?: number
+  modified?: number
+}
+
+export interface OpenCodeFindResult {
+  path: string
+  line?: number
+  column?: number
+  preview?: string
+  matchText?: string
+}
+
+export interface OpenCodeSymbolResult {
+  name: string
+  kind: string
+  path: string
+  line?: number
+  column?: number
+}
+
+export interface OpenCodeShellResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+export interface OpenCodeServerInfo {
+  url: string
+  mode: 'bundled' | 'external'
+  pid?: number
+  startedAt: number
+}
+
+export interface OpenCodePathInfo {
+  config?: string
+  data?: string
+  cache?: string
+  state?: string
+  log?: string
+  cwd?: string
+  root?: string
+}
+
+export interface OpenCodeTodoItem {
+  id: string
+  text: string
+  done?: boolean
+}
+
+export interface OpenCodeAuthMethod {
+  id: string
+  label?: string
+  type: 'oauth' | 'apiKey' | 'env' | 'unknown'
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index f9fe997..14b70b3 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -31,12 +31,27 @@ export type {
   CliAgentBackendState,
   CliAgentBackendStateMap,
   CliAgentProcessStatus,
+  CliAgentTokenUsage,
+  CliAgentMessageType,
   CliAgentMessage,
+  CliAgentPermissionRequest,
   CliAgentStreamDelta,
   CliAgentSession,
+  CliAgentWorkspaceCostSummary,
   CliAgentStatusPayload,
   CliAgentResultPayload,
   CliAgentMessagePayload,
+  OpenCodeProviderSummary,
+  OpenCodeAgentSummary,
+  OpenCodeToolSummary,
+  OpenCodeFileEntry,
+  OpenCodeFindResult,
+  OpenCodeSymbolResult,
+  OpenCodeShellResult,
+  OpenCodeServerInfo,
+  OpenCodePathInfo,
+  OpenCodeTodoItem,
+  OpenCodeAuthMethod,
 } from './cliAgentTypes'
 export type {
   ConversationMeta,
@@ -296,6 +311,62 @@ export const IpcChannels = {
   CLI_AGENT_MESSAGE: 'cli-agent:message',
   CLI_AGENT_STATUS: 'cli-agent:status',
   CLI_AGENT_RESULT: 'cli-agent:result',
+  CLI_AGENT_WORKSPACE_COST: 'cli-agent:workspace-cost',
+
+  // ─── CLI Agent: per-session config ───────────
+  CLI_AGENT_UPDATE_SESSION_CONFIG: 'cli-agent:update-session-config',
+  CLI_AGENT_LIST_PROVIDERS: 'cli-agent:list-providers',
+  CLI_AGENT_LIST_AGENTS: 'cli-agent:list-agents',
+  CLI_AGENT_LIST_MODES: 'cli-agent:list-modes',
+  CLI_AGENT_LIST_TOOLS: 'cli-agent:list-tools',
+
+  // ─── CLI Agent: session ops (OpenCode) ───────
+  CLI_AGENT_SESSION_SHARE: 'cli-agent:session-share',
+  CLI_AGENT_SESSION_UNSHARE: 'cli-agent:session-unshare',
+  CLI_AGENT_SESSION_SUMMARIZE: 'cli-agent:session-summarize',
+  CLI_AGENT_SESSION_REVERT: 'cli-agent:session-revert',
+  CLI_AGENT_SESSION_UNREVERT: 'cli-agent:session-unrevert',
+  CLI_AGENT_SESSION_FORK: 'cli-agent:session-fork',
+  CLI_AGENT_SESSION_ABORT: 'cli-agent:session-abort',
+  CLI_AGENT_SESSION_DIFF: 'cli-agent:session-diff',
+  CLI_AGENT_SESSION_TODO: 'cli-agent:session-todo',
+  CLI_AGENT_SESSION_INIT: 'cli-agent:session-init',
+  CLI_AGENT_SESSION_DELETE_REMOTE: 'cli-agent:session-delete-remote',
+
+  // ─── CLI Agent: workspace ops (OpenCode) ─────
+  CLI_AGENT_FILE_LIST: 'cli-agent:file-list',
+  CLI_AGENT_FILE_READ: 'cli-agent:file-read',
+  CLI_AGENT_FILE_STATUS: 'cli-agent:file-status',
+  CLI_AGENT_FIND_TEXT: 'cli-agent:find-text',
+  CLI_AGENT_FIND_FILES: 'cli-agent:find-files',
+  CLI_AGENT_FIND_SYMBOLS: 'cli-agent:find-symbols',
+  CLI_AGENT_SHELL_RUN: 'cli-agent:shell-run',
+  CLI_AGENT_LSP_STATUS: 'cli-agent:lsp-status',
+  CLI_AGENT_FORMATTER_STATUS: 'cli-agent:formatter-status',
+
+  // ─── CLI Agent: config / auth / providers ────
+  CLI_AGENT_CONFIG_GET: 'cli-agent:config-get',
+  CLI_AGENT_CONFIG_UPDATE: 'cli-agent:config-update',
+  CLI_AGENT_CONFIG_PROVIDERS: 'cli-agent:config-providers',
+  CLI_AGENT_AUTH_SET: 'cli-agent:auth-set',
+  CLI_AGENT_PROVIDER_LIST: 'cli-agent:provider-list',
+  CLI_AGENT_PROVIDER_AUTH: 'cli-agent:provider-auth',
+  CLI_AGENT_PROVIDER_OAUTH_AUTHORIZE: 'cli-agent:provider-oauth-authorize',
+  CLI_AGENT_PROVIDER_OAUTH_CALLBACK: 'cli-agent:provider-oauth-callback',
+  CLI_AGENT_PATH_GET: 'cli-agent:path-get',
+  CLI_AGENT_LOG_WRITE: 'cli-agent:log-write',
+  CLI_AGENT_SERVER_INFO: 'cli-agent:server-info',
+
+  // ─── CLI Agent: TUI control (OpenCode) ───────
+  CLI_AGENT_TUI_APPEND_PROMPT: 'cli-agent:tui-append-prompt',
+  CLI_AGENT_TUI_SUBMIT_PROMPT: 'cli-agent:tui-submit-prompt',
+  CLI_AGENT_TUI_CLEAR_PROMPT: 'cli-agent:tui-clear-prompt',
+  CLI_AGENT_TUI_OPEN_HELP: 'cli-agent:tui-open-help',
+  CLI_AGENT_TUI_OPEN_SESSIONS: 'cli-agent:tui-open-sessions',
+  CLI_AGENT_TUI_OPEN_THEMES: 'cli-agent:tui-open-themes',
+  CLI_AGENT_TUI_OPEN_MODELS: 'cli-agent:tui-open-models',
+  CLI_AGENT_TUI_EXECUTE_COMMAND: 'cli-agent:tui-execute-command',
+  CLI_AGENT_TUI_SHOW_TOAST: 'cli-agent:tui-show-toast',
 
   // ─── Conversation History ────────────────────
   CONVERSATION_LIST: 'conversation:list',
@@ -1072,6 +1143,104 @@ export interface WindowApi {
   onCliAgentMessage: (callback: (msg: CliAgentMessagePayload) => void) => () => void
   onCliAgentStatus: (callback: (status: CliAgentStatusPayload) => void) => () => void
   onCliAgentResult: (callback: (result: CliAgentResultPayload) => void) => () => void
+  onCliAgentWorkspaceCost: (callback: (summary: unknown) => void) => () => void
+
+  // ─── CLI Agent: per-session config + listings ──
+  cliAgentUpdateSessionConfig: (
+    sessionId: string,
+    patch: Record<string, unknown>,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentListProviders: (sessionId: string) => Promise<unknown>
+  cliAgentListAgents: (sessionId: string) => Promise<unknown>
+  cliAgentListModes: (sessionId: string) => Promise<unknown>
+  cliAgentListTools: (
+    sessionId: string,
+    providerID: string,
+    modelID: string,
+  ) => Promise<unknown>
+
+  // ─── CLI Agent: session ops ────────────────────
+  cliAgentSessionShare: (sessionId: string) => Promise<{ url?: string; error?: string }>
+  cliAgentSessionUnshare: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionSummarize: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionRevert: (
+    sessionId: string,
+    messageId: string,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionUnrevert: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionFork: (
+    sessionId: string,
+    messageId: string,
+  ) => Promise<{ newSessionId?: string; error?: string }>
+  cliAgentSessionAbort: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionDiff: (sessionId: string) => Promise<{ diff?: unknown; error?: string }>
+  cliAgentSessionTodo: (sessionId: string) => Promise<{ todos?: unknown; error?: string }>
+  cliAgentSessionInit: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentSessionDeleteRemote: (sessionId: string) => Promise<{ success?: true; error?: string }>
+
+  // ─── CLI Agent: workspace ops ──────────────────
+  cliAgentFileList: (sessionId: string, path: string) => Promise<{ entries?: unknown; error?: string }>
+  cliAgentFileRead: (sessionId: string, path: string) => Promise<{ content?: string; error?: string }>
+  cliAgentFileStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
+  cliAgentFindText: (sessionId: string, query: string) => Promise<{ results?: unknown; error?: string }>
+  cliAgentFindFiles: (sessionId: string, pattern: string) => Promise<{ paths?: unknown; error?: string }>
+  cliAgentFindSymbols: (sessionId: string, query: string) => Promise<{ symbols?: unknown; error?: string }>
+  cliAgentShellRun: (sessionId: string, command: string) => Promise<{ result?: unknown; error?: string }>
+  cliAgentLspStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
+  cliAgentFormatterStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
+
+  // ─── CLI Agent: config / auth / providers ──────
+  cliAgentConfigGet: (sessionId: string) => Promise<{ config?: unknown; error?: string }>
+  cliAgentConfigUpdate: (
+    sessionId: string,
+    patch: Record<string, unknown>,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentConfigProviders: (sessionId: string) => Promise<{ providers?: unknown; error?: string }>
+  cliAgentAuthSet: (
+    sessionId: string,
+    key: string,
+    value: string,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentProviderList: (sessionId: string) => Promise<{ providers?: unknown; error?: string }>
+  cliAgentProviderAuth: (
+    sessionId: string,
+    providerId: string,
+  ) => Promise<{ methods?: unknown; error?: string }>
+  cliAgentProviderOauthAuthorize: (
+    sessionId: string,
+    providerId: string,
+  ) => Promise<{ url?: string; error?: string }>
+  cliAgentProviderOauthCallback: (
+    sessionId: string,
+    code: string,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentPathGet: (sessionId: string) => Promise<{ paths?: unknown; error?: string }>
+  cliAgentLogWrite: (
+    sessionId: string,
+    message: string,
+    level?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentServerInfo: (workspaceId: string) => Promise<unknown>
+
+  // ─── CLI Agent: TUI control ────────────────────
+  cliAgentTuiAppendPrompt: (
+    sessionId: string,
+    text: string,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiSubmitPrompt: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiClearPrompt: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiOpenHelp: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiOpenSessions: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiOpenThemes: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiOpenModels: (sessionId: string) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiExecuteCommand: (
+    sessionId: string,
+    command: string,
+  ) => Promise<{ success?: true; error?: string }>
+  cliAgentTuiShowToast: (
+    sessionId: string,
+    args: { title?: string; message: string; variant: string },
+  ) => Promise<{ success?: true; error?: string }>
 
   // ─── Conversation History ────────────────────
   conversationList: (workspaceId: string) => Promise<ConversationMeta[]>
diff --git a/tests/unit/cliAgentApprovalRouter.test.ts b/tests/unit/cliAgentApprovalRouter.test.ts
new file mode 100644
index 0000000..f35b5f3
--- /dev/null
+++ b/tests/unit/cliAgentApprovalRouter.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+import { ApprovalRouter, type ToolApprovalOwner } from '@main/chat/approvalRouter'
+
+function makeOwner(ownedIds: string[]): ToolApprovalOwner & {
+  approveCalls: Array<{ s: string; t: string }>
+  rejectCalls: Array<{ s: string; t: string }>
+} {
+  const approveCalls: Array<{ s: string; t: string }> = []
+  const rejectCalls: Array<{ s: string; t: string }> = []
+  const owned = new Set(ownedIds)
+  return {
+    approveCalls,
+    rejectCalls,
+    ownsToolCall: (id: string) => owned.has(id),
+    approveToolCall: (s: string, t: string) => approveCalls.push({ s, t }),
+    rejectToolCall: (s: string, t: string) => rejectCalls.push({ s, t }),
+    getPendingApprovalCount: () => owned.size,
+  }
+}
+
+describe('ApprovalRouter', () => {
+  it('routes approve to the owning manager', () => {
+    const router = new ApprovalRouter()
+    const a = makeOwner(['tc-1', 'tc-2'])
+    const b = makeOwner(['tc-3'])
+    router.register(a)
+    router.register(b)
+
+    const dispatched = router.approve('s-1', 'tc-3')
+    expect(dispatched).toBe(true)
+    expect(a.approveCalls).toEqual([])
+    expect(b.approveCalls).toEqual([{ s: 's-1', t: 'tc-3' }])
+  })
+
+  it('routes reject to the owning manager', () => {
+    const router = new ApprovalRouter()
+    const a = makeOwner(['tc-1'])
+    const b = makeOwner(['tc-2'])
+    router.register(a)
+    router.register(b)
+
+    const dispatched = router.reject('s-1', 'tc-1')
+    expect(dispatched).toBe(true)
+    expect(a.rejectCalls).toEqual([{ s: 's-1', t: 'tc-1' }])
+    expect(b.rejectCalls).toEqual([])
+  })
+
+  it('returns false when no owner claims the tool call', () => {
+    const router = new ApprovalRouter()
+    const a = makeOwner(['tc-1'])
+    router.register(a)
+    expect(router.approve('s-1', 'unknown')).toBe(false)
+  })
+
+  it('sums pending approvals across all owners', () => {
+    const router = new ApprovalRouter()
+    router.register(makeOwner(['a', 'b']))
+    router.register(makeOwner(['c']))
+    expect(router.getPendingApprovalCount()).toBe(3)
+  })
+
+  it('unregister removes an owner', () => {
+    const router = new ApprovalRouter()
+    const a = makeOwner(['tc-1'])
+    router.register(a)
+    router.unregister(a)
+    expect(router.approve('s-1', 'tc-1')).toBe(false)
+  })
+
+  it('register is idempotent for the same owner', () => {
+    const router = new ApprovalRouter()
+    const a = makeOwner(['tc-1'])
+    router.register(a)
+    router.register(a)
+    expect(router.getPendingApprovalCount()).toBe(1)
+  })
+})
diff --git a/tests/unit/cliAgentManager.test.ts b/tests/unit/cliAgentManager.test.ts
index 87e0f5e..e566f1d 100644
--- a/tests/unit/cliAgentManager.test.ts
+++ b/tests/unit/cliAgentManager.test.ts
@@ -192,4 +192,102 @@ describe('CliAgentManager', () => {
       expect.objectContaining({ backend: 'codex' }),
     )
   })
+
+  it('updateSessionConfig persists per-backend overrides', async () => {
+    const store = makeStore()
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+      conversationStore: store as never,
+    })
+    const started = await manager.start('ws-1', 'opencode', 'conv-config')
+    if ('error' in started) throw new Error(started.error)
+
+    const result = await manager.updateSessionConfig(started.sessionId, {
+      providerID: 'anthropic',
+      modelID: 'claude-sonnet-4-5',
+      agent: 'build',
+      systemPromptOverride: 'be helpful',
+      toolToggles: { web_search: false },
+    })
+
+    expect('error' in result).toBe(false)
+    const session = manager.getSessionById(started.sessionId)
+    expect(session?.backendStates?.['opencode']?.providerID).toBe('anthropic')
+    expect(session?.backendStates?.['opencode']?.modelID).toBe('claude-sonnet-4-5')
+    expect(session?.backendStates?.['opencode']?.agent).toBe('build')
+    expect(session?.backendStates?.['opencode']?.systemPromptOverride).toBe('be helpful')
+    expect(session?.backendStates?.['opencode']?.toolToggles).toEqual({ web_search: false })
+  })
+
+  it('hot-swap preserves per-backend state across switches', async () => {
+    const store = makeStore()
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+      conversationStore: store as never,
+    })
+    const started = await manager.start('ws-1', 'opencode', 'conv-swap')
+    if ('error' in started) throw new Error(started.error)
+
+    await manager.updateSessionConfig(started.sessionId, {
+      providerID: 'anthropic',
+      modelID: 'claude-sonnet-4-5',
+    })
+
+    // Switch to claude-code, then back.
+    await manager.switchBackend(started.sessionId, 'claude-code')
+    await manager.switchBackend(started.sessionId, 'opencode')
+
+    const session = manager.getSessionById(started.sessionId)
+    // OpenCode-specific overrides survive the round trip.
+    expect(session?.backendStates?.['opencode']?.providerID).toBe('anthropic')
+    expect(session?.backendStates?.['opencode']?.modelID).toBe('claude-sonnet-4-5')
+  })
+
+  it('updatePermissions changes the manager tier without restart', () => {
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+      permissionTier: 'confirm',
+      autoApprove: {},
+    })
+    // No public getter; just verify the method doesn't throw and accepts both args.
+    expect(() => manager.updatePermissions('autopilot', { file_write: true })).not.toThrow()
+  })
+
+  it('getWorkspaceCostSummary aggregates across sessions', async () => {
+    const store = makeStore()
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      workspaceId: 'ws-cost',
+      getWebContents: () => null,
+      conversationStore: store as never,
+    })
+    await manager.start('ws-cost', 'opencode', 'conv-a')
+    await manager.start('ws-cost', 'opencode', 'conv-b')
+
+    const summary = manager.getWorkspaceCostSummary()
+    expect(summary.workspaceId).toBe('ws-cost')
+    expect(summary.sessionCount).toBe(2)
+    expect(summary.totalCostUsd).toBe(0)
+    expect(summary.totalTokens).toEqual({
+      input: 0,
+      output: 0,
+      reasoning: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+    })
+  })
+
+  it('ToolApprovalOwner methods are no-ops when no permission is pending', () => {
+    const manager = new CliAgentManager({
+      workspaceRoot: '/workspace',
+      getWebContents: () => null,
+    })
+    expect(manager.ownsToolCall('nonexistent')).toBe(false)
+    expect(manager.getPendingApprovalCount()).toBe(0)
+    expect(() => manager.approveToolCall('s', 'nonexistent')).not.toThrow()
+    expect(() => manager.rejectToolCall('s', 'nonexistent')).not.toThrow()
+  })
 })
diff --git a/tests/unit/openCodeAdapter.test.ts b/tests/unit/openCodeAdapter.test.ts
index 54df7ea..f2f66c6 100644
--- a/tests/unit/openCodeAdapter.test.ts
+++ b/tests/unit/openCodeAdapter.test.ts
@@ -1,109 +1,84 @@
-import { EventEmitter } from 'events'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-const mocks = vi.hoisted(() => ({
-  createServer: vi.fn(),
-  spawn: vi.fn(),
-  createOpencodeClient: vi.fn(),
-}))
-
-vi.mock('net', () => ({
-  default: {
-    createServer: mocks.createServer,
-  },
-  createServer: mocks.createServer,
-}))
-
-vi.mock('child_process', () => ({
-  default: {
-    spawn: mocks.spawn,
-  },
-  spawn: mocks.spawn,
-}))
-
-vi.mock('@opencode-ai/sdk/client', () => ({
-  createOpencodeClient: mocks.createOpencodeClient,
-}))
-
-import { createOpenCodeAdapter } from '../../packages/main/src/chat/cliAdapters/openCodeAdapter'
-
-function makePortServer() {
-  return {
-    once: vi.fn(),
-    listen: vi.fn((_: number, __: string, onListen?: () => void) => onListen?.()),
-    address: vi.fn(() => ({ port: 43123 })),
-    close: vi.fn((onClose?: (error?: Error) => void) => onClose?.()),
-  }
+import { describe, expect, it, vi } from 'vitest'
+import type { OpenCodeServerHost } from '@main/chat/openCodeServerHost'
+import { createOpenCodeAdapter } from '@main/chat/cliAdapters/openCodeAdapter'
+
+interface MockHost {
+  getClient: ReturnType<typeof vi.fn>
+  subscribe: ReturnType<typeof vi.fn>
+  respondPermission: ReturnType<typeof vi.fn>
+  /** Internal: every subscriber that has been registered. */
+  _listeners: Array<(event: unknown) => void>
+  /** Helper for tests: emit an event to all subscribers. */
+  emit(event: unknown): void
 }
 
-function makeChildProcess() {
-  const proc = new EventEmitter() as EventEmitter & {
-    stdout: EventEmitter
-    stderr: EventEmitter
-    kill: ReturnType<typeof vi.fn>
+function makeMockHost(client: unknown): MockHost {
+  const listeners: Array<(event: unknown) => void> = []
+  return {
+    _listeners: listeners,
+    emit(event: unknown) {
+      for (const l of listeners) l(event)
+    },
+    getClient: vi.fn().mockResolvedValue(client),
+    subscribe: vi.fn((_sessionId: string | null, listener: (e: unknown) => void) => {
+      listeners.push(listener)
+      return () => {
+        const idx = listeners.indexOf(listener)
+        if (idx >= 0) listeners.splice(idx, 1)
+      }
+    }),
+    respondPermission: vi.fn().mockResolvedValue(undefined),
   }
-  proc.stdout = new EventEmitter()
-  proc.stderr = new EventEmitter()
-  proc.kill = vi.fn()
-  queueMicrotask(() => {
-    proc.stdout.emit('data', Buffer.from('opencode server listening'))
-  })
-  return proc
 }
 
-describe('createOpenCodeAdapter', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    vi.spyOn(console, 'log').mockImplementation(() => {})
-    vi.spyOn(console, 'error').mockImplementation(() => {})
-    mocks.createServer.mockImplementation(() => makePortServer())
-    mocks.spawn.mockImplementation(() => makeChildProcess())
-  })
-
-  it('accepts direct Session responses from session.create with responseStyle=data', async () => {
-    mocks.createOpencodeClient.mockReturnValue({
+describe('createOpenCodeAdapter (host-driven)', () => {
+  it('creates a session, sends prompt, and emits text + result', async () => {
+    const client = {
       session: {
         create: vi.fn().mockResolvedValue({ id: 'oc-session-1' }),
-        promptAsync: vi.fn().mockResolvedValue(undefined),
-      },
-      global: {
-        event: vi.fn().mockResolvedValue({
-          stream: (async function* () {
-            yield {
-              directory: '/workspace',
-              payload: {
-                type: 'message.updated',
-                properties: {
-                  info: {
-                    id: 'msg-1',
-                    sessionID: 'oc-session-1',
-                    role: 'assistant',
-                    time: { created: 123 },
-                  },
+        promptAsync: vi.fn().mockImplementation(async () => {
+          // After the prompt is accepted, emit a streaming text part then idle.
+          setTimeout(() => {
+            host.emit({
+              type: 'message.updated',
+              properties: {
+                info: {
+                  id: 'msg-1',
+                  sessionID: 'oc-session-1',
+                  role: 'assistant',
+                  time: { created: 123 },
+                  cost: 0.001,
+                  tokens: { input: 10, output: 5, reasoning: 0, cache: { read: 0, write: 0 } },
                 },
               },
-            }
-            yield {
-              directory: '/workspace',
-              payload: {
-                type: 'message.part.updated',
-                properties: {
-                  delta: 'hello from opencode',
-                  part: {
-                    type: 'text',
-                    sessionID: 'oc-session-1',
-                    messageID: 'msg-1',
-                    text: 'hello from opencode',
-                  },
+            })
+            host.emit({
+              type: 'message.part.updated',
+              properties: {
+                delta: 'hello from opencode',
+                part: {
+                  type: 'text',
+                  sessionID: 'oc-session-1',
+                  messageID: 'msg-1',
+                  text: 'hello from opencode',
                 },
               },
-            }
-          })(),
+            })
+            host.emit({
+              type: 'session.idle',
+              properties: { sessionID: 'oc-session-1' },
+            })
+          })
         }),
       },
+    }
+    const host = makeMockHost(client)
+
+    const adapter = createOpenCodeAdapter({
+      host: host as unknown as OpenCodeServerHost,
+      getPermissionSettings: () => ({ tier: 'confirm', autoApprove: {} }),
     })
 
-    const adapter = createOpenCodeAdapter({ executablePath: '/tmp/opencode' })
     const events: unknown[] = []
     const run = adapter.startTurn(
       {
@@ -112,23 +87,206 @@ describe('createOpenCodeAdapter', () => {
         prompt: 'hello',
         backendState: {},
       },
-      (event: unknown) => events.push(event),
+      (event) => events.push(event),
     )
-
     await run.completed
 
+    // Created a new opencode session
+    expect(client.session.create).toHaveBeenCalled()
     expect(events).toContainEqual({
       type: 'backend-state',
       patch: { sessionId: 'oc-session-1' },
     })
-    expect(events).toContainEqual({
-      type: 'message',
-      message: {
-        id: 'msg-1',
-        type: 'assistant',
-        content: 'hello from opencode',
-        timestamp: 123,
+
+    // Streamed text delta + final result event
+    const streamDelta = events.find(
+      (e) => (e as { type?: string }).type === 'stream-delta',
+    )
+    expect(streamDelta).toMatchObject({ delta: 'hello from opencode' })
+
+    const result = events.find((e) => (e as { type?: string }).type === 'result')
+    expect(result).toMatchObject({
+      isSuccess: true,
+      totalCostUsd: 0.001,
+      tokens: { input: 10, output: 5, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+    })
+  })
+
+  it('reuses an existing sessionId from backendState', async () => {
+    const client = {
+      session: {
+        create: vi.fn(),
+        promptAsync: vi.fn().mockImplementation(async () => {
+          setTimeout(() => {
+            host.emit({ type: 'session.idle', properties: { sessionID: 'preexisting' } })
+          })
+        }),
+      },
+    }
+    const host = makeMockHost(client)
+    const adapter = createOpenCodeAdapter({
+      host: host as unknown as OpenCodeServerHost,
+      getPermissionSettings: () => ({ tier: 'autopilot', autoApprove: {} }),
+    })
+
+    await adapter
+      .startTurn(
+        {
+          conversationId: 'conv-x',
+          cwd: '/workspace',
+          prompt: 'hi',
+          backendState: { sessionId: 'preexisting' },
+        },
+        () => {},
+      )
+      .completed
+
+    expect(client.session.create).not.toHaveBeenCalled()
+    expect(client.session.promptAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ path: { id: 'preexisting' } }),
+    )
+  })
+
+  it('passes provider/model/agent/system/tools overrides on the prompt body', async () => {
+    const client = {
+      session: {
+        create: vi.fn(),
+        promptAsync: vi.fn().mockImplementation(async () => {
+          setTimeout(() => {
+            host.emit({ type: 'session.idle', properties: { sessionID: 's1' } })
+          })
+        }),
       },
+    }
+    const host = makeMockHost(client)
+    const adapter = createOpenCodeAdapter({
+      host: host as unknown as OpenCodeServerHost,
+      getPermissionSettings: () => ({ tier: 'autopilot', autoApprove: {} }),
     })
+
+    await adapter
+      .startTurn(
+        {
+          conversationId: 'conv-x',
+          cwd: '/workspace',
+          prompt: 'hi',
+          backendState: {
+            sessionId: 's1',
+            providerID: 'anthropic',
+            modelID: 'claude-sonnet-4-5',
+            agent: 'build',
+            systemPromptOverride: 'be terse',
+            toolToggles: { web_search: false },
+          },
+        },
+        () => {},
+      )
+      .completed
+
+    expect(client.session.promptAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: { id: 's1' },
+        body: expect.objectContaining({
+          parts: [{ type: 'text', text: 'hi' }],
+          model: { providerID: 'anthropic', modelID: 'claude-sonnet-4-5' },
+          agent: 'build',
+          system: 'be terse',
+          tools: { web_search: false },
+        }),
+      }),
+    )
+  })
+
+  it('auto-approves permission events under autopilot tier without prompting', async () => {
+    const client = {
+      session: {
+        create: vi.fn().mockResolvedValue({ id: 's1' }),
+        promptAsync: vi.fn().mockImplementation(async () => {
+          setTimeout(() => {
+            host.emit({
+              type: 'permission.updated',
+              properties: {
+                id: 'perm-1',
+                sessionID: 's1',
+                type: 'edit',
+                title: 'Edit foo.ts',
+                pattern: 'foo.ts',
+                metadata: {},
+                time: { created: 0 },
+              },
+            })
+            host.emit({ type: 'session.idle', properties: { sessionID: 's1' } })
+          })
+        }),
+      },
+    }
+    const host = makeMockHost(client)
+    const adapter = createOpenCodeAdapter({
+      host: host as unknown as OpenCodeServerHost,
+      getPermissionSettings: () => ({ tier: 'autopilot', autoApprove: {} }),
+    })
+
+    const events: unknown[] = []
+    await adapter
+      .startTurn(
+        { conversationId: 'c', cwd: '/w', prompt: 'p', backendState: {} },
+        (e) => events.push(e),
+      )
+      .completed
+
+    expect(host.respondPermission).toHaveBeenCalledWith('s1', 'perm-1', 'always')
+    // No permission-request emitted to the manager since it was auto-decided.
+    expect(events.find((e) => (e as { type?: string }).type === 'permission-request')).toBeUndefined()
+  })
+
+  it('forwards permission events under confirm tier as permission-request', async () => {
+    const client = {
+      session: {
+        create: vi.fn().mockResolvedValue({ id: 's1' }),
+        promptAsync: vi.fn().mockImplementation(async () => {
+          setTimeout(() => {
+            host.emit({
+              type: 'permission.updated',
+              properties: {
+                id: 'perm-2',
+                sessionID: 's1',
+                type: 'bash',
+                title: 'Run rm -rf',
+                pattern: 'rm -rf /',
+                metadata: {},
+                time: { created: 0 },
+              },
+            })
+            host.emit({ type: 'session.idle', properties: { sessionID: 's1' } })
+          })
+        }),
+      },
+    }
+    const host = makeMockHost(client)
+    const adapter = createOpenCodeAdapter({
+      host: host as unknown as OpenCodeServerHost,
+      getPermissionSettings: () => ({ tier: 'confirm', autoApprove: {} }),
+    })
+
+    const events: unknown[] = []
+    const run = adapter.startTurn(
+      { conversationId: 'c', cwd: '/w', prompt: 'p', backendState: {} },
+      (e) => {
+        events.push(e)
+        // Auto-resolve any permission-request as 'reject' so the run can finish.
+        if ((e as { type?: string }).type === 'permission-request') {
+          ;(e as { resolve: (r: 'reject') => void }).resolve('reject')
+        }
+      },
+    )
+    await run.completed
+
+    const permRequest = events.find(
+      (e) => (e as { type?: string }).type === 'permission-request',
+    )
+    expect(permRequest).toBeDefined()
+    // The test's inline resolver (called from the emit callback) routes
+    // through the adapter's resolve closure which POSTs to the host.
+    expect(host.respondPermission).toHaveBeenCalledWith('s1', 'perm-2', 'reject')
   })
 })
diff --git a/tests/unit/openCodePartConverter.test.ts b/tests/unit/openCodePartConverter.test.ts
new file mode 100644
index 0000000..311d5ae
--- /dev/null
+++ b/tests/unit/openCodePartConverter.test.ts
@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest'
+import {
+  convertOpenCodePart,
+  createConvertContext,
+  extractTokens,
+  sumTokens,
+} from '@main/chat/cliAdapters/openCodePartConverter'
+
+describe('convertOpenCodePart', () => {
+  it('text part with delta returns isTextDelta true and no message', () => {
+    const ctx = createConvertContext()
+    const result = convertOpenCodePart(
+      { id: 'p1', type: 'text', text: 'hi', messageID: 'm1' },
+      'hi',
+      ctx,
+    )
+    expect(result.isTextDelta).toBe(true)
+    expect(result.delta).toBe('hi')
+    expect(result.messages).toEqual([])
+  })
+
+  it('reasoning part emits a reasoning message once per partId', () => {
+    const ctx = createConvertContext()
+    const part = { id: 'r1', type: 'reasoning', text: 'thinking…' }
+    const first = convertOpenCodePart(part, undefined, ctx)
+    const second = convertOpenCodePart(part, undefined, ctx)
+    expect(first.messages[0]?.type).toBe('reasoning')
+    expect(second.messages).toHaveLength(0)
+  })
+
+  it('tool part dedupes repeated statuses but emits on transitions', () => {
+    const ctx = createConvertContext()
+    const base = { id: 't1', type: 'tool', tool: 'bash', callID: 'c1' }
+    const pending1 = convertOpenCodePart(
+      { ...base, state: { status: 'pending' } },
+      undefined,
+      ctx,
+    )
+    const pending2 = convertOpenCodePart(
+      { ...base, state: { status: 'pending' } },
+      undefined,
+      ctx,
+    )
+    const running = convertOpenCodePart({ ...base, state: { status: 'running' } }, undefined, ctx)
+    const completed = convertOpenCodePart(
+      { ...base, state: { status: 'completed', output: 'ok' } },
+      undefined,
+      ctx,
+    )
+    expect(pending1.messages[0]?.type).toBe('tool_use')
+    // Repeated pending → no new message
+    expect(pending2.messages).toHaveLength(0)
+    // pending → running transition → another tool_use message
+    expect(running.messages[0]?.type).toBe('tool_use')
+    expect(completed.messages[0]?.type).toBe('tool_result')
+  })
+
+  it('patch part captures hash + files', () => {
+    const ctx = createConvertContext()
+    const result = convertOpenCodePart(
+      { id: 'p1', type: 'patch', hash: 'abc123def', files: ['a.ts', 'b.ts'] },
+      undefined,
+      ctx,
+    )
+    expect(result.messages[0]).toMatchObject({
+      type: 'patch',
+      patchHash: 'abc123def',
+      patchFiles: ['a.ts', 'b.ts'],
+    })
+  })
+
+  it('step-finish carries cost + tokens', () => {
+    const ctx = createConvertContext()
+    const result = convertOpenCodePart(
+      {
+        id: 's1',
+        type: 'step-finish',
+        reason: 'turn complete',
+        cost: 0.0021,
+        tokens: { input: 100, output: 50, reasoning: 0, cache: { read: 5, write: 2 } },
+      },
+      undefined,
+      ctx,
+    )
+    const msg = result.messages[0]!
+    expect(msg.type).toBe('step')
+    expect(msg.stepPhase).toBe('finish')
+    expect(msg.costUsd).toBe(0.0021)
+    expect(msg.tokens).toEqual({
+      input: 100,
+      output: 50,
+      reasoning: 0,
+      cacheRead: 5,
+      cacheWrite: 2,
+    })
+  })
+
+  it('snapshot / retry / compaction / agent / subtask all map to their type', () => {
+    const ctx = createConvertContext()
+    expect(
+      convertOpenCodePart({ id: '1', type: 'snapshot', snapshot: 'h' }, undefined, ctx).messages[0]
+        ?.type,
+    ).toBe('snapshot')
+    expect(
+      convertOpenCodePart(
+        { id: '2', type: 'retry', attempt: 2, error: { data: { message: 'oops' } } },
+        undefined,
+        ctx,
+      ).messages[0]?.type,
+    ).toBe('retry')
+    expect(
+      convertOpenCodePart({ id: '3', type: 'compaction', auto: true }, undefined, ctx).messages[0]
+        ?.type,
+    ).toBe('compaction')
+    expect(
+      convertOpenCodePart({ id: '4', type: 'agent', name: 'build' }, undefined, ctx).messages[0]
+        ?.type,
+    ).toBe('agent_change')
+    expect(
+      convertOpenCodePart(
+        { id: '5', type: 'subtask', prompt: 'do x', description: 'd', agent: 'a' },
+        undefined,
+        ctx,
+      ).messages[0]?.type,
+    ).toBe('subtask')
+  })
+
+  it('unknown part type falls back to system', () => {
+    const ctx = createConvertContext()
+    const result = convertOpenCodePart({ id: '?', type: 'mystery' }, undefined, ctx)
+    expect(result.messages[0]?.type).toBe('system')
+    expect(result.messages[0]?.content).toContain('mystery')
+  })
+})
+
+describe('extractTokens', () => {
+  it('extracts a non-empty token usage record', () => {
+    expect(
+      extractTokens({ input: 10, output: 5, reasoning: 0, cache: { read: 2, write: 0 } }),
+    ).toEqual({
+      input: 10,
+      output: 5,
+      reasoning: 0,
+      cacheRead: 2,
+      cacheWrite: 0,
+    })
+  })
+
+  it('returns undefined when all fields are zero / missing', () => {
+    expect(extractTokens(undefined)).toBeUndefined()
+    expect(extractTokens({ input: 0, output: 0 })).toBeUndefined()
+  })
+})
+
+describe('sumTokens', () => {
+  it('sums two records', () => {
+    expect(
+      sumTokens(
+        { input: 1, output: 2, reasoning: 3, cacheRead: 4, cacheWrite: 5 },
+        { input: 10, output: 20, reasoning: 30, cacheRead: 40, cacheWrite: 50 },
+      ),
+    ).toEqual({ input: 11, output: 22, reasoning: 33, cacheRead: 44, cacheWrite: 55 })
+  })
+
+  it('handles undefined operands', () => {
+    expect(sumTokens(undefined, { input: 1, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 }))
+      .toEqual({ input: 1, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 })
+  })
+})
diff --git a/tests/unit/openCodePermissionBridge.test.ts b/tests/unit/openCodePermissionBridge.test.ts
new file mode 100644
index 0000000..06710de
--- /dev/null
+++ b/tests/unit/openCodePermissionBridge.test.ts
@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest'
+import {
+  buildOpenCodePermissionConfig,
+  decideOpenCodePermission,
+} from '@main/chat/cliAdapters/openCodePermissionBridge'
+
+describe('buildOpenCodePermissionConfig', () => {
+  it('autopilot tier allows everything', () => {
+    const config = buildOpenCodePermissionConfig('autopilot', {})
+    expect(config).toEqual({
+      edit: 'allow',
+      bash: 'allow',
+      webfetch: 'allow',
+      doom_loop: 'allow',
+      external_directory: 'allow',
+    })
+  })
+
+  it('confirm tier asks for everything', () => {
+    const config = buildOpenCodePermissionConfig('confirm', {})
+    expect(config).toEqual({
+      edit: 'ask',
+      bash: 'ask',
+      webfetch: 'ask',
+      doom_loop: 'ask',
+      external_directory: 'ask',
+    })
+  })
+
+  it('auto-approve tier allows webfetch but asks for edits / bash', () => {
+    const config = buildOpenCodePermissionConfig('auto-approve', {})
+    expect(config.webfetch).toBe('allow')
+    expect(config.edit).toBe('ask')
+    expect(config.bash).toBe('ask')
+  })
+
+  it('per-tool boolean overrides bypass the tier', () => {
+    const config = buildOpenCodePermissionConfig('confirm', {
+      file_write: true,
+      terminal_exec: false,
+    })
+    expect(config.edit).toBe('allow')
+    expect(config.bash).toBe('deny')
+    expect(config.webfetch).toBe('ask')
+  })
+
+  it('pattern overrides defer to runtime ask', () => {
+    const config = buildOpenCodePermissionConfig('confirm', {
+      terminal_exec: { allowPatterns: ['ls *'], denyPatterns: ['rm *'] },
+    })
+    expect(config.bash).toBe('ask')
+  })
+})
+
+describe('decideOpenCodePermission', () => {
+  it('autopilot → always allow', () => {
+    const result = decideOpenCodePermission(
+      { category: 'edit', pattern: 'src/foo.ts' },
+      'autopilot',
+      {},
+    )
+    expect(result).toBe('always')
+  })
+
+  it('confirm → always prompt', () => {
+    const result = decideOpenCodePermission(
+      { category: 'bash', pattern: 'ls -la' },
+      'confirm',
+      {},
+    )
+    expect(result).toBe('prompt')
+  })
+
+  it('auto-approve allows webfetch (read-only) but prompts for edit', () => {
+    expect(
+      decideOpenCodePermission({ category: 'webfetch', pattern: 'https://x' }, 'auto-approve', {}),
+    ).toBe('always')
+    expect(
+      decideOpenCodePermission(
+        { category: 'edit', pattern: 'src/foo.ts' },
+        'auto-approve',
+        {},
+      ),
+    ).toBe('prompt')
+  })
+
+  it('per-tool boolean override forces allow / deny', () => {
+    expect(
+      decideOpenCodePermission(
+        { category: 'edit', pattern: 'x' },
+        'confirm',
+        { file_write: true },
+      ),
+    ).toBe('always')
+    expect(
+      decideOpenCodePermission(
+        { category: 'edit', pattern: 'x' },
+        'autopilot',
+        { file_write: false },
+      ),
+    ).toBe('reject')
+  })
+
+  it('pattern allow / deny on bash matches against the command pattern', () => {
+    expect(
+      decideOpenCodePermission(
+        { category: 'bash', pattern: 'ls -la' },
+        'confirm',
+        { terminal_exec: { allowPatterns: ['ls *'] } },
+      ),
+    ).toBe('always')
+
+    expect(
+      decideOpenCodePermission(
+        { category: 'bash', pattern: 'rm -rf /' },
+        'autopilot',
+        { terminal_exec: { denyPatterns: ['rm *'] } },
+      ),
+    ).toBe('reject')
+
+    // Doesn't match allowPatterns → prompt
+    expect(
+      decideOpenCodePermission(
+        { category: 'bash', pattern: 'cat file' },
+        'confirm',
+        { terminal_exec: { allowPatterns: ['ls *'] } },
+      ),
+    ).toBe('prompt')
+  })
+})
diff --git a/tests/unit/useCliAgent.test.tsx b/tests/unit/useCliAgent.test.tsx
index c8e732b..3876e5d 100644
--- a/tests/unit/useCliAgent.test.tsx
+++ b/tests/unit/useCliAgent.test.tsx
@@ -10,11 +10,14 @@ function stubWindowApi(overrides: Record<string, unknown> = {}) {
     cliAgentStart: vi.fn().mockResolvedValue({ sessionId: 'started-session' }),
     cliAgentSend: vi.fn().mockResolvedValue({ success: true as const }),
     cliAgentStop: vi.fn(),
+    cliAgentSwitchBackend: vi.fn().mockResolvedValue({ success: true as const }),
+    cliAgentUpdateSessionConfig: vi.fn().mockResolvedValue({ success: true as const }),
     conversationGet: vi.fn().mockResolvedValue(null),
     onConversationListChanged: vi.fn().mockReturnValue(() => {}),
     onCliAgentStreamDelta: vi.fn().mockReturnValue(() => {}),
     onCliAgentMessage: vi.fn().mockReturnValue(() => {}),
     onCliAgentStatus: vi.fn().mockReturnValue(() => {}),
+    onCliAgentResult: vi.fn().mockReturnValue(() => {}),
     ...overrides,
   }
   Object.defineProperty(window, 'api', { value: api, writable: true, configurable: true })

From 80324bea1fb6ba5c0203bd648ccd2e0ac89b9cb4 Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 19:15:04 -0400
Subject: [PATCH 8/9] refactor: declutter opencode chat pane with gear popover
 + user defaults
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the three stacked disclosures (session settings / diagnostics /
TUI controls) above every OpenCode chat with a single gear-anchored
popover in the header. Diagnostics, init AGENTS.md, and the TUI controls
move into the OpenCodeToolsPane Status tab; the kebab menu trims to
Share / Summarize / Delete remote.

Add a new agent.opencode.* settings namespace (defaultProvider,
defaultModel, defaultAgent, defaultMode, defaultSystemPrompt,
defaultToolToggles) under Settings → Agent → OpenCode Defaults. New
sessions seed their backendStates['opencode'] from these once on first
touch; per-session overrides set from the popover never write back. The
keys are added to SENSITIVE_AGENT_KEYS so workspace .aide/settings.json
files can't override the user's choice. CliAgentManager exposes
updateOpencodeDefaults() and the settings-changed listener calls it so
edits apply live.

Refined terminal-minimal styling for all OpenCode UI surfaces in a new
cli-agent-settings.css: hairline borders, 2px radii, 9px all-caps mono
labels, transparent inputs with focus underlines, dot-grid popover
backdrop, bottom-border tab indicators.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/main/src/chat/cliAgentManager.ts     |  72 ++
 packages/main/src/index.ts                    |  26 +-
 .../main/src/workspace/settingsResolver.ts    |  37 +
 .../components/cliAgent/DiagnosticsPanel.tsx  | 106 ---
 .../src/components/cliAgent/SessionMenu.tsx   | 151 ++--
 .../cliAgent/SessionSettingsPanel.tsx         | 338 ---------
 .../cliAgent/SessionSettingsPopover.tsx       | 422 +++++++++++
 .../components/cliAgent/TuiControlPanel.tsx   |  92 ---
 .../src/components/panes/CliAgentPane.tsx     |  38 +-
 .../components/panes/OpenCodeToolsPane.tsx    | 376 +++++++---
 packages/renderer/src/lib/settingsSchema.ts   |  46 ++
 .../src/styles/cli-agent-settings.css         | 660 ++++++++++++++++++
 packages/shared/src/index.ts                  |  26 +
 13 files changed, 1647 insertions(+), 743 deletions(-)
 delete mode 100644 packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
 delete mode 100644 packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
 create mode 100644 packages/renderer/src/components/cliAgent/SessionSettingsPopover.tsx
 delete mode 100644 packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
 create mode 100644 packages/renderer/src/styles/cli-agent-settings.css

diff --git a/packages/main/src/chat/cliAgentManager.ts b/packages/main/src/chat/cliAgentManager.ts
index 91ca3e6..26670e1 100644
--- a/packages/main/src/chat/cliAgentManager.ts
+++ b/packages/main/src/chat/cliAgentManager.ts
@@ -88,6 +88,21 @@ interface PendingPermission {
   resolve: (response: 'always' | 'once' | 'reject') => void
 }
 
+/**
+ * User-scoped defaults applied as the *initial* `backendStates['opencode']`
+ * for new sessions. Resolved once at construction (and refreshed via
+ * `updateOpencodeDefaults` when settings change). Per-session edits made
+ * from the chat pane never write back to these.
+ */
+export interface OpencodeSessionDefaults {
+  providerID?: string
+  modelID?: string
+  agent?: string
+  mode?: string
+  systemPromptOverride?: string
+  toolToggles?: Record<string, boolean>
+}
+
 export interface CliAgentManagerOpts {
   workspaceRoot: string
   workspaceId?: string
@@ -99,6 +114,7 @@ export interface CliAgentManagerOpts {
   loadClaudeHistory?: (claudeSessionId: string) => Promise<CliAgentMessage[]>
   permissionTier?: PermissionTier
   autoApprove?: Record<string, boolean | ToolPermissionConfig>
+  opencodeDefaults?: OpencodeSessionDefaults
   /** Called when pending approvals / running session counts change. */
   onWorkloadChanged?: () => void
 }
@@ -169,6 +185,7 @@ export class CliAgentManager implements ToolApprovalOwner {
 
   private permissionTier: PermissionTier
   private autoApprove: Record<string, boolean | ToolPermissionConfig>
+  private opencodeDefaults: OpencodeSessionDefaults
   private readonly onWorkloadChanged?: () => void
 
   private openCodeHost: OpenCodeServerHost | null = null
@@ -185,6 +202,7 @@ export class CliAgentManager implements ToolApprovalOwner {
     this.loadClaudeHistory = opts.loadClaudeHistory ?? null
     this.permissionTier = opts.permissionTier ?? 'confirm'
     this.autoApprove = opts.autoApprove ?? {}
+    this.opencodeDefaults = opts.opencodeDefaults ?? {}
     this.onWorkloadChanged = opts.onWorkloadChanged
   }
 
@@ -213,6 +231,14 @@ export class CliAgentManager implements ToolApprovalOwner {
     let existingMessages = persisted.messages ?? []
     const backendStates = persisted.backendStates ?? {}
 
+    // Seed opencode state from user defaults *only* on the first time we
+    // touch this conversation as opencode (no persisted opencode block).
+    // We never overwrite existing per-session overrides.
+    if (backend === 'opencode' && !backendStates['opencode']) {
+      const seed = this.buildOpencodeSeed()
+      if (seed) backendStates['opencode'] = seed
+    }
+
     if (!backendStates['claude-code']?.sessionId && conversationId?.startsWith('claude-native:')) {
       const raw = conversationId.slice('claude-native:'.length)
       if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) {
@@ -297,6 +323,12 @@ export class CliAgentManager implements ToolApprovalOwner {
       return { error: 'Native Claude conversations cannot switch to a different backend.' }
     }
 
+    // First time this conversation switches to opencode → seed defaults.
+    if (backend === 'opencode' && !session.backendStates['opencode']) {
+      const seed = this.buildOpencodeSeed()
+      if (seed) session.backendStates['opencode'] = seed
+    }
+
     session.backend = backend
     session.model = session.backendStates[backend]?.model
     session.sessionToolNames = undefined
@@ -307,6 +339,36 @@ export class CliAgentManager implements ToolApprovalOwner {
     return { success: true }
   }
 
+  /**
+   * Build a fresh `CliAgentBackendState` for an opencode session from the
+   * user's defaults. Returns `null` when no defaults are set so we don't
+   * pollute the persisted state with empty objects.
+   */
+  private buildOpencodeSeed(): CliAgentBackendState | null {
+    const d = this.opencodeDefaults
+    const hasAny =
+      !!d.providerID ||
+      !!d.modelID ||
+      !!d.agent ||
+      !!d.mode ||
+      !!d.systemPromptOverride ||
+      (d.toolToggles && Object.keys(d.toolToggles).length > 0)
+    if (!hasAny) return null
+    const seed: CliAgentBackendState = {}
+    if (d.providerID && d.modelID) {
+      seed.providerID = d.providerID
+      seed.modelID = d.modelID
+      seed.model = `${d.providerID}/${d.modelID}`
+    }
+    if (d.agent) seed.agent = d.agent
+    if (d.mode) seed.mode = d.mode
+    if (d.systemPromptOverride) seed.systemPromptOverride = d.systemPromptOverride
+    if (d.toolToggles && Object.keys(d.toolToggles).length > 0) {
+      seed.toolToggles = { ...d.toolToggles }
+    }
+    return seed
+  }
+
   async send(sessionId: string, content: string): Promise<{ success: true } | { error: string }> {
     const session = this.sessions.get(sessionId)
     if (!session) return { error: 'Session not found' }
@@ -429,6 +491,16 @@ export class CliAgentManager implements ToolApprovalOwner {
     this.autoApprove = autoApprove
   }
 
+  /**
+   * Replace the opencode session-default seed (called from the settings-
+   * changed handler when any `agent.opencode.default*` key is touched).
+   * Existing sessions keep their per-session overrides; the new defaults
+   * only apply to sessions created/switched-into-opencode after this call.
+   */
+  updateOpencodeDefaults(defaults: OpencodeSessionDefaults): void {
+    this.opencodeDefaults = defaults
+  }
+
   getRunningSessionCount(): number {
     let count = 0
     for (const session of this.sessions.values()) {
diff --git a/packages/main/src/index.ts b/packages/main/src/index.ts
index 1b9390a..323b802 100644
--- a/packages/main/src/index.ts
+++ b/packages/main/src/index.ts
@@ -546,6 +546,14 @@ async function startRuntimeServices(runtime: WorkspaceRuntime): Promise<void> {
       nativeSessionWatcher.loadMessages(claudeSessionId),
     permissionTier: permConfig.permissionTier,
     autoApprove: permConfig.autoApprove,
+    opencodeDefaults: {
+      providerID: resolved['agent.opencode.defaultProvider'] || undefined,
+      modelID: resolved['agent.opencode.defaultModel'] || undefined,
+      agent: resolved['agent.opencode.defaultAgent'] || undefined,
+      mode: resolved['agent.opencode.defaultMode'] || undefined,
+      systemPromptOverride: resolved['agent.opencode.defaultSystemPrompt'] || undefined,
+      toolToggles: resolved['agent.opencode.defaultToolToggles'] ?? undefined,
+    },
     onWorkloadChanged: () => {
       runtime.refreshWorkload()
     },
@@ -1371,15 +1379,25 @@ ipcMain.handle(IpcChannels.SETTINGS_SET_USER, async (_event, key: string, value:
   if (key.startsWith('agent.')) {
     const config = loadLlmConfig()
     const permConfig = loadPermissionConfig()
+    const appDefs = resolveAppDefaults(store)
     for (const runtime of runtimeRegistry.list()) {
       getAgentManager(runtime)?.updateConfig(config)
       getAgentManager(runtime)?.updatePermissions(permConfig.permissionTier, permConfig.autoApprove)
       // Mirror permission updates into the CLI agent manager so OpenCode
       // permission decisions stay in sync with live tier changes.
-      getCliAgentManager(runtime)?.updatePermissions(
-        permConfig.permissionTier,
-        permConfig.autoApprove,
-      )
+      const cm = getCliAgentManager(runtime)
+      cm?.updatePermissions(permConfig.permissionTier, permConfig.autoApprove)
+      // Refresh OpenCode session-default seeds whenever any opencode default
+      // is touched. New sessions started afterwards inherit the new values;
+      // existing sessions retain their per-session overrides.
+      cm?.updateOpencodeDefaults({
+        providerID: appDefs['agent.opencode.defaultProvider'] || undefined,
+        modelID: appDefs['agent.opencode.defaultModel'] || undefined,
+        agent: appDefs['agent.opencode.defaultAgent'] || undefined,
+        mode: appDefs['agent.opencode.defaultMode'] || undefined,
+        systemPromptOverride: appDefs['agent.opencode.defaultSystemPrompt'] || undefined,
+        toolToggles: appDefs['agent.opencode.defaultToolToggles'] ?? undefined,
+      })
       runtime.refreshWorkload()
     }
   }
diff --git a/packages/main/src/workspace/settingsResolver.ts b/packages/main/src/workspace/settingsResolver.ts
index 7ea39d6..b9c7321 100644
--- a/packages/main/src/workspace/settingsResolver.ts
+++ b/packages/main/src/workspace/settingsResolver.ts
@@ -48,6 +48,14 @@ export const BUILT_IN_DEFAULTS: ResolvedSettings = {
   'agent.claudeCodePath': '',
   'agent.opencodePath': '',
   'agent.codexPath': '',
+
+  // OpenCode-specific session defaults
+  'agent.opencode.defaultProvider': '',
+  'agent.opencode.defaultModel': '',
+  'agent.opencode.defaultAgent': '',
+  'agent.opencode.defaultMode': '',
+  'agent.opencode.defaultSystemPrompt': '',
+  'agent.opencode.defaultToolToggles': {} as Record<string, boolean>,
 }
 
 /**
@@ -99,6 +107,27 @@ export function resolveAppDefaults(store: Store<AppSettings>): ResolvedSettings
     'agent.opencodePath':
       userDefaults['agent.opencodePath'] ?? BUILT_IN_DEFAULTS['agent.opencodePath'],
     'agent.codexPath': userDefaults['agent.codexPath'] ?? BUILT_IN_DEFAULTS['agent.codexPath'],
+
+    // OpenCode session defaults
+    'agent.opencode.defaultProvider':
+      userDefaults['agent.opencode.defaultProvider'] ??
+      BUILT_IN_DEFAULTS['agent.opencode.defaultProvider'],
+    'agent.opencode.defaultModel':
+      userDefaults['agent.opencode.defaultModel'] ??
+      BUILT_IN_DEFAULTS['agent.opencode.defaultModel'],
+    'agent.opencode.defaultAgent':
+      userDefaults['agent.opencode.defaultAgent'] ??
+      BUILT_IN_DEFAULTS['agent.opencode.defaultAgent'],
+    'agent.opencode.defaultMode':
+      userDefaults['agent.opencode.defaultMode'] ??
+      BUILT_IN_DEFAULTS['agent.opencode.defaultMode'],
+    'agent.opencode.defaultSystemPrompt':
+      userDefaults['agent.opencode.defaultSystemPrompt'] ??
+      BUILT_IN_DEFAULTS['agent.opencode.defaultSystemPrompt'],
+    'agent.opencode.defaultToolToggles': {
+      ...BUILT_IN_DEFAULTS['agent.opencode.defaultToolToggles'],
+      ...(userDefaults['agent.opencode.defaultToolToggles'] ?? {}),
+    },
   }
 }
 
@@ -170,5 +199,13 @@ export async function resolveSettings(
     'agent.claudeCodePath': appDefaults['agent.claudeCodePath'],
     'agent.opencodePath': appDefaults['agent.opencodePath'],
     'agent.codexPath': appDefaults['agent.codexPath'],
+
+    // OpenCode session defaults (user-only — see SENSITIVE_AGENT_KEYS)
+    'agent.opencode.defaultProvider': appDefaults['agent.opencode.defaultProvider'],
+    'agent.opencode.defaultModel': appDefaults['agent.opencode.defaultModel'],
+    'agent.opencode.defaultAgent': appDefaults['agent.opencode.defaultAgent'],
+    'agent.opencode.defaultMode': appDefaults['agent.opencode.defaultMode'],
+    'agent.opencode.defaultSystemPrompt': appDefaults['agent.opencode.defaultSystemPrompt'],
+    'agent.opencode.defaultToolToggles': appDefaults['agent.opencode.defaultToolToggles'],
   }
 }
diff --git a/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx b/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
deleted file mode 100644
index 106005a..0000000
--- a/packages/renderer/src/components/cliAgent/DiagnosticsPanel.tsx
+++ /dev/null
@@ -1,106 +0,0 @@
-import { useEffect, useState } from 'react'
-import type { OpenCodePathInfo, OpenCodeServerInfo } from '@aide/shared'
-
-/**
- * Read-only diagnostics for an active OpenCode session: server info,
- * resolved paths, LSP/formatter status. Hidden behind a disclosure to
- * keep the pane header tidy.
- */
-export function DiagnosticsPanel({
-  workspaceId,
-  sessionId,
-}: {
-  workspaceId: string | null
-  sessionId: string | null
-}) {
-  const [open, setOpen] = useState(false)
-  const [server, setServer] = useState<OpenCodeServerInfo | null>(null)
-  const [paths, setPaths] = useState<OpenCodePathInfo | null>(null)
-  const [lsp, setLsp] = useState<unknown>(null)
-  const [formatter, setFormatter] = useState<unknown>(null)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    if (!open || !sessionId || !workspaceId) return
-    let cancelled = false
-    void (async () => {
-      try {
-        const s = (await window.api.cliAgentServerInfo(workspaceId)) as OpenCodeServerInfo | null
-        if (!cancelled) setServer(s)
-        const p = await window.api.cliAgentPathGet(sessionId)
-        if (!cancelled && !p.error) setPaths((p.paths as OpenCodePathInfo) ?? null)
-        const l = await window.api.cliAgentLspStatus(sessionId)
-        if (!cancelled) setLsp(l.status)
-        const f = await window.api.cliAgentFormatterStatus(sessionId)
-        if (!cancelled) setFormatter(f.status)
-      } catch (e) {
-        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [open, sessionId, workspaceId])
-
-  if (!sessionId) return null
-
-  return (
-    <details
-      open={open}
-      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
-      style={{
-        margin: '6px 0',
-        padding: '6px 8px',
-        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
-        borderRadius: 4,
-        fontSize: 11,
-      }}
-    >
-      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>Diagnostics</summary>
-      {open && (
-        <div style={{ marginTop: 6, display: 'flex', flexDirection: 'column', gap: 4 }}>
-          {error && <div style={{ color: 'tomato' }}>{error}</div>}
-          {server && (
-            <Field label="Server">
-              {server.url} <em>({server.mode})</em> pid={server.pid}
-            </Field>
-          )}
-          {paths?.config && <Field label="Config">{paths.config}</Field>}
-          {paths?.data && <Field label="Data">{paths.data}</Field>}
-          {paths?.cache && <Field label="Cache">{paths.cache}</Field>}
-          {paths?.log && <Field label="Log">{paths.log}</Field>}
-          {lsp != null && (
-            <Field label="LSP">
-              <code style={{ fontSize: 10 }}>{JSON.stringify(lsp).slice(0, 200)}</code>
-            </Field>
-          )}
-          {formatter != null && (
-            <Field label="Formatter">
-              <code style={{ fontSize: 10 }}>{JSON.stringify(formatter).slice(0, 200)}</code>
-            </Field>
-          )}
-          <button
-            onClick={() => void window.api.cliAgentLogWrite(sessionId, 'log from aIDE diagnostics', 'INFO')}
-            style={{
-              alignSelf: 'flex-start',
-              fontSize: 10,
-              padding: '2px 6px',
-              marginTop: 4,
-            }}
-          >
-            Write test log
-          </button>
-        </div>
-      )}
-    </details>
-  )
-}
-
-function Field({ label, children }: { label: string; children: React.ReactNode }) {
-  return (
-    <div>
-      <strong style={{ opacity: 0.6, marginRight: 4 }}>{label}:</strong>
-      {children}
-    </div>
-  )
-}
diff --git a/packages/renderer/src/components/cliAgent/SessionMenu.tsx b/packages/renderer/src/components/cliAgent/SessionMenu.tsx
index fdf4e32..7283e35 100644
--- a/packages/renderer/src/components/cliAgent/SessionMenu.tsx
+++ b/packages/renderer/src/components/cliAgent/SessionMenu.tsx
@@ -1,12 +1,15 @@
-import { useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 
 /**
- * Kebab menu in the CliAgentPane header for OpenCode session ops:
- * share, summarize, revert, unrevert, abort, fork, view diff, todos,
- * initialize project, delete remote.
+ * Trimmed kebab menu in the CliAgentPane header for OpenCode session ops.
  *
- * Each action calls the corresponding window.api.cliAgentSession* IPC
- * and surfaces success / error in a small toast.
+ * Surfaces only the three actions a user is likely to reach for from inside
+ * the chat itself: Share, Summarize, and Delete (remote). Less-common ops
+ * (init AGENTS.md, abort, fork, revert) live in the OpenCodeToolsPane or
+ * are exposed contextually elsewhere — see frontend redesign 2026-04-08.
+ *
+ * Each action calls the corresponding `window.api.cliAgentSession*` IPC
+ * and surfaces success / error in a small toast (handled by parent).
  */
 export function SessionMenu({
   sessionId,
@@ -19,8 +22,32 @@ export function SessionMenu({
 }) {
   const [open, setOpen] = useState(false)
   const [busy, setBusy] = useState(false)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const menuRef = useRef<HTMLDivElement>(null)
 
-  const wrap = async (fn: () => Promise<{ error?: string } | { url?: string } | { newSessionId?: string }>) => {
+  // Dismiss on outside click + Escape, matching the popover behaviour.
+  useEffect(() => {
+    if (!open) return
+    const onMouseDown = (e: MouseEvent) => {
+      const t = e.target as Node
+      if (menuRef.current?.contains(t)) return
+      if (triggerRef.current?.contains(t)) return
+      setOpen(false)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    window.addEventListener('mousedown', onMouseDown)
+    window.addEventListener('keydown', onKey)
+    return () => {
+      window.removeEventListener('mousedown', onMouseDown)
+      window.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  const wrap = async (
+    fn: () => Promise<{ error?: string } | { url?: string }>,
+  ) => {
     if (!sessionId) return
     setBusy(true)
     setOpen(false)
@@ -31,12 +58,10 @@ export function SessionMenu({
       } else if ('url' in result && result.url) {
         try {
           await navigator.clipboard.writeText(result.url)
-          onMessage(`Shared · URL copied to clipboard`, 'success')
+          onMessage('Shared · URL copied to clipboard', 'success')
         } catch {
           onMessage(`Shared · ${result.url}`, 'success')
         }
-      } else if ('newSessionId' in result && result.newSessionId) {
-        onMessage(`Forked → ${result.newSessionId.slice(0, 8)}`, 'success')
       } else {
         onMessage('Done', 'success')
       }
@@ -50,99 +75,45 @@ export function SessionMenu({
   if (!sessionId) return null
 
   return (
-    <div className="cli-agent-session-menu" style={{ position: 'relative' }}>
+    <div className="oc-kebab">
       <button
+        ref={triggerRef}
+        type="button"
         onClick={() => setOpen((o) => !o)}
         disabled={disabled || busy}
         title="Session actions"
-        style={{
-          background: 'transparent',
-          border: 'none',
-          color: 'inherit',
-          cursor: 'pointer',
-          padding: '2px 6px',
-          fontSize: 14,
-        }}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        className="oc-kebab__trigger"
       >
-        ⋮
+        ⋯
       </button>
       {open && (
-        <div
-          style={{
-            position: 'absolute',
-            right: 0,
-            top: '100%',
-            zIndex: 10,
-            background: 'var(--color-surface-1, #1e1e1e)',
-            border: '1px solid var(--color-border, rgba(255,255,255,0.15))',
-            borderRadius: 4,
-            padding: 4,
-            minWidth: 160,
-            display: 'flex',
-            flexDirection: 'column',
-            fontSize: 12,
-            boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
-          }}
-        >
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionShare(sessionId))}>
+        <div ref={menuRef} role="menu" className="oc-kebab__menu">
+          <button
+            role="menuitem"
+            className="oc-kebab__item"
+            onClick={() => wrap(() => window.api.cliAgentSessionShare(sessionId))}
+          >
             Share session
-          </MenuItem>
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionUnshare(sessionId))}>
-            Unshare
-          </MenuItem>
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionSummarize(sessionId))}>
+          </button>
+          <button
+            role="menuitem"
+            className="oc-kebab__item"
+            onClick={() => wrap(() => window.api.cliAgentSessionSummarize(sessionId))}
+          >
             Summarize
-          </MenuItem>
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionUnrevert(sessionId))}>
-            Unrevert
-          </MenuItem>
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionAbort(sessionId))}>
-            Abort
-          </MenuItem>
-          <MenuItem onClick={() => wrap(() => window.api.cliAgentSessionInit(sessionId))}>
-            Initialize AGENTS.md
-          </MenuItem>
-          <MenuItem
+          </button>
+          <div className="oc-kebab__sep" />
+          <button
+            role="menuitem"
+            className="oc-kebab__item oc-kebab__item--danger"
             onClick={() => wrap(() => window.api.cliAgentSessionDeleteRemote(sessionId))}
-            danger
           >
-            Delete remote session
-          </MenuItem>
+            Delete remote
+          </button>
         </div>
       )}
     </div>
   )
 }
-
-function MenuItem({
-  children,
-  onClick,
-  danger,
-}: {
-  children: React.ReactNode
-  onClick: () => void
-  danger?: boolean
-}) {
-  return (
-    <button
-      onClick={onClick}
-      style={{
-        display: 'block',
-        textAlign: 'left',
-        background: 'transparent',
-        border: 'none',
-        color: danger ? 'tomato' : 'inherit',
-        padding: '4px 8px',
-        cursor: 'pointer',
-        borderRadius: 3,
-        fontSize: 12,
-      }}
-      onMouseEnter={(e) =>
-        ((e.target as HTMLButtonElement).style.background = 'var(--color-surface-2, rgba(255,255,255,0.06))')
-      }
-      onMouseLeave={(e) => ((e.target as HTMLButtonElement).style.background = 'transparent')}
-    >
-      {children}
-    </button>
-  )
-}
diff --git a/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx b/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
deleted file mode 100644
index bc2df05..0000000
--- a/packages/renderer/src/components/cliAgent/SessionSettingsPanel.tsx
+++ /dev/null
@@ -1,338 +0,0 @@
-import { useEffect, useState } from 'react'
-import type {
-  CliAgentBackendState,
-  OpenCodeAgentSummary,
-  OpenCodeProviderSummary,
-  OpenCodeToolSummary,
-} from '@aide/shared'
-
-/**
- * Collapsible per-session settings panel for OpenCode sessions.
- * Wraps provider/model picker, agent picker, mode picker, system prompt
- * editor, and tool toggle list. Each sub-component lazily fetches its
- * options the first time the panel is opened.
- */
-export function SessionSettingsPanel({
-  sessionId,
-  backendState,
-  onPatch,
-}: {
-  sessionId: string | null
-  backendState: CliAgentBackendState
-  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
-}) {
-  const [open, setOpen] = useState(false)
-  if (!sessionId) return null
-
-  return (
-    <details
-      open={open}
-      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
-      className="cli-agent-session-settings"
-      style={{
-        margin: '6px 0',
-        padding: '6px 8px',
-        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
-        borderRadius: 4,
-        fontSize: 12,
-      }}
-    >
-      <summary style={{ cursor: 'pointer', userSelect: 'none', fontWeight: 500 }}>
-        Session settings
-      </summary>
-      {open && (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginTop: 8 }}>
-          <ProviderModelPicker sessionId={sessionId} state={backendState} onPatch={onPatch} />
-          <AgentModePicker sessionId={sessionId} state={backendState} onPatch={onPatch} />
-          <SystemPromptEditor state={backendState} onPatch={onPatch} />
-          <ToolToggleList sessionId={sessionId} state={backendState} onPatch={onPatch} />
-        </div>
-      )}
-    </details>
-  )
-}
-
-function ProviderModelPicker({
-  sessionId,
-  state,
-  onPatch,
-}: {
-  sessionId: string
-  state: CliAgentBackendState
-  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
-}) {
-  const [providers, setProviders] = useState<OpenCodeProviderSummary[]>([])
-  const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    let cancelled = false
-    setLoading(true)
-    void (async () => {
-      try {
-        const result = (await window.api.cliAgentListProviders(sessionId)) as
-          | OpenCodeProviderSummary[]
-          | { error: string }
-          | undefined
-        if (cancelled) return
-        if (Array.isArray(result)) setProviders(result)
-        else if (result && typeof result === 'object' && 'error' in result) {
-          setError(result.error ?? 'Failed to load providers')
-        }
-      } catch (e) {
-        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
-      } finally {
-        if (!cancelled) setLoading(false)
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [sessionId])
-
-  const provider = providers.find((p) => p.id === state.providerID)
-  return (
-    <div>
-      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Provider / Model</label>
-      <div style={{ display: 'flex', gap: 4 }}>
-        <select
-          value={state.providerID ?? ''}
-          onChange={(e) => void onPatch({ providerID: e.target.value || undefined, modelID: undefined })}
-          style={selectStyle}
-          disabled={loading}
-        >
-          <option value="">{loading ? 'Loading…' : '— provider —'}</option>
-          {providers.map((p) => (
-            <option key={p.id} value={p.id}>
-              {p.name}
-            </option>
-          ))}
-        </select>
-        <select
-          value={state.modelID ?? ''}
-          onChange={(e) => void onPatch({ modelID: e.target.value || undefined })}
-          style={selectStyle}
-          disabled={!provider}
-        >
-          <option value="">{provider ? '— model —' : ''}</option>
-          {provider?.models.map((m) => (
-            <option key={m.id} value={m.id}>
-              {m.name}
-            </option>
-          ))}
-        </select>
-      </div>
-      {error && <div style={{ color: 'tomato', fontSize: 10 }}>{error}</div>}
-    </div>
-  )
-}
-
-function AgentModePicker({
-  sessionId,
-  state,
-  onPatch,
-}: {
-  sessionId: string
-  state: CliAgentBackendState
-  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
-}) {
-  const [agents, setAgents] = useState<OpenCodeAgentSummary[]>([])
-  const [modes, setModes] = useState<string[]>([])
-
-  useEffect(() => {
-    let cancelled = false
-    void (async () => {
-      try {
-        const [a, m] = await Promise.all([
-          window.api.cliAgentListAgents(sessionId),
-          window.api.cliAgentListModes(sessionId),
-        ])
-        if (cancelled) return
-        if (Array.isArray(a)) setAgents(a as OpenCodeAgentSummary[])
-        if (Array.isArray(m)) setModes(m as string[])
-      } catch {
-        /* ignore */
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [sessionId])
-
-  return (
-    <div style={{ display: 'flex', gap: 8 }}>
-      <div style={{ flex: 1 }}>
-        <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Agent</label>
-        <select
-          value={state.agent ?? ''}
-          onChange={(e) => void onPatch({ agent: e.target.value || undefined })}
-          style={selectStyle}
-        >
-          <option value="">— default —</option>
-          {agents.map((a) => (
-            <option key={a.name} value={a.name}>
-              {a.name}
-              {a.description ? ` — ${a.description}` : ''}
-            </option>
-          ))}
-        </select>
-      </div>
-      <div style={{ flex: 1 }}>
-        <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Mode</label>
-        <select
-          value={state.mode ?? ''}
-          onChange={(e) => void onPatch({ mode: e.target.value || undefined })}
-          style={selectStyle}
-        >
-          <option value="">— default —</option>
-          {modes.map((m) => (
-            <option key={m} value={m}>
-              {m}
-            </option>
-          ))}
-        </select>
-      </div>
-    </div>
-  )
-}
-
-function SystemPromptEditor({
-  state,
-  onPatch,
-}: {
-  state: CliAgentBackendState
-  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
-}) {
-  const [value, setValue] = useState(state.systemPromptOverride ?? '')
-  useEffect(() => setValue(state.systemPromptOverride ?? ''), [state.systemPromptOverride])
-  return (
-    <div>
-      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>
-        System prompt override
-      </label>
-      <textarea
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        onBlur={() =>
-          void onPatch({ systemPromptOverride: value.trim() ? value : undefined })
-        }
-        rows={3}
-        placeholder="Leave blank to use the agent default"
-        style={{
-          width: '100%',
-          fontFamily: 'inherit',
-          fontSize: 11,
-          padding: 4,
-          borderRadius: 3,
-          background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
-          color: 'inherit',
-          border: '1px solid var(--color-border, rgba(255,255,255,0.1))',
-          resize: 'vertical',
-        }}
-      />
-    </div>
-  )
-}
-
-function ToolToggleList({
-  sessionId,
-  state,
-  onPatch,
-}: {
-  sessionId: string
-  state: CliAgentBackendState
-  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
-}) {
-  const [tools, setTools] = useState<OpenCodeToolSummary[]>([])
-  const [loaded, setLoaded] = useState(false)
-
-  useEffect(() => {
-    if (!state.providerID || !state.modelID) return
-    let cancelled = false
-    void (async () => {
-      try {
-        const result = await window.api.cliAgentListTools(
-          sessionId,
-          state.providerID!,
-          state.modelID!,
-        )
-        if (!cancelled && Array.isArray(result)) {
-          setTools(result as OpenCodeToolSummary[])
-          setLoaded(true)
-        }
-      } catch {
-        /* ignore */
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [sessionId, state.providerID, state.modelID])
-
-  if (!loaded || tools.length === 0) {
-    return (
-      <div style={{ opacity: 0.5, fontSize: 11 }}>
-        {state.providerID && state.modelID
-          ? 'Tools will appear once available…'
-          : 'Pick a provider/model to list tools'}
-      </div>
-    )
-  }
-
-  const toggles = state.toolToggles ?? {}
-  return (
-    <div>
-      <label style={{ display: 'block', opacity: 0.7, marginBottom: 2 }}>Tools</label>
-      <div
-        style={{
-          display: 'flex',
-          flexWrap: 'wrap',
-          gap: 4,
-          maxHeight: 120,
-          overflowY: 'auto',
-          padding: 4,
-          background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
-          borderRadius: 3,
-        }}
-      >
-        {tools.map((t) => {
-          const enabled = toggles[t.id] !== false
-          return (
-            <label
-              key={t.id}
-              title={t.description ?? t.id}
-              style={{
-                display: 'inline-flex',
-                alignItems: 'center',
-                gap: 4,
-                fontSize: 10,
-                padding: '1px 4px',
-              }}
-            >
-              <input
-                type="checkbox"
-                checked={enabled}
-                onChange={(e) =>
-                  void onPatch({
-                    toolToggles: { ...toggles, [t.id]: e.target.checked },
-                  })
-                }
-              />
-              {t.id}
-            </label>
-          )
-        })}
-      </div>
-    </div>
-  )
-}
-
-const selectStyle: React.CSSProperties = {
-  flex: 1,
-  fontSize: 11,
-  padding: '2px 4px',
-  background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
-  color: 'inherit',
-  border: '1px solid var(--color-border, rgba(255,255,255,0.1))',
-  borderRadius: 3,
-}
diff --git a/packages/renderer/src/components/cliAgent/SessionSettingsPopover.tsx b/packages/renderer/src/components/cliAgent/SessionSettingsPopover.tsx
new file mode 100644
index 0000000..3e7639b
--- /dev/null
+++ b/packages/renderer/src/components/cliAgent/SessionSettingsPopover.tsx
@@ -0,0 +1,422 @@
+import { useEffect, useRef, useState } from 'react'
+import type {
+  CliAgentBackendState,
+  OpenCodeAgentSummary,
+  OpenCodeProviderSummary,
+  OpenCodeToolSummary,
+} from '@aide/shared'
+
+/**
+ * Compact, gear-anchored popover holding all per-session OpenCode overrides.
+ *
+ * Replaces the old `SessionSettingsPanel` which stacked four full-width
+ * sections above the chat. The popover keeps the chat area uncluttered:
+ * settings live one click away, never visible until you ask.
+ *
+ * Aesthetic: refined terminal-minimal — hairline borders, monospace section
+ * labels, sharp 2px radii, transparent inputs that draw a focus underline
+ * rather than a fill. Tabs use a bottom-border accent.
+ */
+
+type Tab = 'model' | 'agent' | 'tools' | 'prompt'
+
+interface Props {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (patch: Partial<CliAgentBackendState>) => Promise<boolean>
+  /** Disables the trigger (e.g. while a turn is mid-flight). */
+  disabled?: boolean
+}
+
+export function SessionSettingsPopover({ sessionId, state, onPatch, disabled }: Props) {
+  const [open, setOpen] = useState(false)
+  const [tab, setTab] = useState<Tab>('model')
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+
+  // Dismiss on outside click + Escape.
+  useEffect(() => {
+    if (!open) return
+    const onMouseDown = (e: MouseEvent) => {
+      const target = e.target as Node
+      if (popoverRef.current?.contains(target)) return
+      if (triggerRef.current?.contains(target)) return
+      setOpen(false)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    window.addEventListener('mousedown', onMouseDown)
+    window.addEventListener('keydown', onKey)
+    return () => {
+      window.removeEventListener('mousedown', onMouseDown)
+      window.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  // Visual indicator: a small dot when the session has any non-empty override.
+  const hasOverrides =
+    !!(state.providerID || state.modelID || state.agent || state.mode || state.systemPromptOverride)
+
+  return (
+    <div className="oc-settings-pop">
+      <button
+        ref={triggerRef}
+        type="button"
+        className="oc-settings-pop__trigger"
+        onClick={() => setOpen((o) => !o)}
+        disabled={disabled}
+        title="Session settings"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+      >
+        {/* gear glyph drawn from box-drawing characters keeps the
+            terminal-minimal language consistent with the rest of the pane */}
+        <span className="oc-settings-pop__gear" aria-hidden>⌥</span>
+        {hasOverrides && <span className="oc-settings-pop__dot" aria-hidden />}
+      </button>
+
+      {open && (
+        <div
+          ref={popoverRef}
+          className="oc-settings-pop__panel"
+          role="dialog"
+          aria-label="OpenCode session settings"
+        >
+          <header className="oc-settings-pop__head">
+            <span className="oc-settings-pop__title">SESSION · OVERRIDES</span>
+            <span className="oc-settings-pop__sid" title={sessionId}>
+              {sessionId.slice(0, 8)}
+            </span>
+          </header>
+
+          <nav className="oc-settings-pop__tabs" role="tablist">
+            {(['model', 'agent', 'tools', 'prompt'] as const).map((t) => (
+              <button
+                key={t}
+                role="tab"
+                aria-selected={tab === t}
+                className={`oc-settings-pop__tab${tab === t ? ' is-active' : ''}`}
+                onClick={() => setTab(t)}
+              >
+                {t}
+              </button>
+            ))}
+          </nav>
+
+          <div className="oc-settings-pop__body">
+            {tab === 'model' && (
+              <ModelTab sessionId={sessionId} state={state} onPatch={onPatch} />
+            )}
+            {tab === 'agent' && (
+              <AgentTab sessionId={sessionId} state={state} onPatch={onPatch} />
+            )}
+            {tab === 'tools' && (
+              <ToolsTab sessionId={sessionId} state={state} onPatch={onPatch} />
+            )}
+            {tab === 'prompt' && <PromptTab state={state} onPatch={onPatch} />}
+          </div>
+
+          <footer className="oc-settings-pop__foot">
+            <span className="oc-settings-pop__hint">
+              defaults live in settings → agent → opencode
+            </span>
+          </footer>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ─── Tab: Model ────────────────────────────────────────────────────
+
+function ModelTab({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (p: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [providers, setProviders] = useState<OpenCodeProviderSummary[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    void (async () => {
+      try {
+        const r = (await window.api.cliAgentListProviders(sessionId)) as
+          | OpenCodeProviderSummary[]
+          | { error: string }
+          | undefined
+        if (cancelled) return
+        if (Array.isArray(r)) setProviders(r)
+        else if (r && typeof r === 'object' && 'error' in r) setError(r.error ?? null)
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId])
+
+  const provider = providers.find((p) => p.id === state.providerID)
+
+  return (
+    <div className="oc-tab">
+      <Field label="provider">
+        <select
+          className="oc-input"
+          value={state.providerID ?? ''}
+          disabled={loading}
+          onChange={(e) =>
+            void onPatch({ providerID: e.target.value || undefined, modelID: undefined })
+          }
+        >
+          <option value="">{loading ? 'loading…' : '—'}</option>
+          {providers.map((p) => (
+            <option key={p.id} value={p.id}>
+              {p.name}
+            </option>
+          ))}
+        </select>
+      </Field>
+      <Field label="model">
+        <select
+          className="oc-input"
+          value={state.modelID ?? ''}
+          disabled={!provider}
+          onChange={(e) => void onPatch({ modelID: e.target.value || undefined })}
+        >
+          <option value="">{provider ? '—' : ''}</option>
+          {provider?.models.map((m) => (
+            <option key={m.id} value={m.id}>
+              {m.name}
+            </option>
+          ))}
+        </select>
+      </Field>
+      {provider && state.modelID && (
+        <ModelMeta provider={provider} modelId={state.modelID} />
+      )}
+      {error && <div className="oc-error">{error}</div>}
+    </div>
+  )
+}
+
+function ModelMeta({
+  provider,
+  modelId,
+}: {
+  provider: OpenCodeProviderSummary
+  modelId: string
+}) {
+  const m = provider.models.find((x) => x.id === modelId)
+  if (!m) return null
+  const flags: string[] = []
+  if (m.reasoning) flags.push('reasoning')
+  if (m.toolCall) flags.push('tools')
+  if (m.attachment) flags.push('attach')
+  return (
+    <div className="oc-meta">
+      {flags.length > 0 && <span className="oc-meta__flags">{flags.join(' · ')}</span>}
+      {m.cost && (
+        <span className="oc-meta__cost">
+          ${m.cost.input.toFixed(2)} in / ${m.cost.output.toFixed(2)} out · per 1M
+        </span>
+      )}
+    </div>
+  )
+}
+
+// ─── Tab: Agent ────────────────────────────────────────────────────
+
+function AgentTab({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (p: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [agents, setAgents] = useState<OpenCodeAgentSummary[]>([])
+  const [modes, setModes] = useState<string[]>([])
+
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      try {
+        const [a, m] = await Promise.all([
+          window.api.cliAgentListAgents(sessionId),
+          window.api.cliAgentListModes(sessionId),
+        ])
+        if (cancelled) return
+        if (Array.isArray(a)) setAgents(a as OpenCodeAgentSummary[])
+        if (Array.isArray(m)) setModes(m as string[])
+      } catch {
+        /* ignore */
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId])
+
+  const selected = agents.find((a) => a.name === state.agent)
+
+  return (
+    <div className="oc-tab">
+      <Field label="agent">
+        <select
+          className="oc-input"
+          value={state.agent ?? ''}
+          onChange={(e) => void onPatch({ agent: e.target.value || undefined })}
+        >
+          <option value="">— default —</option>
+          {agents.map((a) => (
+            <option key={a.name} value={a.name}>
+              {a.name}
+            </option>
+          ))}
+        </select>
+      </Field>
+      {selected?.description && (
+        <p className="oc-desc">{selected.description}</p>
+      )}
+      <Field label="mode">
+        <select
+          className="oc-input"
+          value={state.mode ?? ''}
+          onChange={(e) => void onPatch({ mode: e.target.value || undefined })}
+        >
+          <option value="">— default —</option>
+          {modes.map((m) => (
+            <option key={m} value={m}>
+              {m}
+            </option>
+          ))}
+        </select>
+      </Field>
+    </div>
+  )
+}
+
+// ─── Tab: Tools ────────────────────────────────────────────────────
+
+function ToolsTab({
+  sessionId,
+  state,
+  onPatch,
+}: {
+  sessionId: string
+  state: CliAgentBackendState
+  onPatch: (p: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [tools, setTools] = useState<OpenCodeToolSummary[]>([])
+  const [loaded, setLoaded] = useState(false)
+
+  useEffect(() => {
+    if (!state.providerID || !state.modelID) return
+    let cancelled = false
+    void (async () => {
+      try {
+        const r = await window.api.cliAgentListTools(
+          sessionId,
+          state.providerID!,
+          state.modelID!,
+        )
+        if (!cancelled && Array.isArray(r)) {
+          setTools(r as OpenCodeToolSummary[])
+          setLoaded(true)
+        }
+      } catch {
+        /* ignore */
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId, state.providerID, state.modelID])
+
+  if (!state.providerID || !state.modelID) {
+    return <div className="oc-empty">pick a provider/model first</div>
+  }
+  if (!loaded) return <div className="oc-empty">loading tools…</div>
+  if (tools.length === 0) return <div className="oc-empty">no tools available</div>
+
+  const toggles = state.toolToggles ?? {}
+  return (
+    <div className="oc-tab">
+      <ul className="oc-tools">
+        {tools.map((t) => {
+          const enabled = toggles[t.id] !== false
+          return (
+            <li key={t.id} className="oc-tools__item">
+              <label className="oc-tools__row">
+                <input
+                  type="checkbox"
+                  checked={enabled}
+                  onChange={(e) =>
+                    void onPatch({
+                      toolToggles: { ...toggles, [t.id]: e.target.checked },
+                    })
+                  }
+                />
+                <span className="oc-tools__name">{t.id}</span>
+              </label>
+              {t.description && <span className="oc-tools__desc">{t.description}</span>}
+            </li>
+          )
+        })}
+      </ul>
+    </div>
+  )
+}
+
+// ─── Tab: System Prompt ────────────────────────────────────────────
+
+function PromptTab({
+  state,
+  onPatch,
+}: {
+  state: CliAgentBackendState
+  onPatch: (p: Partial<CliAgentBackendState>) => Promise<boolean>
+}) {
+  const [value, setValue] = useState(state.systemPromptOverride ?? '')
+  useEffect(() => setValue(state.systemPromptOverride ?? ''), [state.systemPromptOverride])
+  return (
+    <div className="oc-tab">
+      <Field label="system prompt override">
+        <textarea
+          className="oc-input oc-input--area"
+          rows={6}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onBlur={() =>
+            void onPatch({ systemPromptOverride: value.trim() ? value : undefined })
+          }
+          placeholder="leave blank to use the agent default"
+        />
+      </Field>
+      <p className="oc-hint">applied on top of the agent's own system prompt</p>
+    </div>
+  )
+}
+
+// ─── Primitives ────────────────────────────────────────────────────
+
+function Field({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <label className="oc-field">
+      <span className="oc-field__label">{label}</span>
+      {children}
+    </label>
+  )
+}
diff --git a/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx b/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
deleted file mode 100644
index eeae395..0000000
--- a/packages/renderer/src/components/cliAgent/TuiControlPanel.tsx
+++ /dev/null
@@ -1,92 +0,0 @@
-import { useState } from 'react'
-
-/**
- * TUI control panel for OpenCode sessions. Mostly diagnostic / power-user
- * — these are the same commands the OpenCode TUI exposes (open help,
- * show toast, execute command, etc.). Useful when running an external
- * opencode TUI alongside aIDE.
- */
-export function TuiControlPanel({ sessionId }: { sessionId: string | null }) {
-  const [open, setOpen] = useState(false)
-  const [appendText, setAppendText] = useState('')
-  const [execCmd, setExecCmd] = useState('')
-
-  if (!sessionId) return null
-
-  const call = async (fn: () => Promise<{ error?: string }>) => {
-    const result = await fn()
-    if (result.error) console.warn('TUI op failed', result.error)
-  }
-
-  return (
-    <details
-      open={open}
-      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
-      style={{
-        margin: '6px 0',
-        padding: '6px 8px',
-        background: 'var(--color-surface-2, rgba(255,255,255,0.04))',
-        borderRadius: 4,
-        fontSize: 11,
-      }}
-    >
-      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>TUI control</summary>
-      {open && (
-        <div style={{ marginTop: 6, display: 'flex', flexDirection: 'column', gap: 4 }}>
-          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
-            <button onClick={() => void call(() => window.api.cliAgentTuiOpenHelp(sessionId))}>
-              Help
-            </button>
-            <button onClick={() => void call(() => window.api.cliAgentTuiOpenSessions(sessionId))}>
-              Sessions
-            </button>
-            <button onClick={() => void call(() => window.api.cliAgentTuiOpenThemes(sessionId))}>
-              Themes
-            </button>
-            <button onClick={() => void call(() => window.api.cliAgentTuiOpenModels(sessionId))}>
-              Models
-            </button>
-            <button onClick={() => void call(() => window.api.cliAgentTuiSubmitPrompt(sessionId))}>
-              Submit
-            </button>
-            <button onClick={() => void call(() => window.api.cliAgentTuiClearPrompt(sessionId))}>
-              Clear
-            </button>
-          </div>
-          <div style={{ display: 'flex', gap: 4 }}>
-            <input
-              value={appendText}
-              onChange={(e) => setAppendText(e.target.value)}
-              placeholder="Text to append…"
-              style={{ flex: 1, fontSize: 11 }}
-            />
-            <button
-              onClick={() => {
-                void call(() => window.api.cliAgentTuiAppendPrompt(sessionId, appendText))
-                setAppendText('')
-              }}
-            >
-              Append
-            </button>
-          </div>
-          <div style={{ display: 'flex', gap: 4 }}>
-            <input
-              value={execCmd}
-              onChange={(e) => setExecCmd(e.target.value)}
-              placeholder="TUI command…"
-              style={{ flex: 1, fontSize: 11 }}
-            />
-            <button
-              onClick={() => {
-                void call(() => window.api.cliAgentTuiExecuteCommand(sessionId, execCmd))
-                setExecCmd('')
-              }}
-            >
-              Execute
-            </button>
-          </div>
-        </div>
-      )}
-    </details>
-  )
-}
diff --git a/packages/renderer/src/components/panes/CliAgentPane.tsx b/packages/renderer/src/components/panes/CliAgentPane.tsx
index 1aeb62a..ce09259 100644
--- a/packages/renderer/src/components/panes/CliAgentPane.tsx
+++ b/packages/renderer/src/components/panes/CliAgentPane.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef, useMemo, useState, useCallback } from 'react'
 import type { IDockviewPanelProps } from 'dockview-react'
-import type { AgentBackend, CliAgentBackendState, CliAgentMessage } from '@aide/shared'
+import type { AgentBackend, CliAgentMessage } from '@aide/shared'
 import { useCliAgent } from '../../hooks/useCliAgent'
 import { AgentStatusDot } from '../chat/AgentStatusDot'
 import { ChatInput } from '../chat/ChatInput'
@@ -9,10 +9,9 @@ import { CLI_BACKENDS, backendBadgeLabel, backendLabel } from '../../lib/agentBa
 import { CostTokenBadge } from '../cliAgent/CostTokenBadge'
 import { RichPartRenderer, isRichPartType } from '../cliAgent/RichPartRenderer'
 import { SessionMenu } from '../cliAgent/SessionMenu'
-import { SessionSettingsPanel } from '../cliAgent/SessionSettingsPanel'
-import { DiagnosticsPanel } from '../cliAgent/DiagnosticsPanel'
-import { TuiControlPanel } from '../cliAgent/TuiControlPanel'
+import { SessionSettingsPopover } from '../cliAgent/SessionSettingsPopover'
 import '../../styles/cli-agent-pane.css'
+import '../../styles/cli-agent-settings.css'
 
 interface CliAgentPanelParams {
   workspaceId?: string
@@ -122,11 +121,11 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
   )
 
   const isOpenCode = headerBackend === 'opencode'
-  // Mirror the live per-backend state from the hook so the pickers reflect any
-  // overrides the user has applied (and so dependent dropdowns like the model
-  // picker re-render when the provider changes).
-  const currentBackendState: CliAgentBackendState | null = isOpenCode
-    ? agent.backendState ?? { model: agent.model ?? undefined }
+  // Mirror the live per-backend state from the hook so the popover pickers
+  // reflect any overrides the user has applied (and so dependent dropdowns
+  // like the model picker re-render when the provider changes).
+  const currentBackendState = isOpenCode
+    ? (agent.backendState ?? { model: agent.model ?? undefined })
     : null
 
   return (
@@ -163,6 +162,14 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
           hideCost={headerBackend === 'claude-code'}
         />
         <div className="cli-agent-pane__header-spacer" />
+        {isOpenCode && agent.sessionId && currentBackendState && (
+          <SessionSettingsPopover
+            sessionId={agent.sessionId}
+            state={currentBackendState}
+            onPatch={agent.updateSessionConfig}
+            disabled={isActive}
+          />
+        )}
         {isOpenCode && (
           <SessionMenu
             sessionId={agent.sessionId}
@@ -184,19 +191,6 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
         )}
       </div>
 
-      {/* OpenCode-only collapsible panels */}
-      {isOpenCode && currentBackendState && (
-        <div style={{ padding: '4px 8px 0 8px' }}>
-          <SessionSettingsPanel
-            sessionId={agent.sessionId}
-            backendState={currentBackendState}
-            onPatch={agent.updateSessionConfig}
-          />
-          <DiagnosticsPanel workspaceId={workspaceId ?? null} sessionId={agent.sessionId} />
-          <TuiControlPanel sessionId={agent.sessionId} />
-        </div>
-      )}
-
       {toast && (
         <div
           style={{
diff --git a/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx b/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
index eb961f2..7b45155 100644
--- a/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
+++ b/packages/renderer/src/components/panes/OpenCodeToolsPane.tsx
@@ -4,10 +4,13 @@ import type {
   CliAgentSession,
   OpenCodeFileEntry,
   OpenCodeFindResult,
+  OpenCodePathInfo,
+  OpenCodeServerInfo,
   OpenCodeShellResult,
   OpenCodeSymbolResult,
 } from '@aide/shared'
 import { OpenCodeProvidersTab } from '../settings/OpenCodeProvidersTab'
+import '../../styles/cli-agent-settings.css'
 
 interface OpenCodeToolsPaneParams {
   workspaceId?: string
@@ -17,10 +20,13 @@ interface OpenCodeToolsPaneParams {
 
 type Tab = 'files' | 'search' | 'shell' | 'status' | 'providers'
 
+const TABS: Tab[] = ['files', 'search', 'shell', 'status', 'providers']
+
 /**
  * Dockview pane exposing OpenCode's file/find/shell/lsp endpoints as
- * opt-in commands. Only useful when an OpenCode session is active in the
- * workspace; otherwise shows an empty state.
+ * opt-in commands. The Status tab also hosts diagnostics + TUI controls
+ * + the Initialize AGENTS.md command, which used to live as cluttered
+ * disclosures inside the chat pane itself.
  */
 export function OpenCodeToolsPane({ params }: IDockviewPanelProps<OpenCodeToolsPaneParams>) {
   const { workspaceId, sessionId: paramSessionId } = params ?? {}
@@ -42,53 +48,44 @@ export function OpenCodeToolsPane({ params }: IDockviewPanelProps<OpenCodeToolsP
 
   if (!sessionId) {
     return (
-      <div style={{ padding: 12, fontSize: 12, opacity: 0.6 }}>
-        Open an OpenCode chat in this workspace to use OpenCode tools.
+      <div className="oc-tools-pane">
+        <div className="oc-tools-pane__empty">
+          open an opencode chat in this workspace to use opencode tools
+        </div>
       </div>
     )
   }
 
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', height: '100%', fontSize: 12 }}>
-      <div
-        style={{
-          display: 'flex',
-          gap: 4,
-          padding: 4,
-          borderBottom: '1px solid var(--color-border, rgba(255,255,255,0.1))',
-        }}
-      >
-        {(['files', 'search', 'shell', 'status', 'providers'] as const).map((t) => (
+    <div className="oc-tools-pane">
+      <nav className="oc-tools-pane__tabs" role="tablist">
+        {TABS.map((t) => (
           <button
             key={t}
+            role="tab"
+            aria-selected={tab === t}
             onClick={() => setTab(t)}
-            style={{
-              padding: '2px 8px',
-              background:
-                tab === t
-                  ? 'var(--color-accent-bg, rgba(120,180,255,0.2))'
-                  : 'transparent',
-              border: 'none',
-              color: 'inherit',
-              borderRadius: 3,
-              cursor: 'pointer',
-            }}
+            className={`oc-tools-pane__tab${tab === t ? ' is-active' : ''}`}
           >
             {t}
           </button>
         ))}
-      </div>
-      <div style={{ flex: 1, overflow: 'auto', padding: 8 }}>
+      </nav>
+      <div className="oc-tools-pane__body">
         {tab === 'files' && <FilesTab sessionId={sessionId} />}
         {tab === 'search' && <SearchTab sessionId={sessionId} />}
         {tab === 'shell' && <ShellTab sessionId={sessionId} />}
-        {tab === 'status' && <StatusTab sessionId={sessionId} />}
+        {tab === 'status' && (
+          <StatusTab sessionId={sessionId} workspaceId={workspaceId ?? null} />
+        )}
         {tab === 'providers' && <OpenCodeProvidersTab workspaceId={workspaceId ?? null} />}
       </div>
     </div>
   )
 }
 
+// ─── Files ─────────────────────────────────────────────────────────
+
 function FilesTab({ sessionId }: { sessionId: string }) {
   const [path, setPath] = useState('.')
   const [entries, setEntries] = useState<OpenCodeFileEntry[]>([])
@@ -104,21 +101,23 @@ function FilesTab({ sessionId }: { sessionId: string }) {
 
   useEffect(() => {
     void list('.')
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sessionId])
 
   return (
-    <div>
-      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
+    <div className="oc-status">
+      <div className="oc-status__inline">
         <input
           value={path}
           onChange={(e) => setPath(e.target.value)}
-          style={{ flex: 1, fontSize: 11 }}
           placeholder="path…"
         />
-        <button onClick={() => void list(path)}>List</button>
+        <button className="oc-status__btn" onClick={() => void list(path)}>
+          List
+        </button>
       </div>
-      {error && <div style={{ color: 'tomato' }}>{error}</div>}
-      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
+      {error && <div className="oc-error">{error}</div>}
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none', fontFamily: 'var(--font-mono)', fontSize: 10 }}>
         {entries.map((e) => (
           <li
             key={e.path}
@@ -133,30 +132,19 @@ function FilesTab({ sessionId }: { sessionId: string }) {
                 })()
               }
             }}
-            style={{ cursor: 'pointer', padding: '1px 0' }}
+            style={{ cursor: 'pointer', padding: '2px 0', color: e.isDirectory ? 'var(--accent)' : 'var(--text-primary)' }}
           >
-            {e.isDirectory ? '📁' : '📄'} {e.name}
+            {e.isDirectory ? '▸ ' : '  '}{e.name}
           </li>
         ))}
       </ul>
-      {content !== null && (
-        <pre
-          style={{
-            marginTop: 8,
-            padding: 6,
-            maxHeight: 200,
-            overflow: 'auto',
-            background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
-            fontSize: 10,
-          }}
-        >
-          {content}
-        </pre>
-      )}
+      {content !== null && <pre className="oc-status__pre">{content}</pre>}
     </div>
   )
 }
 
+// ─── Search ────────────────────────────────────────────────────────
+
 function SearchTab({ sessionId }: { sessionId: string }) {
   const [query, setQuery] = useState('')
   const [mode, setMode] = useState<'text' | 'files' | 'symbols'>('text')
@@ -180,12 +168,16 @@ function SearchTab({ sessionId }: { sessionId: string }) {
   }
 
   return (
-    <div>
-      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
-        <select value={mode} onChange={(e) => setMode(e.target.value as 'text')}>
-          <option value="text">Text</option>
-          <option value="files">Files</option>
-          <option value="symbols">Symbols</option>
+    <div className="oc-status">
+      <div className="oc-status__inline">
+        <select
+          value={mode}
+          onChange={(e) => setMode(e.target.value as 'text')}
+          style={{ padding: '3px 6px', background: 'transparent', color: 'var(--text-primary)', border: '1px solid var(--border-subtle)', borderRadius: 2, fontFamily: 'var(--font-mono)', fontSize: 10 }}
+        >
+          <option value="text">text</option>
+          <option value="files">files</option>
+          <option value="symbols">symbols</option>
         </select>
         <input
           value={query}
@@ -194,15 +186,16 @@ function SearchTab({ sessionId }: { sessionId: string }) {
             if (e.key === 'Enter') void run()
           }}
           placeholder="query…"
-          style={{ flex: 1, fontSize: 11 }}
         />
-        <button onClick={() => void run()}>Find</button>
+        <button className="oc-status__btn" onClick={() => void run()}>
+          Find
+        </button>
       </div>
-      {error && <div style={{ color: 'tomato' }}>{error}</div>}
-      <ul style={{ margin: 0, padding: 0, listStyle: 'none', fontSize: 11 }}>
+      {error && <div className="oc-error">{error}</div>}
+      <ul style={{ margin: 0, padding: 0, listStyle: 'none' }}>
         {results.map((r, i) => (
           <li key={i} style={{ padding: '2px 0' }}>
-            <pre style={{ margin: 0, fontSize: 10 }}>{JSON.stringify(r, null, 0)}</pre>
+            <pre className="oc-status__pre">{JSON.stringify(r, null, 0)}</pre>
           </li>
         ))}
       </ul>
@@ -210,6 +203,8 @@ function SearchTab({ sessionId }: { sessionId: string }) {
   )
 }
 
+// ─── Shell ─────────────────────────────────────────────────────────
+
 function ShellTab({ sessionId }: { sessionId: string }) {
   const [cmd, setCmd] = useState('')
   const [output, setOutput] = useState<OpenCodeShellResult | null>(null)
@@ -227,8 +222,8 @@ function ShellTab({ sessionId }: { sessionId: string }) {
   }
 
   return (
-    <div>
-      <div style={{ display: 'flex', gap: 4, marginBottom: 6 }}>
+    <div className="oc-status">
+      <div className="oc-status__inline">
         <input
           value={cmd}
           onChange={(e) => setCmd(e.target.value)}
@@ -236,24 +231,14 @@ function ShellTab({ sessionId }: { sessionId: string }) {
             if (e.key === 'Enter') void run()
           }}
           placeholder="shell command…"
-          style={{ flex: 1, fontSize: 11, fontFamily: 'monospace' }}
         />
-        <button onClick={() => void run()} disabled={busy}>
+        <button className="oc-status__btn" disabled={busy} onClick={() => void run()}>
           Run
         </button>
       </div>
-      {error && <div style={{ color: 'tomato' }}>{error}</div>}
+      {error && <div className="oc-error">{error}</div>}
       {output && (
-        <pre
-          style={{
-            margin: 0,
-            padding: 6,
-            background: 'var(--color-surface-1, rgba(0,0,0,0.2))',
-            fontSize: 10,
-            maxHeight: 240,
-            overflow: 'auto',
-          }}
-        >
+        <pre className="oc-status__pre" style={{ maxHeight: 240 }}>
           [exit {output.exitCode}]{'\n'}
           {output.stdout}
           {output.stderr ? `\n--- stderr ---\n${output.stderr}` : ''}
@@ -263,29 +248,238 @@ function ShellTab({ sessionId }: { sessionId: string }) {
   )
 }
 
-function StatusTab({ sessionId }: { sessionId: string }) {
+// ─── Status (formerly the cluttered DiagnosticsPanel + TuiControlPanel) ───
+
+function StatusTab({
+  sessionId,
+  workspaceId,
+}: {
+  sessionId: string
+  workspaceId: string | null
+}) {
+  const [server, setServer] = useState<OpenCodeServerInfo | null>(null)
+  const [paths, setPaths] = useState<OpenCodePathInfo | null>(null)
   const [lsp, setLsp] = useState<unknown>(null)
   const [formatter, setFormatter] = useState<unknown>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [toast, setToast] = useState<string | null>(null)
 
   useEffect(() => {
+    let cancelled = false
     void (async () => {
-      const l = await window.api.cliAgentLspStatus(sessionId)
-      setLsp(l.status)
-      const f = await window.api.cliAgentFormatterStatus(sessionId)
-      setFormatter(f.status)
+      try {
+        if (workspaceId) {
+          const s = (await window.api.cliAgentServerInfo(workspaceId)) as OpenCodeServerInfo | null
+          if (!cancelled) setServer(s)
+        }
+        const p = await window.api.cliAgentPathGet(sessionId)
+        if (!cancelled && !p.error) setPaths((p.paths as OpenCodePathInfo) ?? null)
+        const l = await window.api.cliAgentLspStatus(sessionId)
+        if (!cancelled) setLsp(l.status)
+        const f = await window.api.cliAgentFormatterStatus(sessionId)
+        if (!cancelled) setFormatter(f.status)
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
+      }
     })()
-  }, [sessionId])
+    return () => {
+      cancelled = true
+    }
+  }, [sessionId, workspaceId])
+
+  const flash = (text: string) => {
+    setToast(text)
+    window.setTimeout(() => setToast(null), 2400)
+  }
+
+  const onInitAgents = async () => {
+    const result = await window.api.cliAgentSessionInit(sessionId)
+    if (result.error) flash(`error: ${result.error}`)
+    else flash('AGENTS.md initialization started')
+  }
 
   return (
-    <div>
-      <h4 style={{ margin: '4px 0' }}>LSP</h4>
-      <pre style={{ fontSize: 10, maxHeight: 120, overflow: 'auto' }}>
-        {JSON.stringify(lsp, null, 2)}
-      </pre>
-      <h4 style={{ margin: '4px 0' }}>Formatter</h4>
-      <pre style={{ fontSize: 10, maxHeight: 120, overflow: 'auto' }}>
-        {JSON.stringify(formatter, null, 2)}
-      </pre>
+    <div className="oc-status">
+      {error && <div className="oc-error">{error}</div>}
+      {toast && (
+        <div
+          style={{
+            padding: '4px 8px',
+            background: 'color-mix(in srgb, var(--accent) 12%, transparent)',
+            border: '1px solid var(--accent)',
+            borderRadius: 2,
+            fontFamily: 'var(--font-mono)',
+            fontSize: 9,
+            color: 'var(--text-primary)',
+            letterSpacing: '0.04em',
+          }}
+        >
+          {toast}
+        </div>
+      )}
+
+      {/* SERVER */}
+      <section className="oc-status__section">
+        <h3 className="oc-status__heading">Server</h3>
+        {server ? (
+          <dl className="oc-status__row">
+            <dt>url</dt>
+            <dd>{server.url}</dd>
+            <dt>mode</dt>
+            <dd>{server.mode}</dd>
+            <dt>pid</dt>
+            <dd>{server.pid ?? '—'}</dd>
+            <dt>started</dt>
+            <dd>{new Date(server.startedAt).toLocaleTimeString()}</dd>
+          </dl>
+        ) : (
+          <div className="oc-empty">no server info</div>
+        )}
+      </section>
+
+      {/* PATHS */}
+      {paths && (
+        <section className="oc-status__section">
+          <h3 className="oc-status__heading">Paths</h3>
+          <dl className="oc-status__row">
+            {paths.config && (
+              <>
+                <dt>config</dt>
+                <dd>{paths.config}</dd>
+              </>
+            )}
+            {paths.data && (
+              <>
+                <dt>data</dt>
+                <dd>{paths.data}</dd>
+              </>
+            )}
+            {paths.cache && (
+              <>
+                <dt>cache</dt>
+                <dd>{paths.cache}</dd>
+              </>
+            )}
+            {paths.log && (
+              <>
+                <dt>log</dt>
+                <dd>{paths.log}</dd>
+              </>
+            )}
+          </dl>
+        </section>
+      )}
+
+      {/* LSP / FORMATTER */}
+      <section className="oc-status__section">
+        <h3 className="oc-status__heading">LSP</h3>
+        <pre className="oc-status__pre">{JSON.stringify(lsp, null, 2)}</pre>
+      </section>
+      <section className="oc-status__section">
+        <h3 className="oc-status__heading">Formatter</h3>
+        <pre className="oc-status__pre">{JSON.stringify(formatter, null, 2)}</pre>
+      </section>
+
+      {/* COMMANDS — pulled in from the old SessionMenu */}
+      <section className="oc-status__section">
+        <h3 className="oc-status__heading">Commands</h3>
+        <button className="oc-status__btn" onClick={() => void onInitAgents()}>
+          Initialize AGENTS.md
+        </button>
+        <button
+          className="oc-status__btn"
+          onClick={() =>
+            void window.api
+              .cliAgentLogWrite(sessionId, 'log from aIDE diagnostics', 'INFO')
+              .then(() => flash('log line written'))
+          }
+        >
+          Write test log
+        </button>
+      </section>
+
+      {/* ADVANCED — opt-in TUI controls (mostly useful for power users
+          driving an external opencode TUI alongside aIDE) */}
+      <details className="oc-status__advanced">
+        <summary>Advanced · TUI controls</summary>
+        <div className="oc-status__advanced-body">
+          <TuiButtons sessionId={sessionId} flash={flash} />
+        </div>
+      </details>
     </div>
   )
 }
+
+function TuiButtons({
+  sessionId,
+  flash,
+}: {
+  sessionId: string
+  flash: (text: string) => void
+}) {
+  const [appendText, setAppendText] = useState('')
+  const [execCmd, setExecCmd] = useState('')
+
+  const call = async (label: string, fn: () => Promise<{ error?: string }>) => {
+    const r = await fn()
+    if (r.error) flash(`${label}: ${r.error}`)
+    else flash(`${label} ok`)
+  }
+
+  return (
+    <>
+      <div className="oc-status__btnrow">
+        <button className="oc-status__btn" onClick={() => void call('help', () => window.api.cliAgentTuiOpenHelp(sessionId))}>
+          Help
+        </button>
+        <button className="oc-status__btn" onClick={() => void call('sessions', () => window.api.cliAgentTuiOpenSessions(sessionId))}>
+          Sessions
+        </button>
+        <button className="oc-status__btn" onClick={() => void call('themes', () => window.api.cliAgentTuiOpenThemes(sessionId))}>
+          Themes
+        </button>
+        <button className="oc-status__btn" onClick={() => void call('models', () => window.api.cliAgentTuiOpenModels(sessionId))}>
+          Models
+        </button>
+        <button className="oc-status__btn" onClick={() => void call('submit', () => window.api.cliAgentTuiSubmitPrompt(sessionId))}>
+          Submit
+        </button>
+        <button className="oc-status__btn" onClick={() => void call('clear', () => window.api.cliAgentTuiClearPrompt(sessionId))}>
+          Clear
+        </button>
+      </div>
+      <div className="oc-status__inline">
+        <input
+          value={appendText}
+          onChange={(e) => setAppendText(e.target.value)}
+          placeholder="text to append…"
+        />
+        <button
+          className="oc-status__btn"
+          onClick={() => {
+            void call('append', () => window.api.cliAgentTuiAppendPrompt(sessionId, appendText))
+            setAppendText('')
+          }}
+        >
+          Append
+        </button>
+      </div>
+      <div className="oc-status__inline">
+        <input
+          value={execCmd}
+          onChange={(e) => setExecCmd(e.target.value)}
+          placeholder="tui command…"
+        />
+        <button
+          className="oc-status__btn"
+          onClick={() => {
+            void call('execute', () => window.api.cliAgentTuiExecuteCommand(sessionId, execCmd))
+            setExecCmd('')
+          }}
+        >
+          Execute
+        </button>
+      </div>
+    </>
+  )
+}
diff --git a/packages/renderer/src/lib/settingsSchema.ts b/packages/renderer/src/lib/settingsSchema.ts
index 4a46178..40bb367 100644
--- a/packages/renderer/src/lib/settingsSchema.ts
+++ b/packages/renderer/src/lib/settingsSchema.ts
@@ -57,6 +57,7 @@ export const SETTINGS_CATEGORIES: SettingsCategory[] = [
       { id: 'agent.backend', label: 'Backend' },
       { id: 'agent.llm', label: 'LLM Configuration' },
       { id: 'agent.permissions', label: 'Permissions' },
+      { id: 'agent.opencode', label: 'OpenCode Defaults' },
     ],
   },
   { id: 'extensions', label: 'Extensions' },
@@ -237,6 +238,51 @@ export const SETTINGS_DESCRIPTORS: SettingDescriptor[] = [
     category: 'agent.permissions',
     scope: 'user',
   },
+
+  // Agent > OpenCode Defaults
+  // Seed values applied to new OpenCode sessions. Per-session overrides
+  // (set from the chat pane's gear menu) take precedence and never modify
+  // these. Leave any of them blank to let OpenCode pick its own default.
+  {
+    key: 'agent.opencode.defaultProvider',
+    label: 'Default Provider',
+    description: "OpenCode provider id used when starting a new chat (e.g. 'anthropic', 'openai', 'openrouter'). Leave blank to use OpenCode's own default.",
+    type: 'string',
+    category: 'agent.opencode',
+    scope: 'user',
+  },
+  {
+    key: 'agent.opencode.defaultModel',
+    label: 'Default Model',
+    description: "Model id paired with the default provider (e.g. 'claude-sonnet-4-5'). Both provider and model must be set together.",
+    type: 'string',
+    category: 'agent.opencode',
+    scope: 'user',
+  },
+  {
+    key: 'agent.opencode.defaultAgent',
+    label: 'Default Agent',
+    description: "OpenCode agent name applied to new chats (e.g. 'build', 'plan'). Leave blank for the workspace agent.",
+    type: 'string',
+    category: 'agent.opencode',
+    scope: 'user',
+  },
+  {
+    key: 'agent.opencode.defaultMode',
+    label: 'Default Mode',
+    description: "OpenCode mode used to scope agent execution (e.g. 'primary', 'subagent', 'all'). Leave blank for the agent's mode.",
+    type: 'string',
+    category: 'agent.opencode',
+    scope: 'user',
+  },
+  {
+    key: 'agent.opencode.defaultSystemPrompt',
+    label: 'Default System Prompt',
+    description: 'A system prompt applied on top of the chosen agent. Leave blank to use the agent default. Per-chat overrides are still possible from the chat pane.',
+    type: 'string',
+    category: 'agent.opencode',
+    scope: 'user',
+  },
 ]
 
 /** Get all descriptors that belong to a given category */
diff --git a/packages/renderer/src/styles/cli-agent-settings.css b/packages/renderer/src/styles/cli-agent-settings.css
new file mode 100644
index 0000000..79faa7f
--- /dev/null
+++ b/packages/renderer/src/styles/cli-agent-settings.css
@@ -0,0 +1,660 @@
+/* ============================================================
+ * cli-agent-settings.css
+ *
+ * Refined terminal-minimal styling for the OpenCode session
+ * settings popover, the trimmed CliAgentPane header chrome,
+ * and the OpenCodeToolsPane status sub-sections.
+ *
+ * Design language:
+ *   - hairline 1px borders, no shadows
+ *   - 2px corner radii everywhere (sharp, never rounded)
+ *   - all-caps mono labels with 0.08em tracking
+ *   - transparent inputs with focus underlines instead of fills
+ *   - high information density without crowding
+ * ============================================================ */
+
+/* ─── Popover trigger (gear button in pane header) ─────────────── */
+
+.oc-settings-pop {
+  position: relative;
+  display: inline-block;
+}
+
+.oc-settings-pop__trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  background: transparent;
+  color: var(--text-secondary);
+  border: 1px solid transparent;
+  border-radius: 2px;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 13px;
+  line-height: 1;
+  transition: color var(--motion-fast), border-color var(--motion-fast),
+    background var(--motion-fast);
+}
+
+.oc-settings-pop__trigger:hover:not(:disabled) {
+  color: var(--text-primary);
+  border-color: var(--border-subtle);
+  background: var(--bg-hover);
+}
+
+.oc-settings-pop__trigger:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.oc-settings-pop__trigger[aria-expanded='true'] {
+  color: var(--accent);
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 8%, transparent);
+}
+
+.oc-settings-pop__gear {
+  display: inline-block;
+  transform: translateY(-1px);
+}
+
+/* small dot indicating per-session overrides exist */
+.oc-settings-pop__dot {
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  width: 4px;
+  height: 4px;
+  border-radius: 50%;
+  background: var(--accent);
+}
+
+/* ─── Popover panel ───────────────────────────────────────────── */
+
+.oc-settings-pop__panel {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 60;
+  width: 320px;
+  background: var(--bg-overlay);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  font-family: var(--font-ui);
+  color: var(--text-primary);
+  /* Subtle dot grid backdrop — adds the terminal feel without noise. */
+  background-image: radial-gradient(
+    circle,
+    color-mix(in srgb, var(--text-muted) 10%, transparent) 0.5px,
+    transparent 0.5px
+  );
+  background-size: 12px 12px;
+  /* A single hairline highlight rather than a drop shadow. */
+  box-shadow:
+    0 1px 0 rgba(0, 0, 0, 0.4),
+    0 0 0 1px var(--border-base);
+  animation: oc-pop-in 100ms ease-out;
+}
+
+@keyframes oc-pop-in {
+  from {
+    opacity: 0;
+    transform: translateY(-2px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Header strip */
+.oc-settings-pop__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 12px 6px;
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+.oc-settings-pop__title {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.oc-settings-pop__sid {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-muted);
+  opacity: 0.7;
+}
+
+/* Tab strip */
+.oc-settings-pop__tabs {
+  display: flex;
+  padding: 0 8px;
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+.oc-settings-pop__tab {
+  flex: 1;
+  padding: 6px 4px;
+  background: transparent;
+  color: var(--text-muted);
+  border: none;
+  border-bottom: 1px solid transparent;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  transition: color var(--motion-fast), border-color var(--motion-fast);
+  margin-bottom: -1px;
+}
+
+.oc-settings-pop__tab:hover {
+  color: var(--text-secondary);
+}
+
+.oc-settings-pop__tab.is-active {
+  color: var(--text-primary);
+  border-bottom-color: var(--accent);
+}
+
+/* Body */
+.oc-settings-pop__body {
+  padding: 12px;
+  min-height: 100px;
+  max-height: 360px;
+  overflow-y: auto;
+}
+
+/* Footer */
+.oc-settings-pop__foot {
+  padding: 6px 12px;
+  border-top: 1px solid var(--border-subtle);
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-muted);
+  letter-spacing: 0.04em;
+}
+
+.oc-settings-pop__hint {
+  display: block;
+  text-align: center;
+}
+
+/* ─── Tab content primitives ──────────────────────────────────── */
+
+.oc-tab {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.oc-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.oc-field__label {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.oc-input {
+  width: 100%;
+  padding: 4px 6px;
+  background: transparent;
+  color: var(--text-primary);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  outline: none;
+  transition: border-color var(--motion-fast), background var(--motion-fast);
+}
+
+.oc-input:hover:not(:disabled) {
+  border-color: var(--border-base);
+}
+
+.oc-input:focus {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 4%, transparent);
+}
+
+.oc-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.oc-input--area {
+  font-family: var(--font-mono);
+  resize: vertical;
+  min-height: 96px;
+  line-height: 1.5;
+}
+
+select.oc-input {
+  /* Native arrow looks fine and matches the rest of the IDE chrome. */
+  appearance: auto;
+  cursor: pointer;
+}
+
+.oc-meta {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 6px 8px;
+  background: color-mix(in srgb, var(--text-muted) 6%, transparent);
+  border-left: 1px solid var(--accent);
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-secondary);
+}
+
+.oc-meta__flags {
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-primary);
+}
+
+.oc-meta__cost {
+  color: var(--text-muted);
+}
+
+.oc-desc {
+  margin: 0;
+  padding: 4px 6px;
+  font-size: 10px;
+  color: var(--text-muted);
+  border-left: 1px solid var(--border-subtle);
+  font-style: italic;
+}
+
+.oc-hint {
+  margin: 0;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-muted);
+  letter-spacing: 0.04em;
+}
+
+.oc-error {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-error);
+  padding: 4px 6px;
+  border-left: 1px solid var(--text-error);
+  background: color-mix(in srgb, var(--text-error) 6%, transparent);
+}
+
+.oc-empty {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--text-muted);
+  padding: 16px 8px;
+  text-align: center;
+  letter-spacing: 0.02em;
+}
+
+/* ─── Tools list ──────────────────────────────────────────────── */
+
+.oc-tools {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.oc-tools__item {
+  padding: 4px 0;
+  border-bottom: 1px dashed var(--border-subtle);
+}
+
+.oc-tools__item:last-child {
+  border-bottom: none;
+}
+
+.oc-tools__row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+}
+
+.oc-tools__row input[type='checkbox'] {
+  accent-color: var(--accent);
+  margin: 0;
+}
+
+.oc-tools__name {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--text-primary);
+}
+
+.oc-tools__desc {
+  display: block;
+  margin-left: 18px;
+  margin-top: 2px;
+  font-size: 9px;
+  color: var(--text-muted);
+  line-height: 1.4;
+}
+
+/* ─── Trimmed kebab menu (re-styled to match popover) ─────────── */
+
+.oc-kebab {
+  position: relative;
+  display: inline-block;
+}
+
+.oc-kebab__trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  background: transparent;
+  color: var(--text-secondary);
+  border: 1px solid transparent;
+  border-radius: 2px;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 14px;
+  line-height: 1;
+  transition: color var(--motion-fast), border-color var(--motion-fast),
+    background var(--motion-fast);
+}
+
+.oc-kebab__trigger:hover:not(:disabled) {
+  color: var(--text-primary);
+  border-color: var(--border-subtle);
+  background: var(--bg-hover);
+}
+
+.oc-kebab__trigger:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.oc-kebab__menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 60;
+  min-width: 160px;
+  background: var(--bg-overlay);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  padding: 4px 0;
+  font-family: var(--font-ui);
+  font-size: 11px;
+  box-shadow:
+    0 1px 0 rgba(0, 0, 0, 0.4),
+    0 0 0 1px var(--border-base);
+  animation: oc-pop-in 100ms ease-out;
+}
+
+.oc-kebab__sep {
+  height: 1px;
+  margin: 4px 0;
+  background: var(--border-subtle);
+}
+
+.oc-kebab__item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 5px 12px;
+  background: transparent;
+  color: var(--text-primary);
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.02em;
+  transition: background var(--motion-fast), color var(--motion-fast);
+}
+
+.oc-kebab__item:hover:not(:disabled) {
+  background: var(--bg-hover);
+  color: var(--text-selected);
+}
+
+.oc-kebab__item:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.oc-kebab__item--danger {
+  color: var(--text-error);
+}
+
+.oc-kebab__item--danger:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--text-error) 10%, transparent);
+}
+
+/* ─── OpenCodeToolsPane refinements (Status tab) ──────────────── */
+
+.oc-tools-pane {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  font-family: var(--font-ui);
+  font-size: 11px;
+  background: var(--bg-base);
+  color: var(--text-primary);
+}
+
+.oc-tools-pane__tabs {
+  display: flex;
+  border-bottom: 1px solid var(--border-base);
+  background: var(--bg-elevated);
+  padding: 0 4px;
+}
+
+.oc-tools-pane__tab {
+  padding: 6px 10px;
+  background: transparent;
+  color: var(--text-muted);
+  border: none;
+  border-bottom: 1px solid transparent;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  margin-bottom: -1px;
+  transition: color var(--motion-fast), border-color var(--motion-fast);
+}
+
+.oc-tools-pane__tab:hover {
+  color: var(--text-secondary);
+}
+
+.oc-tools-pane__tab.is-active {
+  color: var(--text-primary);
+  border-bottom-color: var(--accent);
+}
+
+.oc-tools-pane__body {
+  flex: 1;
+  overflow: auto;
+  padding: 12px;
+}
+
+.oc-tools-pane__empty {
+  padding: 24px 16px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--text-muted);
+  text-align: center;
+  letter-spacing: 0.02em;
+}
+
+/* Status tab specifically */
+
+.oc-status {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.oc-status__section {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.oc-status__heading {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.oc-status__heading::after {
+  content: '';
+  flex: 1;
+  border-top: 1px solid var(--border-subtle);
+}
+
+.oc-status__row {
+  display: grid;
+  grid-template-columns: 80px 1fr;
+  gap: 8px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  line-height: 1.4;
+}
+
+.oc-status__row dt {
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  font-size: 9px;
+}
+
+.oc-status__row dd {
+  margin: 0;
+  color: var(--text-primary);
+  word-break: break-all;
+}
+
+.oc-status__pre {
+  margin: 0;
+  padding: 6px 8px;
+  background: var(--bg-sunken);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  color: var(--text-secondary);
+  max-height: 140px;
+  overflow: auto;
+  white-space: pre-wrap;
+}
+
+.oc-status__btn {
+  align-self: flex-start;
+  padding: 4px 10px;
+  background: transparent;
+  color: var(--text-secondary);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  transition: all var(--motion-fast);
+}
+
+.oc-status__btn:hover {
+  color: var(--text-primary);
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 6%, transparent);
+}
+
+.oc-status__advanced {
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  background: color-mix(in srgb, var(--text-muted) 4%, transparent);
+}
+
+.oc-status__advanced summary {
+  padding: 6px 10px;
+  cursor: pointer;
+  user-select: none;
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  outline: none;
+}
+
+.oc-status__advanced summary:hover {
+  color: var(--text-secondary);
+}
+
+.oc-status__advanced[open] summary {
+  color: var(--text-primary);
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+.oc-status__advanced-body {
+  padding: 8px 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.oc-status__btnrow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.oc-status__inline {
+  display: flex;
+  gap: 4px;
+}
+
+.oc-status__inline input {
+  flex: 1;
+  padding: 3px 6px;
+  background: transparent;
+  color: var(--text-primary);
+  border: 1px solid var(--border-subtle);
+  border-radius: 2px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  outline: none;
+}
+
+.oc-status__inline input:focus {
+  border-color: var(--accent);
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 14b70b3..6f66037 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -523,6 +523,16 @@ export interface AideProjectSettings {
   'agent.claudeCodePath'?: string
   'agent.opencodePath'?: string
   'agent.codexPath'?: string
+
+  // OpenCode-specific defaults (seed values for new opencode sessions).
+  // Per-session overrides happen via the chat pane gear menu and never
+  // mutate these defaults.
+  'agent.opencode.defaultProvider'?: string
+  'agent.opencode.defaultModel'?: string
+  'agent.opencode.defaultAgent'?: string
+  'agent.opencode.defaultMode'?: string
+  'agent.opencode.defaultSystemPrompt'?: string
+  'agent.opencode.defaultToolToggles'?: Record<string, boolean>
 }
 
 // Fully resolved settings (no optional fields)
@@ -554,6 +564,14 @@ export interface ResolvedSettings {
   'agent.claudeCodePath': string
   'agent.opencodePath': string
   'agent.codexPath': string
+
+  // OpenCode-specific defaults
+  'agent.opencode.defaultProvider': string
+  'agent.opencode.defaultModel': string
+  'agent.opencode.defaultAgent': string
+  'agent.opencode.defaultMode': string
+  'agent.opencode.defaultSystemPrompt': string
+  'agent.opencode.defaultToolToggles': Record<string, boolean>
 }
 
 /**
@@ -571,6 +589,14 @@ export const SENSITIVE_AGENT_KEYS: ReadonlySet<string> = new Set([
   'agent.codexPath',
   'agent.permissionTier',
   'agent.autoApprove',
+  // OpenCode defaults are user preferences (model choice, system prompt) that
+  // shouldn't be silently overridden by a checked-in workspace settings file.
+  'agent.opencode.defaultProvider',
+  'agent.opencode.defaultModel',
+  'agent.opencode.defaultAgent',
+  'agent.opencode.defaultMode',
+  'agent.opencode.defaultSystemPrompt',
+  'agent.opencode.defaultToolToggles',
 ])
 
 // .aide/local/workspace.json

From c46fb4b1cc1b17a1f27b4e499a9ccaa0e9ee5668 Mon Sep 17 00:00:00 2001
From: BT Odoy <cheezeiii365@gmail.com>
Date: Wed, 8 Apr 2026 19:59:44 -0400
Subject: [PATCH 9/9] feat: shared chat composer context with @file mentions
 and slash commands

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/IDE_BUILD_PLAN.md                        |   2 +-
 packages/main/src/chat/agentManager.ts        |  92 ++++---
 packages/main/src/chat/chatComposerContext.ts |  72 +++++
 packages/main/src/chat/cliAgentManager.ts     |  71 ++---
 packages/main/src/index.ts                    |  46 ++--
 packages/main/src/preload.ts                  |   8 +-
 .../src/components/chat/ChatInput.tsx         | 259 +++++++++++++++---
 .../components/cliAgent/RichPartRenderer.tsx  |  25 +-
 .../src/components/panes/ChatPane.tsx         |   6 +-
 .../src/components/panes/CliAgentPane.tsx     |  97 +++++--
 packages/renderer/src/hooks/useChat.ts        | 250 +++++++++--------
 packages/renderer/src/hooks/useCliAgent.ts    | 233 +++++++++-------
 packages/renderer/src/lib/chatComposer.ts     | 126 +++++++++
 packages/renderer/src/styles/chat-pane.css    | 120 +++++++-
 .../renderer/src/styles/cli-agent-pane.css    |  89 +++++-
 packages/shared/src/agentTypes.ts             |  11 +
 packages/shared/src/cliAgentTypes.ts          |   4 +
 packages/shared/src/index.ts                  |  42 ++-
 tests/unit/agentManager.test.ts               |  56 +++-
 tests/unit/chatComposer.test.ts               |  48 ++++
 tests/unit/chatComposerContext.test.ts        |  54 ++++
 tests/unit/cliAgentManager.test.ts            |   6 +-
 22 files changed, 1277 insertions(+), 440 deletions(-)
 create mode 100644 packages/main/src/chat/chatComposerContext.ts
 create mode 100644 packages/renderer/src/lib/chatComposer.ts
 create mode 100644 tests/unit/chatComposer.test.ts
 create mode 100644 tests/unit/chatComposerContext.test.ts

diff --git a/docs/IDE_BUILD_PLAN.md b/docs/IDE_BUILD_PLAN.md
index 82037d3..9a69aa0 100644
--- a/docs/IDE_BUILD_PLAN.md
+++ b/docs/IDE_BUILD_PLAN.md
@@ -98,7 +98,7 @@ A desktop IDE built specifically for the workflow of running multiple AI coding
 
 ### Nice-to-have (v2+)
 
-- [x] Agent chat panel UI — Dockview `chatPane` with Ask/Edit/Agent modes, streaming message display, tool call approval cards, working set picker, markdown rendering with syntax highlighting
+- [x] Agent chat panel UI — Dockview `chatPane` with Ask/Edit/Agent modes, streaming message display, tool call approval cards, working set picker, markdown rendering with syntax highlighting, shared `@file` context mentions, and slash-command autocomplete
 - [ ] Cursor-style agent panel UI (structured diffs, progress, pause/resume)
 - [x] Claude Agent SDK integration (replacing raw Claude Code CLI subprocess spawning with `@anthropic-ai/claude-agent-sdk` `query()` async generator)
 - [ ] Tailwind CSS IntelliSense (via tailwindcss-language-server)
diff --git a/packages/main/src/chat/agentManager.ts b/packages/main/src/chat/agentManager.ts
index 7d0b0c8..1fa8d75 100644
--- a/packages/main/src/chat/agentManager.ts
+++ b/packages/main/src/chat/agentManager.ts
@@ -14,6 +14,7 @@ import type { WebContents } from 'electron'
 import {
   IpcChannels,
   deriveTitle,
+  type ChatComposerSubmission,
   type ChatSession,
   type ChatMessage,
   type ChatMode,
@@ -37,6 +38,7 @@ import type { ConversationStore } from './conversationStore'
 import type { TaskVariableContext } from '../tasks/taskVariableResolver'
 import { shouldAutoApprove as evalShouldAutoApprove } from './permissionMatching'
 import type { ToolApprovalOwner } from './approvalRouter'
+import { buildComposerContext } from './chatComposerContext'
 
 // ─── Constants ─────────────────────────────────────────────────────
 
@@ -114,29 +116,40 @@ export class AgentManager implements ToolApprovalOwner {
    */
   async sendMessage(
     sessionId: string,
-    content: string,
+    submission: ChatComposerSubmission,
   ): Promise<{ messageId: string } | { error: string }> {
     const session = this.sessions.get(sessionId)
     if (!session) {
       return { error: `Session not found: ${sessionId}` }
     }
+    if (!submission.text.trim() && submission.mentionedFiles.length === 0) {
+      return { error: 'Message is empty' }
+    }
 
     // Don't allow sending while a loop is running
     if (this.activeLoops.has(sessionId)) {
       return { error: 'Agent is already processing a message' }
     }
 
+    const composerContext = await buildComposerContext(
+      submission,
+      session.worktreePath ?? this.workspaceRoot,
+    )
+
     // Append user message
     const userMsg: ChatMessage = {
       id: randomUUID(),
       role: 'user',
-      content,
+      content: submission.rawText?.trim() || submission.text.trim(),
+      contextualContent: composerContext.contextualContent,
+      mentionedFiles: composerContext.mentionedFiles,
+      commandId: composerContext.commandId,
       timestamp: Date.now(),
     }
     session.messages.push(userMsg)
 
     // Auto-title on first user message
-    await this.maybeAutoTitle(session, content)
+    await this.maybeAutoTitle(session, submission.text)
 
     // Prepare assistant message id
     const assistantMessageId = randomUUID()
@@ -148,11 +161,9 @@ export class AgentManager implements ToolApprovalOwner {
     this.toolRetryCounters.set(sessionId, new Map())
 
     // Fire-and-forget: the loop streams events to renderer
-    this.runAgentLoop(session, assistantMessageId, controller.signal).catch(
-      (err) => {
-        console.error('[AgentManager] Unhandled error in agent loop:', err)
-      },
-    )
+    this.runAgentLoop(session, assistantMessageId, controller.signal).catch((err) => {
+      console.error('[AgentManager] Unhandled error in agent loop:', err)
+    })
 
     return { messageId: assistantMessageId }
   }
@@ -170,8 +181,8 @@ export class AgentManager implements ToolApprovalOwner {
 
     // Try to load from ConversationStore
     if (this.conversationStore) {
-      const targetId = conversationId
-        ?? (await this.conversationStore.getMostRecent(workspaceId, 'built-in'))?.id
+      const targetId =
+        conversationId ?? (await this.conversationStore.getMostRecent(workspaceId, 'built-in'))?.id
 
       if (targetId) {
         // Check memory
@@ -181,7 +192,7 @@ export class AgentManager implements ToolApprovalOwner {
         // Load worktreePath from conversation metadata
         const meta = await this.conversationStore.get(targetId)
         // Load from disk
-        const loaded = await this.conversationStore.loadMessages(targetId) as ChatSession | null
+        const loaded = (await this.conversationStore.loadMessages(targetId)) as ChatSession | null
         if (loaded) {
           loaded.status = 'idle' // Reset status on load
           if (meta?.worktreePath) loaded.worktreePath = meta.worktreePath
@@ -221,16 +232,18 @@ export class AgentManager implements ToolApprovalOwner {
 
     // Register in store if this is a genuinely new session (no conversationId given)
     if (!conversationId && this.conversationStore) {
-      await this.conversationStore.create({
-        workspaceId,
-        backend: 'built-in',
-      }).then(meta => {
-        // Re-key the session with the store-generated ID
-        this.sessions.delete(session.id)
-        session.id = meta.id
-        if (meta.worktreePath) session.worktreePath = meta.worktreePath
-        this.sessions.set(meta.id, session)
-      })
+      await this.conversationStore
+        .create({
+          workspaceId,
+          backend: 'built-in',
+        })
+        .then((meta) => {
+          // Re-key the session with the store-generated ID
+          this.sessions.delete(session.id)
+          session.id = meta.id
+          if (meta.worktreePath) session.worktreePath = meta.worktreePath
+          this.sessions.set(meta.id, session)
+        })
     }
 
     return session
@@ -305,7 +318,10 @@ export class AgentManager implements ToolApprovalOwner {
     this.llmClient.updateConfig(config)
   }
 
-  updatePermissions(tier: PermissionTier, autoApprove: Record<string, boolean | ToolPermissionConfig>): void {
+  updatePermissions(
+    tier: PermissionTier,
+    autoApprove: Record<string, boolean | ToolPermissionConfig>,
+  ): void {
     this.permissionTier = tier
     this.autoApprove = autoApprove
   }
@@ -326,7 +342,11 @@ export class AgentManager implements ToolApprovalOwner {
   /**
    * Pending built-in tool calls waiting for user approval (for global inbox hydration).
    */
-  listPendingToolApprovals(): Array<{ workspaceId: string; sessionId: string; toolCall: ToolCall }> {
+  listPendingToolApprovals(): Array<{
+    workspaceId: string
+    sessionId: string
+    toolCall: ToolCall
+  }> {
     const out: Array<{ workspaceId: string; sessionId: string; toolCall: ToolCall }> = []
     for (const [toolCallId, pending] of this.pendingApprovals) {
       const session = this.sessions.get(pending.sessionId)
@@ -417,11 +437,7 @@ export class AgentManager implements ToolApprovalOwner {
 
         // Execute tool calls and feed results back
         session.status = 'awaiting_approval'
-        const results = await this.executeToolCalls(
-          session,
-          toolCalls,
-          signal,
-        )
+        const results = await this.executeToolCalls(session, toolCalls, signal)
 
         if (signal.aborted) break
 
@@ -523,10 +539,7 @@ export class AgentManager implements ToolApprovalOwner {
             break
 
           case 'tool_use_delta':
-            toolJsonBuffers.set(
-              event.id,
-              (toolJsonBuffers.get(event.id) ?? '') + event.partialJson,
-            )
+            toolJsonBuffers.set(event.id, (toolJsonBuffers.get(event.id) ?? '') + event.partialJson)
             break
 
           case 'tool_use_end': {
@@ -591,8 +604,7 @@ export class AgentManager implements ToolApprovalOwner {
     signal: AbortSignal,
   ): Promise<ToolResult[]> {
     const results: ToolResult[] = []
-    const retryCounters =
-      this.toolRetryCounters.get(session.id) ?? new Map<string, number>()
+    const retryCounters = this.toolRetryCounters.get(session.id) ?? new Map<string, number>()
 
     for (const tc of toolCalls) {
       if (signal.aborted) {
@@ -690,7 +702,7 @@ export class AgentManager implements ToolApprovalOwner {
         case 'user': {
           result.push({
             role: 'user',
-            content: [{ type: 'text', text: msg.content }],
+            content: [{ type: 'text', text: msg.contextualContent ?? msg.content }],
           })
           break
         }
@@ -751,9 +763,7 @@ export class AgentManager implements ToolApprovalOwner {
         )
         break
       case 'edit':
-        lines.push(
-          'You are in EDIT mode. You can read and write files within the working set.',
-        )
+        lines.push('You are in EDIT mode. You can read and write files within the working set.')
         if (session.workingSet.length > 0) {
           lines.push(
             'You may only modify files in the working set:',
@@ -790,11 +800,11 @@ export class AgentManager implements ToolApprovalOwner {
       // Save messages to the conversation store
       await this.conversationStore.saveMessages(session.id, session)
       // Update metadata
-      const userMsgCount = session.messages.filter(m => m.role === 'user').length
+      const userMsgCount = session.messages.filter((m) => m.role === 'user').length
       await this.conversationStore.updateMeta(session.id, {
         updatedAt: Date.now(),
         messageCount: session.messages.length,
-        firstMessage: session.messages.find(m => m.role === 'user')?.content.slice(0, 100),
+        firstMessage: session.messages.find((m) => m.role === 'user')?.content.slice(0, 100),
       })
     } else {
       // Legacy: write to single file
@@ -825,7 +835,7 @@ export class AgentManager implements ToolApprovalOwner {
   private async maybeAutoTitle(session: ChatSession, content: string): Promise<void> {
     if (!this.conversationStore) return
 
-    const userMessages = session.messages.filter(m => m.role === 'user')
+    const userMessages = session.messages.filter((m) => m.role === 'user')
     if (userMessages.length !== 1) return // Only auto-title on the very first user message
 
     const meta = await this.conversationStore.get(session.id)
diff --git a/packages/main/src/chat/chatComposerContext.ts b/packages/main/src/chat/chatComposerContext.ts
new file mode 100644
index 0000000..879158b
--- /dev/null
+++ b/packages/main/src/chat/chatComposerContext.ts
@@ -0,0 +1,72 @@
+import { readFile } from 'fs/promises'
+import { relative, resolve, sep } from 'path'
+import type { ChatComposerSubmission } from '@aide/shared'
+
+const MAX_MENTIONED_FILE_BYTES = 12_000
+
+const COMMAND_INSTRUCTIONS: Record<string, string> = {
+  plan: 'Create a short implementation plan before making changes.',
+  explain: 'Focus on explaining the relevant code and behavior clearly.',
+  fix: 'Focus on identifying the root cause and implementing the smallest correct fix.',
+  tests: 'Focus on adding or updating the smallest useful tests for this work.',
+}
+
+export async function buildComposerContext(
+  submission: ChatComposerSubmission,
+  rootPath: string,
+): Promise<{ contextualContent: string; mentionedFiles: string[]; commandId?: string }> {
+  const mentionedFiles = sanitizeMentionedFiles(submission.mentionedFiles, rootPath)
+  const sections: string[] = []
+  const commandInstruction = submission.commandId
+    ? COMMAND_INSTRUCTIONS[submission.commandId]
+    : undefined
+  if (commandInstruction) {
+    sections.push(`Requested mode: /${submission.commandId}\n${commandInstruction}`)
+  }
+
+  if (mentionedFiles.length > 0) {
+    const fileSections = await Promise.all(
+      mentionedFiles.map(async (filePath) => formatMentionedFile(rootPath, filePath)),
+    )
+    sections.push(['Referenced files:', ...fileSections].join('\n\n'))
+  }
+
+  sections.push(submission.text)
+  return {
+    contextualContent: sections.filter(Boolean).join('\n\n'),
+    mentionedFiles,
+    commandId: submission.commandId,
+  }
+}
+
+function sanitizeMentionedFiles(paths: string[], rootPath: string): string[] {
+  const unique = new Set<string>()
+  for (const filePath of paths) {
+    if (!filePath) continue
+    const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '')
+    const absolute = resolve(rootPath, normalized)
+    if (!isWithinRoot(absolute, rootPath)) continue
+    unique.add(relative(rootPath, absolute).replace(/\\/g, '/'))
+  }
+  return [...unique]
+}
+
+function isWithinRoot(candidate: string, rootPath: string): boolean {
+  const rel = relative(rootPath, candidate)
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.includes(`..${sep}`))
+}
+
+async function formatMentionedFile(rootPath: string, filePath: string): Promise<string> {
+  const absolute = resolve(rootPath, filePath)
+  try {
+    const content = await readFile(absolute, 'utf-8')
+    const trimmed =
+      content.length > MAX_MENTIONED_FILE_BYTES
+        ? `${content.slice(0, MAX_MENTIONED_FILE_BYTES)}\n...[truncated by aIDE]`
+        : content
+    return [`- ${filePath}`, '```', trimmed, '```'].join('\n')
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return `- ${filePath}\n(unavailable: ${message})`
+  }
+}
diff --git a/packages/main/src/chat/cliAgentManager.ts b/packages/main/src/chat/cliAgentManager.ts
index 26670e1..0cbcaa9 100644
--- a/packages/main/src/chat/cliAgentManager.ts
+++ b/packages/main/src/chat/cliAgentManager.ts
@@ -21,6 +21,7 @@ import { app, type WebContents } from 'electron'
 import { IpcChannels, deriveTitle } from '@aide/shared'
 import type {
   AgentBackend,
+  ChatComposerSubmission,
   CliAgentBackendState,
   CliAgentBackendStateMap,
   CliAgentMessage,
@@ -57,6 +58,7 @@ import type { CliBackendAdapter, CliBackendEvent, CliBackendRun } from './cliAda
 import { OpenCodeServerHost } from './openCodeServerHost'
 import type { ToolApprovalOwner } from './approvalRouter'
 import type { ChatToolCallPayload, ToolCall } from '@aide/shared'
+import { buildComposerContext } from './chatComposerContext'
 
 interface PersistedCliConversation {
   messages?: CliAgentMessage[]
@@ -277,9 +279,9 @@ export class CliAgentManager implements ToolApprovalOwner {
       if (existing.activeRun) {
         return { error: 'Agent is already processing a request. Stop it first or wait.' }
       }
-      existing.backend = backend
-      existing.model = existing.backendStates[backend]?.model
-      existing.sessionToolNames = undefined
+      // Do NOT overwrite existing.backend — switchBackend() owns that transition.
+      // Re-running start() must not silently revert a user-selected backend or
+      // throw away its per-session state (model / providerID / sessionId / etc.).
       existing.worktreePath = worktreePath ?? existing.worktreePath
       await this.persistSession(existing)
       await this.broadcastConversationList(existing.workspaceId)
@@ -369,25 +371,39 @@ export class CliAgentManager implements ToolApprovalOwner {
     return seed
   }
 
-  async send(sessionId: string, content: string): Promise<{ success: true } | { error: string }> {
+  async send(
+    sessionId: string,
+    submission: ChatComposerSubmission,
+  ): Promise<{ success: true } | { error: string }> {
     const session = this.sessions.get(sessionId)
     if (!session) return { error: 'Session not found' }
     if (session.activeRun) {
       return { error: 'Agent is already processing a request. Stop it first or wait.' }
     }
+    if (!submission.text.trim() && submission.mentionedFiles.length === 0) {
+      return { error: 'Message is empty' }
+    }
+
+    const composerContext = await buildComposerContext(
+      submission,
+      session.worktreePath ?? this.workspaceRoot,
+    )
 
     const userMsg: CliAgentMessage = {
       id: randomUUID(),
       type: 'user',
-      content,
+      content: submission.rawText?.trim() || submission.text.trim(),
+      contextualContent: composerContext.contextualContent,
+      mentionedFiles: composerContext.mentionedFiles,
+      commandId: composerContext.commandId,
       timestamp: Date.now(),
     }
     session.messages.push(userMsg)
     this.emitMessage(session, userMsg)
-    await this.maybeAutoTitle(session, content)
+    await this.maybeAutoTitle(session, submission.text)
 
     session.lastError = undefined
-    const prompt = this.buildTurnPrompt(session, content)
+    const prompt = this.buildTurnPrompt(session, userMsg)
 
     let adapter: CliBackendAdapter
     try {
@@ -659,9 +675,9 @@ export class CliAgentManager implements ToolApprovalOwner {
 
   async listOpenCodeAgents(sessionId: string): Promise<OpenCodeAgentSummary[]> {
     const client = await this.getOpenCodeClient(sessionId)
-    const result = await callSdk<
-      Array<{ name?: string; description?: string; mode?: string }>
-    >(() => (client as any).app.agents())
+    const result = await callSdk<Array<{ name?: string; description?: string; mode?: string }>>(
+      () => (client as any).app.agents(),
+    )
     if (!Array.isArray(result)) return []
     return result.map((a) => ({
       name: a.name ?? '',
@@ -806,9 +822,7 @@ export class CliAgentManager implements ToolApprovalOwner {
     }
   }
 
-  async sessionDiff(
-    sessionId: string,
-  ): Promise<{ diff?: unknown; error?: string }> {
+  async sessionDiff(sessionId: string): Promise<{ diff?: unknown; error?: string }> {
     try {
       const client = await this.getOpenCodeClient(sessionId)
       const remoteId = this.requireRemoteId(sessionId)
@@ -821,9 +835,7 @@ export class CliAgentManager implements ToolApprovalOwner {
     }
   }
 
-  async sessionTodo(
-    sessionId: string,
-  ): Promise<{ todos?: OpenCodeTodoItem[]; error?: string }> {
+  async sessionTodo(sessionId: string): Promise<{ todos?: OpenCodeTodoItem[]; error?: string }> {
     try {
       const client = await this.getOpenCodeClient(sessionId)
       const remoteId = this.requireRemoteId(sessionId)
@@ -899,10 +911,7 @@ export class CliAgentManager implements ToolApprovalOwner {
     }
   }
 
-  async fileRead(
-    sessionId: string,
-    path: string,
-  ): Promise<{ content?: string; error?: string }> {
+  async fileRead(sessionId: string, path: string): Promise<{ content?: string; error?: string }> {
     try {
       const client = await this.getOpenCodeClient(sessionId)
       const result = await callSdk<{ content?: string } | string>(() =>
@@ -1108,9 +1117,9 @@ export class CliAgentManager implements ToolApprovalOwner {
   ): Promise<{ methods?: OpenCodeAuthMethod[]; error?: string }> {
     try {
       const client = await this.getOpenCodeClient(sessionId)
-      const result = await callSdk<
-        Array<{ id?: string; label?: string; type?: string }>
-      >(() => (client as any).provider.auth({ query: { providerID: providerId } }))
+      const result = await callSdk<Array<{ id?: string; label?: string; type?: string }>>(() =>
+        (client as any).provider.auth({ query: { providerID: providerId } }),
+      )
       const methods = (Array.isArray(result) ? result : []).map((m) => ({
         id: m.id ?? '',
         label: m.label,
@@ -1169,9 +1178,7 @@ export class CliAgentManager implements ToolApprovalOwner {
   ): Promise<{ success?: true; error?: string }> {
     try {
       const client = await this.getOpenCodeClient(sessionId)
-      await callSdk(() =>
-        (client as any).app.log({ body: { message, level: level ?? 'INFO' } }),
-      )
+      await callSdk(() => (client as any).app.log({ body: { message, level: level ?? 'INFO' } }))
       return { success: true }
     } catch (error) {
       return { error: errMsg(error) }
@@ -1517,10 +1524,10 @@ export class CliAgentManager implements ToolApprovalOwner {
     this.notifyWorkloadChanged()
   }
 
-  private buildTurnPrompt(session: CliAgentSessionInternal, content: string): string {
+  private buildTurnPrompt(session: CliAgentSessionInternal, userMessage: CliAgentMessage): string {
     const backendState = session.backendStates[session.backend]
     if (backendState?.sessionId) {
-      return content
+      return userMessage.contextualContent ?? userMessage.content
     }
 
     const priorMessages = session.messages
@@ -1534,14 +1541,16 @@ export class CliAgentManager implements ToolApprovalOwner {
       )
 
     if (priorMessages.length === 0) {
-      return content
+      return userMessage.contextualContent ?? userMessage.content
     }
 
     const transcript = priorMessages
       .slice(-40)
       .map((message) => {
         const source = message.backend ? ` ${message.backend}` : ''
-        return `[${message.type}${source}]\n${message.content}`
+        const content =
+          message.type === 'user' ? (message.contextualContent ?? message.content) : message.content
+        return `[${message.type}${source}]\n${content}`
       })
       .join('\n\n')
 
@@ -1553,7 +1562,7 @@ export class CliAgentManager implements ToolApprovalOwner {
       transcript,
       '',
       'Latest user request:',
-      content,
+      userMessage.contextualContent ?? userMessage.content,
     ].join('\n')
   }
 
diff --git a/packages/main/src/index.ts b/packages/main/src/index.ts
index 56c9cf3..d487629 100644
--- a/packages/main/src/index.ts
+++ b/packages/main/src/index.ts
@@ -7,6 +7,7 @@ import Store from 'electron-store'
 import { IpcChannels, DEFAULT_SETTINGS, SENSITIVE_AGENT_KEYS } from '@aide/shared'
 import type {
   AppSettings,
+  ChatComposerSubmission,
   ThemeId,
   DirEntry,
   SearchOpts,
@@ -753,11 +754,11 @@ ipcMain.handle(IpcChannels.WORKSPACE_RUNTIME_SNAPSHOTS_GET, () => {
 
 ipcMain.handle(
   IpcChannels.CHAT_SEND_MESSAGE,
-  async (_event, sessionId: string, content: string) => {
+  async (_event, sessionId: string, payload: ChatComposerSubmission) => {
     const runtime = findRuntimeWithBuiltInSession(sessionId)
     const agentManager = getAgentManager(runtime)
     if (!agentManager) return { error: 'No workspace open' }
-    const result = await agentManager.sendMessage(sessionId, content)
+    const result = await agentManager.sendMessage(sessionId, payload)
     runtime?.refreshWorkload()
     return result
   },
@@ -863,14 +864,17 @@ ipcMain.handle(
   },
 )
 
-ipcMain.handle(IpcChannels.CLI_AGENT_SEND, async (_event, sessionId: string, content: string) => {
-  const runtime = findRuntimeWithCliSession(sessionId)
-  const cliAgentManager = getCliAgentManager(runtime)
-  if (!cliAgentManager) return { error: 'No workspace open' }
-  const result = await cliAgentManager.send(sessionId, content)
-  runtime?.refreshWorkload()
-  return result
-})
+ipcMain.handle(
+  IpcChannels.CLI_AGENT_SEND,
+  async (_event, sessionId: string, payload: ChatComposerSubmission) => {
+    const runtime = findRuntimeWithCliSession(sessionId)
+    const cliAgentManager = getCliAgentManager(runtime)
+    if (!cliAgentManager) return { error: 'No workspace open' }
+    const result = await cliAgentManager.send(sessionId, payload)
+    runtime?.refreshWorkload()
+    return result
+  },
+)
 
 ipcMain.handle(
   IpcChannels.CLI_AGENT_GET_SESSION,
@@ -957,9 +961,7 @@ ipcMain.handle(IpcChannels.CLI_AGENT_LIST_MODES, async (_event, sessionId: strin
 ipcMain.handle(
   IpcChannels.CLI_AGENT_LIST_TOOLS,
   async (_event, sessionId: string, providerID: string, modelID: string) => {
-    return withCliManager(sessionId, (mgr) =>
-      mgr.listOpenCodeTools(sessionId, providerID, modelID),
-    )
+    return withCliManager(sessionId, (mgr) => mgr.listOpenCodeTools(sessionId, providerID, modelID))
   },
 )
 
@@ -1017,19 +1019,13 @@ ipcMain.handle(IpcChannels.CLI_AGENT_SESSION_DELETE_REMOTE, async (_event, sessi
 
 // ─── CLI Agent: workspace ops ───────────────────────────────────────────
 
-ipcMain.handle(
-  IpcChannels.CLI_AGENT_FILE_LIST,
-  async (_event, sessionId: string, path: string) => {
-    return withCliManager(sessionId, (mgr) => mgr.fileList(sessionId, path))
-  },
-)
+ipcMain.handle(IpcChannels.CLI_AGENT_FILE_LIST, async (_event, sessionId: string, path: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.fileList(sessionId, path))
+})
 
-ipcMain.handle(
-  IpcChannels.CLI_AGENT_FILE_READ,
-  async (_event, sessionId: string, path: string) => {
-    return withCliManager(sessionId, (mgr) => mgr.fileRead(sessionId, path))
-  },
-)
+ipcMain.handle(IpcChannels.CLI_AGENT_FILE_READ, async (_event, sessionId: string, path: string) => {
+  return withCliManager(sessionId, (mgr) => mgr.fileRead(sessionId, path))
+})
 
 ipcMain.handle(IpcChannels.CLI_AGENT_FILE_STATUS, async (_event, sessionId: string) => {
   return withCliManager(sessionId, (mgr) => mgr.fileStatus(sessionId))
diff --git a/packages/main/src/preload.ts b/packages/main/src/preload.ts
index 928a6b4..99ebe71 100644
--- a/packages/main/src/preload.ts
+++ b/packages/main/src/preload.ts
@@ -443,8 +443,8 @@ const api: WindowApi = {
   },
 
   // ─── Agent Chat ───────────────────────────────
-  chatSendMessage: (sessionId: string, content: string) =>
-    ipcRenderer.invoke(IpcChannels.CHAT_SEND_MESSAGE, sessionId, content),
+  chatSendMessage: (sessionId: string, payload: import('@aide/shared').ChatComposerSubmission) =>
+    ipcRenderer.invoke(IpcChannels.CHAT_SEND_MESSAGE, sessionId, payload),
   chatGetHistory: (workspaceId: string, conversationId?: string): Promise<ChatSession | null> =>
     ipcRenderer.invoke(IpcChannels.CHAT_GET_HISTORY, workspaceId, conversationId),
   chatSetMode: (sessionId: string, mode: ChatMode): Promise<void> =>
@@ -504,8 +504,8 @@ const api: WindowApi = {
   cliAgentSwitchBackend: (sessionId: string, backend: AgentBackend) =>
     ipcRenderer.invoke(IpcChannels.CLI_AGENT_SWITCH_BACKEND, sessionId, backend),
   cliAgentStop: (sessionId: string) => ipcRenderer.send(IpcChannels.CLI_AGENT_STOP, sessionId),
-  cliAgentSend: (sessionId: string, content: string) =>
-    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SEND, sessionId, content),
+  cliAgentSend: (sessionId: string, payload: import('@aide/shared').ChatComposerSubmission) =>
+    ipcRenderer.invoke(IpcChannels.CLI_AGENT_SEND, sessionId, payload),
   cliAgentGetSession: (workspaceId: string, sessionId?: string): Promise<CliAgentSession | null> =>
     ipcRenderer.invoke(IpcChannels.CLI_AGENT_GET_SESSION, workspaceId, sessionId),
   cliAgentLoadMessages: (workspaceId: string, conversationId: string): Promise<CliAgentMessage[]> =>
diff --git a/packages/renderer/src/components/chat/ChatInput.tsx b/packages/renderer/src/components/chat/ChatInput.tsx
index d0e4b15..2f2d84c 100644
--- a/packages/renderer/src/components/chat/ChatInput.tsx
+++ b/packages/renderer/src/components/chat/ChatInput.tsx
@@ -1,19 +1,51 @@
-import { useRef, useCallback, useState } from 'react'
-import type { ChatMode, ChatSessionStatus } from '@aide/shared'
+import { useRef, useCallback, useState, useMemo, useEffect } from 'react'
+import type { ChatComposerSubmission, ChatMode, ChatSessionStatus } from '@aide/shared'
 import { Button } from '../ui/Button'
+import {
+  buildComposerSubmission,
+  CHAT_AUTOCOMPLETE_COMMANDS,
+  filterCommandSuggestions,
+  filterFileSuggestions,
+  getComposerTrigger,
+} from '../../lib/chatComposer'
 
 interface ChatInputProps {
-  onSend: (content: string) => void
+  onSend: (payload: ChatComposerSubmission) => void
   onStop: () => void
   status: ChatSessionStatus
   mode: ChatMode
+  workspaceRoot?: string
 }
 
-export function ChatInput({ onSend, onStop, status }: ChatInputProps) {
+export function ChatInput({ onSend, onStop, status, workspaceRoot }: ChatInputProps) {
   const textareaRef = useRef<HTMLTextAreaElement>(null)
   const [value, setValue] = useState('')
+  const [mentionedFiles, setMentionedFiles] = useState<string[]>([])
+  const [allFiles, setAllFiles] = useState<string[]>([])
+  const [activeIndex, setActiveIndex] = useState(0)
   const isActive = status !== 'idle'
 
+  useEffect(() => {
+    let cancelled = false
+    if (!workspaceRoot) {
+      setAllFiles([])
+      return () => {
+        cancelled = true
+      }
+    }
+    window.api
+      .listAllFiles(workspaceRoot)
+      .then((files) => {
+        if (!cancelled) setAllFiles(files)
+      })
+      .catch(() => {
+        if (!cancelled) setAllFiles([])
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [workspaceRoot])
+
   const resize = useCallback(() => {
     const el = textareaRef.current
     if (!el) return
@@ -21,6 +53,31 @@ export function ChatInput({ onSend, onStop, status }: ChatInputProps) {
     el.style.height = `${el.scrollHeight}px`
   }, [])
 
+  const cursor = textareaRef.current?.selectionStart ?? value.length
+  const trigger = useMemo(() => getComposerTrigger(value, cursor), [value, cursor])
+  const fileSuggestions = useMemo(
+    () =>
+      trigger?.kind === 'file'
+        ? filterFileSuggestions(
+            allFiles.filter((file) => !mentionedFiles.includes(file)),
+            trigger.query,
+          )
+        : [],
+    [allFiles, mentionedFiles, trigger],
+  )
+  const commandSuggestions = useMemo(
+    () =>
+      trigger?.kind === 'command'
+        ? filterCommandSuggestions(CHAT_AUTOCOMPLETE_COMMANDS, trigger.query)
+        : [],
+    [trigger],
+  )
+  const suggestions = trigger?.kind === 'file' ? fileSuggestions : commandSuggestions
+
+  useEffect(() => {
+    setActiveIndex(0)
+  }, [trigger?.kind, trigger?.query, suggestions.length])
+
   const handleChange = useCallback(
     (e: React.ChangeEvent<HTMLTextAreaElement>) => {
       setValue(e.target.value)
@@ -29,58 +86,184 @@ export function ChatInput({ onSend, onStop, status }: ChatInputProps) {
     [resize],
   )
 
-  const handleSend = useCallback(() => {
-    const trimmed = value.trim()
-    if (!trimmed || isActive) return
-    onSend(trimmed)
+  const resetComposer = useCallback(() => {
     setValue('')
-    // Reset textarea height
+    setMentionedFiles([])
     requestAnimationFrame(() => {
       const el = textareaRef.current
-      if (el) {
-        el.style.height = 'auto'
-      }
+      if (el) el.style.height = 'auto'
     })
-  }, [value, isActive, onSend])
+  }, [])
+
+  const handleSend = useCallback(() => {
+    const submission = buildComposerSubmission(value, mentionedFiles)
+    if ((!submission.text && submission.mentionedFiles.length === 0) || isActive) return
+    onSend(submission)
+    resetComposer()
+  }, [value, mentionedFiles, isActive, onSend, resetComposer])
+
+  const insertCommand = useCallback(
+    (commandId: string) => {
+      if (!trigger || trigger.kind !== 'command') return
+      const nextValue = `${value.slice(0, trigger.start)}/${commandId} ${value.slice(trigger.end)}`
+      setValue(nextValue)
+      requestAnimationFrame(() => {
+        const el = textareaRef.current
+        if (!el) return
+        const pos = trigger.start + commandId.length + 2
+        el.focus()
+        el.setSelectionRange(pos, pos)
+        resize()
+      })
+    },
+    [trigger, value, resize],
+  )
+
+  const insertMention = useCallback(
+    (filePath: string) => {
+      if (!trigger || trigger.kind !== 'file') return
+      const nextValue = `${value.slice(0, trigger.start)}${value.slice(trigger.end)}`
+      setValue(nextValue)
+      setMentionedFiles((prev) => (prev.includes(filePath) ? prev : [...prev, filePath]))
+      requestAnimationFrame(() => {
+        const el = textareaRef.current
+        if (!el) return
+        const pos = trigger.start
+        el.focus()
+        el.setSelectionRange(pos, pos)
+        resize()
+      })
+    },
+    [trigger, value, resize],
+  )
+
+  const handleSuggestionSelect = useCallback(() => {
+    if (!trigger || suggestions.length === 0) return false
+    const current = suggestions[Math.min(activeIndex, suggestions.length - 1)]
+    if (!current) return false
+    if (trigger.kind === 'file') insertMention(current as string)
+    else insertCommand((current as (typeof commandSuggestions)[number]).id)
+    return true
+  }, [activeIndex, commandSuggestions, insertCommand, insertMention, suggestions, trigger])
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (trigger && suggestions.length > 0) {
+        if (e.key === 'ArrowDown') {
+          e.preventDefault()
+          setActiveIndex((index) => (index + 1) % suggestions.length)
+          return
+        }
+        if (e.key === 'ArrowUp') {
+          e.preventDefault()
+          setActiveIndex((index) => (index - 1 + suggestions.length) % suggestions.length)
+          return
+        }
+        if (e.key === 'Tab') {
+          e.preventDefault()
+          handleSuggestionSelect()
+          return
+        }
+        if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+          e.preventDefault()
+          handleSuggestionSelect()
+          return
+        }
+        if (e.key === 'Escape') {
+          e.preventDefault()
+          setValue((current) => current)
+          return
+        }
+      }
+
       if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
         e.preventDefault()
         handleSend()
       } else if (e.key === 'Escape') {
         textareaRef.current?.blur()
+      } else if (e.key === 'Backspace' && !value && mentionedFiles.length > 0) {
+        setMentionedFiles((prev) => prev.slice(0, -1))
       }
     },
-    [handleSend],
+    [handleSend, handleSuggestionSelect, mentionedFiles.length, suggestions.length, trigger, value],
   )
 
   return (
-    <div className="chat-input">
-      <textarea
-        ref={textareaRef}
-        className="chat-input__textarea"
-        value={value}
-        onChange={handleChange}
-        onKeyDown={handleKeyDown}
-        placeholder="Ask, edit, or build…"
-        rows={1}
-        disabled={isActive}
-      />
-      {isActive ? (
-        <Button variant="danger" size="sm" onClick={onStop} title="Stop">
-          Stop
-        </Button>
-      ) : (
-        <Button
-          variant="accent"
-          size="sm"
-          onClick={handleSend}
-          disabled={!value.trim()}
-        >
-          Send
-        </Button>
+    <div className="chat-input-wrap">
+      {mentionedFiles.length > 0 && (
+        <div className="chat-input__chips">
+          {mentionedFiles.map((path) => (
+            <button
+              key={path}
+              type="button"
+              className="chat-input__chip"
+              onClick={() => setMentionedFiles((prev) => prev.filter((entry) => entry !== path))}
+              title={path}
+            >
+              @{path}
+            </button>
+          ))}
+        </div>
       )}
+
+      <div className="chat-input">
+        <textarea
+          ref={textareaRef}
+          className="chat-input__textarea"
+          value={value}
+          onChange={handleChange}
+          onKeyDown={handleKeyDown}
+          placeholder="Ask, edit, or build… Use @ for files, / for commands"
+          rows={1}
+          disabled={isActive}
+        />
+        {isActive ? (
+          <Button variant="danger" size="sm" onClick={onStop} title="Stop">
+            Stop
+          </Button>
+        ) : (
+          <Button
+            variant="accent"
+            size="sm"
+            onClick={handleSend}
+            disabled={!value.trim() && mentionedFiles.length === 0}
+          >
+            Send
+          </Button>
+        )}
+
+        {trigger && suggestions.length > 0 && !isActive && (
+          <div className="chat-input__suggestions">
+            {trigger.kind === 'file'
+              ? fileSuggestions.map((filePath, index) => (
+                  <button
+                    key={filePath}
+                    type="button"
+                    className={`chat-input__suggestion${index === activeIndex ? ' chat-input__suggestion--active' : ''}`}
+                    onMouseDown={(e) => e.preventDefault()}
+                    onClick={() => insertMention(filePath)}
+                  >
+                    <span className="chat-input__suggestion-label">
+                      @{filePath.split('/').pop() ?? filePath}
+                    </span>
+                    <span className="chat-input__suggestion-detail">{filePath}</span>
+                  </button>
+                ))
+              : commandSuggestions.map((command, index) => (
+                  <button
+                    key={command.id}
+                    type="button"
+                    className={`chat-input__suggestion${index === activeIndex ? ' chat-input__suggestion--active' : ''}`}
+                    onMouseDown={(e) => e.preventDefault()}
+                    onClick={() => insertCommand(command.id)}
+                  >
+                    <span className="chat-input__suggestion-label">{command.label}</span>
+                    <span className="chat-input__suggestion-detail">{command.description}</span>
+                  </button>
+                ))}
+          </div>
+        )}
+      </div>
     </div>
   )
 }
diff --git a/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx b/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
index ed32b0e..e1945b3 100644
--- a/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
+++ b/packages/renderer/src/components/cliAgent/RichPartRenderer.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react'
+import { useMemo } from 'react'
 import type { CliAgentMessage } from '@aide/shared'
 import { renderMarkdown } from '../../lib/markdownRenderer'
 import { CostTokenBadge } from './CostTokenBadge'
@@ -41,26 +41,17 @@ export function RichPartRenderer({
 }
 
 function ReasoningBubble({ message }: { message: CliAgentMessage }) {
-  const [open, setOpen] = useState(!message.reasoningCollapsed)
   const html = useMemo(() => renderMarkdown(message.content || ''), [message.content])
   return (
-    <details
-      open={open}
-      onToggle={(e) => setOpen((e.target as HTMLDetailsElement).open)}
+    <aside
       className="cli-agent-msg cli-agent-msg--reasoning"
-      style={{
-        margin: '4px 0',
-        padding: '4px 8px',
-        borderLeft: '2px solid var(--color-accent-muted, #888)',
-        opacity: 0.85,
-        fontSize: 12,
-      }}
+      aria-label="Model reasoning"
     >
-      <summary style={{ cursor: 'pointer', userSelect: 'none' }}>
-        <em>Reasoning</em>
-      </summary>
-      <div style={{ marginTop: 4 }} dangerouslySetInnerHTML={{ __html: html }} />
-    </details>
+      <div
+        className="cli-agent-msg--reasoning__body cli-agent-msg__markdown"
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    </aside>
   )
 }
 
diff --git a/packages/renderer/src/components/panes/ChatPane.tsx b/packages/renderer/src/components/panes/ChatPane.tsx
index 17f3498..5456f28 100644
--- a/packages/renderer/src/components/panes/ChatPane.tsx
+++ b/packages/renderer/src/components/panes/ChatPane.tsx
@@ -35,7 +35,10 @@ export function ChatPane({ params, api }: IDockviewPanelProps<ChatPanelParams>)
   }, [api, chat.conversationTitle])
 
   return (
-    <div className="chat-pane" style={{ ['--panel-zoom' as string]: String(params?.zoomFactor ?? 1) }}>
+    <div
+      className="chat-pane"
+      style={{ ['--panel-zoom' as string]: String(params?.zoomFactor ?? 1) }}
+    >
       <div className="chat-pane__header">
         <div className="chat-pane__header-row">
           <ModeSelector
@@ -71,6 +74,7 @@ export function ChatPane({ params, api }: IDockviewPanelProps<ChatPanelParams>)
           onStop={chat.stop}
           status={chat.status}
           mode={chat.mode}
+          workspaceRoot={params?.worktreePath ?? params?.workspaceRoot}
         />
       </div>
     </div>
diff --git a/packages/renderer/src/components/panes/CliAgentPane.tsx b/packages/renderer/src/components/panes/CliAgentPane.tsx
index ce09259..bcca8b0 100644
--- a/packages/renderer/src/components/panes/CliAgentPane.tsx
+++ b/packages/renderer/src/components/panes/CliAgentPane.tsx
@@ -24,7 +24,14 @@ interface CliAgentPanelParams {
 }
 
 export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelParams>) {
-  const { workspaceId, workspaceRoot, backend: backendParam, conversationId, worktreePath, zoomFactor } = params ?? {}
+  const {
+    workspaceId,
+    workspaceRoot,
+    backend: backendParam,
+    conversationId,
+    worktreePath,
+    zoomFactor,
+  } = params ?? {}
   const backend = backendParam ?? 'claude-code'
   const agent = useCliAgent({ workspaceId, backend, conversationId, worktreePath })
   const listRef = useRef<HTMLDivElement>(null)
@@ -53,7 +60,7 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
       (conversationId || agent.messages.length === 0)
     ) {
       hasAutoStartedRef.current = true
-      void agent.start(backend)
+      void agent.start(agent.activeBackend ?? backend)
     }
   }, [
     workspaceId,
@@ -81,7 +88,10 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
     isAtBottomRef.current = el.scrollHeight - el.scrollTop - el.clientHeight < 40
   }
 
-  const isActive = agent.processStatus === 'running' || agent.processStatus === 'starting' || agent.processStatus === 'rate_limited'
+  const isActive =
+    agent.processStatus === 'running' ||
+    agent.processStatus === 'starting' ||
+    agent.processStatus === 'rate_limited'
   const headerBackend: AgentBackend = agent.activeBackend ?? backend
 
   // Detect mixed-backend transcripts so we only render per-message badges when
@@ -120,6 +130,24 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
     [agent.sessionId, showToast],
   )
 
+  // Global toggle: hide/show tool call + tool result bubbles in the transcript.
+  const [showTools, setShowTools] = useState<boolean>(() => {
+    try {
+      return localStorage.getItem('aide.cliAgent.showTools') !== '0'
+    } catch {
+      return true
+    }
+  })
+  const toggleShowTools = useCallback(() => {
+    setShowTools((prev) => {
+      const next = !prev
+      try {
+        localStorage.setItem('aide.cliAgent.showTools', next ? '1' : '0')
+      } catch {}
+      return next
+    })
+  }, [])
+
   const isOpenCode = headerBackend === 'opencode'
   // Mirror the live per-backend state from the hook so the popover pickers
   // reflect any overrides the user has applied (and so dependent dropdowns
@@ -137,24 +165,24 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
           className={`cli-agent-pane__backend-switcher cli-agent-pane__backend-switcher--${headerBackend}`}
           title={isActive ? 'Stop the active turn before switching backends' : 'Switch backend'}
         >
-          <span className="cli-agent-pane__backend-label">
-            {backendLabel(headerBackend)}
-          </span>
+          <span className="cli-agent-pane__backend-label">{backendLabel(headerBackend)}</span>
           <span className="cli-agent-pane__backend-caret">{'\u25BE'}</span>
           <select
             className="cli-agent-pane__backend-select"
             value={headerBackend}
             disabled={isActive}
-            onChange={(e) => { void handleBackendChange(e.target.value as AgentBackend) }}
+            onChange={(e) => {
+              void handleBackendChange(e.target.value as AgentBackend)
+            }}
           >
             {CLI_BACKENDS.map((b) => (
-              <option key={b} value={b}>{backendLabel(b)}</option>
+              <option key={b} value={b}>
+                {backendLabel(b)}
+              </option>
             ))}
           </select>
         </label>
-        {agent.model && (
-          <span className="cli-agent-pane__model">{agent.model}</span>
-        )}
+        {agent.model && <span className="cli-agent-pane__model">{agent.model}</span>}
         <CostTokenBadge
           costUsd={agent.totalCostUsd}
           tokens={agent.totalTokens}
@@ -162,6 +190,13 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
           hideCost={headerBackend === 'claude-code'}
         />
         <div className="cli-agent-pane__header-spacer" />
+        <button
+          className="cli-agent-pane__btn"
+          onClick={toggleShowTools}
+          title={showTools ? 'Hide tool calls and results' : 'Show tool calls and results'}
+        >
+          {showTools ? 'Hide tools' : 'Show tools'}
+        </button>
         {isOpenCode && agent.sessionId && currentBackendState && (
           <SessionSettingsPopover
             sessionId={agent.sessionId}
@@ -184,7 +219,7 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
         ) : (
           <button
             className="cli-agent-pane__btn cli-agent-pane__btn--start"
-            onClick={() => agent.start(backend)}
+            onClick={() => agent.start(headerBackend)}
           >
             {agent.processStatus === 'error' ? 'Restart' : 'Start'}
           </button>
@@ -197,9 +232,7 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
             margin: '4px 8px',
             padding: '4px 8px',
             background:
-              toast.variant === 'error'
-                ? 'rgba(255,80,80,0.15)'
-                : 'rgba(80,200,120,0.15)',
+              toast.variant === 'error' ? 'rgba(255,80,80,0.15)' : 'rgba(80,200,120,0.15)',
             color: toast.variant === 'error' ? 'tomato' : undefined,
             borderRadius: 4,
             fontSize: 11,
@@ -221,24 +254,27 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
       <div className="cli-agent-pane__messages" ref={listRef} onScroll={handleScroll}>
         {agent.messages.length === 0 && !agent.streamingContent && (
           <div className="cli-agent-pane__empty">
-            {isActive
-              ? 'Waiting for response...'
-              : 'Send a message to start the agent'}
+            {isActive ? 'Waiting for response...' : 'Send a message to start the agent'}
           </div>
         )}
 
-        {agent.messages.map((msg) => (
-          <CliAgentMessageBubble
-            key={msg.id}
-            message={msg}
-            showBackendBadge={showBackendBadges}
-            onRevertMessage={isOpenCode ? handleRevertMessage : undefined}
-          />
-        ))}
+        {agent.messages.map((msg) => {
+          if (!showTools && (msg.type === 'tool_use' || msg.type === 'tool_result')) return null
+          return (
+            <CliAgentMessageBubble
+              key={msg.id}
+              message={msg}
+              showBackendBadge={showBackendBadges}
+              onRevertMessage={isOpenCode ? handleRevertMessage : undefined}
+            />
+          )
+        })}
 
         {agent.streamingContent && (
           <div className="cli-agent-msg cli-agent-msg--assistant">
-            <CliAgentMarkdown content={agent.streamingContent} />
+            <div className="cli-agent-msg__body">
+              <CliAgentMarkdown content={agent.streamingContent} />
+            </div>
             <span className="cli-agent-msg__cursor">{'\u2588'}</span>
           </div>
         )}
@@ -251,6 +287,7 @@ export function CliAgentPane({ params, api }: IDockviewPanelProps<CliAgentPanelP
           onStop={agent.stop}
           status={isActive ? 'thinking' : 'idle'}
           mode="agent"
+          workspaceRoot={worktreePath ?? workspaceRoot}
         />
       </div>
     </div>
@@ -344,7 +381,9 @@ function CliAgentMessageBubble({
   // Assistant
   return (
     <div className="cli-agent-msg cli-agent-msg--assistant">
-      <CliAgentMarkdown content={message.content} />
+      <div className="cli-agent-msg__body">
+        <CliAgentMarkdown content={message.content} />
+      </div>
       {badge}
     </div>
   )
@@ -356,5 +395,5 @@ function CliAgentMarkdown({ content }: { content: string }) {
     return renderMarkdown(content)
   }, [content])
 
-  return <span dangerouslySetInnerHTML={{ __html: html }} />
+  return <div className="cli-agent-msg__markdown" dangerouslySetInnerHTML={{ __html: html }} />
 }
diff --git a/packages/renderer/src/hooks/useChat.ts b/packages/renderer/src/hooks/useChat.ts
index 5d11965..0f94812 100644
--- a/packages/renderer/src/hooks/useChat.ts
+++ b/packages/renderer/src/hooks/useChat.ts
@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback, useRef } from 'react'
 import type {
+  ChatComposerSubmission,
   ChatSession,
   ChatMessage,
   ChatMode,
@@ -21,7 +22,7 @@ export interface UseChatReturn {
   streamingMessageId: string | null
   streamingContent: string
   conversationTitle: string
-  sendMessage: (content: string) => Promise<void>
+  sendMessage: (payload: ChatComposerSubmission) => Promise<void>
   setMode: (mode: ChatMode) => void
   setWorkingSet: (paths: string[]) => void
   approveToolCall: (toolCallId: string) => void
@@ -60,109 +61,126 @@ export function useChat(workspaceId: string | undefined, conversationId?: string
 
       // Load conversation title from store
       if (session.id) {
-        window.api.conversationGet(workspaceId, session.id).then(meta => {
-          if (!cancelled && meta) {
-            setConversationTitle(meta.title)
-          }
-        }).catch(() => {})
+        window.api
+          .conversationGet(workspaceId, session.id)
+          .then((meta) => {
+            if (!cancelled && meta) {
+              setConversationTitle(meta.title)
+            }
+          })
+          .catch(() => {})
       }
     })
 
-    return () => { cancelled = true }
+    return () => {
+      cancelled = true
+    }
   }, [workspaceId, conversationId, tick])
 
   // Subscribe to conversation list changes (for title updates)
   useEffect(() => {
-    const unsub = window.api.onConversationListChanged(scopedTo<ConversationListChangedPayload>(workspaceId, (payload) => {
-      const sid = sessionIdRef.current
-      if (!sid) return
-      const meta = payload.conversations.find(c => c.id === sid)
-      if (meta) {
-        setConversationTitle(meta.title)
-      }
-    }))
+    const unsub = window.api.onConversationListChanged(
+      scopedTo<ConversationListChangedPayload>(workspaceId, (payload) => {
+        const sid = sessionIdRef.current
+        if (!sid) return
+        const meta = payload.conversations.find((c) => c.id === sid)
+        if (meta) {
+          setConversationTitle(meta.title)
+        }
+      }),
+    )
     return unsub
   }, [workspaceId])
 
   // Subscribe to stream chunks
   useEffect(() => {
-    const unsub = window.api.onChatStreamChunk(scopedTo<ChatStreamChunk>(workspaceId, (chunk) => {
-      if (chunk.sessionId !== sessionIdRef.current) return
+    const unsub = window.api.onChatStreamChunk(
+      scopedTo<ChatStreamChunk>(workspaceId, (chunk) => {
+        if (chunk.sessionId !== sessionIdRef.current) return
 
-      setStreamingMessageId(chunk.messageId)
-      streamingContentRef.current += chunk.delta
-      setStatus('thinking')
+        setStreamingMessageId(chunk.messageId)
+        streamingContentRef.current += chunk.delta
+        setStatus('thinking')
 
-      // Throttle renders to rAF
-      if (rafRef.current === null) {
-        rafRef.current = requestAnimationFrame(() => {
-          rafRef.current = null
-          setStreamingContent(streamingContentRef.current)
-        })
-      }
-    }))
+        // Throttle renders to rAF
+        if (rafRef.current === null) {
+          rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = null
+            setStreamingContent(streamingContentRef.current)
+          })
+        }
+      }),
+    )
     return unsub
   }, [workspaceId])
 
   // Subscribe to stream end
   useEffect(() => {
-    const unsub = window.api.onChatStreamEnd(scopedTo<ChatStreamEnd>(workspaceId, (end) => {
-      if (end.sessionId !== sessionIdRef.current) return
+    const unsub = window.api.onChatStreamEnd(
+      scopedTo<ChatStreamEnd>(workspaceId, (end) => {
+        if (end.sessionId !== sessionIdRef.current) return
 
-      // Finalize the streaming message into the messages array
-      if (streamingContentRef.current) {
-        const finalMsg: ChatMessage = {
-          id: end.messageId,
-          role: 'assistant',
-          content: streamingContentRef.current,
-          timestamp: Date.now(),
-        }
-        // Check if the message already exists (appended by backend via getHistory)
-        const existing = messagesRef.current.find((m) => m.id === end.messageId)
-        if (!existing) {
-          messagesRef.current = [...messagesRef.current, finalMsg]
+        // Finalize the streaming message into the messages array
+        if (streamingContentRef.current) {
+          const finalMsg: ChatMessage = {
+            id: end.messageId,
+            role: 'assistant',
+            content: streamingContentRef.current,
+            timestamp: Date.now(),
+          }
+          // Check if the message already exists (appended by backend via getHistory)
+          const existing = messagesRef.current.find((m) => m.id === end.messageId)
+          if (!existing) {
+            messagesRef.current = [...messagesRef.current, finalMsg]
+          }
         }
-      }
 
-      // Reset streaming state
-      streamingContentRef.current = ''
-      setStreamingContent('')
-      setStreamingMessageId(null)
-      if (rafRef.current !== null) {
-        cancelAnimationFrame(rafRef.current)
-        rafRef.current = null
-      }
+        // Reset streaming state
+        streamingContentRef.current = ''
+        setStreamingContent('')
+        setStreamingMessageId(null)
+        if (rafRef.current !== null) {
+          cancelAnimationFrame(rafRef.current)
+          rafRef.current = null
+        }
 
-      // Refresh session to get full message history with tool results
-      if (sessionIdRef.current) {
-        window.api.chatGetHistory(workspaceId!, end.sessionId).then((session: ChatSession | null) => {
-          if (!session) return
-          messagesRef.current = session.messages
-          setStatus(session.status)
+        // Refresh session to get full message history with tool results
+        if (sessionIdRef.current) {
+          window.api
+            .chatGetHistory(workspaceId!, end.sessionId)
+            .then((session: ChatSession | null) => {
+              if (!session) return
+              messagesRef.current = session.messages
+              setStatus(session.status)
+              tick()
+            })
+        } else {
+          setStatus('idle')
           tick()
-        })
-      } else {
-        setStatus('idle')
-        tick()
-      }
-    }))
+        }
+      }),
+    )
     return unsub
   }, [workspaceId, tick])
 
   // Subscribe to tool calls
   useEffect(() => {
-    const unsub = window.api.onChatToolCall(scopedTo<ChatToolCallPayload>(workspaceId, (payload) => {
-      if (payload.sessionId !== sessionIdRef.current) return
-      setStatus('awaiting_approval')
+    const unsub = window.api.onChatToolCall(
+      scopedTo<ChatToolCallPayload>(workspaceId, (payload) => {
+        if (payload.sessionId !== sessionIdRef.current) return
+        setStatus('awaiting_approval')
 
-      // Find the assistant message and add the tool call, or refresh from backend
-      window.api.chatGetHistory(workspaceId!, payload.sessionId).then((session: ChatSession | null) => {
-        if (!session) return
-        messagesRef.current = session.messages
-        setStatus(session.status)
-        tick()
-      })
-    }))
+        // Find the assistant message and add the tool call, or refresh from backend
+        window.api
+          .chatGetHistory(workspaceId!, payload.sessionId)
+          .then((session: ChatSession | null) => {
+            if (!session) return
+            messagesRef.current = session.messages
+            setStatus(session.status)
+            tick()
+          })
+      }),
+    )
     return unsub
   }, [workspaceId, tick])
 
@@ -173,29 +191,35 @@ export function useChat(workspaceId: string | undefined, conversationId?: string
     }
   }, [])
 
-  const sendMessage = useCallback(async (content: string) => {
-    const sid = sessionIdRef.current
-    if (!sid || !content.trim()) return
-
-    // Optimistic: add user message locally
-    const userMsg: ChatMessage = {
-      id: `local-${Date.now()}`,
-      role: 'user',
-      content: content.trim(),
-      timestamp: Date.now(),
-    }
-    messagesRef.current = [...messagesRef.current, userMsg]
-    setStatus('thinking')
-    streamingContentRef.current = ''
-    setStreamingContent('')
-    tick()
+  const sendMessage = useCallback(
+    async (payload: ChatComposerSubmission) => {
+      const sid = sessionIdRef.current
+      if (!sid || (!payload.text.trim() && payload.mentionedFiles.length === 0)) return
 
-    const result = await window.api.chatSendMessage(sid, content.trim())
-    if ('error' in result) {
-      setStatus('idle')
+      // Optimistic: add user message locally
+      const userMsg: ChatMessage = {
+        id: `local-${Date.now()}`,
+        role: 'user',
+        content: payload.rawText?.trim() || payload.text.trim(),
+        contextualContent: payload.text.trim(),
+        mentionedFiles: payload.mentionedFiles,
+        commandId: payload.commandId,
+        timestamp: Date.now(),
+      }
+      messagesRef.current = [...messagesRef.current, userMsg]
+      setStatus('thinking')
+      streamingContentRef.current = ''
+      setStreamingContent('')
       tick()
-    }
-  }, [tick])
+
+      const result = await window.api.chatSendMessage(sid, payload)
+      if ('error' in result) {
+        setStatus('idle')
+        tick()
+      }
+    },
+    [tick],
+  )
 
   const setMode = useCallback((newMode: ChatMode) => {
     const sid = sessionIdRef.current
@@ -211,22 +235,28 @@ export function useChat(workspaceId: string | undefined, conversationId?: string
     window.api.chatSetWorkingSet(sid, paths)
   }, [])
 
-  const approveToolCall = useCallback((toolCallId: string) => {
-    const sid = sessionIdRef.current
-    const wid = workspaceId
-    if (!sid || !wid) return
-    void window.api.chatToolApprove(sid, toolCallId)
-    approvalInboxRemove(wid, sid, toolCallId)
-    setStatus('tool_running')
-  }, [workspaceId])
+  const approveToolCall = useCallback(
+    (toolCallId: string) => {
+      const sid = sessionIdRef.current
+      const wid = workspaceId
+      if (!sid || !wid) return
+      void window.api.chatToolApprove(sid, toolCallId)
+      approvalInboxRemove(wid, sid, toolCallId)
+      setStatus('tool_running')
+    },
+    [workspaceId],
+  )
 
-  const rejectToolCall = useCallback((toolCallId: string) => {
-    const sid = sessionIdRef.current
-    const wid = workspaceId
-    if (!sid || !wid) return
-    void window.api.chatToolReject(sid, toolCallId)
-    approvalInboxRemove(wid, sid, toolCallId)
-  }, [workspaceId])
+  const rejectToolCall = useCallback(
+    (toolCallId: string) => {
+      const sid = sessionIdRef.current
+      const wid = workspaceId
+      if (!sid || !wid) return
+      void window.api.chatToolReject(sid, toolCallId)
+      approvalInboxRemove(wid, sid, toolCallId)
+    },
+    [workspaceId],
+  )
 
   const stop = useCallback(() => {
     const sid = sessionIdRef.current
diff --git a/packages/renderer/src/hooks/useCliAgent.ts b/packages/renderer/src/hooks/useCliAgent.ts
index 985337b..5dcfbb2 100644
--- a/packages/renderer/src/hooks/useCliAgent.ts
+++ b/packages/renderer/src/hooks/useCliAgent.ts
@@ -1,6 +1,7 @@
 import { useState, useEffect, useCallback, useRef } from 'react'
 import type {
   AgentBackend,
+  ChatComposerSubmission,
   CliAgentBackendState,
   CliAgentProcessStatus,
   CliAgentMessage,
@@ -34,7 +35,7 @@ export interface UseCliAgentReturn {
   /** Per-backend state (provider/model/agent/system/tools) for the active backend. */
   backendState: CliAgentBackendState | null
   start: (backend: AgentBackend) => Promise<void>
-  send: (content: string) => Promise<void>
+  send: (payload: ChatComposerSubmission) => Promise<void>
   stop: () => void
   /** Hot-swap the underlying CLI backend for this conversation. Returns true on success. */
   switchBackend: (backend: AgentBackend) => Promise<boolean>
@@ -81,7 +82,9 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     // No workspace-wide session lookup: multiple unsaved CLI tabs must not share the first in-memory match.
     if (!conversationId) {
       setHistoryHydrated(true)
-      return () => { cancelled = true }
+      return () => {
+        cancelled = true
+      }
     }
 
     setHistoryHydrated(false)
@@ -125,92 +128,105 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
       }
     })()
 
-    window.api.conversationGet(workspaceId, conversationId).then(meta => {
-      if (!cancelled && meta) setConversationTitle(meta.title)
-    }).catch(() => {})
+    window.api
+      .conversationGet(workspaceId, conversationId)
+      .then((meta) => {
+        if (!cancelled && meta) setConversationTitle(meta.title)
+      })
+      .catch(() => {})
 
-    return () => { cancelled = true }
+    return () => {
+      cancelled = true
+    }
   }, [workspaceId, conversationId, tick])
 
   // Subscribe to conversation list changes (titles + late native hydration when the watcher fills the cache).
   useEffect(() => {
-    const unsub = window.api.onConversationListChanged(scopedTo<ConversationListChangedPayload>(workspaceId, (payload) => {
-      const sid = sessionIdRef.current ?? conversationId
-      if (!sid) return
-      const meta = payload.conversations.find(c => c.id === sid)
-      if (meta) {
-        setConversationTitle(meta.title)
-      }
-      if (
-        !conversationId ||
-        !meta ||
-        meta.source !== 'claude-native' ||
-        (meta.messageCount ?? 0) < 1 ||
-        messagesRef.current.length > 0
-      ) {
-        return
-      }
-      const g = ++listRetryGenRef.current
-      void (async () => {
-        const prior = await window.api.cliAgentLoadMessages(workspaceId!, conversationId)
-        if (g !== listRetryGenRef.current) return
-        if (prior.length > 0) {
-          messagesRef.current = prior
-          tick()
+    const unsub = window.api.onConversationListChanged(
+      scopedTo<ConversationListChangedPayload>(workspaceId, (payload) => {
+        const sid = sessionIdRef.current ?? conversationId
+        if (!sid) return
+        const meta = payload.conversations.find((c) => c.id === sid)
+        if (meta) {
+          setConversationTitle(meta.title)
         }
-      })()
-    }))
+        if (
+          !conversationId ||
+          !meta ||
+          meta.source !== 'claude-native' ||
+          (meta.messageCount ?? 0) < 1 ||
+          messagesRef.current.length > 0
+        ) {
+          return
+        }
+        const g = ++listRetryGenRef.current
+        void (async () => {
+          const prior = await window.api.cliAgentLoadMessages(workspaceId!, conversationId)
+          if (g !== listRetryGenRef.current) return
+          if (prior.length > 0) {
+            messagesRef.current = prior
+            tick()
+          }
+        })()
+      }),
+    )
     return unsub
   }, [workspaceId, conversationId, tick])
 
   // Subscribe to stream deltas
   useEffect(() => {
-    const unsub = window.api.onCliAgentStreamDelta(scopedTo<CliAgentStreamDelta>(workspaceId, (delta) => {
-      if (delta.sessionId !== sessionIdRef.current) return
+    const unsub = window.api.onCliAgentStreamDelta(
+      scopedTo<CliAgentStreamDelta>(workspaceId, (delta) => {
+        if (delta.sessionId !== sessionIdRef.current) return
 
-      setStreamingMessageId(delta.messageId)
-      streamingContentRef.current += delta.delta
+        setStreamingMessageId(delta.messageId)
+        streamingContentRef.current += delta.delta
 
-      if (rafRef.current === null) {
-        rafRef.current = requestAnimationFrame(() => {
-          rafRef.current = null
-          setStreamingContent(streamingContentRef.current)
-        })
-      }
-    }))
+        if (rafRef.current === null) {
+          rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = null
+            setStreamingContent(streamingContentRef.current)
+          })
+        }
+      }),
+    )
     return unsub
   }, [workspaceId])
 
   // Subscribe to messages
   useEffect(() => {
-    const unsub = window.api.onCliAgentMessage(scopedTo<CliAgentMessagePayload>(workspaceId, (msg) => {
-      if (msg.sessionId !== sessionIdRef.current) return
+    const unsub = window.api.onCliAgentMessage(
+      scopedTo<CliAgentMessagePayload>(workspaceId, (msg) => {
+        if (msg.sessionId !== sessionIdRef.current) return
 
-      // If we have streaming content, finalize it into the message
-      if (msg.type === 'assistant' && streamingContentRef.current) {
-        streamingContentRef.current = ''
-        setStreamingContent('')
-        setStreamingMessageId(null)
-        if (rafRef.current !== null) {
-          cancelAnimationFrame(rafRef.current)
-          rafRef.current = null
+        // If we have streaming content, finalize it into the message
+        if (msg.type === 'assistant' && streamingContentRef.current) {
+          streamingContentRef.current = ''
+          setStreamingContent('')
+          setStreamingMessageId(null)
+          if (rafRef.current !== null) {
+            cancelAnimationFrame(rafRef.current)
+            rafRef.current = null
+          }
         }
-      }
 
-      const { workspaceId: _w, sessionId: _s, ...rest } = msg
-      messagesRef.current = [...messagesRef.current, rest as CliAgentMessage]
-      tick()
-    }))
+        const { workspaceId: _w, sessionId: _s, ...rest } = msg
+        messagesRef.current = [...messagesRef.current, rest as CliAgentMessage]
+        tick()
+      }),
+    )
     return unsub
   }, [workspaceId, tick])
 
   // Subscribe to status changes
   useEffect(() => {
-    const unsub = window.api.onCliAgentStatus(scopedTo<CliAgentStatusPayload>(workspaceId, (status) => {
-      if (status.sessionId !== sessionIdRef.current) return
-      setProcessStatus(status.processStatus)
-      if (status.error) setLastError(status.error)
-    }))
+    const unsub = window.api.onCliAgentStatus(
+      scopedTo<CliAgentStatusPayload>(workspaceId, (status) => {
+        if (status.sessionId !== sessionIdRef.current) return
+        setProcessStatus(status.processStatus)
+        if (status.error) setLastError(status.error)
+      }),
+    )
     return unsub
   }, [workspaceId])
 
@@ -231,44 +247,52 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     }
   }, [])
 
-  const start = useCallback(async (backend: AgentBackend) => {
-    if (!workspaceId) return
+  const start = useCallback(
+    async (backend: AgentBackend) => {
+      if (!workspaceId) return
 
-    // New chat: clear local state. Resuming (conversationId set): main loads history; we hydrate after start.
-    if (!conversationId) {
-      messagesRef.current = []
-    }
-    streamingContentRef.current = ''
-    setStreamingContent('')
-    setStreamingMessageId(null)
-    setLastError(null)
-    tick()
+      // New chat: clear local state. Resuming (conversationId set): main loads history; we hydrate after start.
+      if (!conversationId) {
+        messagesRef.current = []
+      }
+      streamingContentRef.current = ''
+      setStreamingContent('')
+      setStreamingMessageId(null)
+      setLastError(null)
+      tick()
 
-    const result = await window.api.cliAgentStart(workspaceId, backend, conversationId, worktreePath)
-    if ('error' in result) {
-      setLastError(result.error)
-      setProcessStatus('error')
-    } else {
-      sessionIdRef.current = result.sessionId
-      setActiveBackend(backend)
-      const session = await window.api.cliAgentGetSession(workspaceId, result.sessionId)
-      if (session) {
-        // Main starts native / external sessions with [] until first send; keep hydrated history.
-        if (session.messages.length > 0) {
-          messagesRef.current = session.messages
+      const result = await window.api.cliAgentStart(
+        workspaceId,
+        backend,
+        conversationId,
+        worktreePath,
+      )
+      if ('error' in result) {
+        setLastError(result.error)
+        setProcessStatus('error')
+      } else {
+        sessionIdRef.current = result.sessionId
+        setActiveBackend(backend)
+        const session = await window.api.cliAgentGetSession(workspaceId, result.sessionId)
+        if (session) {
+          // Main starts native / external sessions with [] until first send; keep hydrated history.
+          if (session.messages.length > 0) {
+            messagesRef.current = session.messages
+          }
+          setProcessStatus(session.processStatus)
+          setModel(session.model ?? null)
+          setLastError(session.lastError ?? null)
+          const ab = session.activeBackend ?? session.backend ?? backend
+          setActiveBackend(ab)
+          setBackendState(extractBackendState(session, ab))
+          if (typeof session.totalCostUsd === 'number') setTotalCostUsd(session.totalCostUsd)
+          if (session.totalTokens) setTotalTokens(session.totalTokens)
         }
-        setProcessStatus(session.processStatus)
-        setModel(session.model ?? null)
-        setLastError(session.lastError ?? null)
-        const ab = session.activeBackend ?? session.backend ?? backend
-        setActiveBackend(ab)
-        setBackendState(extractBackendState(session, ab))
-        if (typeof session.totalCostUsd === 'number') setTotalCostUsd(session.totalCostUsd)
-        if (session.totalTokens) setTotalTokens(session.totalTokens)
+        tick()
       }
-      tick()
-    }
-  }, [workspaceId, conversationId, worktreePath, tick])
+    },
+    [workspaceId, conversationId, worktreePath, tick],
+  )
 
   const updateSessionConfig = useCallback(
     async (patch: Partial<CliAgentBackendState>): Promise<boolean> => {
@@ -278,7 +302,10 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
       // (main only emits a status event afterwards, which doesn't carry
       // backend-state, so we cannot rely on a roundtrip refresh).
       setBackendState((prev) => ({ ...(prev ?? {}), ...patch }))
-      const result = await window.api.cliAgentUpdateSessionConfig(sid, patch as Record<string, unknown>)
+      const result = await window.api.cliAgentUpdateSessionConfig(
+        sid,
+        patch as Record<string, unknown>,
+      )
       if (result.error) {
         setLastError(result.error)
         return false
@@ -302,14 +329,14 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
     return true
   }, [])
 
-  const send = useCallback(async (content: string) => {
+  const send = useCallback(async (payload: ChatComposerSubmission) => {
     const sid = sessionIdRef.current
-    if (!sid || !content.trim()) return
+    if (!sid || (!payload.text.trim() && payload.mentionedFiles.length === 0)) return
 
     streamingContentRef.current = ''
     setStreamingContent('')
 
-    const result = await window.api.cliAgentSend(sid, content.trim())
+    const result = await window.api.cliAgentSend(sid, payload)
     if ('error' in result) {
       setLastError(result.error)
     }
@@ -355,7 +382,11 @@ export function useCliAgent(options: UseCliAgentOptions): UseCliAgentReturn {
  * backend yet (e.g. fresh session, no overrides applied).
  */
 function extractBackendState(
-  session: { activeBackend?: AgentBackend; backend?: AgentBackend; backendStates?: Record<string, CliAgentBackendState> | undefined },
+  session: {
+    activeBackend?: AgentBackend
+    backend?: AgentBackend
+    backendStates?: Record<string, CliAgentBackendState> | undefined
+  },
   active: AgentBackend | null,
 ): CliAgentBackendState | null {
   const key = active ?? session.activeBackend ?? session.backend
diff --git a/packages/renderer/src/lib/chatComposer.ts b/packages/renderer/src/lib/chatComposer.ts
new file mode 100644
index 0000000..9321c40
--- /dev/null
+++ b/packages/renderer/src/lib/chatComposer.ts
@@ -0,0 +1,126 @@
+import type { ChatComposerSubmission } from '@aide/shared'
+
+export interface ChatAutocompleteCommand {
+  id: string
+  label: string
+  description: string
+  promptHint: string
+}
+
+export interface ComposerTriggerMatch {
+  kind: 'file' | 'command'
+  query: string
+  start: number
+  end: number
+}
+
+export const CHAT_AUTOCOMPLETE_COMMANDS: readonly ChatAutocompleteCommand[] = [
+  {
+    id: 'plan',
+    label: '/plan',
+    description: 'Plan before coding',
+    promptHint: 'Create a short implementation plan before making changes.',
+  },
+  {
+    id: 'explain',
+    label: '/explain',
+    description: 'Explain code or behavior',
+    promptHint: 'Focus on explaining the relevant code and behavior clearly.',
+  },
+  {
+    id: 'fix',
+    label: '/fix',
+    description: 'Focus on bug fixing',
+    promptHint: 'Focus on identifying the root cause and implementing a fix.',
+  },
+  {
+    id: 'tests',
+    label: '/tests',
+    description: 'Focus on tests',
+    promptHint: 'Focus on adding or updating the smallest useful tests for this work.',
+  },
+] as const
+
+function scoreMatch(query: string, value: string): number | null {
+  if (!query) return 0
+  const q = query.toLowerCase()
+  const v = value.toLowerCase()
+  const direct = v.indexOf(q)
+  if (direct >= 0) return direct
+
+  let qi = 0
+  let score = 0
+  for (let vi = 0; vi < v.length && qi < q.length; vi++) {
+    if (v[vi] === q[qi]) {
+      score += vi === 0 || v[vi - 1] === '/' || v[vi - 1] === '-' || v[vi - 1] === '_' ? 2 : 1
+      qi += 1
+    }
+  }
+  return qi === q.length ? 1000 - score : null
+}
+
+export function getComposerTrigger(text: string, cursor: number): ComposerTriggerMatch | null {
+  const beforeCursor = text.slice(0, cursor)
+  const token = /(^|\s)([@/])([^\s@]*)$/.exec(beforeCursor)
+  if (!token) return null
+
+  const marker = token[2]
+  const query = token[3] ?? ''
+  const start = cursor - query.length - 1
+  if (start < 0) return null
+  if (marker === '/' && query.includes('/')) return null
+  if (marker === '/' && start !== 0) return null
+
+  return {
+    kind: marker === '@' ? 'file' : 'command',
+    query,
+    start,
+    end: cursor,
+  }
+}
+
+export function filterFileSuggestions(files: string[], query: string, limit = 8): string[] {
+  return files
+    .map((file) => ({
+      file,
+      score: scoreMatch(query, `${file.split('/').pop() ?? file} ${file}`),
+    }))
+    .filter((entry): entry is { file: string; score: number } => entry.score !== null)
+    .sort((a, b) => a.score - b.score || a.file.localeCompare(b.file))
+    .slice(0, limit)
+    .map((entry) => entry.file)
+}
+
+export function filterCommandSuggestions(
+  commands: readonly ChatAutocompleteCommand[],
+  query: string,
+  limit = 6,
+): ChatAutocompleteCommand[] {
+  return commands
+    .map((command) => ({
+      command,
+      score: scoreMatch(query, `${command.id} ${command.label} ${command.description}`),
+    }))
+    .filter(
+      (entry): entry is { command: ChatAutocompleteCommand; score: number } => entry.score !== null,
+    )
+    .sort((a, b) => a.score - b.score || a.command.label.localeCompare(b.command.label))
+    .slice(0, limit)
+    .map((entry) => entry.command)
+}
+
+export function buildComposerSubmission(
+  text: string,
+  mentionedFiles: string[],
+): ChatComposerSubmission {
+  const rawText = text.trim()
+  const commandMatch = /^\/(\w+)\b\s*/.exec(rawText)
+  const commandId = commandMatch?.[1]
+  const normalizedText = commandMatch ? rawText.slice(commandMatch[0].length).trim() : rawText
+  return {
+    text: normalizedText,
+    rawText,
+    mentionedFiles: Array.from(new Set(mentionedFiles)),
+    commandId,
+  }
+}
diff --git a/packages/renderer/src/styles/chat-pane.css b/packages/renderer/src/styles/chat-pane.css
index 1453c24..ec12eed 100644
--- a/packages/renderer/src/styles/chat-pane.css
+++ b/packages/renderer/src/styles/chat-pane.css
@@ -170,8 +170,13 @@
 }
 
 @keyframes chat-cursor-blink {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0; }
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
 }
 
 /* --- Working Set ------------------------------------------------ */
@@ -442,7 +447,30 @@
   background: var(--bg-elevated);
 }
 
+.chat-input-wrap {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.chat-input__chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+
+.chat-input__chip {
+  border: 1px solid color-mix(in srgb, var(--accent) 35%, var(--border-subtle));
+  background: color-mix(in srgb, var(--accent) 12%, var(--bg-sunken));
+  color: var(--text-primary);
+  border-radius: 999px;
+  padding: 4px 10px;
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
 .chat-input {
+  position: relative;
   display: flex;
   align-items: flex-end;
   gap: var(--space-3);
@@ -477,15 +505,83 @@
   color: var(--text-muted);
 }
 
+.chat-input__suggestions {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: calc(100% + var(--space-2));
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: var(--space-2);
+  border: 1px solid var(--border-base);
+  border-radius: var(--radius-lg);
+  background: var(--bg-elevated);
+  box-shadow: var(--shadow-lg);
+  max-height: 240px;
+  overflow: auto;
+  z-index: 20;
+}
+
+.chat-input__suggestion {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  width: 100%;
+  border: none;
+  border-radius: var(--radius-md);
+  background: transparent;
+  color: var(--text-primary);
+  padding: 8px 10px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.chat-input__suggestion:hover,
+.chat-input__suggestion--active {
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+
+.chat-input__suggestion-label {
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+}
+
+.chat-input__suggestion-detail {
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
+}
+
 /* --- Syntax highlight tokens (inherit from themes) -------------- */
 
-.chat-msg--assistant .chat-msg__body .hljs-keyword { color: var(--syntax-keyword); }
-.chat-msg--assistant .chat-msg__body .hljs-title.function_ { color: var(--syntax-fn); }
-.chat-msg--assistant .chat-msg__body .hljs-string { color: var(--syntax-string); }
-.chat-msg--assistant .chat-msg__body .hljs-number { color: var(--syntax-number); }
-.chat-msg--assistant .chat-msg__body .hljs-comment { color: var(--syntax-comment); }
-.chat-msg--assistant .chat-msg__body .hljs-tag { color: var(--syntax-tag); }
-.chat-msg--assistant .chat-msg__body .hljs-attr { color: var(--syntax-attr); }
-.chat-msg--assistant .chat-msg__body .hljs-built_in { color: var(--syntax-fn); }
-.chat-msg--assistant .chat-msg__body .hljs-literal { color: var(--syntax-number); }
-.chat-msg--assistant .chat-msg__body .hljs-type { color: var(--syntax-keyword); }
+.chat-msg--assistant .chat-msg__body .hljs-keyword {
+  color: var(--syntax-keyword);
+}
+.chat-msg--assistant .chat-msg__body .hljs-title.function_ {
+  color: var(--syntax-fn);
+}
+.chat-msg--assistant .chat-msg__body .hljs-string {
+  color: var(--syntax-string);
+}
+.chat-msg--assistant .chat-msg__body .hljs-number {
+  color: var(--syntax-number);
+}
+.chat-msg--assistant .chat-msg__body .hljs-comment {
+  color: var(--syntax-comment);
+}
+.chat-msg--assistant .chat-msg__body .hljs-tag {
+  color: var(--syntax-tag);
+}
+.chat-msg--assistant .chat-msg__body .hljs-attr {
+  color: var(--syntax-attr);
+}
+.chat-msg--assistant .chat-msg__body .hljs-built_in {
+  color: var(--syntax-fn);
+}
+.chat-msg--assistant .chat-msg__body .hljs-literal {
+  color: var(--syntax-number);
+}
+.chat-msg--assistant .chat-msg__body .hljs-type {
+  color: var(--syntax-keyword);
+}
diff --git a/packages/renderer/src/styles/cli-agent-pane.css b/packages/renderer/src/styles/cli-agent-pane.css
index 9283a32..30821bf 100644
--- a/packages/renderer/src/styles/cli-agent-pane.css
+++ b/packages/renderer/src/styles/cli-agent-pane.css
@@ -195,7 +195,55 @@
   line-height: 1.5;
 }
 
-.cli-agent-msg--assistant code {
+.cli-agent-msg--assistant .cli-agent-msg__body {
+  white-space: normal;
+}
+
+.cli-agent-msg__markdown p {
+  margin: 0 0 var(--space-3) 0;
+}
+
+.cli-agent-msg__markdown p:last-child {
+  margin-bottom: 0;
+}
+
+.cli-agent-msg__markdown h1,
+.cli-agent-msg__markdown h2,
+.cli-agent-msg__markdown h3,
+.cli-agent-msg__markdown h4,
+.cli-agent-msg__markdown h5,
+.cli-agent-msg__markdown h6 {
+  margin: var(--space-4) 0 var(--space-2);
+  line-height: 1.25;
+}
+
+.cli-agent-msg__markdown ul,
+.cli-agent-msg__markdown ol {
+  margin: var(--space-2) 0;
+  padding-left: var(--space-5);
+}
+
+.cli-agent-msg__markdown li + li {
+  margin-top: 2px;
+}
+
+.cli-agent-msg__markdown blockquote {
+  margin: var(--space-3) 0;
+  padding-left: var(--space-3);
+  border-left: 2px solid var(--border-subtle);
+  color: var(--text-secondary);
+}
+
+.cli-agent-msg__markdown a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.cli-agent-msg__markdown a:hover {
+  text-decoration: underline;
+}
+
+.cli-agent-msg__markdown code {
   background: var(--bg-sunken);
   padding: 1px 4px;
   border-radius: var(--radius-sm);
@@ -203,7 +251,7 @@
   font-family: var(--font-mono);
 }
 
-.cli-agent-msg--assistant pre {
+.cli-agent-msg__markdown pre {
   background: var(--bg-sunken);
   border: 1px solid var(--border-subtle);
   padding: var(--space-3);
@@ -213,6 +261,12 @@
   font-family: var(--font-mono);
 }
 
+.cli-agent-msg__markdown :not(pre) > code {
+  background: var(--bg-sunken);
+  padding: 1px var(--space-2);
+  border-radius: var(--radius-sm);
+}
+
 .cli-agent-msg__cursor {
   animation: cli-agent-cursor-blink 0.8s step-end infinite;
   color: var(--accent);
@@ -306,3 +360,34 @@
   color: var(--text-warning);
   background: color-mix(in srgb, var(--text-warning) 14%, transparent);
 }
+
+/* --- Reasoning (editorial whisper) ------------------------------- */
+/* Always visible. Smaller, italic, muted — sits beside the assistant
+   stream like a marginal annotation rather than a card. */
+.cli-agent-msg--reasoning {
+  display: block;
+  margin: 2px 0 6px;
+  padding: 2px 0 2px 14px;
+  border-left: 1px solid color-mix(in srgb, var(--text-secondary) 35%, transparent);
+  font-family: ui-serif, 'New York', 'Charter', 'Source Serif Pro', 'Hoefler Text', serif;
+  font-style: italic;
+  font-size: 12px;
+  line-height: 1.55;
+  color: color-mix(in srgb, var(--text-secondary) 88%, transparent);
+  letter-spacing: 0.005em;
+}
+
+.cli-agent-msg--reasoning__body > :first-child { margin-top: 0; }
+.cli-agent-msg--reasoning__body > :last-child  { margin-bottom: 0; }
+
+.cli-agent-msg--reasoning__body p {
+  margin: 0 0 4px;
+}
+
+.cli-agent-msg--reasoning__body code {
+  font-style: normal;
+  font-size: 10px;
+  padding: 0 3px;
+  border-radius: 2px;
+  background: color-mix(in srgb, var(--text-secondary) 10%, transparent);
+}
diff --git a/packages/shared/src/agentTypes.ts b/packages/shared/src/agentTypes.ts
index e9bf550..ccc0b56 100644
--- a/packages/shared/src/agentTypes.ts
+++ b/packages/shared/src/agentTypes.ts
@@ -27,10 +27,21 @@ export interface ToolResult {
   isError: boolean
 }
 
+export interface ChatComposerSubmission {
+  text: string
+  rawText?: string
+  mentionedFiles: string[]
+  commandId?: string
+}
+
 export interface ChatMessage {
   id: string
   role: 'user' | 'assistant' | 'tool_result'
   content: string
+  /** Prompt text after aIDE expands slash commands or file mentions. */
+  contextualContent?: string
+  mentionedFiles?: string[]
+  commandId?: string
   timestamp: number
   toolCalls?: ToolCall[]
   toolResults?: ToolResult[]
diff --git a/packages/shared/src/cliAgentTypes.ts b/packages/shared/src/cliAgentTypes.ts
index cb46670..9947d64 100644
--- a/packages/shared/src/cliAgentTypes.ts
+++ b/packages/shared/src/cliAgentTypes.ts
@@ -97,6 +97,10 @@ export interface CliAgentMessage {
   id: string
   type: CliAgentMessageType
   content: string
+  /** Prompt text after aIDE expands slash commands or file mentions. */
+  contextualContent?: string
+  mentionedFiles?: string[]
+  commandId?: string
   timestamp: number
   /** Which backend produced this message (set on external-agent messages). */
   backend?: ExternalCliBackend
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index c2e6db4..7bcc2ec 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -17,6 +17,7 @@ export type {
   ToolCallStatus,
   ToolCall,
   ToolResult,
+  ChatComposerSubmission,
   ChatMessage,
   ChatSession,
   ChatStreamChunk,
@@ -89,6 +90,7 @@ export type {
 } from './llmTypes'
 import type {
   ChatMode,
+  ChatComposerSubmission,
   ChatSession,
   ChatStreamChunk,
   ChatStreamEnd,
@@ -1150,7 +1152,7 @@ export interface WindowApi {
   // ─── Agent Chat ───────────────────────────────
   chatSendMessage: (
     sessionId: string,
-    content: string,
+    payload: ChatComposerSubmission,
   ) => Promise<{ messageId: string } | { error: string }>
   chatGetHistory: (workspaceId: string, conversationId?: string) => Promise<ChatSession | null>
   chatSetMode: (sessionId: string, mode: ChatMode) => Promise<void>
@@ -1183,7 +1185,7 @@ export interface WindowApi {
   cliAgentStop: (sessionId: string) => void
   cliAgentSend: (
     sessionId: string,
-    content: string,
+    payload: ChatComposerSubmission,
   ) => Promise<{ success: true } | { error: string }>
   cliAgentGetSession: (workspaceId: string, sessionId?: string) => Promise<CliAgentSession | null>
   cliAgentLoadMessages: (workspaceId: string, conversationId: string) => Promise<CliAgentMessage[]>
@@ -1201,11 +1203,7 @@ export interface WindowApi {
   cliAgentListProviders: (sessionId: string) => Promise<unknown>
   cliAgentListAgents: (sessionId: string) => Promise<unknown>
   cliAgentListModes: (sessionId: string) => Promise<unknown>
-  cliAgentListTools: (
-    sessionId: string,
-    providerID: string,
-    modelID: string,
-  ) => Promise<unknown>
+  cliAgentListTools: (sessionId: string, providerID: string, modelID: string) => Promise<unknown>
 
   // ─── CLI Agent: session ops ────────────────────
   cliAgentSessionShare: (sessionId: string) => Promise<{ url?: string; error?: string }>
@@ -1227,13 +1225,31 @@ export interface WindowApi {
   cliAgentSessionDeleteRemote: (sessionId: string) => Promise<{ success?: true; error?: string }>
 
   // ─── CLI Agent: workspace ops ──────────────────
-  cliAgentFileList: (sessionId: string, path: string) => Promise<{ entries?: unknown; error?: string }>
-  cliAgentFileRead: (sessionId: string, path: string) => Promise<{ content?: string; error?: string }>
+  cliAgentFileList: (
+    sessionId: string,
+    path: string,
+  ) => Promise<{ entries?: unknown; error?: string }>
+  cliAgentFileRead: (
+    sessionId: string,
+    path: string,
+  ) => Promise<{ content?: string; error?: string }>
   cliAgentFileStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
-  cliAgentFindText: (sessionId: string, query: string) => Promise<{ results?: unknown; error?: string }>
-  cliAgentFindFiles: (sessionId: string, pattern: string) => Promise<{ paths?: unknown; error?: string }>
-  cliAgentFindSymbols: (sessionId: string, query: string) => Promise<{ symbols?: unknown; error?: string }>
-  cliAgentShellRun: (sessionId: string, command: string) => Promise<{ result?: unknown; error?: string }>
+  cliAgentFindText: (
+    sessionId: string,
+    query: string,
+  ) => Promise<{ results?: unknown; error?: string }>
+  cliAgentFindFiles: (
+    sessionId: string,
+    pattern: string,
+  ) => Promise<{ paths?: unknown; error?: string }>
+  cliAgentFindSymbols: (
+    sessionId: string,
+    query: string,
+  ) => Promise<{ symbols?: unknown; error?: string }>
+  cliAgentShellRun: (
+    sessionId: string,
+    command: string,
+  ) => Promise<{ result?: unknown; error?: string }>
   cliAgentLspStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
   cliAgentFormatterStatus: (sessionId: string) => Promise<{ status?: unknown; error?: string }>
 
diff --git a/tests/unit/agentManager.test.ts b/tests/unit/agentManager.test.ts
index 6ad1920..f7fe877 100644
--- a/tests/unit/agentManager.test.ts
+++ b/tests/unit/agentManager.test.ts
@@ -28,8 +28,8 @@ vi.mock('@main/toolRegistry', () => ({
   })),
 }))
 
-import { AgentManager } from '@main/agentManager'
-import type { ChatSession, ChatMessage, LlmProviderConfig } from '@shared/agentTypes'
+import { AgentManager } from '@main/chat/agentManager'
+import type { ChatSession, ChatMessage, LlmProviderConfig } from '@aide/shared'
 
 // ─── Helpers ───────────────────────────────────────────────────────
 
@@ -67,9 +67,23 @@ describe('AgentManager.buildLlmMessages', () => {
       timestamp: Date.now(),
     })
 
+    const result = manager.buildLlmMessages(session)
+    expect(result).toEqual([{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }])
+  })
+
+  it('prefers contextualContent for user messages', async () => {
+    const session = await manager.getHistory('ws1')
+    session.messages.push({
+      id: 'msg1',
+      role: 'user',
+      content: '/plan fix the bug',
+      contextualContent: 'Requested mode: /plan\n\nFix the bug.',
+      timestamp: Date.now(),
+    })
+
     const result = manager.buildLlmMessages(session)
     expect(result).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'Hello' }] },
+      { role: 'user', content: [{ type: 'text', text: 'Requested mode: /plan\n\nFix the bug.' }] },
     ])
   })
 
@@ -83,9 +97,7 @@ describe('AgentManager.buildLlmMessages', () => {
     })
 
     const result = manager.buildLlmMessages(session)
-    expect(result).toEqual([
-      { role: 'assistant', content: [{ type: 'text', text: 'Hi there' }] },
-    ])
+    expect(result).toEqual([{ role: 'assistant', content: [{ type: 'text', text: 'Hi there' }] }])
   })
 
   it('converts an assistant message with tool calls', async () => {
@@ -120,9 +132,7 @@ describe('AgentManager.buildLlmMessages', () => {
       role: 'tool_result',
       content: '',
       timestamp: Date.now(),
-      toolResults: [
-        { toolCallId: 'tc1', output: 'file contents here', isError: false },
-      ],
+      toolResults: [{ toolCallId: 'tc1', output: 'file contents here', isError: false }],
     })
 
     const result = manager.buildLlmMessages(session)
@@ -138,11 +148,19 @@ describe('AgentManager.buildLlmMessages', () => {
     session.messages.push(
       { id: '1', role: 'user', content: 'Read test.ts', timestamp: 1 },
       {
-        id: '2', role: 'assistant', content: '', timestamp: 2,
-        toolCalls: [{ id: 'tc1', name: 'file_read', input: { path: 'test.ts' }, status: 'completed' }],
+        id: '2',
+        role: 'assistant',
+        content: '',
+        timestamp: 2,
+        toolCalls: [
+          { id: 'tc1', name: 'file_read', input: { path: 'test.ts' }, status: 'completed' },
+        ],
       },
       {
-        id: '3', role: 'tool_result', content: '', timestamp: 3,
+        id: '3',
+        role: 'tool_result',
+        content: '',
+        timestamp: 3,
         toolResults: [{ toolCallId: 'tc1', output: 'console.log("hi")', isError: false }],
       },
       { id: '4', role: 'assistant', content: 'The file logs "hi".', timestamp: 4 },
@@ -286,7 +304,12 @@ describe('AgentManager approval gate', () => {
 
     // Access private method via type cast for testing
     const mgr = manager as any
-    const approvalPromise = mgr.waitForApproval({ id: 'tc1', name: 'file_read', input: {}, status: 'pending' })
+    const approvalPromise = mgr.waitForApproval({
+      id: 'tc1',
+      name: 'file_read',
+      input: {},
+      status: 'pending',
+    })
 
     // Approve it
     manager.approveToolCall(session.id, 'tc1')
@@ -299,7 +322,12 @@ describe('AgentManager approval gate', () => {
     const session = await manager.getHistory('ws1')
 
     const mgr = manager as any
-    const approvalPromise = mgr.waitForApproval({ id: 'tc2', name: 'file_write', input: {}, status: 'pending' })
+    const approvalPromise = mgr.waitForApproval({
+      id: 'tc2',
+      name: 'file_write',
+      input: {},
+      status: 'pending',
+    })
 
     manager.rejectToolCall(session.id, 'tc2')
 
diff --git a/tests/unit/chatComposer.test.ts b/tests/unit/chatComposer.test.ts
new file mode 100644
index 0000000..0b6ebd5
--- /dev/null
+++ b/tests/unit/chatComposer.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildComposerSubmission,
+  CHAT_AUTOCOMPLETE_COMMANDS,
+  filterCommandSuggestions,
+  filterFileSuggestions,
+  getComposerTrigger,
+} from '@renderer/lib/chatComposer'
+
+describe('chatComposer helpers', () => {
+  it('detects @file triggers at the cursor', () => {
+    expect(getComposerTrigger('inspect @src/Cha', 'inspect @src/Cha'.length)).toEqual({
+      kind: 'file',
+      query: 'src/Cha',
+      start: 8,
+      end: 16,
+    })
+  })
+
+  it('detects slash commands only at the start of the prompt', () => {
+    expect(getComposerTrigger('/pl', 3)).toEqual({
+      kind: 'command',
+      query: 'pl',
+      start: 0,
+      end: 3,
+    })
+    expect(getComposerTrigger('please /pl', 'please /pl'.length)).toBeNull()
+  })
+
+  it('builds a structured submission from slash-command text and mentioned files', () => {
+    expect(buildComposerSubmission('/plan fix the broken tests', ['src/app.tsx'])).toEqual({
+      text: 'fix the broken tests',
+      rawText: '/plan fix the broken tests',
+      mentionedFiles: ['src/app.tsx'],
+      commandId: 'plan',
+    })
+  })
+
+  it('filters file suggestions by basename and path', () => {
+    expect(filterFileSuggestions(['src/components/ChatInput.tsx', 'src/App.tsx'], 'chat')).toEqual([
+      'src/components/ChatInput.tsx',
+    ])
+  })
+
+  it('filters command suggestions from the shared command list', () => {
+    expect(filterCommandSuggestions(CHAT_AUTOCOMPLETE_COMMANDS, 'tes')[0]?.id).toBe('tests')
+  })
+})
diff --git a/tests/unit/chatComposerContext.test.ts b/tests/unit/chatComposerContext.test.ts
new file mode 100644
index 0000000..912dec9
--- /dev/null
+++ b/tests/unit/chatComposerContext.test.ts
@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtemp, rm, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { buildComposerContext } from '@main/chat/chatComposerContext'
+
+describe('buildComposerContext', () => {
+  let rootPath: string | null = null
+
+  afterEach(async () => {
+    if (rootPath) {
+      await rm(rootPath, { recursive: true, force: true })
+      rootPath = null
+    }
+  })
+
+  it('adds slash-command instructions and referenced file contents', async () => {
+    rootPath = await mkdtemp(join(tmpdir(), 'aide-chat-composer-'))
+    await writeFile(join(rootPath, 'notes.txt'), 'hello from context', 'utf-8')
+
+    const result = await buildComposerContext(
+      {
+        text: 'fix this flow',
+        rawText: '/fix fix this flow',
+        mentionedFiles: ['notes.txt'],
+        commandId: 'fix',
+      },
+      rootPath,
+    )
+
+    expect(result.commandId).toBe('fix')
+    expect(result.mentionedFiles).toEqual(['notes.txt'])
+    expect(result.contextualContent).toContain('Requested mode: /fix')
+    expect(result.contextualContent).toContain('Referenced files:')
+    expect(result.contextualContent).toContain('hello from context')
+    expect(result.contextualContent).toContain('fix this flow')
+  })
+
+  it('drops mentioned files that escape the workspace root', async () => {
+    rootPath = await mkdtemp(join(tmpdir(), 'aide-chat-composer-'))
+
+    const result = await buildComposerContext(
+      {
+        text: 'explain the issue',
+        mentionedFiles: ['../secret.txt', 'safe.ts'],
+      },
+      rootPath,
+    )
+
+    expect(result.mentionedFiles).toEqual(['safe.ts'])
+    expect(result.contextualContent).toContain('safe.ts')
+    expect(result.contextualContent).not.toContain('secret.txt')
+  })
+})
diff --git a/tests/unit/cliAgentManager.test.ts b/tests/unit/cliAgentManager.test.ts
index e566f1d..8c57af1 100644
--- a/tests/unit/cliAgentManager.test.ts
+++ b/tests/unit/cliAgentManager.test.ts
@@ -156,7 +156,11 @@ describe('CliAgentManager', () => {
     const started = await manager.start('ws-1', 'claude-code')
     if ('error' in started) throw new Error(started.error)
 
-    await manager.send(started.sessionId, 'hello from test')
+    await manager.send(started.sessionId, {
+      text: 'hello from test',
+      rawText: 'hello from test',
+      mentionedFiles: [],
+    })
 
     expect(queryMock).toHaveBeenCalledWith(
       expect.objectContaining({