cli.py

#!/usr/bin/env python3
"""
Kai Agent CLI - Interactive Terminal Interface

A beautiful command-line interface for the Kai Agent.
Features ASCII art branding, interactive REPL, toolset selection, and rich formatting.

Usage:
    python cli.py                          # Start interactive mode with all tools
    python cli.py --toolsets web,terminal  # Start with specific toolsets
    python cli.py -q "your question"       # Single query mode
    python cli.py --list-tools             # List available tools and exit
"""

import logging
import os
import shutil
import sys
import json
import atexit
import uuid
import textwrap
from contextlib import contextmanager
from pathlib import Path
from datetime import datetime
from typing import List, Dict, Any, Optional

logger = logging.getLogger(__name__)

# Suppress startup messages for clean CLI experience
os.environ["MSWEA_SILENT_STARTUP"] = "1"  # mini-swe-agent
os.environ["KAI_QUIET"] = "1"  # Our own modules

import yaml

# prompt_toolkit for fixed input area TUI
from prompt_toolkit.history import FileHistory
from prompt_toolkit.styles import Style as PTStyle
from prompt_toolkit.patch_stdout import patch_stdout
from prompt_toolkit.application import Application
from prompt_toolkit.layout import Layout, HSplit, Window, FormattedTextControl, ConditionalContainer
from prompt_toolkit.layout.processors import Processor, Transformation, PasswordProcessor, ConditionalProcessor
from prompt_toolkit.filters import Condition
from prompt_toolkit.layout.dimension import Dimension
from prompt_toolkit.layout.menus import CompletionsMenu
from prompt_toolkit.widgets import TextArea
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit import print_formatted_text as _pt_print
from prompt_toolkit.formatted_text import ANSI as _PT_ANSI
try:
    from prompt_toolkit.cursor_shapes import CursorShape
    _STEADY_CURSOR = CursorShape.BLOCK  # Non-blinking block cursor
except (ImportError, AttributeError):
    _STEADY_CURSOR = None
import threading
import queue

_COMMAND_SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")


# Load .env from ~/.kai-agent/.env first, then project root as dev fallback
from dotenv import load_dotenv
from kai_constants import OPENROUTER_BASE_URL
from kai_env import kai_home, get_env

_kai_home = kai_home()
_user_env = _kai_home / ".env"
_project_env = Path(__file__).parent / '.env'
if _user_env.exists():
    try:
        load_dotenv(dotenv_path=_user_env, encoding="utf-8")
    except UnicodeDecodeError:
        load_dotenv(dotenv_path=_user_env, encoding="latin-1")
elif _project_env.exists():
    try:
        load_dotenv(dotenv_path=_project_env, encoding="utf-8")
    except UnicodeDecodeError:
        load_dotenv(dotenv_path=_project_env, encoding="latin-1")

# Point mini-swe-agent at ~/.kai-agent/ so it shares our config
os.environ.setdefault("MSWEA_GLOBAL_CONFIG_DIR", str(_kai_home))

# =============================================================================
# Configuration Loading
# =============================================================================

def _load_prefill_messages(file_path: str) -> List[Dict[str, Any]]:
    """Load ephemeral prefill messages from a JSON file.
    
    The file should contain a JSON array of {role, content} dicts, e.g.:
        [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}]
    
    Relative paths are resolved from ~/.kai-agent/.
    Returns an empty list if the path is empty or the file doesn't exist.
    """
    if not file_path:
        return []
    path = Path(file_path).expanduser()
    if not path.is_absolute():
        path = Path.home() / ".kai-agent" / path
    if not path.exists():
        logger.warning("Prefill messages file not found: %s", path)
        return []
    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
        if not isinstance(data, list):
            logger.warning("Prefill messages file must contain a JSON array: %s", path)
            return []
        return data
    except Exception as e:
        logger.warning("Failed to load prefill messages from %s: %s", path, e)
        return []


def _parse_reasoning_config(effort: str) -> dict | None:
    """Parse a reasoning effort level into an OpenRouter reasoning config dict.
    
    Valid levels: "xhigh", "high", "medium", "low", "minimal", "none".
    Returns None to use the default (medium), or a config dict to override.
    """
    if not effort or not effort.strip():
        return None
    effort = effort.strip().lower()
    if effort == "none":
        return {"enabled": False}
    valid = ("xhigh", "high", "medium", "low", "minimal")
    if effort in valid:
        return {"enabled": True, "effort": effort}
    logger.warning("Unknown reasoning_effort '%s', using default (medium)", effort)
    return None


def load_cli_config() -> Dict[str, Any]:
    """
    Load CLI configuration from config files.
    
    Config lookup order:
    1. ~/.kai-agent/config.yaml (user config - preferred)
    2. ./cli-config.yaml (project config - fallback)

    Environment variables take precedence over config file values.
    Returns default values if no config file exists.
    """
    # Check user config first (~/.kai-agent/config.yaml)
    user_config_path = Path.home() / '.kai-agent' / 'config.yaml'
    project_config_path = Path(__file__).parent / 'cli-config.yaml'
    
    # Use user config if it exists, otherwise project config
    if user_config_path.exists():
        config_path = user_config_path
    else:
        config_path = project_config_path
    
    # Default configuration
    defaults = {
        "model": {
            "default": "anthropic/claude-opus-4.6",
            "base_url": OPENROUTER_BASE_URL,
            "provider": "auto",
        },
        "terminal": {
            "env_type": "local",
            "cwd": ".",  # "." is resolved to os.getcwd() at runtime
            "timeout": 60,
            "lifetime_seconds": 300,
            "docker_image": "python:3.11",
            "singularity_image": "docker://python:3.11",
            "modal_image": "python:3.11",
            "daytona_image": "nikolaik/python-nodejs:python3.11-nodejs20",
            "docker_volumes": [],  # host:container volume mounts for Docker backend
        },
        "browser": {
            "inactivity_timeout": 120,  # Auto-cleanup inactive browser sessions after 2 min
            "record_sessions": False,  # Auto-record browser sessions as WebM videos
        },
        "compression": {
            "enabled": True,      # Auto-compress when approaching context limit
            "threshold": 0.85,    # Compress at 85% of model's context limit
            "summary_model": "google/gemini-3-flash-preview",  # Fast/cheap model for summaries
        },
        "agent": {
            "max_turns": 90,  # Default max tool-calling iterations (shared with subagents)
            "verbose": False,
            "system_prompt": "",
            "prefill_messages_file": "",
            "reasoning_effort": "",
            "personalities": {
                "focused": "You are in focused mode. Terse, no commentary, just results. Act like a senior engineer in deep flow state. No preamble, no summaries unless asked. Code and data first, explanation only when necessary.",
                "detailed": "You are in detailed mode. Explain your reasoning, cite sources, show your work. When analyzing results, walk through the logic step by step. Cross-reference with documentation and papers. This is research mode.",
                "brief": "You are in brief mode. One-liner answers, bullet points only. Maximum information density. No prose. Tables over paragraphs. Numbers over words.",
                "advisor": "You are in advisor mode. Frame everything strategically. For every finding, explain the business impact, the priority, and what you would do next. Be opinionated. Say 'I would...' not 'You could...'.",
                "mentor": "You are in mentor mode. Be patient, teach concepts alongside results. When you find a vulnerability or optimization, explain the underlying principle so the user learns. Connect dots across findings.",
                "karpathy": "Channel Andrej Karpathy's communication style. Explain from first principles. Build intuition before giving answers. 'Let me break down what is actually happening here...' Use analogies to make complex systems tangible. Educational but never condescending. When reviewing code or results, trace the computational path clearly.",
                "hassabis": "Channel Demis Hassabis's communication style. Think in systems. Connect everything to the bigger picture. 'This optimization relates to a broader pattern in...' Be interdisciplinary, draw parallels between domains. Calmly ambitious about what the technology can achieve. Frame results in terms of scientific significance.",
                "amodei": "Channel Dario Amodei's communication style. Be careful, thorough, and weigh trade-offs explicitly. 'The risk here is... but the upside is...' Safety-conscious but pragmatic. Think about edge cases and failure modes. When analyzing vulnerabilities, consider systemic risk, not just individual findings. Long-form reasoning when the stakes are high.",
                "hopper": "Channel Grace Hopper's communication style. Be practical and action-biased. 'It is easier to ask forgiveness than permission.' Cut through complexity and get to the point. Ship first, optimize later. When someone is overthinking, redirect them to the simplest working solution. No patience for bureaucratic thinking.",
                "feynman": "Channel Richard Feynman's communication style. Be curious and playful with ideas. Simplify the complex. 'Imagine you are an electron...' Make hard problems feel approachable. Question assumptions. When explaining results, find the surprising insight that makes everything click. If you cannot explain it simply, you do not understand it well enough.",
                "turing": "Channel Alan Turing's communication style. Be formal, precise, and mathematical. Think in proofs and invariants. Minimal words, maximum precision. When analyzing code, reason about correctness formally. Define terms before using them. Express uncertainty as probability, not hedging.",
                "carmack": "Channel John Carmack's communication style. Be performance-obsessed. Think in cycles, cache lines, memory layouts. 'You are leaving performance on the table here...' Deep technical analysis of every optimization opportunity. When reviewing evolved code, evaluate not just correctness but efficiency at the hardware level. No wasted cycles, no wasted words.",
            },
        },
        "toolsets": ["all"],
        "display": {
            "compact": False,
            "resume_display": "full",
            "show_reasoning": False,
            "skin": "default",
        },
        "clarify": {
            "timeout": 120,  # Seconds to wait for a clarify answer before auto-proceeding
        },
        "code_execution": {
            "timeout": 300,    # Max seconds a sandbox script can run before being killed (5 min)
            "max_tool_calls": 50,  # Max RPC tool calls per execution
        },
        "delegation": {
            "max_iterations": 45,  # Max tool-calling turns per child agent
            "default_toolsets": ["terminal", "file", "web"],  # Default toolsets for subagents
            "model": "",       # Subagent model override (empty = inherit parent model)
            "provider": "",    # Subagent provider override (empty = inherit parent provider)
        },
    }
    
    # Track whether the config file explicitly set terminal config.
    # When using defaults (no config file / no terminal section), we should NOT
    # overwrite env vars that were already set by .env -- only a user's config
    # file should be authoritative.
    _file_has_terminal_config = False

    # Load from file if exists
    if config_path.exists():
        try:
            with open(config_path, "r") as f:
                file_config = yaml.safe_load(f) or {}
            
            _file_has_terminal_config = "terminal" in file_config

            # Handle model config - can be string (new format) or dict (old format)
            if "model" in file_config:
                if isinstance(file_config["model"], str):
                    # New format: model is just a string, convert to dict structure
                    defaults["model"]["default"] = file_config["model"]
                elif isinstance(file_config["model"], dict):
                    # Old format: model is a dict with default/base_url
                    defaults["model"].update(file_config["model"])
            
            # Deep merge file_config into defaults.
            # First: merge keys that exist in both (deep-merge dicts, overwrite scalars)
            for key in defaults:
                if key == "model":
                    continue  # Already handled above
                if key in file_config:
                    if isinstance(defaults[key], dict) and isinstance(file_config[key], dict):
                        defaults[key].update(file_config[key])
                    else:
                        defaults[key] = file_config[key]
            
            # Second: carry over keys from file_config that aren't in defaults
            # (e.g. platform_toolsets, provider_routing, memory, honcho, etc.)
            for key in file_config:
                if key not in defaults and key != "model":
                    defaults[key] = file_config[key]
            
            # Handle legacy root-level max_turns (backwards compat) - copy to
            # agent.max_turns whenever the nested key is missing.
            agent_file_config = file_config.get("agent")
            if "max_turns" in file_config and not (
                isinstance(agent_file_config, dict)
                and agent_file_config.get("max_turns") is not None
            ):
                defaults["agent"]["max_turns"] = file_config["max_turns"]
        except Exception as e:
            logger.warning("Failed to load cli-config.yaml: %s", e)
    
    # Apply terminal config to environment variables (so terminal_tool picks them up)
    terminal_config = defaults.get("terminal", {})
    
    # Normalize config key: the new config system (kai_cli/config.py) and all
    # documentation use "backend", the legacy cli-config.yaml uses "env_type".
    # Accept both, with "backend" taking precedence (it's the documented key).
    if "backend" in terminal_config:
        terminal_config["env_type"] = terminal_config["backend"]
    
    # Handle special cwd values: "." or "auto" means use current working directory.
    # Only resolve to the host's CWD for the local backend where the host
    # filesystem is directly accessible.  For ALL remote/container backends
    # (ssh, docker, modal, singularity), the host path doesn't exist on the
    # target -- remove the key so terminal_tool.py uses its per-backend default.
    if terminal_config.get("cwd") in (".", "auto", "cwd"):
        effective_backend = terminal_config.get("env_type", "local")
        if effective_backend == "local":
            terminal_config["cwd"] = os.getcwd()
            defaults["terminal"]["cwd"] = terminal_config["cwd"]
        else:
            # Remove so TERMINAL_CWD stays unset → tool picks backend default
            terminal_config.pop("cwd", None)
    
    env_mappings = {
        "env_type": "TERMINAL_ENV",
        "cwd": "TERMINAL_CWD",
        "timeout": "TERMINAL_TIMEOUT",
        "lifetime_seconds": "TERMINAL_LIFETIME_SECONDS",
        "docker_image": "TERMINAL_DOCKER_IMAGE",
        "singularity_image": "TERMINAL_SINGULARITY_IMAGE",
        "modal_image": "TERMINAL_MODAL_IMAGE",
        "daytona_image": "TERMINAL_DAYTONA_IMAGE",
        # SSH config
        "ssh_host": "TERMINAL_SSH_HOST",
        "ssh_user": "TERMINAL_SSH_USER",
        "ssh_port": "TERMINAL_SSH_PORT",
        "ssh_key": "TERMINAL_SSH_KEY",
        # Container resource config (docker, singularity, modal, daytona -- ignored for local/ssh)
        "container_cpu": "TERMINAL_CONTAINER_CPU",
        "container_memory": "TERMINAL_CONTAINER_MEMORY",
        "container_disk": "TERMINAL_CONTAINER_DISK",
        "container_persistent": "TERMINAL_CONTAINER_PERSISTENT",
        "docker_volumes": "TERMINAL_DOCKER_VOLUMES",
        "sandbox_dir": "TERMINAL_SANDBOX_DIR",
        # Sudo support (works with all backends)
        "sudo_password": "SUDO_PASSWORD",
    }
    
    # Apply config values to env vars so terminal_tool picks them up.
    # If the config file explicitly has a [terminal] section, those values are
    # authoritative and override any .env settings.  When using defaults only
    # (no config file or no terminal section), don't overwrite env vars that
    # were already set by .env -- the user's .env is the fallback source.
    for config_key, env_var in env_mappings.items():
        if config_key in terminal_config:
            if _file_has_terminal_config or env_var not in os.environ:
                val = terminal_config[config_key]
                if isinstance(val, list):
                    import json
                    os.environ[env_var] = json.dumps(val)
                else:
                    os.environ[env_var] = str(val)
    
    # Apply browser config to environment variables
    browser_config = defaults.get("browser", {})
    browser_env_mappings = {
        "inactivity_timeout": "BROWSER_INACTIVITY_TIMEOUT",
    }
    
    for config_key, env_var in browser_env_mappings.items():
        if config_key in browser_config:
            os.environ[env_var] = str(browser_config[config_key])
    
    # Apply compression config to environment variables
    compression_config = defaults.get("compression", {})
    compression_env_mappings = {
        "enabled": "CONTEXT_COMPRESSION_ENABLED",
        "threshold": "CONTEXT_COMPRESSION_THRESHOLD",
        "summary_model": "CONTEXT_COMPRESSION_MODEL",
        "summary_provider": "CONTEXT_COMPRESSION_PROVIDER",
    }
    
    for config_key, env_var in compression_env_mappings.items():
        if config_key in compression_config:
            os.environ[env_var] = str(compression_config[config_key])
    
    # Apply auxiliary model overrides to environment variables.
    # Vision and web_extract each have their own provider + model pair.
    # (Compression is handled in the compression section above.)
    # Only set env vars for non-empty / non-default values so auto-detection
    # still works.
    auxiliary_config = defaults.get("auxiliary", {})
    auxiliary_task_env = {
        # config key → (provider env var, model env var)
        "vision":      ("AUXILIARY_VISION_PROVIDER",      "AUXILIARY_VISION_MODEL"),
        "web_extract": ("AUXILIARY_WEB_EXTRACT_PROVIDER",  "AUXILIARY_WEB_EXTRACT_MODEL"),
    }
    
    for task_key, (prov_env, model_env) in auxiliary_task_env.items():
        task_cfg = auxiliary_config.get(task_key, {})
        if not isinstance(task_cfg, dict):
            continue
        prov = str(task_cfg.get("provider", "")).strip()
        model = str(task_cfg.get("model", "")).strip()
        if prov and prov != "auto":
            os.environ[prov_env] = prov
        if model:
            os.environ[model_env] = model
    
    # Security settings
    security_config = defaults.get("security", {})
    if isinstance(security_config, dict):
        redact = security_config.get("redact_secrets")
        if redact is not None:
            os.environ["KAI_REDACT_SECRETS"] = str(redact).lower()

    return defaults

# Load configuration at module startup
CLI_CONFIG = load_cli_config()

# Initialize the skin engine from config
try:
    from kai_cli.skin_engine import init_skin_from_config
    init_skin_from_config(CLI_CONFIG)
except Exception:
    pass  # Skin engine is optional — default skin used if unavailable

from rich import box as rich_box
from rich.console import Console
from rich.panel import Panel
from rich.table import Table

import fire

# Import the agent and tool systems
from run_agent import AIAgent
from model_tools import get_tool_definitions, get_toolset_for_tool

# Extracted CLI modules (Phase 3)
# Shared console primitives / branding live in kai_cli.banner; cli.py keeps
# its own live build_welcome_banner / _get_available_skills below.
from kai_cli.banner import (
    cprint as _cprint, _GOLD, _BOLD, _DIM, _RST,
    VERSION, RELEASE_DATE, KAI_AGENT_LOGO, KAI_BANNER, COMPACT_BANNER,
)
from kai_cli.commands import COMMANDS, SlashCommandCompleter
from kai_cli.cli_callbacks import InteractiveCallbacksMixin
from kai_cli.cli_images import ImageInputMixin
from kai_cli.cli_session import SessionOpsMixin
from kai_cli.cli_display import DisplayMixin
from kai_cli.cli_command_handlers import CommandHandlersMixin
from toolsets import get_all_toolsets, get_toolset_info, resolve_toolset, validate_toolset

# Cron job system for scheduled tasks (CRUD only — execution is handled by the gateway)
from cron import create_job, list_jobs, remove_job, get_job

# Resource cleanup imports for safe shutdown (terminal VMs, browser sessions)
from tools.terminal_tool import cleanup_all_environments as _cleanup_all_terminals
from tools.terminal_tool import set_sudo_password_callback, set_approval_callback
from tools.browser_tool import _emergency_cleanup_all_sessions as _cleanup_all_browsers

# Guard to prevent cleanup from running multiple times on exit
_cleanup_done = False

def _run_cleanup():
    """Run resource cleanup exactly once."""
    global _cleanup_done
    if _cleanup_done:
        return
    _cleanup_done = True
    try:
        # Flush any queued memory-graph writes before the process exits, so a
        # short one-shot session (e.g. a bench issue) doesn't lose a `remember`
        # that's still being filed on the background single-writer thread.
        from memory_graph import runtime as _mem_runtime
        _mem_runtime.drain(timeout=60.0)
    except Exception:
        pass
    try:
        _cleanup_all_terminals()
    except Exception:
        pass
    try:
        _cleanup_all_browsers()
    except Exception:
        pass
    try:
        from tools.mcp_tool import shutdown_mcp_servers
        shutdown_mcp_servers()
    except Exception:
        pass


# =============================================================================
# Git Worktree Isolation (#652)
# =============================================================================

# Tracks the active worktree for cleanup on exit
_active_worktree: Optional[Dict[str, str]] = None


def _git_repo_root() -> Optional[str]:
    """Return the git repo root for CWD, or None if not in a repo."""
    import subprocess
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            capture_output=True, text=True, timeout=5,
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None


def _setup_worktree(repo_root: str = None) -> Optional[Dict[str, str]]:
    """Create an isolated git worktree for this CLI session.

    Returns a dict with worktree metadata on success, None on failure.
    The dict contains: path, branch, repo_root.
    """
    import subprocess

    repo_root = repo_root or _git_repo_root()
    if not repo_root:
        print("\033[31m✗ --worktree requires being inside a git repository.\033[0m")
        print("  cd into your project repo first, then run kai -w")
        return None

    short_id = uuid.uuid4().hex[:8]
    wt_name = f"kai-{short_id}"
    branch_name = f"kai/{wt_name}"

    worktrees_dir = Path(repo_root) / ".worktrees"
    worktrees_dir.mkdir(parents=True, exist_ok=True)

    wt_path = worktrees_dir / wt_name

    # Ensure .worktrees/ is in .gitignore
    gitignore = Path(repo_root) / ".gitignore"
    _ignore_entry = ".worktrees/"
    try:
        existing = gitignore.read_text() if gitignore.exists() else ""
        if _ignore_entry not in existing.splitlines():
            with open(gitignore, "a") as f:
                if existing and not existing.endswith("\n"):
                    f.write("\n")
                f.write(f"{_ignore_entry}\n")
    except Exception as e:
        logger.debug("Could not update .gitignore: %s", e)

    # Create the worktree
    try:
        result = subprocess.run(
            ["git", "worktree", "add", str(wt_path), "-b", branch_name, "HEAD"],
            capture_output=True, text=True, timeout=30, cwd=repo_root,
        )
        if result.returncode != 0:
            print(f"\033[31m✗ Failed to create worktree: {result.stderr.strip()}\033[0m")
            return None
    except Exception as e:
        print(f"\033[31m✗ Failed to create worktree: {e}\033[0m")
        return None

    # Copy files listed in .worktreeinclude (gitignored files the agent needs)
    include_file = Path(repo_root) / ".worktreeinclude"
    if include_file.exists():
        try:
            for line in include_file.read_text().splitlines():
                entry = line.strip()
                if not entry or entry.startswith("#"):
                    continue
                src = Path(repo_root) / entry
                dst = wt_path / entry
                if src.is_file():
                    dst.parent.mkdir(parents=True, exist_ok=True)
                    shutil.copy2(str(src), str(dst))
                elif src.is_dir():
                    # Symlink directories (faster, saves disk)
                    if not dst.exists():
                        dst.parent.mkdir(parents=True, exist_ok=True)
                        os.symlink(str(src.resolve()), str(dst))
        except Exception as e:
            logger.debug("Error copying .worktreeinclude entries: %s", e)

    info = {
        "path": str(wt_path),
        "branch": branch_name,
        "repo_root": repo_root,
    }

    print(f"\033[32m✓ Worktree created:\033[0m {wt_path}")
    print(f"  Branch: {branch_name}")

    return info


def _cleanup_worktree(info: Dict[str, str] = None) -> None:
    """Remove a worktree and its branch on exit.

    If the worktree has uncommitted changes, warn and keep it.
    """
    global _active_worktree
    info = info or _active_worktree
    if not info:
        return

    import subprocess

    wt_path = info["path"]
    branch = info["branch"]
    repo_root = info["repo_root"]

    if not Path(wt_path).exists():
        return

    # Check for uncommitted changes
    try:
        status = subprocess.run(
            ["git", "status", "--porcelain"],
            capture_output=True, text=True, timeout=10, cwd=wt_path,
        )
        has_changes = bool(status.stdout.strip())
    except Exception:
        has_changes = True  # Assume dirty on error — don't delete

    if has_changes:
        print(f"\n\033[33m⚠ Worktree has uncommitted changes, keeping: {wt_path}\033[0m")
        print(f"  To clean up manually: git worktree remove {wt_path}")
        _active_worktree = None
        return

    # Remove worktree
    try:
        subprocess.run(
            ["git", "worktree", "remove", wt_path, "--force"],
            capture_output=True, text=True, timeout=15, cwd=repo_root,
        )
    except Exception as e:
        logger.debug("Failed to remove worktree: %s", e)

    # Delete the branch (only if it was never pushed / has no upstream)
    try:
        subprocess.run(
            ["git", "branch", "-D", branch],
            capture_output=True, text=True, timeout=10, cwd=repo_root,
        )
    except Exception as e:
        logger.debug("Failed to delete branch %s: %s", branch, e)

    _active_worktree = None
    print(f"\033[32m✓ Worktree cleaned up: {wt_path}\033[0m")


def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
    """Remove worktrees older than max_age_hours that have no uncommitted changes.

    Runs silently on startup to clean up after crashed/killed sessions.
    """
    import subprocess
    import time

    worktrees_dir = Path(repo_root) / ".worktrees"
    if not worktrees_dir.exists():
        return

    now = time.time()
    cutoff = now - (max_age_hours * 3600)

    for entry in worktrees_dir.iterdir():
        if not entry.is_dir() or not entry.name.startswith("kai-"):
            continue

        # Check age
        try:
            mtime = entry.stat().st_mtime
            if mtime > cutoff:
                continue  # Too recent — skip
        except Exception:
            continue

        # Check for uncommitted changes
        try:
            status = subprocess.run(
                ["git", "status", "--porcelain"],
                capture_output=True, text=True, timeout=5, cwd=str(entry),
            )
            if status.stdout.strip():
                continue  # Has changes — skip
        except Exception:
            continue  # Can't check — skip

        # Safe to remove
        try:
            branch_result = subprocess.run(
                ["git", "branch", "--show-current"],
                capture_output=True, text=True, timeout=5, cwd=str(entry),
            )
            branch = branch_result.stdout.strip()

            subprocess.run(
                ["git", "worktree", "remove", str(entry), "--force"],
                capture_output=True, text=True, timeout=15, cwd=repo_root,
            )
            if branch:
                subprocess.run(
                    ["git", "branch", "-D", branch],
                    capture_output=True, text=True, timeout=10, cwd=repo_root,
                )
            logger.debug("Pruned stale worktree: %s", entry.name)
        except Exception as e:
            logger.debug("Failed to prune worktree %s: %s", entry.name, e)

# ============================================================================
# ASCII Art & Branding
# ============================================================================

# Kai cloud palette (hex colors for Rich markup) — matches kai-frontend:
# - Brand teal:  #2a7ba5 (structure — borders, rules, labels, mark top)
# - Light teal:  #5fb0d4 (emphasis — titles, accents, model, mark bottom)
# - Text:        #EAEAEA (body text / values)
# - Dim:         #5a6b78 (muted text / separators)
# Danger affordances (sudo/approval warning reds & oranges) are kept as-is.

class ChatConsole:
    """Rich Console adapter for prompt_toolkit's patch_stdout context.

    Captures Rich's rendered ANSI output and routes it through _cprint
    so colors and markup render correctly inside the interactive chat loop.
    Drop-in replacement for Rich Console — just pass this to any function
    that expects a console.print() interface.
    """

    def __init__(self):
        from io import StringIO
        self._buffer = StringIO()
        self._inner = Console(file=self._buffer, force_terminal=True, highlight=False)

    def print(self, *args, **kwargs):
        self._buffer.seek(0)
        self._buffer.truncate()
        # Read terminal width at render time so panels adapt to current size.
        # Reserve the last column: a rule/panel exactly `columns` wide overflows
        # by one cell under prompt_toolkit's patch_stdout and wraps the border
        # rules onto extra lines. columns-1 keeps them on a single line.
        self._inner.width = max(20, shutil.get_terminal_size((80, 24)).columns - 1)
        self._inner.print(*args, **kwargs)
        output = self._buffer.getvalue()
        for line in output.rstrip("\n").split("\n"):
            _cprint(line)

def _build_compact_banner() -> str:
    """Build a compact banner that fits the current terminal width."""
    w = min(shutil.get_terminal_size().columns - 2, 64)
    if w < 30:
        return "\n[#2a7ba5]◆ kai[/] [dim #5fb0d4]· by Dria[/]\n"
    inner = w - 2  # inside the box border
    bar = "═" * w
    line1 = "◆ kai · open-source coding agent"
    line2 = "research · engineering · sub-harnesses  ·  Dria"
    # Truncate and pad to fit
    line1 = line1[:inner - 2].ljust(inner - 2)
    line2 = line2[:inner - 2].ljust(inner - 2)
    return (
        f"\n[bold #2a7ba5]╔{bar}╗[/]\n"
        f"[bold #2a7ba5]║[/] [#EAEAEA]{line1}[/] [bold #2a7ba5]║[/]\n"
        f"[bold #2a7ba5]║[/] [#5fb0d4]{line2}[/] [bold #2a7ba5]║[/]\n"
        f"[bold #2a7ba5]╚{bar}╝[/]\n"
    )


def _get_available_skills() -> Dict[str, List[str]]:
    """
    Scan ~/.kai-agent/skills/ and return skills grouped by category.
    
    Returns:
        Dict mapping category name to list of skill names
    """
    import os
    
    kai_home_dir = kai_home()
    skills_dir = kai_home_dir / "skills"
    skills_by_category = {}
    
    if not skills_dir.exists():
        return skills_by_category
    
    for skill_file in skills_dir.rglob("SKILL.md"):
        rel_path = skill_file.relative_to(skills_dir)
        parts = rel_path.parts
        
        if len(parts) >= 2:
            category = parts[0]
            skill_name = parts[-2]
        else:
            category = "general"
            skill_name = skill_file.parent.name
        
        skills_by_category.setdefault(category, []).append(skill_name)
    
    return skills_by_category


def _format_context_length(tokens: int) -> str:
    """Format a token count for display (e.g. 128000 → '128K', 1048576 → '1M')."""
    if tokens >= 1_000_000:
        val = tokens / 1_000_000
        return f"{val:g}M"
    elif tokens >= 1_000:
        val = tokens / 1_000
        return f"{val:g}K"
    return str(tokens)


def build_welcome_banner(console: Console, model: str, cwd: str, tools: List[dict] = None, enabled_toolsets: List[str] = None, session_id: str = None, context_length: int = None):
    """
    Build and print a Claude Code-style welcome banner with Kai mark on left and info on right.
    
    Args:
        console: Rich Console instance for printing
        model: The current model name (e.g., "anthropic/claude-opus-4")
        cwd: Current working directory
        tools: List of tool definitions
        enabled_toolsets: List of enabled toolset names
        session_id: Unique session identifier for logging
        context_length: Model's context window size in tokens
    """
    from model_tools import check_tool_availability, TOOLSET_REQUIREMENTS
    
    tools = tools or []
    enabled_toolsets = enabled_toolsets or []
    
    # Get unavailable tools info for coloring
    _, unavailable_toolsets = check_tool_availability(quiet=True)
    disabled_tools = set()
    for item in unavailable_toolsets:
        disabled_tools.update(item.get("tools", []))
    
    # Build the side-by-side content using a table for precise control
    layout_table = Table.grid(padding=(0, 2))
    layout_table.add_column("left", justify="center")
    layout_table.add_column("right", justify="left")
    
    # Build left content: Kai mark + model info
    # Resolve skin colors for the banner
    try:
        from kai_cli.skin_engine import get_active_skin
        _bskin = get_active_skin()
        _accent = _bskin.get_color("banner_accent", "#5fb0d4")
        _dim = _bskin.get_color("banner_dim", "#5a6b78")
        _text = _bskin.get_color("banner_text", "#EAEAEA")
        _session_c = _bskin.get_color("session_border", "#5a6b78")
        _title_c = _bskin.get_color("banner_title", "#2a7ba5")
        _border_c = _bskin.get_color("banner_border", "#2a7ba5")
        _agent_name = _bskin.get_branding("agent_name", "kai")
    except Exception:
        _bskin = None
        _accent, _dim, _text = "#5fb0d4", "#5a6b78", "#EAEAEA"
        _session_c, _title_c, _border_c = "#5a6b78", "#2a7ba5", "#2a7ba5"
        _agent_name = "kai"

    _hero = _bskin.banner_hero if hasattr(_bskin, 'banner_hero') and _bskin.banner_hero else KAI_AGENT_LOGO
    left_lines = ["", _hero, ""]
    
    # Shorten model name for display
    model_short = model.split("/")[-1] if "/" in model else model
    if len(model_short) > 28:
        model_short = model_short[:25] + "..."
    
    ctx_str = f" [dim {_dim}]·[/] [dim {_dim}]{_format_context_length(context_length)} context[/]" if context_length else ""
    left_lines.append(f"[{_accent}]{model_short}[/]{ctx_str} [dim {_dim}]·[/] [dim {_dim}]Dria[/]")
    left_lines.append(f"[dim {_dim}]{cwd}[/]")
    
    # Add session ID if provided
    if session_id:
        left_lines.append(f"[dim {_session_c}]Session: {session_id}[/]")
    left_content = "\n".join(left_lines)
    
    # Build right content: tools list grouped by toolset
    right_lines = []
    right_lines.append(f"[bold {_accent}]Available Tools[/]")
    
    # Group tools by toolset (include all possible tools, both enabled and disabled)
    toolsets_dict = {}
    
    # First, add all enabled tools
    for tool in tools:
        tool_name = tool["function"]["name"]
        toolset = get_toolset_for_tool(tool_name) or "other"
        if toolset not in toolsets_dict:
            toolsets_dict[toolset] = []
        toolsets_dict[toolset].append(tool_name)
    
    # Also add disabled toolsets so they show in the banner
    for item in unavailable_toolsets:
        # Map the internal toolset ID to display name
        toolset_id = item.get("id", item.get("name", "unknown"))
        display_name = f"{toolset_id}_tools" if not toolset_id.endswith("_tools") else toolset_id
        if display_name not in toolsets_dict:
            toolsets_dict[display_name] = []
        for tool_name in item.get("tools", []):
            if tool_name not in toolsets_dict[display_name]:
                toolsets_dict[display_name].append(tool_name)
    
    # Display tools grouped by toolset (compact format, max 8 groups)
    sorted_toolsets = sorted(toolsets_dict.keys())
    display_toolsets = sorted_toolsets[:8]
    remaining_toolsets = len(sorted_toolsets) - 8
    
    for toolset in display_toolsets:
        tool_names = toolsets_dict[toolset]
        # Color each tool name - red if disabled, normal if enabled
        colored_names = []
        for name in sorted(tool_names):
            if name in disabled_tools:
                colored_names.append(f"[red]{name}[/]")
            else:
                colored_names.append(f"[{_text}]{name}[/]")
        
        tools_str = ", ".join(colored_names)
        # Truncate if too long (accounting for markup)
        if len(", ".join(sorted(tool_names))) > 45:
            # Rebuild with truncation
            short_names = []
            length = 0
            for name in sorted(tool_names):
                if length + len(name) + 2 > 42:
                    short_names.append("...")
                    break
                short_names.append(name)
                length += len(name) + 2
            # Re-color the truncated list
            colored_names = []
            for name in short_names:
                if name == "...":
                    colored_names.append("[dim]...[/]")
                elif name in disabled_tools:
                    colored_names.append(f"[red]{name}[/]")
                else:
                    colored_names.append(f"[{_text}]{name}[/]")
            tools_str = ", ".join(colored_names)
        
        right_lines.append(f"[dim {_dim}]{toolset}:[/] {tools_str}")
    
    if remaining_toolsets > 0:
        right_lines.append(f"[dim {_dim}](and {remaining_toolsets} more toolsets...)[/]")
    
    right_lines.append("")
    
    # Add skills section
    right_lines.append(f"[bold {_accent}]Available Skills[/]")
    skills_by_category = _get_available_skills()
    total_skills = sum(len(s) for s in skills_by_category.values())
    
    if skills_by_category:
        for category in sorted(skills_by_category.keys()):
            skill_names = sorted(skills_by_category[category])
            # Show first 8 skills, then "..." if more
            if len(skill_names) > 8:
                display_names = skill_names[:8]
                skills_str = ", ".join(display_names) + f" +{len(skill_names) - 8} more"
            else:
                skills_str = ", ".join(skill_names)
            # Truncate if still too long
            if len(skills_str) > 50:
                skills_str = skills_str[:47] + "..."
            right_lines.append(f"[dim {_dim}]{category}:[/] [{_text}]{skills_str}[/]")
    else:
        right_lines.append(f"[dim {_dim}]No skills installed[/]")
    
    right_lines.append("")
    right_lines.append(f"[dim {_dim}]{len(tools)} tools · {total_skills} skills · /help for commands[/]")
    
    right_content = "\n".join(right_lines)
    
    # Add to table
    layout_table.add_row(left_content, right_content)
    
    # Wrap in a panel with the title
    outer_panel = Panel(
        layout_table,
        title=f"[bold {_title_c}]{_agent_name} v{VERSION} ({RELEASE_DATE})[/]",
        border_style=_border_c,
        padding=(0, 2),
    )
    
    # Print the panel with the Kai wordmark and info
    console.print()
    console.print(outer_panel)


# ============================================================================
# Skill Slash Commands — dynamic commands generated from installed skills
# ============================================================================

from agent.skill_commands import scan_skill_commands, get_skill_commands, build_skill_invocation_message

_skill_commands = scan_skill_commands()


def save_config_value(key_path: str, value: any) -> bool:
    """
    Save a value to the active config file at the specified key path.
    
    Respects the same lookup order as load_cli_config():
    1. ~/.kai-agent/config.yaml (user config - preferred, used if it exists)
    2. ./cli-config.yaml (project config - fallback)
    
    Args:
        key_path: Dot-separated path like "agent.system_prompt"
        value: Value to save
    
    Returns:
        True if successful, False otherwise
    """
    # Use the same precedence as load_cli_config: user config first, then project config
    user_config_path = Path.home() / '.kai-agent' / 'config.yaml'
    project_config_path = Path(__file__).parent / 'cli-config.yaml'
    config_path = user_config_path if user_config_path.exists() else project_config_path

    try:
        # Ensure parent directory exists (for ~/.kai-agent/config.yaml on first use)
        config_path.parent.mkdir(parents=True, exist_ok=True)
        
        # Load existing config
        if config_path.exists():
            with open(config_path, 'r') as f:
                config = yaml.safe_load(f) or {}
        else:
            config = {}
        
        # Navigate to the key and set value
        keys = key_path.split('.')
        current = config
        for key in keys[:-1]:
            if key not in current or not isinstance(current[key], dict):
                current[key] = {}
            current = current[key]
        current[keys[-1]] = value
        
        # Save back
        with open(config_path, 'w') as f:
            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
        
        # Enforce owner-only permissions on config files (contain API keys)
        try:
            os.chmod(config_path, 0o600)
        except (OSError, NotImplementedError):
            pass
        
        return True
    except Exception as e:
        logger.error("Failed to save config: %s", e)
        return False


# ============================================================================
# KaiCLI Class
# ============================================================================

class KaiCLI(InteractiveCallbacksMixin, ImageInputMixin, SessionOpsMixin, DisplayMixin, CommandHandlersMixin):
    """
    Interactive CLI for Kai Agent.
    
    Provides a REPL interface with rich formatting, command history,
    and tool execution capabilities.
    """
    
    def __init__(
        self,
        model: str = None,
        toolsets: List[str] = None,
        provider: str = None,
        api_key: str = None,
        base_url: str = None,
        max_turns: int = None,
        verbose: bool = False,
        compact: bool = False,
        resume: str = None,
        checkpoints: bool = False,
        pass_session_id: bool = False,
    ):
        """
        Initialize the Kai CLI.

        Args:
            model: Model to use (default: from env or claude-sonnet)
            toolsets: List of toolsets to enable (default: all)
            provider: Inference provider ("auto", "openrouter", "nous", "openai-codex", "zai", "kimi-coding", "minimax", "minimax-cn")
            api_key: API key (default: from environment)
            base_url: API base URL (default: OpenRouter)
            max_turns: Maximum tool-calling iterations shared with subagents (default: 90)
            verbose: Enable verbose logging
            compact: Use compact display mode
            resume: Session ID to resume (restores conversation history from SQLite)
            pass_session_id: Include the session ID in the agent's system prompt
        """
        # Initialize Rich console
        self.console = Console()
        self.config = CLI_CONFIG
        self.compact = compact if compact is not None else CLI_CONFIG["display"].get("compact", False)
        # tool_progress: "off", "new", "all", "verbose" (from config.yaml display section)
        self.tool_progress_mode = CLI_CONFIG["display"].get("tool_progress", "all")
        # resume_display: "full" (show history) | "minimal" (one-liner only)
        self.resume_display = CLI_CONFIG["display"].get("resume_display", "full")
        # bell_on_complete: play terminal bell (\a) when agent finishes a response
        self.bell_on_complete = CLI_CONFIG["display"].get("bell_on_complete", False)
        # show_reasoning: display model thinking/reasoning before the response
        self.show_reasoning = CLI_CONFIG["display"].get("show_reasoning", False)
        self.verbose = verbose if verbose is not None else (self.tool_progress_mode == "verbose")
        
        # Configuration - priority: CLI args > env vars > config file
        # Model comes from: CLI arg or config.yaml (single source of truth).
        # LLM_MODEL/OPENAI_MODEL env vars are NOT checked — config.yaml is
        # authoritative.  This avoids conflicts in multi-agent setups where
        # env vars would stomp each other.
        _model_config = CLI_CONFIG.get("model", {})
        _config_model = _model_config.get("default", "") if isinstance(_model_config, dict) else (_model_config or "")
        self.model = model or _config_model or "anthropic/claude-opus-4.6"
        # Track whether model was explicitly chosen by the user or fell back
        # to the global default.  Provider-specific normalisation may override
        # the default silently but should warn when overriding an explicit choice.
        self._model_is_default = not model

        self._explicit_api_key = api_key
        self._explicit_base_url = base_url

        # Provider selection is resolved lazily at use-time via _ensure_runtime_credentials().
        self.requested_provider = (
            provider
            or get_env("KAI_INFERENCE_PROVIDER")
            or CLI_CONFIG["model"].get("provider")
            or "auto"
        )
        self._provider_source: Optional[str] = None
        self.provider = self.requested_provider
        self.api_mode = "chat_completions"
        self.base_url = (
            base_url
            or os.getenv("OPENAI_BASE_URL")
            or os.getenv("OPENROUTER_BASE_URL", CLI_CONFIG["model"]["base_url"])
        )
        # Match key to resolved base_url: OpenRouter URL → prefer OPENROUTER_API_KEY,
        # custom endpoint → prefer OPENAI_API_KEY (issue #560).
        # Note: _ensure_runtime_credentials() re-resolves this before first use.
        if "openrouter.ai" in self.base_url:
            self.api_key = api_key or os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENAI_API_KEY")
        else:
            self.api_key = api_key or os.getenv("OPENAI_API_KEY") or os.getenv("OPENROUTER_API_KEY")
        self._nous_key_expires_at: Optional[str] = None
        self._nous_key_source: Optional[str] = None
        # Max turns priority: CLI arg > config file > env var > default
        if max_turns is not None:  # CLI arg was explicitly set
            self.max_turns = max_turns
        elif CLI_CONFIG["agent"].get("max_turns"):
            self.max_turns = CLI_CONFIG["agent"]["max_turns"]
        elif CLI_CONFIG.get("max_turns"):  # Backwards compat: root-level max_turns
            self.max_turns = CLI_CONFIG["max_turns"]
        elif get_env("KAI_MAX_ITERATIONS"):
            self.max_turns = int(get_env("KAI_MAX_ITERATIONS"))
        else:
            self.max_turns = 90
        
        # Parse and validate toolsets
        self.enabled_toolsets = toolsets
        if toolsets and "all" not in toolsets and "*" not in toolsets:
            # Validate each toolset
            invalid = [t for t in toolsets if not validate_toolset(t)]
            if invalid:
                self.console.print(f"[bold red]Warning: Unknown toolsets: {', '.join(invalid)}[/]")
        
        # Filesystem checkpoints: CLI flag > config
        cp_cfg = CLI_CONFIG.get("checkpoints", {})
        if isinstance(cp_cfg, bool):
            cp_cfg = {"enabled": cp_cfg}
        self.checkpoints_enabled = checkpoints or cp_cfg.get("enabled", False)
        self.checkpoint_max_snapshots = cp_cfg.get("max_snapshots", 50)
        self.pass_session_id = pass_session_id
        
        # Ephemeral system prompt: env var takes precedence, then config
        self.system_prompt = (
            get_env("KAI_EPHEMERAL_SYSTEM_PROMPT")
            or CLI_CONFIG["agent"].get("system_prompt", "")
        )
        self.personalities = CLI_CONFIG["agent"].get("personalities", {})
        
        # Ephemeral prefill messages (few-shot priming, never persisted)
        self.prefill_messages = _load_prefill_messages(
            CLI_CONFIG["agent"].get("prefill_messages_file", "")
        )
        
        # Reasoning config (OpenRouter reasoning effort level)
        self.reasoning_config = _parse_reasoning_config(
            CLI_CONFIG["agent"].get("reasoning_effort", "")
        )
        
        # OpenRouter provider routing preferences
        pr = CLI_CONFIG.get("provider_routing", {}) or {}
        self._provider_sort = pr.get("sort")
        self._providers_only = pr.get("only")
        self._providers_ignore = pr.get("ignore")
        self._providers_order = pr.get("order")
        self._provider_require_params = pr.get("require_parameters", False)
        self._provider_data_collection = pr.get("data_collection")
        
        # Fallback model config — tried when primary provider fails after retries
        fb = CLI_CONFIG.get("fallback_model") or {}
        self._fallback_model = fb if fb.get("provider") and fb.get("model") else None

        # Agent will be initialized on first use
        self.agent: Optional[AIAgent] = None
        self._app = None  # prompt_toolkit Application (set in run())
        
        # Conversation state
        self.conversation_history: List[Dict[str, Any]] = []
        self.session_start = datetime.now()
        self._resumed = False
        # Initialize SQLite session store early so /title works before first message
        self._session_db = None
        try:
            from kai_state import SessionDB
            self._session_db = SessionDB()
        except Exception:
            pass
        
        # Deferred title: stored in memory until the session is created in the DB
        self._pending_title: Optional[str] = None
        
        # Session ID: reuse existing one when resuming, otherwise generate fresh
        if resume:
            self.session_id = resume
            self._resumed = True
        else:
            timestamp_str = self.session_start.strftime("%Y%m%d_%H%M%S")
            short_uuid = uuid.uuid4().hex[:6]
            self.session_id = f"{timestamp_str}_{short_uuid}"
        
        # History file for persistent input recall across sessions
        self._history_file = Path.home() / ".kai_history"
        self._last_invalidate: float = 0.0  # throttle UI repaints
        self._spinner_text: str = ""  # thinking spinner text for TUI
        self._command_running = False
        self._command_status = ""

        # Background task tracking: {task_id: threading.Thread}
        self._background_tasks: Dict[str, threading.Thread] = {}
        self._background_task_counter = 0
        # Async hand-off: worker threads push progress/result strings here; the
        # process_loop thread drains + prints them so all output is single-threaded.
        self._handoff_notifications: "queue.Queue[str]" = queue.Queue()

    def _invalidate(self, min_interval: float = 0.25) -> None:
        """Throttled UI repaint — prevents terminal blinking on slow/SSH connections."""
        import time as _time
        now = _time.monotonic()
        if hasattr(self, "_app") and self._app and (now - self._last_invalidate) >= min_interval:
            self._last_invalidate = now
            self._app.invalidate()

    def _normalize_model_for_provider(self, resolved_provider: str) -> bool:
        """Strip provider prefixes and swap the default model for Codex.

        When the resolved provider is ``openai-codex``:

        1. Strip any ``provider/`` prefix (the Codex Responses API only
           accepts bare model slugs like ``gpt-5.4``, not ``openai/gpt-5.4``).
        2. If the active model is still the *untouched default* (user never
           explicitly chose a model), replace it with a Codex-compatible
           default so the first session doesn't immediately error.

        When the resolved provider is ``anthropic`` or ``openai`` (native
        first-party endpoints), strip the OpenRouter ``vendor/`` prefix so the
        native API receives a bare model id (``claude-opus-4-5`` / ``gpt-5``).

        If the user explicitly chose a model — *any* model — we trust them
        and let the API be the judge.  No allowlists, no slug checks.

        Returns True when the active model was changed.
        """
        if resolved_provider in ("anthropic", "openai"):
            from kai_cli.runtime_provider import normalize_model_for_provider
            normalized = normalize_model_for_provider(self.model or "", resolved_provider)
            if normalized != (self.model or ""):
                self.model = normalized
                return True
            return False

        if resolved_provider != "openai-codex":
            return False

        current_model = (self.model or "").strip()
        changed = False

        # 1. Strip provider prefix ("openai/gpt-5.4" → "gpt-5.4")
        if "/" in current_model:
            slug = current_model.split("/", 1)[1]
            if not self._model_is_default:
                self.console.print(
                    f"[yellow]⚠️  Stripped provider prefix from '{current_model}'; "
                    f"using '{slug}' for OpenAI Codex.[/]"
                )
            self.model = slug
            current_model = slug
            changed = True

        # 2. Replace untouched non-Codex defaults with a Codex model.
        # A config-selected Codex default is still a default, but it is already
        # provider-compatible and should not be overwritten by account ordering.
        if self._model_is_default and "codex" not in current_model.lower():
            fallback_model = "gpt-5.3-codex"
            try:
                from kai_cli.codex_models import get_codex_model_ids

                available = get_codex_model_ids(
                    access_token=self.api_key if self.api_key else None,
                )
                if available:
                    fallback_model = available[0]
            except Exception:
                pass

            if current_model != fallback_model:
                self.model = fallback_model
                changed = True

        return changed

    def _on_thinking(self, text: str) -> None:
        """Called by agent when thinking starts/stops. Updates TUI spinner."""
        self._spinner_text = text or ""
        self._invalidate()

    def _slow_command_status(self, command: str) -> str:
        """Return a user-facing status message for slower slash commands."""
        cmd_lower = command.lower().strip()
        if cmd_lower.startswith("/skills search"):
            return "Searching skills..."
        if cmd_lower.startswith("/skills browse"):
            return "Loading skills..."
        if cmd_lower.startswith("/skills inspect"):
            return "Inspecting skill..."
        if cmd_lower.startswith("/skills install"):
            return "Installing skill..."
        if cmd_lower.startswith("/skills"):
            return "Processing skills command..."
        if cmd_lower.startswith("/jobs"):
            return "Fetching GitHub jobs..."
        if cmd_lower == "/reload-mcp":
            return "Reloading MCP servers..."
        return "Processing command..."

    def _command_spinner_frame(self) -> str:
        """Return the current spinner frame for slow slash commands."""
        import time as _time

        frame_idx = int(_time.monotonic() * 10) % len(_COMMAND_SPINNER_FRAMES)
        return _COMMAND_SPINNER_FRAMES[frame_idx]

    @contextmanager
    def _busy_command(self, status: str):
        """Expose a temporary busy state in the TUI while a slash command runs."""
        self._command_running = True
        self._command_status = status
        self._invalidate(min_interval=0.0)
        try:
            print(f"⏳ {status}")
            yield
        finally:
            self._command_running = False
            self._command_status = ""
            self._invalidate(min_interval=0.0)

    def _ensure_runtime_credentials(self) -> bool:
        """
        Ensure runtime credentials are resolved before agent use.
        Re-resolves provider credentials so key rotation and token refresh
        are picked up without restarting the CLI.
        Returns True if credentials are ready, False on auth failure.
        """
        from kai_cli.runtime_provider import (
            resolve_runtime_provider,
            format_runtime_provider_error,
        )

        try:
            runtime = resolve_runtime_provider(
                requested=self.requested_provider,
                explicit_api_key=self._explicit_api_key,
                explicit_base_url=self._explicit_base_url,
            )
        except Exception as exc:
            message = format_runtime_provider_error(exc)
            self.console.print(f"[bold red]{message}[/]")
            return False

        api_key = runtime.get("api_key")
        base_url = runtime.get("base_url")
        resolved_provider = runtime.get("provider", "openrouter")
        resolved_api_mode = runtime.get("api_mode", self.api_mode)
        if not isinstance(api_key, str) or not api_key:
            self.console.print("[bold red]Provider resolver returned an empty API key.[/]")
            return False
        if not isinstance(base_url, str) or not base_url:
            self.console.print("[bold red]Provider resolver returned an empty base URL.[/]")
            return False

        credentials_changed = api_key != self.api_key or base_url != self.base_url
        routing_changed = (
            resolved_provider != self.provider
            or resolved_api_mode != self.api_mode
        )
        self.provider = resolved_provider
        self.api_mode = resolved_api_mode
        self._provider_source = runtime.get("source")
        self.api_key = api_key
        self.base_url = base_url

        # Normalize model for the resolved provider (e.g. swap non-Codex
        # models when provider is openai-codex).  Fixes #651.
        model_changed = self._normalize_model_for_provider(resolved_provider)

        # AIAgent/OpenAI client holds auth at init time, so rebuild if key,
        # routing, or the effective model changed.
        if (credentials_changed or routing_changed or model_changed) and self.agent is not None:
            self.agent = None

        return True

    def _init_agent(self) -> bool:
        """
        Initialize the agent on first use.
        When resuming a session, restores conversation history from SQLite.
        
        Returns:
            bool: True if successful, False otherwise
        """
        if self.agent is not None:
            return True

        if not self._ensure_runtime_credentials():
            return False

        # Initialize SQLite session store for CLI sessions (if not already done in __init__)
        if self._session_db is None:
            try:
                from kai_state import SessionDB
                self._session_db = SessionDB()
            except Exception as e:
                logger.debug("SQLite session store not available: %s", e)
        
        # If resuming, validate the session exists and load its history.
        # _preload_resumed_session() may have already loaded it (called from
        # run() for immediate display).  In that case, conversation_history
        # is non-empty and we skip the DB round-trip.
        if self._resumed and self._session_db and not self.conversation_history:
            session_meta = self._session_db.get_session(self.session_id)
            if not session_meta:
                _cprint(f"\033[1;31mSession not found: {self.session_id}{_RST}")
                _cprint(f"{_DIM}Use a session ID from a previous CLI run (kai sessions list).{_RST}")
                return False
            restored = self._session_db.get_messages_as_conversation(self.session_id)
            if restored:
                self.conversation_history = restored
                msg_count = len([m for m in restored if m.get("role") == "user"])
                title_part = ""
                if session_meta.get("title"):
                    title_part = f" \"{session_meta['title']}\""
                _cprint(
                    f"{_GOLD}↻ Resumed session {_BOLD}{self.session_id}{_RST}{_GOLD}{title_part} "
                    f"({msg_count} user message{'s' if msg_count != 1 else ''}, "
                    f"{len(restored)} total messages){_RST}"
                )
            else:
                _cprint(f"{_GOLD}Session {self.session_id} found but has no messages. Starting fresh.{_RST}")
            # Re-open the session (clear ended_at so it's active again)
            try:
                self._session_db._conn.execute(
                    "UPDATE sessions SET ended_at = NULL, end_reason = NULL WHERE id = ?",
                    (self.session_id,),
                )
                self._session_db._conn.commit()
            except Exception:
                pass
        
        # Load shared workspace context for cross-thread awareness
        self._ws_status = None
        self._ws_prompt = None
        try:
            from workspace_context_bridge import fetch_workspace_status, build_workspace_status_prompt, update_workspace_status
            self._ws_status = fetch_workspace_status()
            self._ws_prompt = build_workspace_status_prompt(self._ws_status) if self._ws_status else ""
            if self._ws_status and self._ws_status.get("onboardingStatus") == "not_started":
                update_workspace_status(
                    os.environ.get("KAI_WORKSPACE_ID", os.environ.get("KAI_WORKSPACE_ID", "default")),
                    "in_progress", "introduction"
                )
        except Exception as _wce:
            logger.debug("Workspace context load failed (non-fatal): %s", _wce)

        try:
            self.agent = AIAgent(
                model=self.model,
                api_key=self.api_key,
                base_url=self.base_url,
                provider=self.provider,
                api_mode=self.api_mode,
                max_iterations=self.max_turns,
                enabled_toolsets=self.enabled_toolsets,
                verbose_logging=self.verbose,
                quiet_mode=True,
                ephemeral_system_prompt=self.system_prompt if self.system_prompt else None,
                prefill_messages=self.prefill_messages or None,
                reasoning_config=self.reasoning_config,
                providers_allowed=self._providers_only,
                providers_ignored=self._providers_ignore,
                providers_order=self._providers_order,
                provider_sort=self._provider_sort,
                provider_require_parameters=self._provider_require_params,
                provider_data_collection=self._provider_data_collection,
                session_id=self.session_id,
                platform="cli",
                session_db=self._session_db,
                clarify_callback=self._clarify_callback,
                reasoning_callback=self._on_reasoning if self.show_reasoning else None,
                honcho_session_key=self.session_id,
                fallback_model=self._fallback_model,
                thinking_callback=self._on_thinking,
                checkpoints_enabled=self.checkpoints_enabled,
                checkpoint_max_snapshots=self.checkpoint_max_snapshots,
                pass_session_id=self.pass_session_id,
                # Clean memory kill-switch for A/B control arms: disables the
                # knowledge-graph (briefing, recall, flush, backfill) WITHOUT
                # changing the toolset, so memory is the only variable. Distinct
                # from --stateless, which also swaps the toolset.
                skip_memory=os.getenv("KAI_SKIP_MEMORY") == "1",
            )
            # Apply any pending title now that the session exists in the DB
            if self._pending_title and self._session_db:
                try:
                    self._session_db.set_session_title(self.session_id, self._pending_title)
                    _cprint(f"  Session title applied: {self._pending_title}")
                    self._pending_title = None
                except (ValueError, Exception) as e:
                    _cprint(f"  Could not apply pending title: {e}")
                    self._pending_title = None
            return True
        except Exception as e:
            self.console.print(f"[bold red]Failed to initialize agent: {e}[/]")
            return False
    








    
    
    
    
    
    
    
    
    
    
    

    


    

    

    
    # Terminal backends the agent's shell/file tools can run in (terminal_tool).
    _VALID_BACKENDS = ["local", "docker", "singularity", "modal", "daytona", "ssh"]

    def _current_backend(self) -> str:
        return os.getenv("TERMINAL_ENV", "local")

    def _interactive_pick(self, title, labels, current_idx=0):
        """Arrow-key picker — same selection UX as the clarify/approval prompts.

        Blocks the calling (command) thread until the user picks or cancels; the
        prompt_toolkit keybindings drive ↑/↓ + Enter on the UI thread and feed the
        result back through a queue. Returns the chosen index, or None if the user
        cancelled or there's no live TUI. MUST be called off the UI thread — slash
        commands run on the process_loop worker thread, so that holds.
        """
        if not labels:
            return None
        if getattr(self, "_app", None) is None:
            return None  # no live TUI (e.g. one-shot/non-interactive mode)
        response_queue = queue.Queue()
        self._picker_state = {
            "title": title,
            "labels": list(labels),
            "selected": max(0, min(current_idx, len(labels) - 1)),
            "response_queue": response_queue,
        }
        self._invalidate()
        try:
            while True:
                try:
                    return response_queue.get(timeout=0.5)
                except queue.Empty:
                    if self._picker_state is None:
                        return None  # cleared out from under us → treat as cancel
        finally:
            self._picker_state = None
            self._invalidate()

    def _show_backend_picker(self):
        """Arrow-key picker for the terminal backend; applies the choice."""
        current = self._current_backend()
        labels = [f"{b}  (active)" if b == current else b for b in self._VALID_BACKENDS]
        cur = self._VALID_BACKENDS.index(current) if current in self._VALID_BACKENDS else 0
        idx = self._interactive_pick("Terminal backend", labels, cur)
        if idx is not None:
            # Re-queue the typed command so the (tested) arg path applies it.
            self._pending_input.put(f"/backend {self._VALID_BACKENDS[idx]}")

    def _switch_backend(self, arg: str):
        name = arg.strip().lower()
        if name.isdigit():
            idx = int(name) - 1
            if not (0 <= idx < len(self._VALID_BACKENDS)):
                print(f"(>_<) No backend #{name}. Run /backend to see the list.")
                return
            name = self._VALID_BACKENDS[idx]
        if name not in self._VALID_BACKENDS:
            print(f"(>_<) Unknown backend '{arg}'. Options: {', '.join(self._VALID_BACKENDS)}")
            return
        if name == self._current_backend():
            print(f"(^_^) Terminal backend already: {name}")
            return
        # Live effect: terminal_tool reads TERMINAL_ENV fresh on each tool call,
        # so updating the running process env switches the next tool call. The
        # save also writes terminal.backend to config.yaml + syncs .env.
        os.environ["TERMINAL_ENV"] = name
        saved = save_config_value("terminal.backend", name)
        suffix = " (saved to config)" if saved else " (this session only)"
        print(f"(^_^)b Terminal backend → {name}{suffix}")
        if name in ("docker", "singularity", "modal", "daytona"):
            print(f"  Note: needs the {name} runtime available/running for tools to work.")

    def _resolve_current_provider(self) -> str:
        from kai_cli.models import normalize_provider
        from kai_cli.auth import resolve_provider as _resolve_provider
        raw = normalize_provider(self.provider)
        if raw != "auto":
            return raw
        try:
            return _resolve_provider(
                self.requested_provider,
                explicit_api_key=self._explicit_api_key,
                explicit_base_url=self._explicit_base_url,
            )
        except Exception:
            return "openrouter"

    def _show_provider_picker(self):
        """Arrow-key picker for the provider; applies the choice."""
        from kai_cli.models import list_available_providers
        providers = list_available_providers()
        current = self._resolve_current_provider()
        labels, cur = [], 0
        for i, p in enumerate(providers):
            if p["id"] == current:
                cur, tag = i, "  (active)"
            elif not p.get("authenticated"):
                tag = "  (not configured)"
            else:
                tag = ""
            labels.append(f"{p['label']}{tag}")
        idx = self._interactive_pick("Provider", labels, cur)
        if idx is not None:
            self._pending_input.put(f"/provider {providers[idx]['id']}")

    def _switch_provider(self, arg: str):
        from kai_cli.models import _PROVIDER_LABELS, normalize_provider, list_available_providers
        name = arg.strip().lower()
        if name.isdigit():
            choices = [p["id"] for p in list_available_providers()]
            idx = int(name) - 1
            if not (0 <= idx < len(choices)):
                print(f"(>_<) No provider #{name}. Run /provider to see the list.")
                return
            name = choices[idx]
        name = normalize_provider(name)
        try:
            from kai_cli.runtime_provider import resolve_runtime_provider
            runtime = resolve_runtime_provider(requested=name)
        except Exception as e:
            label = _PROVIDER_LABELS.get(name, name)
            print(f"(>_<) Could not switch to provider '{label}': {e}")
            print("  Tip: run `kai setup` to configure its credentials.")
            return
        # OAuth providers (nous, openai-codex) resolve creds lazily; others need a key.
        if not runtime.get("api_key") and name not in ("nous", "openai-codex"):
            label = _PROVIDER_LABELS.get(name, name)
            print(f"(>_<) Provider '{label}' has no credentials configured. Run: kai setup")
            return
        self.requested_provider = name
        self.provider = name
        self.api_key = runtime.get("api_key", "") or self.api_key
        self.base_url = runtime.get("base_url", "") or self.base_url
        self.agent = None  # force re-init with the new provider/creds
        save_config_value("model.provider", name)
        label = _PROVIDER_LABELS.get(name, name)
        print(f"(^_^)b Provider → {label} (saved). Model stays: {self.model}")
        print("  If that model isn't available there, pick a new one with /model")

    def _show_model_picker(self):
        """Arrow-key picker for the model (curated models, authenticated providers).

        Falls back to the detailed text view when no curated models are available.
        """
        from kai_cli.models import list_available_providers, curated_models_for_provider
        providers = [p for p in list_available_providers() if p.get("authenticated")]
        labels, values, cur = [], [], 0
        for p in providers:
            for mid, _desc in curated_models_for_provider(p["id"]):
                if mid == self.model:
                    cur = len(values)
                suffix = "  (current)" if mid == self.model else ""
                labels.append(f"{p['label']}: {mid}{suffix}")
                values.append(f"{p['id']}:{mid}")
        if not values:
            self._show_model_and_providers()
            return
        idx = self._interactive_pick("Model", labels, cur)
        if idx is not None:
            self._pending_input.put(f"/model {values[idx]}")

    def _handle_handoff_command(self, prompt: str):
        """/hand-off <task>: ship the current workspace to a sandbox agent that
        works autonomously, IN THE BACKGROUND — you keep talking to the main
        agent and the result is reported above the prompt when it's done.

        Research preview. Runs persist to ~/.kai-agent/handoffs/<id>/; see
        ``/handoffs`` to list/inspect them.
        """
        import os
        prompt = (prompt or "").strip()
        if not prompt:
            print("Usage: /hand-off <what the sandbox agent should do>")
            print("  e.g. /hand-off add a README and a basic test suite")
            print("  (runs in the background — keep working; /handoffs to check status)")
            return
        try:
            from deploy.sandbox import get_provider
            from kai_cli import handoff_runner
        except Exception as e:
            print(f"(>_<) Hand-off unavailable: {e}")
            return
        try:
            provider = get_provider()
        except Exception as e:
            print(f"(>_<) Sandbox provider error: {e}")
            return
        provider_name = getattr(provider, "name", "?")
        workspace = os.getcwd()
        try:
            hid, run_dir, thread = handoff_runner.start_handoff(
                prompt, provider, workspace,
                notify=self._handoff_notifications.put,
            )
        except Exception as e:
            print(f"(>_<) Hand-off failed to start: {e}")
            return
        self._background_tasks[f"handoff:{hid}"] = thread
        print(f"\n  ⚗️  Hand-off {hid} started in the background "
              f"(provider: {provider_name}, research preview).")
        print("      Keep working — I'll report the result here when it's done.")
        print(f"      First sandbox run installs kai-agent in the box (can take a few "
              "minutes).")
        print(f"      /handoffs to check status · log: {run_dir}")

    def _handle_handoffs_command(self, arg: str = ""):
        """/handoffs [id]: list background hand-offs, or inspect one by id."""
        from kai_cli import handoff_runner
        arg = (arg or "").strip()
        if arg:
            rec = handoff_runner.get_handoff(arg)
            if not rec:
                print(f"(>_<) No hand-off '{arg}'. Try /handoffs to list them.")
                return
            meta = rec.get("meta", {})
            print(f"\n ─ ◆ hand-off {arg} ─")
            print(f"  status:  {meta.get('status', '?')}"
                  + (f"  ({meta.get('elapsed')}s)" if meta.get('elapsed') else ""))
            print(f"  prompt:  {meta.get('prompt', '')}")
            print(f"  provider:{meta.get('provider', '?')}   dir: {rec.get('dir')}")
            res = rec.get("result") or {}
            if res.get("response"):
                print(f"\n  response:\n{res['response']}")
            if meta.get("status") == "error":
                err = res.get("error") or rec.get("stderr", "")[-500:]
                print(f"\n  error: {err}")
            return
        runs = handoff_runner.list_handoffs()
        if not runs:
            print("\n  No hand-offs yet. Start one with /hand-off <task>.")
            return
        print("\n ─ ◆ hand-offs ─")
        for m in runs[:15]:
            mark = {"running": "⧖", "ok": "✓", "error": "✗"}.get(m.get("status"), "?")
            el = f" {m.get('elapsed')}s" if m.get("elapsed") else ""
            print(f"  {mark} {m.get('id')}  [{m.get('status','?')}{el}]  "
                  f"{(m.get('prompt') or '')[:54]}")
        print("  /handoffs <id> to inspect one.")

    def _handle_teleport_command(self):
        """/teleport: move this session to a sandbox and get a web URL to keep
        talking to the agent there (workspace + conversation come along).

        Research preview — boots a full agent in a sandbox seeded with the
        current conversation + workspace and serves it over a browser URL. The
        richer bidirectional-sync / polished-UI version is a future effort.
        """
        import os
        import secrets
        try:
            from deploy.sandbox import Job, get_provider
            from deploy.sandbox.payloads import TeleportPayload
        except Exception as e:
            print(f"(>_<) Teleport unavailable: {e}")
            return
        try:
            provider = get_provider()
        except Exception as e:
            print(f"(>_<) Sandbox provider error: {e}")
            return
        provider_name = getattr(provider, "name", "?")
        if provider_name == "local":
            print("\n  ⚗️  Teleport (research preview): on the 'local' provider the URL "
                  "is 127.0.0.1")
            print("      on THIS machine — handy for testing. Set KAI_SANDBOX_PROVIDER="
                  "e2b|vercel")
            print("      for a real shareable cloud URL.")
        else:
            print("\n  ⚗️  Teleport is a research preview — your session moves to a "
                  f"{provider_name}")
            print("      sandbox and you continue in the browser. Review its output; "
                  "results vary.")
        workspace = os.getcwd()
        token = secrets.token_urlsafe(24)
        history = list(getattr(self, "conversation_history", []) or [])
        payload = TeleportPayload(token=token, seed_history=history)
        # teardown=False — the sandbox must outlive this command so you can talk
        # to it. Synchronous on purpose: teleport is a one-way move to the
        # sandbox, so we block until the URL is ready (first run installs
        # kai-agent in the box, which can take a few minutes).
        job = Job(provider, payload, workspace_dir=workspace, teardown=False)
        try:
            with self._busy_command(f"Teleporting to {provider_name} sandbox "
                                    "(first run installs kai-agent, ~minutes)..."):
                result = job.run()
        except Exception as e:
            print(f"(>_<) Teleport failed: {e}")
            return
        if not (isinstance(result, dict) and result.get("status") == "ok"):
            err = result.get("error") if isinstance(result, dict) else result
            print(f"(>_<) Teleport did not come up cleanly: {err}")
            return

        url, tok = result.get("url"), result.get("token")
        full = f"{url}?token={tok}" if url and tok else url
        print("\n ─ ◆ Teleport ready ─")
        print(f"  Open: {full}")
        print(f"  Sandbox: {result.get('sandbox_id')}  (port {result.get('port')})")
        print("  Your conversation moved there. This terminal is paused until you")
        print("  click 'End session' in the web UI (which terminates the sandbox).")

        # Block the TUI while the session lives in the browser — it's one
        # conversation, so we don't let you talk in two places. We poll the
        # sandbox's /status (public, no token); the web "End session" button
        # flips alive→false, then we tear the sandbox down and return here.
        import json as _json
        import time as _time
        import urllib.request as _u
        status_url = f"{url.rstrip('/')}/status"
        fails = 0
        deadline = _time.monotonic() + 7200  # absolute cap (matches job timeout)
        try:
            with self._busy_command("Teleport session active in the browser — "
                                    "End it there to return…"):
                while _time.monotonic() < deadline:
                    _time.sleep(3)
                    try:
                        s = _json.loads(_u.urlopen(status_url, timeout=5).read())
                        fails = 0
                        if not s.get("alive", True):
                            break
                    except Exception:
                        fails += 1
                        if fails >= 10:  # ~30s unreachable → sandbox is gone
                            break
        except KeyboardInterrupt:
            print("\n  Interrupted — terminating the teleport sandbox.")
        try:
            job.handle.kill()
        except Exception:
            pass
        print("  ◆ Teleport ended — sandbox terminated. You're back in your terminal.")

    def process_command(self, command: str) -> bool:
        """
        Process a slash command.
        
        Args:
            command: The command string (starting with /)
            
        Returns:
            bool: True to continue, False to exit
        """
        # Lowercase only for dispatch matching; preserve original case for arguments
        cmd_lower = command.lower().strip()
        cmd_original = command.strip()
        
        if cmd_lower in ("/quit", "/exit", "/q"):
            return False
        elif cmd_lower == "/help":
            self.show_help()
        elif cmd_lower == "/tools":
            self.show_tools()
        elif cmd_lower == "/toolsets":
            self.show_toolsets()
        elif cmd_lower == "/config":
            self.show_config()
        elif cmd_lower == "/clear":
            # Flush memories before clearing
            if self.agent and self.conversation_history:
                try:
                    self.agent.flush_memories(self.conversation_history)
                except Exception:
                    pass
            # Clear terminal screen.  Inside the TUI, Rich's console.clear()
            # goes through patch_stdout's StdoutProxy which swallows the
            # screen-clear escape sequences.  Use prompt_toolkit's output
            # object directly to actually clear the terminal.
            if self._app:
                out = self._app.output
                out.erase_screen()
                out.cursor_goto(0, 0)
                out.flush()
            else:
                self.console.clear()
            # Reset conversation
            self.conversation_history = []
            # Show fresh banner.  Inside the TUI we must route Rich output
            # through ChatConsole (which uses prompt_toolkit's native ANSI
            # renderer) instead of self.console (which writes raw to stdout
            # and gets mangled by patch_stdout).
            if self._app:
                cc = ChatConsole()
                term_w = shutil.get_terminal_size().columns
                if self.compact or term_w < 80:
                    cc.print(_build_compact_banner())
                else:
                    tools = get_tool_definitions(enabled_toolsets=self.enabled_toolsets, quiet_mode=True)
                    cwd = os.getenv("TERMINAL_CWD", os.getcwd())
                    ctx_len = None
                    if hasattr(self, 'agent') and self.agent and hasattr(self.agent, 'context_compressor'):
                        ctx_len = self.agent.context_compressor.context_length
                    build_welcome_banner(
                        console=cc,
                        model=self.model,
                        cwd=cwd,
                        tools=tools,
                        enabled_toolsets=self.enabled_toolsets,
                        session_id=self.session_id,
                        context_length=ctx_len,
                    )
                _cprint("  ✨ (◕‿◕)✨ Fresh start! Screen cleared and conversation reset.\n")
            else:
                self.show_banner()
                print("  ✨ (◕‿◕)✨ Fresh start! Screen cleared and conversation reset.\n")
        elif cmd_lower == "/history":
            self.show_history()
        elif cmd_lower.startswith("/title"):
            parts = cmd_original.split(maxsplit=1)
            if len(parts) > 1:
                raw_title = parts[1].strip()
                if raw_title:
                    if self._session_db:
                        # Sanitize the title early so feedback matches what gets stored
                        try:
                            from kai_state import SessionDB
                            new_title = SessionDB.sanitize_title(raw_title)
                        except ValueError as e:
                            _cprint(f"  {e}")
                            new_title = None
                        if not new_title:
                            _cprint("  Title is empty after cleanup. Please use printable characters.")
                        elif self._session_db.get_session(self.session_id):
                            # Session exists in DB — set title directly
                            try:
                                if self._session_db.set_session_title(self.session_id, new_title):
                                    _cprint(f"  Session title set: {new_title}")
                                else:
                                    _cprint("  Session not found in database.")
                            except ValueError as e:
                                _cprint(f"  {e}")
                        else:
                            # Session not created yet — defer the title
                            # Check uniqueness proactively with the sanitized title
                            existing = self._session_db.get_session_by_title(new_title)
                            if existing:
                                _cprint(f"  Title '{new_title}' is already in use by session {existing['id']}")
                            else:
                                self._pending_title = new_title
                                _cprint(f"  Session title queued: {new_title} (will be saved on first message)")
                    else:
                        _cprint("  Session database not available.")
                else:
                    _cprint("  Usage: /title <your session title>")
            else:
                # Show current title if no argument given
                if self._session_db:
                    session = self._session_db.get_session(self.session_id)
                    if session and session.get("title"):
                        _cprint(f"  Session title: {session['title']}")
                    elif self._pending_title:
                        _cprint(f"  Session title (pending): {self._pending_title}")
                    else:
                        _cprint(f"  No title set. Usage: /title <your session title>")
                else:
                    _cprint("  Session database not available.")
        elif cmd_lower in ("/reset", "/new"):
            self.reset_conversation()
        elif cmd_lower.startswith("/model"):
            # Use original case so model names like "Anthropic/Claude-Opus-4" are preserved
            parts = cmd_original.split(maxsplit=1)
            if len(parts) > 1:
                from kai_cli.auth import resolve_provider
                from kai_cli.models import (
                    parse_model_input,
                    validate_requested_model,
                    _PROVIDER_LABELS,
                )

                raw_input = parts[1].strip()

                # Parse provider:model syntax (e.g. "openrouter:anthropic/claude-sonnet-4.5")
                current_provider = self.provider or self.requested_provider or "openrouter"
                target_provider, new_model = parse_model_input(raw_input, current_provider)
                provider_changed = target_provider != current_provider

                # If provider is changing, re-resolve credentials for the new provider
                api_key_for_probe = self.api_key
                base_url_for_probe = self.base_url
                if provider_changed:
                    try:
                        from kai_cli.runtime_provider import resolve_runtime_provider
                        runtime = resolve_runtime_provider(requested=target_provider)
                        api_key_for_probe = runtime.get("api_key", "")
                        base_url_for_probe = runtime.get("base_url", "")
                    except Exception as e:
                        provider_label = _PROVIDER_LABELS.get(target_provider, target_provider)
                        if target_provider == "custom":
                            print(f"(>_<) Custom endpoint not configured. Set OPENAI_BASE_URL and OPENAI_API_KEY,")
                            print(f"      or run: kai setup → Custom OpenAI-compatible endpoint")
                        else:
                            print(f"(>_<) Could not resolve credentials for provider '{provider_label}': {e}")
                        print(f"(^_^) Current model unchanged: {self.model}")
                        return True

                try:
                    validation = validate_requested_model(
                        new_model,
                        target_provider,
                        api_key=api_key_for_probe,
                        base_url=base_url_for_probe,
                    )
                except Exception:
                    validation = {"accepted": True, "persist": True, "recognized": False, "message": None}

                if not validation.get("accepted"):
                    print(f"(>_<) {validation.get('message')}")
                    print(f"  Model unchanged: {self.model}")
                    if "Did you mean" not in (validation.get("message") or ""):
                        print("  Tip: Use /model to see available models, /provider to see providers")
                else:
                    self.model = new_model
                    self.agent = None  # Force re-init

                    if provider_changed:
                        self.requested_provider = target_provider
                        self.provider = target_provider
                        self.api_key = api_key_for_probe
                        self.base_url = base_url_for_probe

                    provider_label = _PROVIDER_LABELS.get(target_provider, target_provider)
                    provider_note = f" [provider: {provider_label}]" if provider_changed else ""

                    if validation.get("persist"):
                        saved_model = save_config_value("model.default", new_model)
                        if provider_changed:
                            save_config_value("model.provider", target_provider)
                        if saved_model:
                            print(f"(^_^)b Model changed to: {new_model}{provider_note} (saved to config)")
                        else:
                            print(f"(^_^) Model changed to: {new_model}{provider_note} (this session only)")
                    else:
                        message = validation.get("message") or ""
                        print(f"(^_^) Model changed to: {new_model}{provider_note} (this session only)")
                        if message:
                            print(f"  Reason: {message}")
                        print("  Note: Model will revert on restart. Use a verified model to save to config.")
            else:
                self._show_model_picker()
        elif cmd_lower.startswith("/provider"):
            parts = cmd_original.split(maxsplit=1)
            if len(parts) > 1:
                self._switch_provider(parts[1].strip())
            else:
                self._show_provider_picker()
        elif cmd_lower.startswith("/backend") or cmd_lower.startswith("/terminal"):
            parts = cmd_original.split(maxsplit=1)
            if len(parts) > 1:
                self._switch_backend(parts[1].strip())
            else:
                self._show_backend_picker()
        elif cmd_lower.startswith("/prompt"):
            # Use original case so prompt text isn't lowercased
            self._handle_prompt_command(cmd_original)
        elif cmd_lower.startswith("/personality"):
            # Use original case (handler lowercases the personality name itself)
            self._handle_personality_command(cmd_original)
        elif cmd_lower == "/retry":
            retry_msg = self.retry_last()
            if retry_msg and hasattr(self, '_pending_input'):
                # Re-queue the message so process_loop sends it to the agent
                self._pending_input.put(retry_msg)
        elif cmd_lower == "/undo":
            self.undo_last()
        elif cmd_lower == "/save":
            self.save_conversation()
        elif cmd_lower.startswith("/cron"):
            self._handle_cron_command(cmd_original)
        elif cmd_lower.startswith("/jobs"):
            with self._busy_command("Fetching GitHub jobs..."):
                self._handle_jobs_command(cmd_original)
        elif cmd_lower.startswith("/skills"):
            with self._busy_command(self._slow_command_status(cmd_original)):
                self._handle_skills_command(cmd_original)
        elif cmd_lower == "/platforms" or cmd_lower == "/gateway":
            self._show_gateway_status()
        elif cmd_lower == "/verbose":
            self._toggle_verbose()
        elif cmd_lower.startswith("/reasoning"):
            self._handle_reasoning_command(cmd_original)
        elif cmd_lower == "/compress":
            self._manual_compress()
        elif cmd_lower == "/usage":
            self._show_usage()
        elif cmd_lower.startswith("/insights"):
            self._show_insights(cmd_original)
        elif cmd_lower == "/paste":
            self._handle_paste_command()
        elif cmd_lower == "/reload-mcp":
            with self._busy_command(self._slow_command_status(cmd_original)):
                self._reload_mcp()
        elif cmd_lower.startswith("/rollback"):
            self._handle_rollback_command(cmd_original)
        elif cmd_lower.startswith("/background"):
            self._handle_background_command(cmd_original)
        elif cmd_lower.startswith("/handoffs") or cmd_lower.startswith("/hand-offs"):
            parts = cmd_original.split(maxsplit=1)
            self._handle_handoffs_command(parts[1] if len(parts) > 1 else "")
        elif cmd_lower.startswith("/hand-off") or cmd_lower.startswith("/handoff"):
            parts = cmd_original.split(maxsplit=1)
            self._handle_handoff_command(parts[1] if len(parts) > 1 else "")
        elif cmd_lower.startswith("/teleport"):
            self._handle_teleport_command()
        elif cmd_lower.startswith("/skin"):
            self._handle_skin_command(cmd_original)
        else:
            # Check for user-defined quick commands (bypass agent loop, no LLM call)
            base_cmd = cmd_lower.split()[0]
            quick_commands = self.config.get("quick_commands", {})
            if base_cmd.lstrip("/") in quick_commands:
                qcmd = quick_commands[base_cmd.lstrip("/")]
                if qcmd.get("type") == "exec":
                    import shlex
                    import subprocess
                    exec_cmd = qcmd.get("command", "")
                    if exec_cmd:
                        # shell=False + shlex.split so a tampered config can't
                        # inject `;`, `&&`, `|`, `$()` etc. and bypass approval.
                        # If a quick command genuinely needs a shell, the user
                        # must write `bash -c '...'` explicitly in their config.
                        try:
                            argv = shlex.split(exec_cmd)
                        except ValueError as e:
                            self.console.print(f"[bold red]Quick command parse error: {e}[/]")
                            return True
                        if not argv:
                            self.console.print(f"[bold red]Quick command '{base_cmd}' has no command defined[/]")
                            return True
                        try:
                            result = subprocess.run(
                                argv, shell=False, capture_output=True,
                                text=True, timeout=30
                            )
                            output = result.stdout.strip() or result.stderr.strip()
                            self.console.print(output if output else "[dim]Command returned no output[/]")
                        except subprocess.TimeoutExpired:
                            self.console.print("[bold red]Quick command timed out (30s)[/]")
                        except FileNotFoundError:
                            self.console.print(f"[bold red]Quick command not found: {argv[0]}[/]")
                        except Exception as e:
                            self.console.print(f"[bold red]Quick command error: {e}[/]")
                    else:
                        self.console.print(f"[bold red]Quick command '{base_cmd}' has no command defined[/]")
                else:
                    self.console.print(f"[bold red]Quick command '{base_cmd}' has unsupported type (only 'exec' is supported)[/]")
            # Check for skill slash commands (/gif-search, /axolotl, etc.)
            elif base_cmd in _skill_commands:
                user_instruction = cmd_original[len(base_cmd):].strip()
                msg = build_skill_invocation_message(base_cmd, user_instruction)
                if msg:
                    skill_name = _skill_commands[base_cmd]["name"]
                    print(f"\n⚡ Loading skill: {skill_name}")
                    if hasattr(self, '_pending_input'):
                        self._pending_input.put(msg)
                else:
                    self.console.print(f"[bold red]Failed to load skill for {base_cmd}[/]")
            else:
                self.console.print(f"[bold red]Unknown command: {cmd_lower}[/]")
                self.console.print("[dim #5a6b78]Type /help for available commands[/]")
        
        return True
    




    def _on_reasoning(self, reasoning_text: str):
        """Callback for intermediate reasoning display during tool-call loops."""
        lines = reasoning_text.strip().splitlines()
        if len(lines) > 5:
            preview = "\n".join(lines[:5])
            preview += f"\n  ... ({len(lines) - 5} more lines)"
        else:
            preview = reasoning_text.strip()
        _cprint(f"  {_DIM}[thinking] {preview}{_RST}")








    def chat(self, message, images: list = None) -> Optional[str]:
        """
        Send a message to the agent and get a response.
        
        Handles streaming output, interrupt detection (user typing while agent
        is working), and re-queueing of interrupted messages.
        
        Uses a dedicated _interrupt_queue (separate from _pending_input) to avoid
        race conditions between the process_loop and interrupt monitoring. Messages
        typed while the agent is running go to _interrupt_queue; messages typed while
        idle go to _pending_input.
        
        Args:
            message: The user's message (str or multimodal content list)
            images: Optional list of Path objects for attached images
            
        Returns:
            The agent's response, or None on error
        """
        # Refresh provider credentials if needed (handles key rotation transparently)
        if not self._ensure_runtime_credentials():
            return None

        # Initialize agent if needed
        if not self._init_agent():
            return None
        
        # Build native multimodal attachments for vision-capable models.
        # The agent always runs on vision-capable models, so we forward image
        # bytes as content blocks instead of going through a text-description
        # preprocessor.
        text_message = message if isinstance(message, str) else ""
        image_attachments = self._build_image_attachments(images) if images else None

        # Add user message to history — store content blocks when images are
        # attached so replays on subsequent turns include the image data.
        from run_agent import AIAgent as _AIAgent
        history_content = _AIAgent._build_user_content(text_message, image_attachments)
        self.conversation_history.append({"role": "user", "content": history_content})
        
        _cprint(f"{_GOLD}{'─' * 40}{_RST}")
        print(flush=True)
        
        try:
            # Run the conversation with interrupt monitoring
            result = None
            
            def run_agent():
                nonlocal result
                result = self.agent.run_conversation(
                    user_message=text_message,
                    system_message=self._ws_prompt or None,
                    conversation_history=self.conversation_history[:-1],  # Exclude the message we just added
                    task_id=self.session_id,
                    image_attachments=image_attachments,
                )
            
            # Start agent in background thread
            agent_thread = threading.Thread(target=run_agent)
            agent_thread.start()
            
            # Monitor the dedicated interrupt queue while the agent runs.
            # _interrupt_queue is separate from _pending_input, so process_loop
            # and chat() never compete for the same queue.
            # When a clarify question is active, user input is handled entirely
            # by the Enter key binding (routed to the clarify response queue),
            # so we skip interrupt processing to avoid stealing that input.
            interrupt_msg = None
            while agent_thread.is_alive():
                if hasattr(self, '_interrupt_queue'):
                    try:
                        interrupt_msg = self._interrupt_queue.get(timeout=0.1)
                        if interrupt_msg:
                            # If clarify is active, the Enter handler routes
                            # input directly; this queue shouldn't have anything.
                            # But if it does (race condition), don't interrupt.
                            if self._clarify_state or self._clarify_freetext:
                                continue
                            print(f"\n⚡ New message detected, interrupting...")
                            self.agent.interrupt(interrupt_msg)
                            # Debug: log to file (stdout may be devnull from redirect_stdout)
                            try:
                                import pathlib as _pl
                                _dbg = _pl.Path.home() / ".kai-agent" / "interrupt_debug.log"
                                with open(_dbg, "a") as _f:
                                    import time as _t
                                    _f.write(f"{_t.strftime('%H:%M:%S')} interrupt fired: msg={str(interrupt_msg)[:60]!r}, "
                                             f"children={len(self.agent._active_children)}, "
                                             f"parent._interrupt={self.agent._interrupt_requested}\n")
                                    for _ci, _ch in enumerate(self.agent._active_children):
                                        _f.write(f"  child[{_ci}]._interrupt={_ch._interrupt_requested}\n")
                            except Exception:
                                pass
                            break
                    except queue.Empty:
                        pass  # Queue empty or timeout, continue waiting
                else:
                    # Fallback for non-interactive mode (e.g., single-query)
                    agent_thread.join(0.1)
            
            agent_thread.join()  # Ensure agent thread completes

            # Drain any remaining agent output still in the StdoutProxy
            # buffer so tool/status lines render ABOVE our response box.
            # The flush pushes data into the renderer queue; the short
            # sleep lets the renderer actually paint it before we draw.
            import time as _time
            sys.stdout.flush()
            _time.sleep(0.15)


            # Update history with full conversation
            self.conversation_history = result.get("messages", self.conversation_history) if result else self.conversation_history
            
            # Get the final response
            response = result.get("final_response", "") if result else ""
            
            # Handle failed results (e.g., non-retryable errors like invalid model)
            if result and result.get("failed") and not response:
                error_detail = result.get("error", "Unknown error")
                response = f"Error: {error_detail}"
            
            # Handle interrupt - check if we were interrupted
            pending_message = None
            if result and result.get("interrupted"):
                pending_message = result.get("interrupt_message") or interrupt_msg
                # Add indicator that we were interrupted
                if response and pending_message:
                    response = response + "\n\n---\n_[Interrupted - processing new message]_"
            
            # Display reasoning (thinking) box if enabled and available
            if self.show_reasoning and result:
                reasoning = result.get("last_reasoning")
                if reasoning:
                    w = shutil.get_terminal_size().columns
                    r_label = " Reasoning "
                    r_fill = w - 2 - len(r_label)
                    r_top = f"{_DIM}┌─{r_label}{'─' * max(r_fill - 1, 0)}┐{_RST}"
                    r_bot = f"{_DIM}└{'─' * (w - 2)}┘{_RST}"
                    # Collapse long reasoning: show first 10 lines
                    lines = reasoning.strip().splitlines()
                    if len(lines) > 10:
                        display_reasoning = "\n".join(lines[:10])
                        display_reasoning += f"\n{_DIM}  ... ({len(lines) - 10} more lines){_RST}"
                    else:
                        display_reasoning = reasoning.strip()
                    _cprint(f"\n{r_top}\n{_DIM}{display_reasoning}{_RST}\n{r_bot}")

            if response:
                # Use a Rich Panel for the response box — adapts to terminal
                # width at render time instead of hard-coding border length.
                try:
                    from kai_cli.skin_engine import get_active_skin
                    _skin = get_active_skin()
                    label = _skin.get_branding("response_label", "◆ Kai")
                    _resp_color = _skin.get_color("response_border", "#5fb0d4")
                except Exception:
                    label = "◆ Kai"
                    _resp_color = "#5fb0d4"

                _chat_console = ChatConsole()
                _chat_console.print(Panel(
                    response,
                    title=f"[bold]{label}[/bold]",
                    title_align="left",
                    border_style=_resp_color,
                    box=rich_box.HORIZONTALS,
                    padding=(1, 2),
                ))
            
            # Play terminal bell when agent finishes (if enabled).
            # Works over SSH — the bell propagates to the user's terminal.
            if self.bell_on_complete:
                sys.stdout.write("\a")
                sys.stdout.flush()
            
            # Combine all interrupt messages (user may have typed multiple while waiting)
            # and re-queue as one prompt for process_loop
            if pending_message and hasattr(self, '_pending_input'):
                all_parts = [pending_message]
                while not self._interrupt_queue.empty():
                    try:
                        extra = self._interrupt_queue.get_nowait()
                        if extra:
                            all_parts.append(extra)
                    except queue.Empty:
                        break
                combined = "\n".join(all_parts)
                print(f"\n📨 Queued: '{combined[:50]}{'...' if len(combined) > 50 else ''}'")
                self._pending_input.put(combined)
            
            return response
            
        except Exception as e:
            print(f"Error: {e}")
            return None
    


    def run(self):
        """Run the interactive CLI loop with persistent input at bottom."""
        self.show_banner()

        # If resuming a session, load history and display it immediately
        # so the user has context before typing their first message.
        if self._resumed:
            if self._preload_resumed_session():
                self._display_resumed_history()

        try:
            from kai_cli.skin_engine import get_active_skin
            _welcome_skin = get_active_skin()
            _welcome_text = _welcome_skin.get_branding("welcome", "Kai Agent ready. Type your message or /help for commands.")
            _welcome_color = _welcome_skin.get_color("banner_text", "#EAEAEA")
        except Exception:
            _welcome_text = "Kai Agent ready. Type your message or /help for commands."
            _welcome_color = "#EAEAEA"
        self.console.print(f"[{_welcome_color}]{_welcome_text}[/]")
        self.console.print()
        
        # State for async operation
        self._agent_running = False
        self._pending_input = queue.Queue()     # For normal input (commands + new queries)
        self._interrupt_queue = queue.Queue()   # For messages typed while agent is running
        self._should_exit = False
        self._last_ctrl_c_time = 0  # Track double Ctrl+C for force exit

        # Clarify tool state: interactive question/answer with the user.
        # When the agent calls the clarify tool, _clarify_state is set and
        # the prompt_toolkit UI switches to a selection mode.
        self._clarify_state = None      # dict with question, choices, selected, response_queue
        self._clarify_freetext = False  # True when user chose "Other" and is typing
        self._clarify_deadline = 0      # monotonic timestamp when the clarify times out

        # Sudo password prompt state (similar mechanism to clarify)
        self._sudo_state = None         # dict with response_queue when active
        self._sudo_deadline = 0

        # Dangerous command approval state (similar mechanism to clarify)
        self._approval_state = None     # dict with command, description, choices, selected, response_queue
        self._approval_deadline = 0

        # Generic arrow-key picker state (for /model, /provider, /backend) —
        # same selection UX as clarify/approval. dict: title, labels, selected,
        # response_queue. Driven from a command thread (blocks on the queue).
        self._picker_state = None

        # Slash command loading state
        self._command_running = False
        self._command_status = ""

        # Clipboard image attachments (paste images into the CLI)
        self._attached_images: list[Path] = []
        self._image_counter = 0

        # Register callbacks so terminal_tool prompts route through our UI
        set_sudo_password_callback(self._sudo_password_callback)
        set_approval_callback(self._approval_callback)
        
        # Key bindings for the input area
        kb = KeyBindings()
        
        @kb.add('enter')
        def handle_enter(event):
            """Handle Enter key - submit input.
            
            Routes to the correct queue based on active UI state:
            - Sudo password prompt: password goes to sudo response queue
            - Approval selection: selected choice goes to approval response queue
            - Clarify freetext mode: answer goes to the clarify response queue
            - Clarify choice mode: selected choice goes to the clarify response queue
            - Agent running: goes to _interrupt_queue (chat() monitors this)
            - Agent idle: goes to _pending_input (process_loop monitors this)
            Commands (starting with /) always go to _pending_input so they're
            handled as commands, not sent as interrupt text to the agent.
            """
            # --- Sudo password prompt: submit the typed password ---
            if self._sudo_state:
                text = event.app.current_buffer.text
                self._sudo_state["response_queue"].put(text)
                self._sudo_state = None
                event.app.current_buffer.reset()
                event.app.invalidate()
                return

            # --- Interactive picker (/model, /provider, /backend): confirm ---
            if self._picker_state:
                state = self._picker_state
                sel = state["selected"]
                labels = state.get("labels") or []
                state["response_queue"].put(sel if 0 <= sel < len(labels) else None)
                self._picker_state = None
                event.app.invalidate()
                return

            # --- Approval selection: confirm the highlighted choice ---
            if self._approval_state:
                state = self._approval_state
                selected = state["selected"]
                choices = state["choices"]
                if 0 <= selected < len(choices):
                    chosen = choices[selected]
                    if chosen == "view":
                        # Toggle full command display without closing the prompt
                        state["show_full"] = True
                        # Remove the "view" option since it's been used
                        state["choices"] = [c for c in choices if c != "view"]
                        if state["selected"] >= len(state["choices"]):
                            state["selected"] = len(state["choices"]) - 1
                        event.app.invalidate()
                        return
                    state["response_queue"].put(chosen)
                self._approval_state = None
                event.app.invalidate()
                return

            # --- Clarify freetext mode: user typed their own answer ---
            if self._clarify_freetext and self._clarify_state:
                text = event.app.current_buffer.text.strip()
                if text:
                    self._clarify_state["response_queue"].put(text)
                    self._clarify_state = None
                    self._clarify_freetext = False
                    event.app.current_buffer.reset()
                    event.app.invalidate()
                return

            # --- Clarify choice mode: confirm the highlighted selection ---
            if self._clarify_state and not self._clarify_freetext:
                state = self._clarify_state
                selected = state["selected"]
                choices = state.get("choices") or []
                if selected < len(choices):
                    state["response_queue"].put(choices[selected])
                    self._clarify_state = None
                    event.app.invalidate()
                else:
                    # "Other" selected → switch to freetext
                    self._clarify_freetext = True
                    event.app.invalidate()
                return

            # --- Normal input routing ---
            text = event.app.current_buffer.text.strip()
            has_images = bool(self._attached_images)
            if text or has_images:
                # Snapshot and clear attached images
                images = list(self._attached_images)
                self._attached_images.clear()
                event.app.invalidate()
                # Bundle text + images as a tuple when images are present
                payload = (text, images) if images else text
                if self._agent_running and not (text and text.startswith("/")):
                    self._interrupt_queue.put(payload)
                    # Debug: log to file when message enters interrupt queue
                    try:
                        import pathlib as _pl
                        _dbg = _pl.Path.home() / ".kai-agent" / "interrupt_debug.log"
                        with open(_dbg, "a") as _f:
                            import time as _t
                            _f.write(f"{_t.strftime('%H:%M:%S')} ENTER: queued interrupt msg={str(payload)[:60]!r}, "
                                     f"agent_running={self._agent_running}\n")
                    except Exception:
                        pass
                else:
                    self._pending_input.put(payload)
                event.app.current_buffer.reset(append_to_history=True)
        
        @kb.add('escape', 'enter')
        def handle_alt_enter(event):
            """Alt+Enter inserts a newline for multi-line input."""
            event.current_buffer.insert_text('\n')

        @kb.add('c-j')
        def handle_ctrl_enter(event):
            """Ctrl+Enter (c-j) inserts a newline. Most terminals send c-j for Ctrl+Enter."""
            event.current_buffer.insert_text('\n')

        # --- Clarify tool: arrow-key navigation for multiple-choice questions ---

        @kb.add('up', filter=Condition(lambda: bool(self._clarify_state) and not self._clarify_freetext))
        def clarify_up(event):
            """Move selection up in clarify choices."""
            if self._clarify_state:
                self._clarify_state["selected"] = max(0, self._clarify_state["selected"] - 1)
                event.app.invalidate()

        @kb.add('down', filter=Condition(lambda: bool(self._clarify_state) and not self._clarify_freetext))
        def clarify_down(event):
            """Move selection down in clarify choices."""
            if self._clarify_state:
                choices = self._clarify_state.get("choices") or []
                max_idx = len(choices)  # last index is the "Other" option
                self._clarify_state["selected"] = min(max_idx, self._clarify_state["selected"] + 1)
                event.app.invalidate()

        # --- Dangerous command approval: arrow-key navigation ---

        @kb.add('up', filter=Condition(lambda: bool(self._picker_state)))
        def picker_up(event):
            if self._picker_state:
                self._picker_state["selected"] = max(0, self._picker_state["selected"] - 1)
                event.app.invalidate()

        @kb.add('down', filter=Condition(lambda: bool(self._picker_state)))
        def picker_down(event):
            if self._picker_state:
                max_idx = len(self._picker_state.get("labels") or []) - 1
                self._picker_state["selected"] = min(max_idx, self._picker_state["selected"] + 1)
                event.app.invalidate()

        @kb.add('up', filter=Condition(lambda: bool(self._approval_state)))
        def approval_up(event):
            if self._approval_state:
                self._approval_state["selected"] = max(0, self._approval_state["selected"] - 1)
                event.app.invalidate()

        @kb.add('down', filter=Condition(lambda: bool(self._approval_state)))
        def approval_down(event):
            if self._approval_state:
                max_idx = len(self._approval_state["choices"]) - 1
                self._approval_state["selected"] = min(max_idx, self._approval_state["selected"] + 1)
                event.app.invalidate()

        # --- History navigation: up/down browse history in normal input mode ---
        # The TextArea is multiline, so by default up/down only move the cursor.
        # Buffer.auto_up/auto_down handle both: cursor movement when multi-line,
        # history browsing when on the first/last line (or single-line input).
        _normal_input = Condition(
            lambda: not self._clarify_state and not self._approval_state and not self._sudo_state and not self._picker_state
        )

        @kb.add('up', filter=_normal_input)
        def history_up(event):
            """Up arrow: browse history when on first line, else move cursor up."""
            event.app.current_buffer.auto_up(count=event.arg)

        @kb.add('down', filter=_normal_input)
        def history_down(event):
            """Down arrow: browse history when on last line, else move cursor down."""
            event.app.current_buffer.auto_down(count=event.arg)

        @kb.add('c-c')
        def handle_ctrl_c(event):
            """Handle Ctrl+C - cancel interactive prompts, interrupt agent, or exit.
            
            Priority:
            1. Cancel active sudo/approval/clarify prompt
            2. Interrupt the running agent (first press)
            3. Force exit (second press within 2s, or when idle)
            """
            import time as _time
            now = _time.time()

            # Cancel sudo prompt
            if self._sudo_state:
                self._sudo_state["response_queue"].put("")
                self._sudo_state = None
                event.app.current_buffer.reset()
                event.app.invalidate()
                return

            # Cancel interactive picker (no change)
            if self._picker_state:
                self._picker_state["response_queue"].put(None)
                self._picker_state = None
                event.app.invalidate()
                return

            # Cancel approval prompt (deny)
            if self._approval_state:
                self._approval_state["response_queue"].put("deny")
                self._approval_state = None
                event.app.invalidate()
                return

            # Cancel clarify prompt
            if self._clarify_state:
                self._clarify_state["response_queue"].put(
                    "The user cancelled. Use your best judgement to proceed."
                )
                self._clarify_state = None
                self._clarify_freetext = False
                event.app.current_buffer.reset()
                event.app.invalidate()
                return

            if self._agent_running and self.agent:
                if now - self._last_ctrl_c_time < 2.0:
                    print("\n⚡ Force exiting...")
                    self._should_exit = True
                    event.app.exit()
                    return
                
                self._last_ctrl_c_time = now
                print("\n⚡ Interrupting agent... (press Ctrl+C again to force exit)")
                self.agent.interrupt()
            else:
                # If there's text or images, clear them (like bash).
                # If everything is already empty, exit.
                if event.app.current_buffer.text or self._attached_images:
                    event.app.current_buffer.reset()
                    self._attached_images.clear()
                    event.app.invalidate()
                else:
                    self._should_exit = True
                    event.app.exit()
        
        @kb.add('c-d')
        def handle_ctrl_d(event):
            """Handle Ctrl+D - exit."""
            self._should_exit = True
            event.app.exit()

        from prompt_toolkit.keys import Keys

        @kb.add(Keys.BracketedPaste, eager=True)
        def handle_paste(event):
            """Handle terminal paste — detect clipboard images.

            When the terminal supports bracketed paste, Ctrl+V / Cmd+V
            triggers this with the pasted text.  We also check the
            clipboard for an image on every paste event.
            """
            pasted_text = event.data or ""
            if self._try_attach_clipboard_image():
                event.app.invalidate()
            if pasted_text:
                event.current_buffer.insert_text(pasted_text)

        @kb.add('c-v')
        def handle_ctrl_v(event):
            """Fallback image paste for terminals without bracketed paste.

            On Linux terminals (GNOME Terminal, Konsole, etc.), Ctrl+V
            sends raw byte 0x16 instead of triggering a paste.  This
            binding catches that and checks the clipboard for images.
            On terminals that DO intercept Ctrl+V for paste (macOS
            Terminal, iTerm2, VSCode, Windows Terminal), the bracketed
            paste handler fires instead and this binding never triggers.
            """
            if self._try_attach_clipboard_image():
                event.app.invalidate()

        @kb.add('escape', 'v')
        def handle_alt_v(event):
            """Alt+V — paste image from clipboard.

            Alt key combos pass through all terminal emulators (sent as
            ESC + key), unlike Ctrl+V which terminals intercept for text
            paste.  This is the reliable way to attach clipboard images
            on WSL2, VSCode, and any terminal over SSH where Ctrl+V
            can't reach the application for image-only clipboard.
            """
            if self._try_attach_clipboard_image():
                event.app.invalidate()
            else:
                # No image found — show a hint
                pass  # silent when no image (avoid noise on accidental press)

        # Dynamic prompt: shows Kai symbol when agent is working,
        # or answer prompt when clarify freetext mode is active.
        cli_ref = self

        def get_prompt():
            if cli_ref._sudo_state:
                return [('class:sudo-prompt', '🔐 ❯ ')]
            if cli_ref._approval_state:
                return [('class:prompt-working', '⚠ ❯ ')]
            if cli_ref._picker_state:
                return [('class:prompt-working', '⊕ ❯ ')]
            if cli_ref._clarify_freetext:
                return [('class:clarify-selected', '✎ ❯ ')]
            if cli_ref._clarify_state:
                return [('class:prompt-working', '? ❯ ')]
            if cli_ref._command_running:
                return [('class:prompt-working', f"{cli_ref._command_spinner_frame()} ❯ ")]
            if cli_ref._agent_running:
                return [('class:prompt-working', '◆ ❯ ')]
            return [('class:prompt', '❯ ')]

        # Create the input area with multiline (shift+enter), autocomplete, and paste handling
        input_area = TextArea(
            height=Dimension(min=1, max=8, preferred=1),
            prompt=get_prompt,
            style='class:input-area',
            multiline=True,
            wrap_lines=True,
            read_only=Condition(lambda: bool(cli_ref._command_running)),
            history=FileHistory(str(self._history_file)),
            completer=SlashCommandCompleter(skill_commands_provider=lambda: _skill_commands),
            complete_while_typing=True,
        )

        # Dynamic height: accounts for both explicit newlines AND visual
        # wrapping of long lines so the input area always fits its content.
        # The prompt characters ("❯ " etc.) consume ~4 columns.
        def _input_height():
            try:
                doc = input_area.buffer.document
                available_width = shutil.get_terminal_size().columns - 4  # subtract prompt width
                if available_width < 10:
                    available_width = 40
                visual_lines = 0
                for line in doc.lines:
                    # Each logical line takes at least 1 visual row; long lines wrap
                    if len(line) == 0:
                        visual_lines += 1
                    else:
                        visual_lines += max(1, -(-len(line) // available_width))  # ceil division
                return min(max(visual_lines, 1), 8)
            except Exception:
                return 1

        input_area.window.height = _input_height

        # Paste collapsing: detect large pastes and save to temp file
        _paste_counter = [0]
        _prev_text_len = [0]

        def _on_text_changed(buf):
            """Detect large pastes and collapse them to a file reference."""
            text = buf.text
            line_count = text.count('\n')
            chars_added = len(text) - _prev_text_len[0]
            _prev_text_len[0] = len(text)
            # Heuristic: a real paste adds many characters at once (not just a
            # single newline from Alt+Enter) AND the result has 5+ lines.
            if line_count >= 5 and chars_added > 1 and not text.startswith('/'):
                _paste_counter[0] += 1
                # Save to temp file
                paste_dir = Path(os.path.expanduser("~/.kai-agent/pastes"))
                paste_dir.mkdir(parents=True, exist_ok=True)
                paste_file = paste_dir / f"paste_{_paste_counter[0]}_{datetime.now().strftime('%H%M%S')}.txt"
                paste_file.write_text(text, encoding="utf-8")
                # Replace buffer with compact reference
                buf.text = f"[Pasted text #{_paste_counter[0]}: {line_count + 1} lines → {paste_file}]"
                buf.cursor_position = len(buf.text)

        input_area.buffer.on_text_changed += _on_text_changed

        # --- Input processors for password masking and inline placeholder ---

        # Mask input with '*' when the sudo password prompt is active
        input_area.control.input_processors.append(
            ConditionalProcessor(
                PasswordProcessor(),
                filter=Condition(lambda: bool(cli_ref._sudo_state)),
            )
        )

        class _PlaceholderProcessor(Processor):
            """Render grayed-out placeholder text inside the input when empty."""
            def __init__(self, get_text):
                self._get_text = get_text

            def apply_transformation(self, ti):
                if not ti.document.text and ti.lineno == 0:
                    text = self._get_text()
                    if text:
                        # Append after existing fragments (preserves the ❯ prompt)
                        return Transformation(fragments=ti.fragments + [('class:placeholder', text)])
                return Transformation(fragments=ti.fragments)

        def _get_placeholder():
            if cli_ref._sudo_state:
                return "type password (hidden), Enter to skip"
            if cli_ref._approval_state:
                return ""
            if cli_ref._picker_state:
                return ""
            if cli_ref._clarify_freetext:
                return "type your answer here and press Enter"
            if cli_ref._clarify_state:
                return ""
            if cli_ref._command_running:
                frame = cli_ref._command_spinner_frame()
                status = cli_ref._command_status or "Processing command..."
                return f"{frame} {status}"
            if cli_ref._agent_running:
                return "type a message + Enter to interrupt, Ctrl+C to cancel"
            return ""

        input_area.control.input_processors.append(_PlaceholderProcessor(_get_placeholder))

        # Hint line above input: shown only for interactive prompts that need
        # extra instructions (sudo countdown, approval navigation, clarify).
        # The agent-running interrupt hint is now an inline placeholder above.
        def get_hint_text():
            import time as _time

            if cli_ref._sudo_state:
                remaining = max(0, int(cli_ref._sudo_deadline - _time.monotonic()))
                return [
                    ('class:hint', '  password hidden · Enter to skip'),
                    ('class:clarify-countdown', f'  ({remaining}s)'),
                ]

            if cli_ref._approval_state:
                remaining = max(0, int(cli_ref._approval_deadline - _time.monotonic()))
                return [
                    ('class:hint', '  ↑/↓ to select, Enter to confirm'),
                    ('class:clarify-countdown', f'  ({remaining}s)'),
                ]

            if cli_ref._picker_state:
                return [
                    ('class:hint', '  ↑/↓ to select, Enter to confirm, Ctrl+C to cancel'),
                ]

            if cli_ref._clarify_state:
                remaining = max(0, int(cli_ref._clarify_deadline - _time.monotonic()))
                countdown = f'  ({remaining}s)' if cli_ref._clarify_deadline else ''
                if cli_ref._clarify_freetext:
                    return [
                        ('class:hint', '  type your answer and press Enter'),
                        ('class:clarify-countdown', countdown),
                    ]
                return [
                    ('class:hint', '  ↑/↓ to select, Enter to confirm'),
                    ('class:clarify-countdown', countdown),
                ]

            if cli_ref._command_running:
                frame = cli_ref._command_spinner_frame()
                return [
                    ('class:hint', f'  {frame} command in progress · input temporarily disabled'),
                ]

            return []

        def get_hint_height():
            if cli_ref._sudo_state or cli_ref._approval_state or cli_ref._clarify_state or cli_ref._command_running or cli_ref._picker_state:
                return 1
            # Keep a 1-line spacer while agent runs so output doesn't push
            # right up against the top rule of the input area
            return 1 if cli_ref._agent_running else 0

        def get_spinner_text():
            txt = cli_ref._spinner_text
            if not txt:
                return []
            return [('class:hint', f'  {txt}')]

        def get_spinner_height():
            return 1 if cli_ref._spinner_text else 0

        spinner_widget = Window(
            content=FormattedTextControl(get_spinner_text),
            height=get_spinner_height,
        )

        spacer = Window(
            content=FormattedTextControl(get_hint_text),
            height=get_hint_height,
        )

        # --- Clarify tool: dynamic display widget for questions + choices ---

        def _panel_box_width(title: str, content_lines: list[str], min_width: int = 46, max_width: int = 76) -> int:
            """Choose a stable panel width wide enough for the title and content."""
            term_cols = shutil.get_terminal_size((100, 20)).columns
            longest = max([len(title)] + [len(line) for line in content_lines] + [min_width - 4])
            inner = min(max(longest + 4, min_width - 2), max_width - 2, max(24, term_cols - 6))
            return inner + 2  # account for the single leading/trailing spaces inside borders

        def _wrap_panel_text(text: str, width: int, subsequent_indent: str = "") -> list[str]:
            wrapped = textwrap.wrap(
                text,
                width=max(8, width),
                break_long_words=False,
                break_on_hyphens=False,
                subsequent_indent=subsequent_indent,
            )
            return wrapped or [""]

        def _append_panel_line(lines, border_style: str, content_style: str, text: str, box_width: int) -> None:
            inner_width = max(0, box_width - 2)
            lines.append((border_style, "│ "))
            lines.append((content_style, text.ljust(inner_width)))
            lines.append((border_style, " │\n"))

        def _append_blank_panel_line(lines, border_style: str, box_width: int) -> None:
            lines.append((border_style, "│" + (" " * box_width) + "│\n"))

        def _get_clarify_display():
            """Build styled text for the clarify question/choices panel."""
            state = cli_ref._clarify_state
            if not state:
                return []

            question = state["question"]
            choices = state.get("choices") or []
            selected = state.get("selected", 0)
            preview_lines = _wrap_panel_text(question, 60)
            for i, choice in enumerate(choices):
                prefix = "❯ " if i == selected and not cli_ref._clarify_freetext else "  "
                preview_lines.extend(_wrap_panel_text(f"{prefix}{choice}", 60, subsequent_indent="  "))
            other_label = (
                "❯ Other (type below)" if cli_ref._clarify_freetext
                else "❯ Other (type your answer)" if selected == len(choices)
                else "  Other (type your answer)"
            )
            preview_lines.extend(_wrap_panel_text(other_label, 60, subsequent_indent="  "))
            box_width = _panel_box_width("Kai needs your input", preview_lines)
            inner_text_width = max(8, box_width - 2)

            lines = []
            # Box top border
            lines.append(('class:clarify-border', '╭─ '))
            lines.append(('class:clarify-title', 'Kai needs your input'))
            lines.append(('class:clarify-border', ' ' + ('─' * max(0, box_width - len("Kai needs your input") - 3)) + '╮\n'))
            _append_blank_panel_line(lines, 'class:clarify-border', box_width)

            # Question text
            for wrapped in _wrap_panel_text(question, inner_text_width):
                _append_panel_line(lines, 'class:clarify-border', 'class:clarify-question', wrapped, box_width)
            _append_blank_panel_line(lines, 'class:clarify-border', box_width)

            if cli_ref._clarify_freetext and not choices:
                guidance = "Type your answer in the prompt below, then press Enter."
                for wrapped in _wrap_panel_text(guidance, inner_text_width):
                    _append_panel_line(lines, 'class:clarify-border', 'class:clarify-choice', wrapped, box_width)
                _append_blank_panel_line(lines, 'class:clarify-border', box_width)

            if choices:
                # Multiple-choice mode: show selectable options
                for i, choice in enumerate(choices):
                    style = 'class:clarify-selected' if i == selected and not cli_ref._clarify_freetext else 'class:clarify-choice'
                    prefix = '❯ ' if i == selected and not cli_ref._clarify_freetext else '  '
                    wrapped_lines = _wrap_panel_text(f"{prefix}{choice}", inner_text_width, subsequent_indent="  ")
                    for wrapped in wrapped_lines:
                        _append_panel_line(lines, 'class:clarify-border', style, wrapped, box_width)

                # "Other" option (5th line, only shown when choices exist)
                other_idx = len(choices)
                if selected == other_idx and not cli_ref._clarify_freetext:
                    other_style = 'class:clarify-selected'
                    other_label = '❯ Other (type your answer)'
                elif cli_ref._clarify_freetext:
                    other_style = 'class:clarify-active-other'
                    other_label = '❯ Other (type below)'
                else:
                    other_style = 'class:clarify-choice'
                    other_label = '  Other (type your answer)'
                for wrapped in _wrap_panel_text(other_label, inner_text_width, subsequent_indent="  "):
                    _append_panel_line(lines, 'class:clarify-border', other_style, wrapped, box_width)

            _append_blank_panel_line(lines, 'class:clarify-border', box_width)
            lines.append(('class:clarify-border', '╰' + ('─' * box_width) + '╯\n'))
            return lines

        clarify_widget = ConditionalContainer(
            Window(
                FormattedTextControl(_get_clarify_display),
                wrap_lines=True,
            ),
            filter=Condition(lambda: cli_ref._clarify_state is not None),
        )

        # --- Sudo password: display widget ---

        def _get_sudo_display():
            state = cli_ref._sudo_state
            if not state:
                return []
            title = '🔐 Sudo Password Required'
            body = 'Enter password below (hidden), or press Enter to skip'
            box_width = _panel_box_width(title, [body])
            inner = max(0, box_width - 2)
            lines = []
            lines.append(('class:sudo-border', '╭─ '))
            lines.append(('class:sudo-title', title))
            lines.append(('class:sudo-border', ' ' + ('─' * max(0, box_width - len(title) - 3)) + '╮\n'))
            _append_blank_panel_line(lines, 'class:sudo-border', box_width)
            _append_panel_line(lines, 'class:sudo-border', 'class:sudo-text', body, box_width)
            _append_blank_panel_line(lines, 'class:sudo-border', box_width)
            lines.append(('class:sudo-border', '╰' + ('─' * box_width) + '╯\n'))
            return lines

        sudo_widget = ConditionalContainer(
            Window(
                FormattedTextControl(_get_sudo_display),
                wrap_lines=True,
            ),
            filter=Condition(lambda: cli_ref._sudo_state is not None),
        )

        # --- Dangerous command approval: display widget ---

        def _get_approval_display():
            state = cli_ref._approval_state
            if not state:
                return []
            command = state["command"]
            description = state["description"]
            choices = state["choices"]
            selected = state.get("selected", 0)
            show_full = state.get("show_full", False)

            if show_full or len(command) <= 70:
                cmd_display = command
            else:
                cmd_display = command[:70] + '...'
            choice_labels = {
                "once": "Allow once",
                "session": "Allow for this session",
                "always": "Add to permanent allowlist",
                "deny": "Deny",
                "view": "Show full command",
            }
            preview_lines = _wrap_panel_text(description, 60)
            preview_lines.extend(_wrap_panel_text(cmd_display, 60))
            for i, choice in enumerate(choices):
                prefix = '❯ ' if i == selected else '  '
                preview_lines.extend(_wrap_panel_text(f"{prefix}{choice_labels.get(choice, choice)}", 60, subsequent_indent="  "))
            box_width = _panel_box_width("⚠️  Dangerous Command", preview_lines)
            inner_text_width = max(8, box_width - 2)

            lines = []
            lines.append(('class:approval-border', '╭─ '))
            lines.append(('class:approval-title', '⚠️  Dangerous Command'))
            lines.append(('class:approval-border', ' ' + ('─' * max(0, box_width - len("⚠️  Dangerous Command") - 3)) + '╮\n'))
            _append_blank_panel_line(lines, 'class:approval-border', box_width)
            for wrapped in _wrap_panel_text(description, inner_text_width):
                _append_panel_line(lines, 'class:approval-border', 'class:approval-desc', wrapped, box_width)
            for wrapped in _wrap_panel_text(cmd_display, inner_text_width):
                _append_panel_line(lines, 'class:approval-border', 'class:approval-cmd', wrapped, box_width)
            _append_blank_panel_line(lines, 'class:approval-border', box_width)
            for i, choice in enumerate(choices):
                label = choice_labels.get(choice, choice)
                style = 'class:approval-selected' if i == selected else 'class:approval-choice'
                prefix = '❯ ' if i == selected else '  '
                for wrapped in _wrap_panel_text(f"{prefix}{label}", inner_text_width, subsequent_indent="  "):
                    _append_panel_line(lines, 'class:approval-border', style, wrapped, box_width)
            _append_blank_panel_line(lines, 'class:approval-border', box_width)
            lines.append(('class:approval-border', '╰' + ('─' * box_width) + '╯\n'))
            return lines

        approval_widget = ConditionalContainer(
            Window(
                FormattedTextControl(_get_approval_display),
                wrap_lines=True,
            ),
            filter=Condition(lambda: cli_ref._approval_state is not None),
        )

        def _get_picker_display():
            state = cli_ref._picker_state
            if not state:
                return []
            title = state.get("title", "Select")
            labels = state.get("labels") or []
            selected = state.get("selected", 0)

            preview_lines = []
            for i, label in enumerate(labels):
                prefix = '❯ ' if i == selected else '  '
                preview_lines.extend(_wrap_panel_text(f"{prefix}{label}", 60, subsequent_indent="  "))
            box_width = _panel_box_width(title, preview_lines)
            inner_text_width = max(8, box_width - 2)

            lines = []
            lines.append(('class:picker-border', '╭─ '))
            lines.append(('class:picker-title', title))
            lines.append(('class:picker-border', ' ' + ('─' * max(0, box_width - len(title) - 3)) + '╮\n'))
            _append_blank_panel_line(lines, 'class:picker-border', box_width)
            for i, label in enumerate(labels):
                style = 'class:picker-selected' if i == selected else 'class:picker-choice'
                prefix = '❯ ' if i == selected else '  '
                for wrapped in _wrap_panel_text(f"{prefix}{label}", inner_text_width, subsequent_indent="  "):
                    _append_panel_line(lines, 'class:picker-border', style, wrapped, box_width)
            _append_blank_panel_line(lines, 'class:picker-border', box_width)
            lines.append(('class:picker-border', '╰' + ('─' * box_width) + '╯\n'))
            return lines

        picker_widget = ConditionalContainer(
            Window(
                FormattedTextControl(_get_picker_display),
                wrap_lines=True,
            ),
            filter=Condition(lambda: cli_ref._picker_state is not None),
        )

        # Horizontal rules above and below the input (bronze, 1 line each).
        # The bottom rule moves down as the TextArea grows with newlines.
        # Using char='─' instead of hardcoded repetition so the rule
        # always spans the full terminal width on any screen size.
        input_rule_top = Window(
            char='─',
            height=1,
            style='class:input-rule',
        )
        input_rule_bot = Window(
            char='─',
            height=1,
            style='class:input-rule',
        )

        # Image attachment indicator — shows badges like [📎 Image #1] above input
        cli_ref = self

        def _get_image_bar():
            if not cli_ref._attached_images:
                return []
            base = cli_ref._image_counter - len(cli_ref._attached_images) + 1
            badges = " ".join(
                f"[📎 Image #{base + i}]"
                for i in range(len(cli_ref._attached_images))
            )
            return [("class:image-badge", f" {badges} ")]

        image_bar = Window(
            content=FormattedTextControl(_get_image_bar),
            height=Condition(lambda: bool(cli_ref._attached_images)),
        )

        # Layout: interactive prompt widgets + ruled input at bottom.
        # The sudo, approval, and clarify widgets appear above the input when
        # the corresponding interactive prompt is active.
        layout = Layout(
            HSplit([
                Window(height=0),
                sudo_widget,
                approval_widget,
                picker_widget,
                clarify_widget,
                spinner_widget,
                spacer,
                input_rule_top,
                image_bar,
                input_area,
                input_rule_bot,
                CompletionsMenu(max_height=12, scroll_offset=1),
            ])
        )
        
        # Style for the application
        # Kai cloud palette: borders/rules = brand teal #2a7ba5, selections/
        # titles/badges = light teal #5fb0d4, text = neutral #EAEAEA. Danger
        # affordances (sudo / approval warning reds & oranges) are kept as-is.
        style = PTStyle.from_dict({
            'input-area': '#EAEAEA',
            'placeholder': '#555555 italic',
            'prompt': '#EAEAEA',
            'prompt-working': '#888888 italic',
            'hint': '#555555 italic',
            # Brand horizontal rules around the input area
            'input-rule': '#2a7ba5',
            # Clipboard image attachment badges
            'image-badge': '#5fb0d4 bold',
            'completion-menu': 'bg:#1a1a2e #EAEAEA',
            'completion-menu.completion': 'bg:#1a1a2e #EAEAEA',
            'completion-menu.completion.current': 'bg:#333355 #5fb0d4',
            'completion-menu.meta.completion': 'bg:#1a1a2e #888888',
            'completion-menu.meta.completion.current': 'bg:#333355 #5fb0d4',
            # Clarify question panel
            'clarify-border': '#2a7ba5',
            'clarify-title': '#5fb0d4 bold',
            'clarify-question': '#EAEAEA bold',
            'clarify-choice': '#AAAAAA',
            'clarify-selected': '#5fb0d4 bold',
            'clarify-active-other': '#5fb0d4 italic',
            'clarify-countdown': '#2a7ba5',
            # Sudo password panel (danger colors kept intentionally)
            'sudo-prompt': '#FF6B6B bold',
            'sudo-border': '#2a7ba5',
            'sudo-title': '#FF6B6B bold',
            'sudo-text': '#EAEAEA',
            # Dangerous command approval panel (warning colors kept)
            'approval-border': '#2a7ba5',
            'approval-title': '#FF8C00 bold',
            'approval-desc': '#EAEAEA bold',
            'approval-cmd': '#AAAAAA italic',
            'approval-choice': '#AAAAAA',
            'approval-selected': '#5fb0d4 bold',
            # Generic arrow-key picker panel (/model, /provider, /backend)
            'picker-border': '#2a7ba5',
            'picker-title': '#5fb0d4 bold',
            'picker-choice': '#AAAAAA',
            'picker-selected': '#5fb0d4 bold',
        })
        
        # Create the application
        app = Application(
            layout=layout,
            key_bindings=kb,
            style=style,
            full_screen=False,
            mouse_support=False,
            **({'cursor': _STEADY_CURSOR} if _STEADY_CURSOR is not None else {}),
        )
        self._app = app  # Store reference for clarify_callback

        def spinner_loop():
            import time as _time

            while not self._should_exit:
                if self._command_running and self._app:
                    self._invalidate(min_interval=0.1)
                    _time.sleep(0.1)
                else:
                    _time.sleep(0.05)

        spinner_thread = threading.Thread(target=spinner_loop, daemon=True)
        spinner_thread.start()
        
        # Background thread to process inputs and run agent
        def process_loop():
            while not self._should_exit:
                try:
                    # Drain async hand-off progress/result messages and print them
                    # above the prompt (single-threaded: only this loop writes).
                    try:
                        while True:
                            _cprint(self._handoff_notifications.get_nowait())
                    except queue.Empty:
                        pass
                    # Check for pending input with timeout
                    try:
                        user_input = self._pending_input.get(timeout=0.1)
                    except queue.Empty:
                        continue
                    
                    if not user_input:
                        continue

                    # Unpack image payload: (text, [Path, ...]) or plain str
                    submit_images = []
                    if isinstance(user_input, tuple):
                        user_input, submit_images = user_input
                    
                    # Check for commands
                    if isinstance(user_input, str) and user_input.startswith("/"):
                        _cprint(f"\n⚙️  {user_input}")
                        if not self.process_command(user_input):
                            self._should_exit = True
                            # Schedule app exit
                            if app.is_running:
                                app.exit()
                        continue
                    
                    # Expand paste references back to full content
                    import re as _re
                    paste_match = _re.match(r'\[Pasted text #\d+: \d+ lines → (.+)\]', user_input) if isinstance(user_input, str) else None
                    if paste_match:
                        paste_path = Path(paste_match.group(1))
                        if paste_path.exists():
                            full_text = paste_path.read_text(encoding="utf-8")
                            line_count = full_text.count('\n') + 1
                            print()
                            _cprint(f"{_GOLD}●{_RST} {_BOLD}[Pasted text: {line_count} lines]{_RST}")
                            user_input = full_text
                        else:
                            print()
                            _cprint(f"{_GOLD}●{_RST} {_BOLD}{user_input}{_RST}")
                    else:
                        if '\n' in user_input:
                            first_line = user_input.split('\n')[0]
                            line_count = user_input.count('\n') + 1
                            print()
                            _cprint(f"{_GOLD}●{_RST} {_BOLD}{first_line}{_RST} {_DIM}(+{line_count - 1} lines){_RST}")
                        else:
                            print()
                            _cprint(f"{_GOLD}●{_RST} {_BOLD}{user_input}{_RST}")
                    
                    # Show image attachment count
                    if submit_images:
                        n = len(submit_images)
                        _cprint(f"  {_DIM}📎 {n} image{'s' if n > 1 else ''} attached{_RST}")

                    # Regular chat - run agent
                    self._agent_running = True
                    app.invalidate()  # Refresh status line
                    
                    try:
                        self.chat(user_input, images=submit_images or None)
                    finally:
                        self._agent_running = False
                        self._spinner_text = ""
                        app.invalidate()  # Refresh status line
                    
                except Exception as e:
                    print(f"Error: {e}")
        
        # Start processing thread
        process_thread = threading.Thread(target=process_loop, daemon=True)
        process_thread.start()
        
        # Register atexit cleanup so resources are freed even on unexpected exit
        atexit.register(_run_cleanup)
        
        # Run the application with patch_stdout for proper output handling
        try:
            with patch_stdout():
                app.run()
        except (EOFError, KeyboardInterrupt):
            pass
        finally:
            self._should_exit = True
            # Flush memories before exit (only for substantial conversations)
            if self.agent and self.conversation_history:
                try:
                    self.agent.flush_memories(self.conversation_history)
                except Exception:
                    pass
            # Unregister terminal_tool callbacks to avoid dangling references
            set_sudo_password_callback(None)
            set_approval_callback(None)
            # Close session in SQLite
            if hasattr(self, '_session_db') and self._session_db and self.agent:
                try:
                    self._session_db.end_session(self.agent.session_id, "cli_close")
                except Exception as e:
                    logger.debug("Could not close session in DB: %s", e)
            _run_cleanup()
            self._print_exit_summary()


# ============================================================================
# Main Entry Point
# ============================================================================

def main(
    query: str = None,
    q: str = None,
    toolsets: str = None,
    model: str = None,
    provider: str = None,
    api_key: str = None,
    base_url: str = None,
    max_turns: int = None,
    verbose: bool = False,
    quiet: bool = False,
    compact: bool = False,
    list_tools: bool = False,
    list_toolsets: bool = False,
    gateway: bool = False,
    resume: str = None,
    worktree: bool = False,
    w: bool = False,
    checkpoints: bool = False,
    pass_session_id: bool = False,
):
    """
    Kai Agent CLI - Interactive AI Assistant
    
    Args:
        query: Single query to execute (then exit). Alias: -q
        q: Shorthand for --query
        toolsets: Comma-separated list of toolsets to enable (e.g., "web,terminal")
        model: Model to use (default: anthropic/claude-opus-4-20250514)
        provider: Inference provider ("auto", "openrouter", "nous", "openai-codex", "zai", "kimi-coding", "minimax", "minimax-cn")
        api_key: API key for authentication
        base_url: Base URL for the API
        max_turns: Maximum tool-calling iterations (default: 60)
        verbose: Enable verbose logging
        compact: Use compact display mode
        list_tools: List available tools and exit
        list_toolsets: List available toolsets and exit
        resume: Resume a previous session by its ID (e.g., 20260225_143052_a1b2c3)
        worktree: Run in an isolated git worktree (for parallel agents). Alias: -w
        w: Shorthand for --worktree
    
    Examples:
        python cli.py                            # Start interactive mode
        python cli.py --toolsets web,terminal    # Use specific toolsets
        python cli.py -q "What is Python?"       # Single query mode
        python cli.py --list-tools               # List tools and exit
        python cli.py --resume 20260225_143052_a1b2c3  # Resume session
        python cli.py -w                         # Start in isolated git worktree
        python cli.py -w -q "Fix issue #123"     # Single query in worktree
    """
    global _active_worktree

    # Signal to terminal_tool that we're in interactive mode
    # This enables interactive sudo password prompts with timeout
    os.environ["KAI_INTERACTIVE"] = "1"
    
    # Handle gateway mode (messaging + cron)
    if gateway:
        import asyncio
        from gateway.run import start_gateway
        print("Starting Kai Gateway (messaging platforms)...")
        asyncio.run(start_gateway())
        return

    # Skip worktree for list commands (they exit immediately)
    if not list_tools and not list_toolsets:
        # ── Git worktree isolation (#652) ──
        # Create an isolated worktree so this agent instance doesn't collide
        # with other agents working on the same repo.
        use_worktree = worktree or w or CLI_CONFIG.get("worktree", False)
        wt_info = None
        if use_worktree:
            # Prune stale worktrees from crashed/killed sessions
            _repo = _git_repo_root()
            if _repo:
                _prune_stale_worktrees(_repo)
            wt_info = _setup_worktree()
            if wt_info:
                _active_worktree = wt_info
                os.environ["TERMINAL_CWD"] = wt_info["path"]
                atexit.register(_cleanup_worktree, wt_info)
            else:
                # Worktree was explicitly requested but setup failed —
                # don't silently run without isolation.
                return
    else:
        wt_info = None
    
    # Handle query shorthand
    query = query or q
    
    # Parse toolsets - handle both string and tuple/list inputs
    # Default to kai-cli toolset which includes cronjob management tools
    toolsets_list = None
    if toolsets:
        if isinstance(toolsets, str):
            toolsets_list = [t.strip() for t in toolsets.split(",")]
        elif isinstance(toolsets, (list, tuple)):
            # Fire may pass multiple --toolsets as a tuple
            toolsets_list = []
            for t in toolsets:
                if isinstance(t, str):
                    toolsets_list.extend([x.strip() for x in t.split(",")])
                else:
                    toolsets_list.append(str(t))
    else:
        # Check config for CLI toolsets, fallback to kai-cli
        config_cli_toolsets = CLI_CONFIG.get("platform_toolsets", {}).get("cli")
        if config_cli_toolsets and isinstance(config_cli_toolsets, list):
            toolsets_list = config_cli_toolsets
        else:
            toolsets_list = ["kai-cli"]
    
    # Create CLI instance
    cli = KaiCLI(
        model=model,
        toolsets=toolsets_list,
        provider=provider,
        api_key=api_key,
        base_url=base_url,
        max_turns=max_turns,
        verbose=verbose,
        compact=compact,
        resume=resume,
        checkpoints=checkpoints,
        pass_session_id=pass_session_id,
    )

    # Inject worktree context into agent's system prompt
    if wt_info:
        wt_note = (
            f"\n\n[System note: You are working in an isolated git worktree at "
            f"{wt_info['path']}. Your branch is `{wt_info['branch']}`. "
            f"Changes here do not affect the main working tree or other agents. "
            f"Remember to commit and push your changes, and create a PR if appropriate. "
            f"The original repo is at {wt_info['repo_root']}.]"
        )
        cli.system_prompt = (cli.system_prompt or "") + wt_note
    
    # Handle list commands (don't init agent for these)
    if list_tools:
        cli.show_banner()
        cli.show_tools()
        sys.exit(0)
    
    if list_toolsets:
        cli.show_banner()
        cli.show_toolsets()
        sys.exit(0)
    
    # Register cleanup for single-query mode (interactive mode registers in run())
    atexit.register(_run_cleanup)
    
    # Handle single query mode
    if query:
        # Single-query is non-interactive: there's no follow-up turn, so the
        # agent must operate autonomously (never pause to ask for confirmation —
        # no one can answer). Set before _init_agent so it reaches the prompt.
        os.environ.setdefault("KAI_AUTONOMOUS", "1")
        if quiet:
            # Quiet mode: suppress banner, spinner, tool previews.
            # Only print the final response and parseable session info.
            cli.tool_progress_mode = "off"
            if cli._init_agent():
                cli.agent.quiet_mode = True
                result = cli.agent.run_conversation(query)
                # One-shot/autonomous sessions have a single user turn, so the
                # interactive flush points (REPL exit, /clear) never fire and the
                # mid-task memory reflex is unreliable. Give the agent one
                # dedicated end-of-session turn to persist what it learned
                # (conventions, corrections, feedback). min_turns=0 forces it
                # despite the single user turn; writes are drained by the
                # telemetry call below so their cost lands in the footer.
                try:
                    cli.agent.flush_memories(min_turns=0)
                except Exception:
                    pass
                response = result.get("final_response", "") if isinstance(result, dict) else str(result)
                if response:
                    print(response)
                print(f"\nsession_id: {cli.session_id}")
                # Emit the canonical Cost: line in quiet mode too — kai-bench
                # and other harnesses parse this from stdout. Without this,
                # quiet-mode runs would expose tokens only via /tokens (which
                # is unreachable from -q mode). _print_session_telemetry drains
                # queued memory writes first so their cost lands in the footer.
                cli._print_session_telemetry()
        else:
            cli.show_banner()
            cli.console.print(f"[bold blue]Query:[/] {query}")
            cli.chat(query)
            # Dedicated end-of-session reflection turn (see quiet branch above):
            # one-shot mode never hits the interactive flush points.
            try:
                cli.agent.flush_memories(min_turns=0)
            except Exception:
                pass
            cli._print_exit_summary()
        return
    
    # Run interactive mode
    cli.run()


if __name__ == "__main__":
    fire.Fire(main)