@brimveyn/aimux 1.14.3 → 1.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.14.3",
+  "version": "1.14.4",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -60,7 +60,7 @@
     "bump": "bun run scripts/bump.ts"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.6.5",
+    "@brimveyn/aimux-config": "0.6.6",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/app-runtime/use-terminal-resize.ts

@@ -44,21 +44,26 @@ function resizeSplitTabs(
   tabIds: string[],
   cols: number,
   rows: number,
-  options?: { sync?: boolean }
+  options?: { sync?: boolean },
+  skipTabId?: string | null
 ): void {
   const bounds = getTerminalBounds(cols, rows)
   const resizedTabIds = new Set<string>()
 
   forEachSplitPaneRect(Object.values(layoutTrees), bounds, (tabId, rect) => {
+    if (skipTabId != null && tabId === skipTabId) {
+      resizedTabIds.add(tabId)
+      return
+    }
     const size = toTerminalContentSize(rect)
     backend.resizeTab(tabId, size.cols, size.rows, options)
     resizedTabIds.add(tabId)
   })
 
   for (const id of tabIds) {
-    if (!resizedTabIds.has(id)) {
-      backend.resizeTab(id, cols, rows, options)
-    }
+    if (resizedTabIds.has(id)) continue
+    if (skipTabId != null && id === skipTabId) continue
+    backend.resizeTab(id, cols, rows, options)
   }
 }
 
@@ -81,6 +86,12 @@ interface RunResizeCascadeArgs {
   layoutTrees: AppState['layoutTrees']
   stableTabIds: string[]
   sync: boolean
+  /** Tab whose backend resize is owned exclusively by `usePaneSizeReport`. The
+   *  cascade still dispatches the global terminal-size update and resizes every
+   *  other tab, but the active pane is left to be sized by its measurement —
+   *  preventing the open-loop chrome estimate from competing with the closed
+   *  measurement loop and tearing the rendered viewport. */
+  skipTabId: string | null
 }
 
 function runResizeCascade({
@@ -91,6 +102,7 @@ function runResizeCascade({
   resizingRef,
   resizingTimerRef,
   rows,
+  skipTabId,
   stableTabIds,
   sync,
 }: RunResizeCascadeArgs): void {
@@ -104,9 +116,14 @@ function runResizeCascade({
       clearTimeout(resizingTimerRef.current)
     }
     if (hasSplits) {
-      resizeSplitTabs(backend, layoutTrees, stableTabIds, cols, rows, options)
-    } else {
+      resizeSplitTabs(backend, layoutTrees, stableTabIds, cols, rows, options, skipTabId)
+    } else if (skipTabId == null) {
       backend.resizeAll(cols, rows, options)
+    } else {
+      for (const id of stableTabIds) {
+        if (id === skipTabId) continue
+        backend.resizeTab(id, cols, rows, options)
+      }
     }
     resizingTimerRef.current = setTimeout(() => {
       resizingRef.current = false
@@ -162,11 +179,16 @@ export function useTerminalResize({
         contentOriginRef.current = { cols, rows, x: rect.x, y: rect.y }
       }
       const prev = measuredRef.current.get(tabId)
-      if (prev && prev.cols === cols && prev.rows === rows) {
+      if (prev !== undefined && prev.cols === cols && prev.rows === rows) {
         return
       }
+      // First measurement for this tab: even if it happens to match the
+      // open-loop bootstrap size, we still call resizeTab so the backend
+      // gate (snapshot suppression until measurement confirms the pane
+      // size) is lifted. confirmedFromMeasurement marks this call as the
+      // authoritative size for the rendered viewport.
       measuredRef.current.set(tabId, { cols, rows })
-      backend.resizeTab(tabId, cols, rows)
+      backend.resizeTab(tabId, cols, rows, { confirmedFromMeasurement: true })
     },
     [backend, contentOriginRef]
   )
@@ -222,6 +244,7 @@ export function useTerminalResize({
       resizingRef,
       resizingTimerRef,
       rows: terminalSize.rows,
+      skipTabId: activeTabIdRef.current ?? null,
       stableTabIds,
       sync: true,
     })
@@ -249,6 +272,7 @@ export function useTerminalResize({
       resizingRef,
       resizingTimerRef,
       rows: terminalSize.rows,
+      skipTabId: activeTabIdRef.current ?? null,
       stableTabIds,
       sync: false,
     })

package/src/app.tsx

@@ -27,6 +27,7 @@ import { setActiveKeymap } from './input/keymap/keymap-ref'
 import { deriveModeId } from './input/modes/bridge'
 import { registerAllModes } from './input/modes/handlers'
 import { getHandler, transitionTo } from './input/modes/registry'
+import { ensureClaudeSettingsHooks } from './integrations/claude-hooks-install'
 import { highlightSnapshot, warmClaudeSyntaxOverlay } from './integrations/claude-syntax-overlay'
 import { ensureClaudeSettingsThemePref, syncClaudeTheme } from './integrations/claude-theme-sync'
 import { getProfileConfigDir, getProfileName } from './profile-paths'
@@ -191,6 +192,16 @@ export function App({
     })
   }, [resolvedConfig.theme?.beta?.harmonizeClaudeTheme])
 
+  useEffect(() => {
+    // Opt-in via `integrations.claudeHooks` in aimux.config.ts. When enabled,
+    // idempotently patches ~/.claude/settings.json so Claude Code's hooks
+    // call back into the daemon for per-tab activity detection. Silent on
+    // failure; the visual PTY detector is the fallback either way.
+    if (resolvedConfig.integrations.claudeHooks) {
+      ensureClaudeSettingsHooks()
+    }
+  }, [resolvedConfig.integrations.claudeHooks])
+
   useEffect(() => {
     const aiUsage = resolvedConfig.statusBar?.aiUsage
     if (!(aiUsage?.enabled === true)) {

package/src/daemon/daemon.ts

@@ -1,8 +1,10 @@
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs'
 import { connect, createServer, type Socket } from 'node:net'
 
 import type { AssistantId, TerminalSnapshot } from '../state/types'
 
 import { logDebug } from '../debug/input-log'
+import { type ClaudeHookServer, startClaudeHookServer } from '../integrations/claude-hook-server'
 import {
   type ClientRequest,
   encodeMessage,
@@ -19,6 +21,7 @@ import { findSocketProcessPid, spawnDetachedTerminalManager } from '../platform/
 import { type LoopTabView, runStatusDetectionLoop } from '../pty/assistant-status-detection-loop'
 import { TerminalManagerClient } from '../terminal-manager/manager-client'
 import {
+  getClaudeHookUrlFilePath,
   getIpcDaemonSocketPath,
   getSocketSecurityIssue,
   getTerminalManagerSocketPath,
@@ -282,6 +285,39 @@ export async function runDaemon(): Promise<void> {
     },
   })
 
+  // Local HTTP server that receives Claude Code hook callbacks for every PTY
+  // spawned by this daemon. We publish its URL to a stable file path that the
+  // shipped shell bridge reads on every invocation, so PTYs spawned by a
+  // *previous* daemon transparently follow URL changes after a restart.
+  // Failure to start is non-fatal — detection falls back to the visual PTY scanner.
+  let hookServer: ClaudeHookServer | null = null
+  const hookUrlFilePath = getClaudeHookUrlFilePath()
+  try {
+    hookServer = startClaudeHookServer({
+      onEvent: (event) => {
+        statusLoop.recordHookEvent({
+          hookEventName: event.hookEventName,
+          paneId: event.paneId,
+          payload: event.payload,
+          receivedAt: event.receivedAt,
+        })
+      },
+    })
+    try {
+      writeFileSync(hookUrlFilePath, hookServer.url, { mode: 0o600 })
+      logDebug('daemon.hookServer.started', { path: hookUrlFilePath, url: hookServer.url })
+    } catch (error) {
+      logDebug('daemon.hookServer.urlFileWriteFailed', {
+        error: error instanceof Error ? error.message : String(error),
+        path: hookUrlFilePath,
+      })
+    }
+  } catch (error) {
+    logDebug('daemon.hookServer.startFailed', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+
   /**
    * Tell the TM whether to bother snapshotting + broadcasting. Toggled on
    * 0↔1 transitions of the client socket count: when no UI is watching, the
@@ -454,7 +490,15 @@ export async function runDaemon(): Promise<void> {
                     message.payload.assistant,
                     [message.payload.command, ...(message.payload.args ?? [])].join(' ')
                   )
-                  await manager.createTab({ ...message.payload, sessionId })
+                  // Inject the hook bridge env so Claude Code's hooks can
+                  // call back into our status loop. Safe to add for every
+                  // assistant: non-Claude binaries simply ignore the vars.
+                  // We pass the URL *file path*, not the URL itself, so the
+                  // bridge can pick up a fresh URL after a daemon restart
+                  // even on PTYs that outlive this daemon process.
+                  const env: Record<string, string> = { AIMUX_PANE_ID: message.payload.tabId }
+                  if (hookServer) env.AIMUX_HOOK_URL_FILE = hookUrlFilePath
+                  await manager.createTab({ ...message.payload, env, sessionId })
                   sendOk(socket, message.id)
                   logDebug('daemon.request.createTab.success', {
                     sessionId,
@@ -577,6 +621,16 @@ export async function runDaemon(): Promise<void> {
   const gracefulShutdown = (signal: string) => {
     logDebug(`daemon.${signal}`)
     statusLoop.stop()
+    if (hookServer) {
+      void hookServer.stop()
+      try {
+        if (existsSync(hookUrlFilePath)) unlinkSync(hookUrlFilePath)
+      } catch (error) {
+        logDebug('daemon.hookServer.urlFileCleanupFailed', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
     manager.destroy()
     server.close()
     process.exit(0)

package/src/daemon/runtime-paths.ts

@@ -38,6 +38,15 @@ export function getTerminalManagerSocketPath(): string {
   return join(ensureRuntimeDir(), 'terminal-manager.sock')
 }
 
+/**
+ * File the daemon writes its current Claude hook server URL into. Stable path
+ * per profile, so PTYs spawned by a previous daemon can still resolve the
+ * URL of a freshly-restarted daemon by reading this file on every invocation.
+ */
+export function getClaudeHookUrlFilePath(): string {
+  return join(ensureRuntimeDir(), 'claude-hook.url')
+}
+
 export function ensureParentDir(filePath: string): void {
   mkdirSync(dirname(filePath), { recursive: true })
 }

package/src/daemon/session-registry.ts

@@ -129,6 +129,8 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
     cols: number
     rows: number
     cwd?: string
+    /** Extra env injected into the spawned shell. Passed through to the PTY. */
+    env?: Record<string, string>
   }): void {
     logDebug('daemon.registry.createSession', {
       args: options.args ?? [],

package/src/index.tsx

@@ -13,6 +13,7 @@ import { runRestartTerminalManager } from './restart-terminal-manager'
 import { createSessionBackend } from './session-backend/bootstrap'
 import { runTerminalManager } from './terminal-manager/terminal-manager'
 import { BreakingUpdateScreen } from './ui/breaking-update-screen'
+import { setHostPalette } from './ui/host-palette'
 import { runUpdate } from './update'
 
 const command = process.argv[2]
@@ -65,6 +66,19 @@ const renderer = await createCliRenderer({
   useMouse: true,
 })
 
+// Query the host terminal's actual ANSI palette (OSC 4) so PTY cells that
+// emit indexed colors render with the user's configured terminal theme
+// instead of hardcoded xterm defaults. Best-effort: terminals that don't
+// respond keep the fallback xterm palette.
+try {
+  const { palette } = await renderer.getPalette({ size: 256, timeout: 200 })
+  setHostPalette(palette)
+} catch (error) {
+  logDebug('index.paletteDetectFailed', {
+    message: error instanceof Error ? error.message : String(error),
+  })
+}
+
 const root = createRoot(renderer)
 
 const resolvedConfig = await loadUserConfig()

package/src/integrations/claude-hook-server.ts

@@ -0,0 +1,99 @@
+// Local HTTP server that receives Claude Code hook events from the shipped
+// shell bridge (assets/claude-hooks/aimux-agent-state.sh). Bound to 127.0.0.1
+// on an OS-assigned port; the URL is injected into each PTY via
+// `AIMUX_HOOK_URL` so the bridge knows where to POST.
+//
+// The body is the Claude hook payload (see https://code.claude.com/docs/en/hooks.md)
+// augmented with `aimuxPaneId` by the shell bridge. We forward minimal info
+// to the daemon's status loop, which performs the actual hook → activity
+// mapping in assistant-status-arbiter.
+
+import { logDebug } from '../debug/input-log'
+
+export interface ClaudeHookEvent {
+  paneId: string
+  hookEventName: string
+  /** Raw payload from Claude, keyed by hook event. */
+  payload: Record<string, unknown>
+  receivedAt: number
+}
+
+export interface ClaudeHookServer {
+  url: string
+  stop: () => Promise<void>
+}
+
+function pickString(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+/**
+ * Start the hook ingestion server. Throws if Bun.serve is unavailable (e.g.
+ * running under plain Node). The daemon catches that and logs — detection
+ * falls back to the visual PTY scanner.
+ */
+export function startClaudeHookServer(options: {
+  onEvent: (event: ClaudeHookEvent) => void
+}): ClaudeHookServer {
+  if (typeof Bun === 'undefined' || typeof Bun.serve !== 'function') {
+    throw new Error('claude-hook-server requires Bun.serve')
+  }
+
+  const handle = Bun.serve({
+    fetch: async (req) => {
+      const url = new URL(req.url)
+      if (req.method !== 'POST' || url.pathname !== '/hook/claude') {
+        return new Response('Not Found', { status: 404 })
+      }
+      let body: unknown
+      try {
+        body = await req.json()
+      } catch {
+        return new Response('Bad JSON', { status: 400 })
+      }
+      if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return new Response('Body must be an object', { status: 400 })
+      }
+      const record = body as Record<string, unknown>
+      const paneId = pickString(record.aimuxPaneId)
+      const hookEventName = pickString(record.hook_event_name)
+      if (paneId === '' || hookEventName === '') {
+        return new Response('Missing aimuxPaneId or hook_event_name', { status: 400 })
+      }
+      try {
+        options.onEvent({
+          hookEventName,
+          paneId,
+          payload: record,
+          receivedAt: Date.now(),
+        })
+      } catch (error) {
+        logDebug('claudeHookServer.dispatchError', {
+          error: error instanceof Error ? error.message : String(error),
+          hookEventName,
+          paneId,
+        })
+      }
+      return new Response('ok', { status: 200 })
+    },
+    hostname: '127.0.0.1',
+    port: 0,
+  })
+
+  const port = handle.port
+  const url = `http://127.0.0.1:${port}/hook/claude`
+  logDebug('claudeHookServer.listening', { url })
+
+  return {
+    stop: async () => {
+      try {
+        await handle.stop(true)
+      } catch (error) {
+        logDebug('claudeHookServer.stopError', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    },
+    url,
+  }
+}

package/src/integrations/claude-hooks-install.ts

@@ -0,0 +1,199 @@
+// Patch `~/.claude/settings.json` so Claude Code invokes aimux's hook bridge
+// for the lifecycle events that drive per-tab activity detection. Idempotent:
+// existing aimux entries (marked via `__aimux: true`) are replaced; unrelated
+// hooks the user has configured are preserved.
+//
+// Hooks reference: https://code.claude.com/docs/en/hooks.md
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { logDebug } from '../debug/input-log'
+
+const HOOK_EVENTS = [
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'SubagentStop',
+  'Notification',
+] as const
+
+type HookEvent = (typeof HOOK_EVENTS)[number]
+
+interface HookCommandEntry {
+  type: 'command'
+  command: string
+  __aimux?: true
+}
+
+interface HookGroupEntry {
+  matcher?: string
+  hooks: HookCommandEntry[]
+}
+
+function claudeDir(): string {
+  return join(homedir(), '.claude')
+}
+
+function settingsFilePath(): string {
+  return join(claudeDir(), 'settings.json')
+}
+
+function writeAtomic(target: string, contents: string): void {
+  const tmp = `${target}.aimux.tmp`
+  writeFileSync(tmp, contents, 'utf8')
+  try {
+    renameSync(tmp, target)
+  } catch (error) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      /* ignore */
+    }
+    throw error
+  }
+}
+
+function logSyncWarn(reason: string, details?: Record<string, unknown>): void {
+  logDebug('claude-hooks-install:warn', { reason, ...details })
+}
+
+/**
+ * Absolute path to the shipped hook script. Resolved from this module's URL so
+ * it works from the install directory regardless of how aimux was launched.
+ * Walks up from `src/integrations` / built equivalent until it finds the
+ * `assets/claude-hooks` directory.
+ */
+export function resolveHookScriptPath(): string | null {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const candidates = [
+    resolve(here, '..', '..', 'assets', 'claude-hooks', 'aimux-agent-state.sh'),
+    resolve(here, '..', '..', '..', 'assets', 'claude-hooks', 'aimux-agent-state.sh'),
+    resolve(here, '..', 'assets', 'claude-hooks', 'aimux-agent-state.sh'),
+  ]
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  logSyncWarn('hook-script-not-found', { candidates })
+  return null
+}
+
+function isHookCommandEntry(value: unknown): value is HookCommandEntry {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { type?: unknown }).type === 'command' &&
+    typeof (value as { command?: unknown }).command === 'string'
+  )
+}
+
+function isHookGroupEntry(value: unknown): value is HookGroupEntry {
+  if (typeof value !== 'object' || value === null) return false
+  const hooks = (value as { hooks?: unknown }).hooks
+  return Array.isArray(hooks)
+}
+
+function isAimuxEntry(entry: HookGroupEntry): boolean {
+  return entry.hooks.some((hook) => {
+    if (!isHookCommandEntry(hook)) return false
+    if (hook.__aimux === true) return true
+    return hook.command.includes('aimux-agent-state')
+  })
+}
+
+function buildAimuxEntry(event: HookEvent, scriptPath: string): HookGroupEntry {
+  // PreToolUse / PostToolUse expect a tool matcher. `*` matches every tool.
+  // The other events ignore `matcher` entirely.
+  const needsMatcher = event === 'PreToolUse' || event === 'PostToolUse'
+  return {
+    ...(needsMatcher ? { matcher: '*' } : {}),
+    hooks: [{ __aimux: true, command: scriptPath, type: 'command' }],
+  }
+}
+
+/**
+ * Idempotently install aimux hook entries into `~/.claude/settings.json`.
+ * Returns true when settings were written (or already correct), false on a
+ * hard failure that should be logged. Errors never throw — a failed install
+ * just means activity detection falls back to the visual detector.
+ */
+export function ensureClaudeSettingsHooks(): boolean {
+  const scriptPath = resolveHookScriptPath()
+  if (scriptPath === null || scriptPath === '') return false
+
+  const target = settingsFilePath()
+
+  let parsed: Record<string, unknown> = {}
+  if (existsSync(target)) {
+    let raw: string
+    try {
+      raw = readFileSync(target, 'utf8')
+    } catch (error) {
+      logSyncWarn('settings-read-failed', { err: String(error), path: target })
+      return false
+    }
+    if (raw.trim().length > 0) {
+      try {
+        const json = JSON.parse(raw) as unknown
+        if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+          logSyncWarn('settings-not-object', { path: target })
+          return false
+        }
+        parsed = json as Record<string, unknown>
+      } catch (error) {
+        logSyncWarn('settings-parse-failed', { err: String(error), path: target })
+        return false
+      }
+    }
+  }
+
+  const existingHooks = (
+    typeof parsed.hooks === 'object' && parsed.hooks !== null && !Array.isArray(parsed.hooks)
+      ? parsed.hooks
+      : {}
+  ) as Record<string, unknown>
+
+  const nextHooks: Record<string, HookGroupEntry[]> = {}
+  let changed = false
+
+  for (const event of HOOK_EVENTS) {
+    const raw = existingHooks[event]
+    const arr: HookGroupEntry[] = Array.isArray(raw) ? raw.filter(isHookGroupEntry) : []
+    const filtered = arr.filter((entry) => !isAimuxEntry(entry))
+    const desired = buildAimuxEntry(event, scriptPath)
+    const next = [...filtered, desired]
+    nextHooks[event] = next
+    if (!arraysShallowEqual(arr, next)) changed = true
+  }
+
+  // Preserve any non-aimux hook events the user already had.
+  for (const [event, value] of Object.entries(existingHooks)) {
+    if (HOOK_EVENTS.includes(event as HookEvent)) continue
+    if (Array.isArray(value)) nextHooks[event] = value as HookGroupEntry[]
+  }
+
+  if (!changed && parsed.hooks !== undefined) return true
+
+  parsed.hooks = nextHooks
+
+  try {
+    mkdirSync(claudeDir(), { recursive: true })
+    writeAtomic(target, `${JSON.stringify(parsed, null, 2)}\n`)
+    logDebug('claude-hooks-install:wrote', { events: HOOK_EVENTS, path: target, scriptPath })
+    return true
+  } catch (error) {
+    logSyncWarn('settings-write-failed', { err: String(error), path: target })
+    return false
+  }
+}
+
+function arraysShallowEqual<T>(a: T[], b: T[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return false
+  }
+  return true
+}

package/src/ipc/manager-protocol.ts

@@ -17,8 +17,23 @@ import {
 // `intent`/`intents` from resize messages and the `reapplyScrollIntent`
 // message. Min is raised in lockstep so a pre-v5 peer (which could still send
 // the dropped message) can't negotiate a now-incompatible version.
-export const MANAGER_PROTOCOL_MIN_VERSION = 5
-export const MANAGER_PROTOCOL_VERSION = 5
+//
+// v6: `createTab` carries an optional `env` payload that the TM merges into
+// the spawned PTY. Daemon uses it to inject `AIMUX_HOOK_URL_FILE` /
+// `AIMUX_PANE_ID` for the Claude Code hook bridge. A pre-v6 TM silently
+// drops the field, so Min is raised in lockstep to force a fresh TM that
+// will actually forward env to the spawn.
+//
+// v7: `TerminalSpan` carries optional `fgPalette`/`bgPalette` (ANSI 0-255
+// indices) instead of pre-converting palette cells to hex. The client
+// resolves them against the host terminal's actual palette (queried via
+// OSC 4 at startup) so user themes (Ghostty, iTerm2, …) show through
+// instead of hardcoded xterm defaults. Cross-version mixing breaks colors
+// either way (pre-v7 TM → new client never sees the indices; new TM →
+// pre-v7 client ignores them and falls back to the theme default), so Min
+// is raised in lockstep to force matching binaries.
+export const MANAGER_PROTOCOL_MIN_VERSION = 7
+export const MANAGER_PROTOCOL_VERSION = 7
 /**
  * Minimum version required to send `setBroadcastEnabled`. Older TMs (v3) will
  * not understand the message; the daemon must check the negotiated version
@@ -68,6 +83,8 @@ export type ManagerRequest =
         cols: number
         rows: number
         cwd?: string
+        /** Extra env vars merged into the spawned PTY's environment. */
+        env?: Record<string, string>
       }
     }
   | { id: string; type: 'write'; payload: { sessionId: string; tabId: string; data: string } }
@@ -147,12 +164,22 @@ function isStringArray(value: unknown): value is string[] {
   return Array.isArray(value) && value.every(isString)
 }
 
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!isObjectRecord(value)) return false
+  for (const v of Object.values(value)) {
+    if (!isString(v)) return false
+  }
+  return true
+}
+
 function isTerminalSpan(value: unknown): boolean {
   return (
     isObjectRecord(value) &&
     isString(value.text) &&
     (value.fg === undefined || isString(value.fg)) &&
     (value.bg === undefined || isString(value.bg)) &&
+    (value.fgPalette === undefined || isFiniteNumber(value.fgPalette)) &&
+    (value.bgPalette === undefined || isFiniteNumber(value.bgPalette)) &&
     (value.bold === undefined || typeof value.bold === 'boolean') &&
     (value.italic === undefined || typeof value.italic === 'boolean') &&
     (value.underline === undefined || typeof value.underline === 'boolean') &&
@@ -277,6 +304,10 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
         value.payload.cwd === undefined || isString(value.payload.cwd),
         'createTab.cwd must be a string'
       )
+      assert(
+        value.payload.env === undefined || isStringRecord(value.payload.env),
+        'createTab.env must be a string-keyed string record'
+      )
       return value as ManagerRequest
     case 'write':
       assert(isString(value.payload.sessionId), 'write.sessionId must be a string')

package/src/pty/assistant-status-arbiter.ts

@@ -0,0 +1,94 @@
+// Merges Claude Code hook events with the visual PTY detector. Hooks are
+// authoritative when fresh: they tell us exactly when a user prompt was
+// submitted, when a tool started or finished, and when Claude is idle. The
+// visual detector still runs every tick — its job is to catch states the
+// hooks don't reliably report (permission prompts that don't fire a
+// Notification, or stale "working" when the hook stream lags).
+//
+// Hooks reference: https://code.claude.com/docs/en/hooks.md
+
+import type { TabActivity } from '../state/types'
+
+/** How long a hook event keeps authority over the visual detector. */
+const HOOK_AUTHORITY_WINDOW_MS = 10_000
+
+interface HookEntry {
+  state: TabActivity
+  at: number
+}
+
+export interface RecordHookEventInput {
+  paneId: string
+  hookEventName: string
+  payload: Record<string, unknown>
+  receivedAt?: number
+}
+
+export class AssistantStatusArbiter {
+  private readonly entries = new Map<string, HookEntry>()
+
+  /**
+   * Map a Claude hook event to a `TabActivity` and record it. Returns the
+   * mapped state (or null if the event was ignored, e.g. SubagentStop on a
+   * parent agent — we don't want a subagent finishing to flip the parent
+   * pane to idle while the parent is still mid-turn).
+   */
+  recordHookEvent(input: RecordHookEventInput): TabActivity | null {
+    const at = input.receivedAt ?? Date.now()
+    const mapped = mapHookEvent(input.hookEventName, input.payload)
+    if (mapped === null) return null
+    this.entries.set(input.paneId, { at, state: mapped })
+    return mapped
+  }
+
+  /**
+   * Arbitrate between a fresh visual classification and the most recent hook
+   * event for the same pane. Hook wins for `working`/`idle`. If the visual
+   * detector saw a permission/yes-no prompt (`waiting-input`) we trust it
+   * regardless of the hook state — some prompts don't fire `Notification`,
+   * and Claude is genuinely paused on user input.
+   */
+  arbitrate(paneId: string, visual: TabActivity, now: number): TabActivity {
+    const hook = this.entries.get(paneId)
+    if (!hook || now - hook.at >= HOOK_AUTHORITY_WINDOW_MS) {
+      return visual
+    }
+    if (visual === 'waiting-input') return 'waiting-input'
+    return hook.state
+  }
+
+  forget(paneId: string): void {
+    this.entries.delete(paneId)
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}
+
+function mapHookEvent(hookEventName: string, payload: Record<string, unknown>): TabActivity | null {
+  // Anything originating inside a subagent has a non-null parent_tool_use_id.
+  // Forwarding its lifecycle to the parent pane is wrong: the parent is still
+  // working while the subagent runs.
+  const parentToolUseId = payload.parent_tool_use_id
+  if (typeof parentToolUseId === 'string' && parentToolUseId.length > 0) {
+    return null
+  }
+
+  switch (hookEventName) {
+    case 'UserPromptSubmit':
+    case 'PreToolUse':
+    case 'PostToolUse':
+      return 'working'
+    case 'Stop':
+      return 'idle'
+    case 'Notification':
+      // Permission requests and other Claude-initiated notifications pause
+      // execution until the user acts — mirror the visual detector's term.
+      return 'waiting-input'
+    case 'SubagentStop':
+      return null
+    default:
+      return null
+  }
+}

package/src/pty/assistant-status-detection-loop.ts

@@ -17,6 +17,7 @@ import type { AssistantId, SessionStatus, TabActivity, TerminalSnapshot } from '
 
 import { logDebug } from '../debug/input-log'
 import { getLineText } from '../input/terminal-text-extraction'
+import { AssistantStatusArbiter, type RecordHookEventInput } from './assistant-status-arbiter'
 import { AssistantStatusDetector } from './assistant-status-detector'
 
 function tailPreview(viewport: TerminalSnapshot | undefined): string {
@@ -67,6 +68,12 @@ export interface StatusDetectionLoopHandle {
    * rather than relying on the next scheduled tick.
    */
   classifyNow: (sessionId: string, tabs: LoopTabView[]) => void
+  /**
+   * Feed a Claude Code hook event into the arbiter. The next tick will
+   * combine it with the visual detector's verdict. Called by the daemon's
+   * hook HTTP server.
+   */
+  recordHookEvent: (input: RecordHookEventInput) => void
 }
 
 export function runStatusDetectionLoop(
@@ -74,6 +81,7 @@ export function runStatusDetectionLoop(
 ): StatusDetectionLoopHandle {
   const tickMs = options.tickMs ?? DEFAULT_TICK_MS
   const detector = new AssistantStatusDetector()
+  const arbiter = new AssistantStatusArbiter()
   const lastTabStatus = new Map<string, { status: TabActivity; sessionId: string }>()
   const lastSessionStatus = new Map<string, SessionStatus>()
 
@@ -99,13 +107,14 @@ export function runStatusDetectionLoop(
     let waiting = false
     for (const tab of tabs) {
       seenTabs?.add(tab.id)
-      const status = detector.classify({
+      const visual = detector.classify({
         assistant: tab.assistant,
         command: tab.command,
         now,
         tabId: tab.id,
         viewport: tab.viewport,
       })
+      const status = arbiter.arbitrate(tab.id, visual, now)
       if (status === 'working') working = true
       if (status === 'waiting-input') waiting = true
       const prev = lastTabStatus.get(tab.id)
@@ -158,6 +167,7 @@ export function runStatusDetectionLoop(
     for (const tabId of lastTabStatus.keys()) {
       if (!seenTabs.has(tabId)) {
         detector.forget(tabId)
+        arbiter.forget(tabId)
         lastTabStatus.delete(tabId)
       }
     }
@@ -174,6 +184,14 @@ export function runStatusDetectionLoop(
     },
     getSessionStatus: (sessionId) => lastSessionStatus.get(sessionId),
     getTabStatus: (tabId) => lastTabStatus.get(tabId)?.status,
+    recordHookEvent: (input) => {
+      const mapped = arbiter.recordHookEvent(input)
+      logDebug('statusLoop.recordHookEvent', {
+        hookEventName: input.hookEventName,
+        mapped,
+        paneId: input.paneId,
+      })
+    },
     snapshotSessions: () =>
       [...lastSessionStatus.entries()].map(([sessionId, status]) => ({ sessionId, status })),
     snapshotTabs: () =>
@@ -185,6 +203,7 @@ export function runStatusDetectionLoop(
     stop: () => {
       clearInterval(timer)
       detector.clear()
+      arbiter.clear()
       lastTabStatus.clear()
       lastSessionStatus.clear()
     },

package/src/pty/pty-manager.ts

@@ -238,6 +238,8 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
     cols: number
     rows: number
     cwd?: string
+    /** Extra environment variables merged on top of `process.env` for this PTY. */
+    env?: Record<string, string>
   }): void {
     this.disposeSession(options.tabId)
     logDebug('ptyManager.create.start', {
@@ -262,7 +264,9 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
         cwd: options.cwd ?? process.cwd(),
         env: {
           ...process.env,
+          COLORTERM: 'truecolor',
           TERM: 'xterm-256color',
+          ...options.env,
         },
         name: 'xterm-256color',
         rows: options.rows,

package/src/pty/terminal-snapshot.ts

@@ -6,66 +6,30 @@ import { getCurrentTheme } from '../ui/theme'
 
 const SNAPSHOT_TAIL_LINE_COUNT = 10
 
-const ANSI_PALETTE = [
-  '#000000',
-  '#cd0000',
-  '#00cd00',
-  '#cdcd00',
-  '#0000ee',
-  '#cd00cd',
-  '#00cdcd',
-  '#e5e5e5',
-  '#7f7f7f',
-  '#ff0000',
-  '#00ff00',
-  '#ffff00',
-  '#5c5cff',
-  '#ff00ff',
-  '#00ffff',
-  '#ffffff',
-]
+// CellColor preserves whether the cell emitted an indexed (ANSI 0-255) color
+// or an RGB color, so the renderer process can resolve indices against the
+// host terminal's actual palette (queried via OSC 4 at startup). Converting
+// indices to RGB here would lock in xterm defaults and silently override the
+// user's terminal theme — that's the very bug we're fixing.
+type CellColor = { kind: 'rgb'; hex: string } | { kind: 'palette'; index: number } | undefined
 
 function toHex(value: number): string {
   return `#${value.toString(16).padStart(6, '0')}`
 }
 
-function paletteToHex(index: number): string {
-  if (index < ANSI_PALETTE.length) {
-    return ANSI_PALETTE[index] ?? ANSI_PALETTE[0] ?? '#000000'
-  }
-
-  if (index >= 232) {
-    const shade = 8 + (index - 232) * 10
-    return toHex((shade << 16) | (shade << 8) | shade)
-  }
-
-  const normalized = index - 16
-  const r = Math.floor(normalized / 36)
-  const g = Math.floor((normalized % 36) / 6)
-  const b = normalized % 6
-  const channel = [0, 95, 135, 175, 215, 255]
-
-  return toHex(((channel[r] ?? 0) << 16) | ((channel[g] ?? 0) << 8) | (channel[b] ?? 0))
-}
-
-function getColorHex(color: number, mode: 'rgb' | 'palette' | 'default'): string | undefined {
-  if (mode === 'default') {
-    return undefined
-  }
-
-  return mode === 'rgb' ? toHex(color) : paletteToHex(color)
+function readCellColor(value: number, isRgb: boolean, isPalette: boolean): CellColor {
+  if (isRgb) return { hex: toHex(value), kind: 'rgb' }
+  if (isPalette) return { index: value, kind: 'palette' }
+  return undefined
 }
 
-function getColorMode(isRgb: boolean, isPalette: boolean): 'rgb' | 'palette' | 'default' {
-  if (isRgb) {
-    return 'rgb'
-  }
-
-  if (isPalette) {
-    return 'palette'
+function applySpanColor(span: TerminalSpan, color: CellColor, side: 'fg' | 'bg'): void {
+  if (!color) return
+  if (color.kind === 'rgb') {
+    span[side] = color.hex
+  } else {
+    span[side === 'fg' ? 'fgPalette' : 'bgPalette'] = color.index
   }
-
-  return 'default'
 }
 
 function pushSpan(spans: TerminalSpan[], span: TerminalSpan): void {
@@ -74,6 +38,8 @@ function pushSpan(spans: TerminalSpan[], span: TerminalSpan): void {
     previous &&
     previous.fg === span.fg &&
     previous.bg === span.bg &&
+    previous.fgPalette === span.fgPalette &&
+    previous.bgPalette === span.bgPalette &&
     previous.bold === span.bold &&
     previous.italic === span.italic &&
     previous.underline === span.underline &&
@@ -109,36 +75,45 @@ function buildLine(
     }
 
     const text = current.getChars() || ' '
-    const fgMode = getColorMode(current.isFgRGB(), current.isFgPalette())
-    const bgMode = getColorMode(current.isBgRGB(), current.isBgPalette())
 
-    let fg = getColorHex(current.getFgColor(), fgMode)
-    let bg = getColorHex(current.getBgColor(), bgMode)
+    let fg: CellColor = readCellColor(
+      current.getFgColor(),
+      current.isFgRGB(),
+      current.isFgPalette()
+    )
+    let bg: CellColor = readCellColor(
+      current.getBgColor(),
+      current.isBgRGB(),
+      current.isBgPalette()
+    )
 
     if (current.isInverse()) {
       const tokens = getCurrentTheme()
-      const resolvedFg = fg ?? tokens.text
-      const resolvedBg = bg ?? tokens.background
-      ;[fg, bg] = [resolvedBg, resolvedFg]
+      const resolvedFg: CellColor = fg ?? { hex: tokens.text, kind: 'rgb' }
+      const resolvedBg: CellColor = bg ?? { hex: tokens.background, kind: 'rgb' }
+      fg = resolvedBg
+      bg = resolvedFg
     }
 
     const isCursorCell = cursorVisible && cursorColumn === column
     if (isCursorCell) {
       const tokens = getCurrentTheme()
-      const resolvedFg = fg ?? tokens.text
-      const resolvedBg = bg ?? tokens.background
-      ;[fg, bg] = [resolvedBg, resolvedFg]
+      const resolvedFg: CellColor = fg ?? { hex: tokens.text, kind: 'rgb' }
+      const resolvedBg: CellColor = bg ?? { hex: tokens.background, kind: 'rgb' }
+      fg = resolvedBg
+      bg = resolvedFg
     }
 
-    pushSpan(spans, {
-      bg,
+    const span: TerminalSpan = {
       bold: current.isBold() ? true : undefined,
       cursor: isCursorCell ? true : undefined,
-      fg,
       italic: current.isItalic() ? true : undefined,
       text,
       underline: current.isUnderline() ? true : undefined,
-    })
+    }
+    applySpanColor(span, fg, 'fg')
+    applySpanColor(span, bg, 'bg')
+    pushSpan(spans, span)
 
     visualColumns += current.getWidth()
   }
@@ -238,6 +213,8 @@ function areSpansEqual(left: TerminalSpan, right: TerminalSpan): boolean {
     left.text === right.text &&
     left.fg === right.fg &&
     left.bg === right.bg &&
+    left.fgPalette === right.fgPalette &&
+    left.bgPalette === right.bgPalette &&
     left.bold === right.bold &&
     left.italic === right.italic &&
     left.underline === right.underline &&

package/src/session-backend/local-session-backend.ts

@@ -1,7 +1,12 @@
 import { EventEmitter } from 'node:events'
 
-import type { AssistantId, WorkspaceSnapshotV1 } from '../state/types'
-import type { SessionBackend, SessionBackendEvents } from './types'
+import type {
+  AssistantId,
+  TerminalModeState,
+  TerminalSnapshot,
+  WorkspaceSnapshotV1,
+} from '../state/types'
+import type { ResizeOptions, SessionBackend, SessionBackendEvents } from './types'
 
 import { SessionManager } from '../daemon/session-manager'
 import { logDebug } from '../debug/input-log'
@@ -20,13 +25,31 @@ export class LocalSessionBackend
   private readonly sessionManager = new SessionManager()
   private currentSessionId: string | null = null
   private readonly statusLoop: ReturnType<typeof runStatusDetectionLoop>
+  /**
+   * Per-tab snapshot gate. While `false`, render events from the underlying
+   * `sessionManager` are buffered (latest-wins) instead of being forwarded to
+   * the UI. The frontend lifts the gate once `usePaneSizeReport` has reported
+   * the *actual* rendered pane size via `resizeTab({ confirmedFromMeasurement })`,
+   * so the first snapshot the UI ever paints is sized against the real box —
+   * never against the open-loop chrome estimate used at session create / attach.
+   * A tab without an entry here is treated as ready (legacy paths, sessions
+   * not subject to the gate). See plan: il-y-a-eu-stateful-boot.md.
+   */
+  private readonly paneReady = new Map<string, boolean>()
+  private readonly pendingRender = new Map<
+    string,
+    { viewport: TerminalSnapshot; terminalModes: TerminalModeState }
+  >()
 
   constructor() {
     super()
     this.sessionManager.on('render', (sessionId, tabId, viewport, terminalModes) => {
-      if (sessionId === this.currentSessionId) {
-        this.emit('render', tabId, viewport, terminalModes)
+      if (sessionId !== this.currentSessionId) return
+      if (this.paneReady.get(tabId) === false) {
+        this.pendingRender.set(tabId, { terminalModes, viewport })
+        return
       }
+      this.emit('render', tabId, viewport, terminalModes)
     })
     this.sessionManager.on('exit', (sessionId, tabId, exitCode) => {
       if (sessionId === this.currentSessionId) {
@@ -71,6 +94,7 @@ export class LocalSessionBackend
       const bounds = createTerminalBounds(options.cols, options.rows)
       forEachSplitPaneRect(splitTrees, bounds, (tabId, rect) => {
         const size = toTerminalContentSize(rect)
+        this.gatePaneRender(tabId)
         this.sessionManager.resizeTab(options.sessionId, tabId, size.cols, size.rows)
       })
     } else {
@@ -80,6 +104,9 @@ export class LocalSessionBackend
       options.sessionId,
       options.workspaceSnapshot
     )
+    for (const tab of attachResult.tabs) {
+      this.gatePaneRender(tab.id)
+    }
     // Run a synchronous classification pass so every tab's activity and the
     // session-status snapshot are available to embed in the reply — mirrors
     // the remote backend's behavior and keeps hydrate dispatches atomic on
@@ -115,9 +142,27 @@ export class LocalSessionBackend
       tabId: options.tabId,
       title: options.title,
     })
+    this.gatePaneRender(options.tabId)
     this.sessionManager.createTab(this.currentSessionId, options)
   }
 
+  /** Suppress render emission for this tab until the frontend acknowledges its
+   *  measured pane size via `resizeTab({ confirmedFromMeasurement: true })`. */
+  private gatePaneRender(tabId: string): void {
+    this.paneReady.set(tabId, false)
+    this.pendingRender.delete(tabId)
+  }
+
+  /** Lift the suppression and flush the most recent buffered snapshot, if any. */
+  private releasePaneRender(tabId: string): void {
+    if (this.paneReady.get(tabId) === true) return
+    this.paneReady.set(tabId, true)
+    const pending = this.pendingRender.get(tabId)
+    if (!pending) return
+    this.pendingRender.delete(tabId)
+    this.emit('render', tabId, pending.viewport, pending.terminalModes)
+  }
+
   write(tabId: string, input: string): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) {
       logDebug('backend.local.skipWriteWithoutSession', { inputLength: input.length, tabId })
@@ -147,25 +192,32 @@ export class LocalSessionBackend
     this.sessionManager.setActiveTab(this.currentSessionId, tabId)
   }
 
-  resizeAll(cols: number, rows: number, options?: { sync?: boolean }): void {
+  resizeAll(cols: number, rows: number, options?: ResizeOptions): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resize(this.currentSessionId, cols, rows, options)
   }
 
-  resizeTab(tabId: string, cols: number, rows: number, options?: { sync?: boolean }): void {
+  resizeTab(tabId: string, cols: number, rows: number, options?: ResizeOptions): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resizeTab(this.currentSessionId, tabId, cols, rows, options)
+    if (options?.confirmedFromMeasurement === true) {
+      this.releasePaneRender(tabId)
+    }
   }
 
   disposeSession(tabId: string): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeSession', { sessionId: this.currentSessionId, tabId })
+    this.paneReady.delete(tabId)
+    this.pendingRender.delete(tabId)
     this.sessionManager.closeTab(this.currentSessionId, tabId)
   }
 
   disposeAll(): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeAll', { sessionId: this.currentSessionId })
+    this.paneReady.clear()
+    this.pendingRender.clear()
     this.sessionManager.disposeSession(this.currentSessionId)
   }
 

package/src/session-backend/remote-session-backend.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events'
 import { connect, type Socket } from 'node:net'
 
 import type { AssistantId, WorkspaceSnapshotV1 } from '../state/types'
-import type { SessionBackend, SessionBackendEvents } from './types'
+import type { ResizeOptions, SessionBackend, SessionBackendEvents } from './types'
 
 import { getIpcDaemonSocketPath } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
@@ -414,7 +414,7 @@ export class RemoteSessionBackend
     )
   }
 
-  resizeAll(cols: number, rows: number, _options?: { sync?: boolean }): void {
+  resizeAll(cols: number, rows: number, _options?: ResizeOptions): void {
     if (!this.attached) {
       logDebug('backend.remote.skipResizeBeforeAttach', { cols, rows })
       return
@@ -426,7 +426,14 @@ export class RemoteSessionBackend
     )
   }
 
-  resizeTab(tabId: string, cols: number, rows: number, _options?: { sync?: boolean }): void {
+  // The remote backend forwards every resize over IPC; the daemon-side
+  // pty-manager is the authoritative emulator. `confirmedFromMeasurement` is
+  // not yet plumbed through the wire protocol — the local backend uses it to
+  // gate the per-tab render emission, but in the remote path the daemon emits
+  // snapshots based on its own emulator state, so the flag is intentionally
+  // ignored here. If the boot-time visual desync ever shows up against a
+  // daemon, plumb the flag through the resizeTab IPC message.
+  resizeTab(tabId: string, cols: number, rows: number, _options?: ResizeOptions): void {
     if (!this.attached) {
       return
     }

package/src/session-backend/types.ts

@@ -17,6 +17,20 @@ export interface SessionBackendEvents {
   tabActivity: [tabId: string, activity: TabActivity]
 }
 
+export interface ResizeOptions {
+  /** When set, opentui's flush is invoked synchronously so the resize lands
+   *  in the same commit. Used by the chrome cascade to keep the cols/rows
+   *  state and the backend buffer in lockstep on sidebar/session-bar toggles. */
+  sync?: boolean
+  /** When true, this resize is the closed-loop measurement of the rendered
+   *  content box — the authoritative size for the visible viewport. The
+   *  `LocalSessionBackend` uses this to lift the per-tab snapshot gate that
+   *  suppresses renders between session/attach time and the first measurement,
+   *  so the frontend never paints a snapshot whose row count disagrees with
+   *  the pane's actual height. */
+  confirmedFromMeasurement?: boolean
+}
+
 export interface BackendAttachResult {
   tabs: TabSession[]
   activeTabId: string | null
@@ -49,8 +63,8 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
   scrollViewport(tabId: string, deltaLines: number): void
   scrollViewportToBottom(tabId: string): void
   setActiveTab(tabId: string | null): void
-  resizeAll(cols: number, rows: number, options?: { sync?: boolean }): void
-  resizeTab(tabId: string, cols: number, rows: number, options?: { sync?: boolean }): void
+  resizeAll(cols: number, rows: number, options?: ResizeOptions): void
+  resizeTab(tabId: string, cols: number, rows: number, options?: ResizeOptions): void
   disposeSession(tabId: string): void
   disposeAll(): void
   destroy(keepSessions?: boolean): Promise<void> | void

package/src/state/types.ts

@@ -50,8 +50,16 @@ export type ModalType =
 
 export interface TerminalSpan {
   text: string
+  /** Hex color for RGB cells, or undefined for the "default" foreground. */
   fg?: string
+  /** Hex color for RGB cells, or undefined for the "default" background. */
   bg?: string
+  /** ANSI palette index (0-255) when the cell emitted an indexed color.
+   *  Resolved client-side against the host terminal's queried palette so
+   *  user themes (Ghostty, iTerm2, …) show through. Wins over `fg` if set. */
+  fgPalette?: number
+  /** ANSI palette index (0-255). Resolved client-side. Wins over `bg`. */
+  bgPalette?: number
   bold?: boolean
   italic?: boolean
   underline?: boolean

package/src/ui/components/layout/terminal-pane.tsx

@@ -10,6 +10,7 @@ import { type MeasuredPaneRect, usePaneSizeReport } from '../../../app-runtime/u
 import { logInputDebug } from '../../../debug/input-log'
 import { dispatchGlobal, runSideEffectGlobal } from '../../../state/dispatch-ref'
 import { type ContextMenuItem, openContextMenu } from '../../context-menu/controller'
+import { resolvePaletteIndex } from '../../host-palette'
 import { getCurrentTheme, useTheme } from '../../theme'
 import { ContextMenuBox } from '../overlays/context-menu/context-menu-box'
 
@@ -76,8 +77,16 @@ function renderSpan(span: TerminalSpan, key: string): ReactNode {
     node = <strong>{node}</strong>
   }
 
+  // Palette indices are resolved here (not in the daemon) so they pick up
+  // the host terminal's actual ANSI palette queried at startup.
+  const fg =
+    span.fgPalette !== undefined
+      ? resolvePaletteIndex(span.fgPalette)
+      : (span.fg ?? getCurrentTheme().text)
+  const bg = span.bgPalette !== undefined ? resolvePaletteIndex(span.bgPalette) : span.bg
+
   return (
-    <span key={key} fg={span.fg ?? getCurrentTheme().text} bg={span.bg}>
+    <span key={key} fg={fg} bg={bg}>
       {node}
     </span>
   )

package/src/ui/host-palette.ts

@@ -0,0 +1,75 @@
+// Resolves ANSI palette indices (0-255) to hex strings using the host
+// terminal's actual palette, queried via OSC 4 at startup (see index.tsx).
+//
+// Before detection completes — or when the host terminal doesn't respond —
+// FALLBACK_PALETTE (xterm defaults) is used. Indices ≥16 fall back to the
+// universal 6×6×6 cube + grayscale ramp, which every terminal agrees on.
+
+const FALLBACK_PALETTE: readonly string[] = [
+  '#000000',
+  '#cd0000',
+  '#00cd00',
+  '#cdcd00',
+  '#0000ee',
+  '#cd00cd',
+  '#00cdcd',
+  '#e5e5e5',
+  '#7f7f7f',
+  '#ff0000',
+  '#00ff00',
+  '#ffff00',
+  '#5c5cff',
+  '#ff00ff',
+  '#00ffff',
+  '#ffffff',
+]
+
+const CUBE_CHANNELS = [0, 95, 135, 175, 215, 255] as const
+
+const hostPalette: string[] = [...FALLBACK_PALETTE]
+
+function toHex(value: number): string {
+  return `#${value.toString(16).padStart(6, '0')}`
+}
+
+function paletteFromFormula(index: number): string {
+  if (index >= 232) {
+    const shade = 8 + (index - 232) * 10
+    return toHex((shade << 16) | (shade << 8) | shade)
+  }
+
+  const normalized = index - 16
+  const r = Math.floor(normalized / 36)
+  const g = Math.floor((normalized % 36) / 6)
+  const b = normalized % 6
+  return toHex(
+    ((CUBE_CHANNELS[r] ?? 0) << 16) | ((CUBE_CHANNELS[g] ?? 0) << 8) | (CUBE_CHANNELS[b] ?? 0)
+  )
+}
+
+/** Replace entries 0..N-1 of the resolver with values queried from the host
+ *  terminal. Null entries keep the existing fallback (terminal didn't respond
+ *  for that index). Safe to call before any snapshots have been rendered. */
+export function setHostPalette(palette: readonly (string | null)[]): void {
+  for (let index = 0; index < palette.length; index += 1) {
+    const value = palette[index]
+    if (typeof value === 'string' && value.length > 0) {
+      hostPalette[index] = value
+    }
+  }
+}
+
+/** Resolve an ANSI palette index (0-255) to a hex color. Indices 0-15 use
+ *  the host-queried palette (or xterm fallback); 16-255 use the universal
+ *  cube/grayscale formula unless the host explicitly customized them. */
+const BLACK = '#000000'
+const WHITE = '#ffffff'
+
+export function resolvePaletteIndex(index: number): string {
+  if (index < 0) return BLACK
+  const override = hostPalette[index]
+  if (typeof override === 'string' && override.length > 0) return override
+  if (index < 16) return FALLBACK_PALETTE.at(index) ?? BLACK
+  if (index > 255) return WHITE
+  return paletteFromFormula(index)
+}