refactor(tests): re-architect tests + fix CI failures (#5946)

* refactor: re-architect tests to mirror the codebase

* Update tests.yml

* fix: add missing tool_error imports after registry refactor

* fix(tests): replace patch.dict with monkeypatch to prevent env var leaks under xdist

patch.dict(os.environ) can leak TERMINAL_ENV across xdist workers,
causing test_code_execution tests to hit the Modal remote path.

* fix(tests): fix update_check and telegram xdist failures

- test_update_check: replace patch("hermes_cli.banner.os.getenv") with
  monkeypatch.setenv("HERMES_HOME") — banner.py no longer imports os
  directly, it uses get_hermes_home() from hermes_constants.

- test_telegram_conflict/approval_buttons: provide real exception classes
  for telegram.error mock (NetworkError, TimedOut, BadRequest) so the
  except clause in connect() doesn't fail with "catching classes that do
  not inherit from BaseException" when xdist pollutes sys.modules.

* fix(tests): accept unavailable_models kwarg in _prompt_model_selection mock

tests/cli/test_branch_command.py

@@ -0,0 +1,198 @@
+"""Tests for the /branch (/fork) command — session branching.
+
+Verifies that:
+- Branching creates a new session with copied conversation history
+- The original session is preserved (ended with "branched" reason)
+- Auto-generated titles use lineage numbering
+- Custom branch names are used when provided
+- parent_session_id links are set correctly
+- Edge cases: empty conversation, missing session DB
+"""
+
+import os
+import uuid
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import MagicMock, patch, PropertyMock
+
+import pytest
+
+
+@pytest.fixture
+def session_db(tmp_path):
+    """Create a real SessionDB for testing."""
+    os.environ["HERMES_HOME"] = str(tmp_path / ".hermes")
+    os.makedirs(tmp_path / ".hermes", exist_ok=True)
+    from hermes_state import SessionDB
+    db = SessionDB(db_path=tmp_path / ".hermes" / "test_sessions.db")
+    yield db
+    db.close()
+
+
+@pytest.fixture
+def cli_instance(tmp_path, session_db):
+    """Create a minimal HermesCLI-like object for testing _handle_branch_command."""
+    # We'll mock the CLI enough to test the branch logic without full init
+    from unittest.mock import MagicMock
+
+    cli = MagicMock()
+    cli._session_db = session_db
+    cli.session_id = "20260403_120000_abc123"
+    cli.model = "anthropic/claude-sonnet-4.6"
+    cli.max_turns = 90
+    cli.reasoning_config = {"enabled": True, "effort": "medium"}
+    cli.session_start = datetime.now()
+    cli._pending_title = None
+    cli._resumed = False
+    cli.agent = None
+    cli.conversation_history = [
+        {"role": "user", "content": "Hello, can you help me?"},
+        {"role": "assistant", "content": "Of course! How can I help?"},
+        {"role": "user", "content": "Write a Python function to sort a list."},
+        {"role": "assistant", "content": "def sort_list(lst): return sorted(lst)"},
+    ]
+
+    # Create the original session in the DB
+    session_db.create_session(
+        session_id=cli.session_id,
+        source="cli",
+        model=cli.model,
+    )
+    session_db.set_session_title(cli.session_id, "My Coding Session")
+
+    return cli
+
+
+class TestBranchCommandCLI:
+    """Test the /branch command logic for the CLI."""
+
+    def test_branch_creates_new_session(self, cli_instance, session_db):
+        """Branching should create a new session in the DB."""
+        from cli import HermesCLI
+
+        # Call the real method on the mock, using the real implementation
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        # Verify a new session was created
+        assert cli_instance.session_id != "20260403_120000_abc123"
+        new_session = session_db.get_session(cli_instance.session_id)
+        assert new_session is not None
+
+    def test_branch_copies_history(self, cli_instance, session_db):
+        """Branching should copy all messages to the new session."""
+        from cli import HermesCLI
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        messages = session_db.get_messages_as_conversation(cli_instance.session_id)
+        assert len(messages) == 4  # All 4 messages copied
+
+    def test_branch_preserves_parent_link(self, cli_instance, session_db):
+        """The new session should reference the original as parent."""
+        from cli import HermesCLI
+        original_id = cli_instance.session_id
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        new_session = session_db.get_session(cli_instance.session_id)
+        assert new_session["parent_session_id"] == original_id
+
+    def test_branch_ends_original_session(self, cli_instance, session_db):
+        """The original session should be marked as ended with 'branched' reason."""
+        from cli import HermesCLI
+        original_id = cli_instance.session_id
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        original = session_db.get_session(original_id)
+        assert original["end_reason"] == "branched"
+
+    def test_branch_with_custom_name(self, cli_instance, session_db):
+        """Custom branch name should be used as the title."""
+        from cli import HermesCLI
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch refactor approach")
+
+        title = session_db.get_session_title(cli_instance.session_id)
+        assert title == "refactor approach"
+
+    def test_branch_auto_title_lineage(self, cli_instance, session_db):
+        """Without a name, branch should auto-generate a title from the parent's title."""
+        from cli import HermesCLI
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        title = session_db.get_session_title(cli_instance.session_id)
+        assert title == "My Coding Session #2"
+
+    def test_branch_empty_conversation(self, cli_instance, session_db):
+        """Branching with no history should show an error."""
+        from cli import HermesCLI
+        cli_instance.conversation_history = []
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        # session_id should not have changed
+        assert cli_instance.session_id == "20260403_120000_abc123"
+
+    def test_branch_no_session_db(self, cli_instance):
+        """Branching without a session DB should show an error."""
+        from cli import HermesCLI
+        cli_instance._session_db = None
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        # session_id should not have changed
+        assert cli_instance.session_id == "20260403_120000_abc123"
+
+    def test_branch_syncs_agent(self, cli_instance, session_db):
+        """If an agent is active, branch should sync it to the new session."""
+        from cli import HermesCLI
+
+        agent = MagicMock()
+        agent._last_flushed_db_idx = 0
+        cli_instance.agent = agent
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        # Agent should have been updated
+        assert agent.session_id == cli_instance.session_id
+        assert agent.reset_session_state.called
+        assert agent._last_flushed_db_idx == 4  # len(conversation_history)
+
+    def test_branch_sets_resumed_flag(self, cli_instance, session_db):
+        """Branch should set _resumed=True to prevent auto-title generation."""
+        from cli import HermesCLI
+
+        HermesCLI._handle_branch_command(cli_instance, "/branch")
+
+        assert cli_instance._resumed is True
+
+    def test_fork_alias(self):
+        """The /fork alias should resolve to 'branch'."""
+        from hermes_cli.commands import resolve_command
+        result = resolve_command("fork")
+        assert result is not None
+        assert result.name == "branch"
+
+
+class TestBranchCommandDef:
+    """Test the CommandDef registration for /branch."""
+
+    def test_branch_in_registry(self):
+        """The branch command should be in the command registry."""
+        from hermes_cli.commands import COMMAND_REGISTRY
+        names = [c.name for c in COMMAND_REGISTRY]
+        assert "branch" in names
+
+    def test_branch_has_fork_alias(self):
+        """The branch command should have 'fork' as an alias."""
+        from hermes_cli.commands import COMMAND_REGISTRY
+        branch = next(c for c in COMMAND_REGISTRY if c.name == "branch")
+        assert "fork" in branch.aliases
+
+    def test_branch_in_session_category(self):
+        """The branch command should be in the Session category."""
+        from hermes_cli.commands import COMMAND_REGISTRY
+        branch = next(c for c in COMMAND_REGISTRY if c.name == "branch")
+        assert branch.category == "Session"

tests/cli/test_cli_approval_ui.py

@@ -0,0 +1,100 @@
+import queue
+import threading
+import time
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from cli import HermesCLI
+
+
+def _make_cli_stub():
+    cli = HermesCLI.__new__(HermesCLI)
+    cli._approval_state = None
+    cli._approval_deadline = 0
+    cli._approval_lock = threading.Lock()
+    cli._invalidate = MagicMock()
+    cli._app = SimpleNamespace(invalidate=MagicMock())
+    return cli
+
+
+class TestCliApprovalUi:
+    def test_approval_callback_includes_view_for_long_commands(self):
+        cli = _make_cli_stub()
+        command = "sudo dd if=/tmp/githubcli-keyring.gpg of=/usr/share/keyrings/githubcli-archive-keyring.gpg bs=4M status=progress"
+        result = {}
+
+        def _run_callback():
+            result["value"] = cli._approval_callback(command, "disk copy")
+
+        thread = threading.Thread(target=_run_callback, daemon=True)
+        thread.start()
+
+        deadline = time.time() + 2
+        while cli._approval_state is None and time.time() < deadline:
+            time.sleep(0.01)
+
+        assert cli._approval_state is not None
+        assert "view" in cli._approval_state["choices"]
+
+        cli._approval_state["response_queue"].put("deny")
+        thread.join(timeout=2)
+        assert result["value"] == "deny"
+
+    def test_handle_approval_selection_view_expands_in_place(self):
+        cli = _make_cli_stub()
+        cli._approval_state = {
+            "command": "sudo dd if=/tmp/in of=/usr/share/keyrings/githubcli-archive-keyring.gpg bs=4M status=progress",
+            "description": "disk copy",
+            "choices": ["once", "session", "always", "deny", "view"],
+            "selected": 4,
+            "response_queue": queue.Queue(),
+        }
+
+        cli._handle_approval_selection()
+
+        assert cli._approval_state is not None
+        assert cli._approval_state["show_full"] is True
+        assert "view" not in cli._approval_state["choices"]
+        assert cli._approval_state["selected"] == 3
+        assert cli._approval_state["response_queue"].empty()
+
+    def test_approval_display_places_title_inside_box_not_border(self):
+        cli = _make_cli_stub()
+        cli._approval_state = {
+            "command": "sudo dd if=/tmp/in of=/usr/share/keyrings/githubcli-archive-keyring.gpg bs=4M status=progress",
+            "description": "disk copy",
+            "choices": ["once", "session", "always", "deny", "view"],
+            "selected": 0,
+            "response_queue": queue.Queue(),
+        }
+
+        fragments = cli._get_approval_display_fragments()
+        rendered = "".join(text for _style, text in fragments)
+        lines = rendered.splitlines()
+
+        assert lines[0].startswith("╭")
+        assert "Dangerous Command" not in lines[0]
+        assert any("Dangerous Command" in line for line in lines[1:3])
+        assert "Show full command" in rendered
+        assert "githubcli-archive-keyring.gpg" not in rendered
+
+    def test_approval_display_shows_full_command_after_view(self):
+        cli = _make_cli_stub()
+        full_command = "sudo dd if=/tmp/in of=/usr/share/keyrings/githubcli-archive-keyring.gpg bs=4M status=progress"
+        cli._approval_state = {
+            "command": full_command,
+            "description": "disk copy",
+            "choices": ["once", "session", "always", "deny"],
+            "selected": 0,
+            "show_full": True,
+            "response_queue": queue.Queue(),
+        }
+
+        fragments = cli._get_approval_display_fragments()
+        rendered = "".join(text for _style, text in fragments)
+
+        assert "..." not in rendered
+        assert "githubcli-" in rendered
+        assert "archive-" in rendered
+        assert "keyring.gpg" in rendered
+        assert "status=progress" in rendered

tests/cli/test_cli_background_tui_refresh.py

@@ -0,0 +1,105 @@
+"""Tests for CLI background command TUI refresh behavior.
+
+Ensures the TUI is properly refreshed before printing background task output
+to prevent spinner/status bar overlap (#2718).
+"""
+
+import threading
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from cli import HermesCLI
+
+
+def _make_cli():
+    """Create a minimal HermesCLI instance for testing."""
+    cli_obj = HermesCLI.__new__(HermesCLI)
+    cli_obj.model = "test-model"
+    cli_obj._background_tasks = {}
+    cli_obj._background_task_counter = 0
+    cli_obj.conversation_history = []
+    cli_obj.agent = None
+    cli_obj._app = None
+    return cli_obj
+
+
+class TestBackgroundCommandTuiRefresh:
+    """Tests for TUI refresh in background command output."""
+
+    def test_invalidate_called_before_success_output(self):
+        """App.invalidate() is called before printing background success output."""
+        cli_obj = _make_cli()
+        mock_app = MagicMock()
+        cli_obj._app = mock_app
+
+        # Track call order
+        call_order = []
+        original_invalidate = mock_app.invalidate
+
+        def track_invalidate():
+            call_order.append("invalidate")
+            return original_invalidate()
+
+        mock_app.invalidate = track_invalidate
+
+        # Patch print to track when it's called
+        with patch("builtins.print") as mock_print:
+            mock_print.side_effect = lambda *args, **kwargs: call_order.append("print")
+
+            # Simulate the background task output code path
+            if cli_obj._app:
+                cli_obj._app.invalidate()
+                import time
+                time.sleep(0.01)  # reduced for test
+            print()
+
+        # Verify invalidate was called before print
+        assert call_order[0] == "invalidate"
+        assert "print" in call_order
+
+    def test_invalidate_called_before_error_output(self):
+        """App.invalidate() is called before printing background error output."""
+        cli_obj = _make_cli()
+        mock_app = MagicMock()
+        cli_obj._app = mock_app
+
+        call_order = []
+        mock_app.invalidate.side_effect = lambda: call_order.append("invalidate")
+
+        with patch("builtins.print") as mock_print:
+            mock_print.side_effect = lambda *args, **kwargs: call_order.append("print")
+
+            # Simulate error path
+            if cli_obj._app:
+                cli_obj._app.invalidate()
+                import time
+                time.sleep(0.01)
+            print()
+
+        assert call_order[0] == "invalidate"
+        assert "print" in call_order
+
+    def test_no_crash_when_app_is_none(self):
+        """No crash when _app is None (non-TUI mode)."""
+        cli_obj = _make_cli()
+        cli_obj._app = None
+
+        # This should not raise
+        if cli_obj._app:
+            cli_obj._app.invalidate()
+        # If we get here without exception, test passes
+
+    def test_background_task_thread_safety(self):
+        """Background task tracking is thread-safe."""
+        cli_obj = _make_cli()
+
+        # Simulate adding and removing background tasks
+        task_id = "test_task_1"
+        cli_obj._background_tasks[task_id] = MagicMock()
+        assert task_id in cli_obj._background_tasks
+
+        # Clean up
+        cli_obj._background_tasks.pop(task_id, None)
+        assert task_id not in cli_obj._background_tasks

tests/cli/test_cli_browser_connect.py

@@ -0,0 +1,46 @@
+"""Tests for CLI browser CDP auto-launch helpers."""
+
+import os
+from unittest.mock import patch
+
+from cli import HermesCLI
+
+
+class TestChromeDebugLaunch:
+    def test_windows_launch_uses_browser_found_on_path(self):
+        captured = {}
+
+        def fake_popen(cmd, **kwargs):
+            captured["cmd"] = cmd
+            captured["kwargs"] = kwargs
+            return object()
+
+        with patch("cli.shutil.which", side_effect=lambda name: r"C:\Chrome\chrome.exe" if name == "chrome.exe" else None), \
+             patch("cli.os.path.isfile", side_effect=lambda path: path == r"C:\Chrome\chrome.exe"), \
+             patch("subprocess.Popen", side_effect=fake_popen):
+            assert HermesCLI._try_launch_chrome_debug(9333, "Windows") is True
+
+        assert captured["cmd"] == [r"C:\Chrome\chrome.exe", "--remote-debugging-port=9333"]
+        assert captured["kwargs"]["start_new_session"] is True
+
+    def test_windows_launch_falls_back_to_common_install_dirs(self, monkeypatch):
+        captured = {}
+        program_files = r"C:\Program Files"
+        # Use os.path.join so path separators match cross-platform
+        installed = os.path.join(program_files, "Google", "Chrome", "Application", "chrome.exe")
+
+        def fake_popen(cmd, **kwargs):
+            captured["cmd"] = cmd
+            captured["kwargs"] = kwargs
+            return object()
+
+        monkeypatch.setenv("ProgramFiles", program_files)
+        monkeypatch.delenv("ProgramFiles(x86)", raising=False)
+        monkeypatch.delenv("LOCALAPPDATA", raising=False)
+
+        with patch("cli.shutil.which", return_value=None), \
+             patch("cli.os.path.isfile", side_effect=lambda path: path == installed), \
+             patch("subprocess.Popen", side_effect=fake_popen):
+            assert HermesCLI._try_launch_chrome_debug(9222, "Windows") is True
+
+        assert captured["cmd"] == [installed, "--remote-debugging-port=9222"]

tests/cli/test_cli_context_warning.py

@@ -0,0 +1,161 @@
+"""Tests for the low context length warning in the CLI banner."""
+
+import os
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+@pytest.fixture
+def _isolate(tmp_path, monkeypatch):
+    """Isolate HERMES_HOME so tests don't touch real config."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+
+@pytest.fixture
+def cli_obj(_isolate):
+    """Create a minimal HermesCLI instance for banner testing."""
+    with patch("cli.load_cli_config", return_value={
+        "display": {"tool_progress": "new"},
+        "terminal": {},
+    }), patch("cli.get_tool_definitions", return_value=[]), \
+         patch("cli.build_welcome_banner"):
+        from cli import HermesCLI
+        obj = HermesCLI.__new__(HermesCLI)
+        obj.model = "test-model"
+        obj.enabled_toolsets = ["hermes-core"]
+        obj.compact = False
+        obj.console = MagicMock()
+        obj.session_id = None
+        obj.api_key = "test"
+        obj.base_url = ""
+        obj.provider = "test"
+        obj._provider_source = None
+        # Mock agent with context compressor
+        obj.agent = SimpleNamespace(
+            context_compressor=SimpleNamespace(context_length=None)
+        )
+        return obj
+
+
+class TestLowContextWarning:
+    """Tests that the CLI warns about low context lengths."""
+
+    def test_no_warning_for_normal_context(self, cli_obj):
+        """No warning when context is 32k+."""
+        cli_obj.agent.context_compressor.context_length = 32768
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        # Check that no yellow warning was printed
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 0
+
+    def test_warning_for_low_context(self, cli_obj):
+        """Warning shown when context is 4096 (Ollama default)."""
+        cli_obj.agent.context_compressor.context_length = 4096
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 1
+        assert "4,096" in warning_calls[0]
+
+    def test_warning_for_2048_context(self, cli_obj):
+        """Warning shown for 2048 tokens (common LM Studio default)."""
+        cli_obj.agent.context_compressor.context_length = 2048
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 1
+
+    def test_no_warning_at_boundary(self, cli_obj):
+        """No warning at exactly 8192 — 8192 is borderline but included in warning."""
+        cli_obj.agent.context_compressor.context_length = 8192
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 1  # 8192 is still warned about
+
+    def test_no_warning_above_boundary(self, cli_obj):
+        """No warning at 16384."""
+        cli_obj.agent.context_compressor.context_length = 16384
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 0
+
+    def test_ollama_specific_hint(self, cli_obj):
+        """Ollama-specific fix shown when port 11434 detected."""
+        cli_obj.agent.context_compressor.context_length = 4096
+        cli_obj.base_url = "http://localhost:11434/v1"
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        ollama_hints = [c for c in calls if "OLLAMA_CONTEXT_LENGTH" in c]
+        assert len(ollama_hints) == 1
+
+    def test_lm_studio_specific_hint(self, cli_obj):
+        """LM Studio-specific fix shown when port 1234 detected."""
+        cli_obj.agent.context_compressor.context_length = 2048
+        cli_obj.base_url = "http://localhost:1234/v1"
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        lms_hints = [c for c in calls if "LM Studio" in c]
+        assert len(lms_hints) == 1
+
+    def test_generic_hint_for_other_servers(self, cli_obj):
+        """Generic fix shown for unknown servers."""
+        cli_obj.agent.context_compressor.context_length = 4096
+        cli_obj.base_url = "http://localhost:8080/v1"
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        generic_hints = [c for c in calls if "config.yaml" in c]
+        assert len(generic_hints) == 1
+
+    def test_no_warning_when_no_context_length(self, cli_obj):
+        """No warning when context length is not yet known."""
+        cli_obj.agent.context_compressor.context_length = None
+        with patch("cli.get_tool_definitions", return_value=[]), \
+             patch("cli.build_welcome_banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 0
+
+    def test_compact_banner_does_not_crash_on_narrow_terminal(self, cli_obj):
+        """Compact mode should still have ctx_len defined for warning logic."""
+        cli_obj.agent.context_compressor.context_length = 4096
+
+        with patch("shutil.get_terminal_size", return_value=os.terminal_size((70, 40))), \
+             patch("cli._build_compact_banner", return_value="compact banner"):
+            cli_obj.show_banner()
+
+        calls = [str(c) for c in cli_obj.console.print.call_args_list]
+        warning_calls = [c for c in calls if "too low" in c]
+        assert len(warning_calls) == 1

tests/cli/test_cli_extension_hooks.py

@@ -0,0 +1,138 @@
+"""Tests for protected HermesCLI TUI extension hooks.
+
+Verifies that wrapper CLIs can extend the TUI via:
+  - _get_extra_tui_widgets()
+  - _register_extra_tui_keybindings()
+  - _build_tui_layout_children()
+without overriding run().
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from unittest.mock import MagicMock, patch
+
+from prompt_toolkit.key_binding import KeyBindings
+
+
+def _make_cli(**kwargs):
+    """Create a HermesCLI with prompt_toolkit stubs (same pattern as test_cli_init)."""
+    _clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+    clean_env = {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}
+    prompt_toolkit_stubs = {
+        "prompt_toolkit": MagicMock(),
+        "prompt_toolkit.history": MagicMock(),
+        "prompt_toolkit.styles": MagicMock(),
+        "prompt_toolkit.patch_stdout": MagicMock(),
+        "prompt_toolkit.application": MagicMock(),
+        "prompt_toolkit.layout": MagicMock(),
+        "prompt_toolkit.layout.processors": MagicMock(),
+        "prompt_toolkit.filters": MagicMock(),
+        "prompt_toolkit.layout.dimension": MagicMock(),
+        "prompt_toolkit.layout.menus": MagicMock(),
+        "prompt_toolkit.widgets": MagicMock(),
+        "prompt_toolkit.key_binding": MagicMock(),
+        "prompt_toolkit.completion": MagicMock(),
+        "prompt_toolkit.formatted_text": MagicMock(),
+        "prompt_toolkit.auto_suggest": MagicMock(),
+    }
+    with patch.dict(sys.modules, prompt_toolkit_stubs), patch.dict(
+        "os.environ", clean_env, clear=False
+    ):
+        import cli as _cli_mod
+
+        _cli_mod = importlib.reload(_cli_mod)
+        with patch.object(_cli_mod, "get_tool_definitions", return_value=[]), patch.dict(
+            _cli_mod.__dict__, {"CLI_CONFIG": _clean_config}
+        ):
+            return _cli_mod.HermesCLI(**kwargs)
+
+
+class TestExtensionHookDefaults:
+    def test_extra_tui_widgets_default_empty(self):
+        cli = _make_cli()
+        assert cli._get_extra_tui_widgets() == []
+
+    def test_register_extra_tui_keybindings_default_noop(self):
+        cli = _make_cli()
+        kb = KeyBindings()
+        result = cli._register_extra_tui_keybindings(kb, input_area=None)
+        assert result is None
+        assert kb.bindings == []
+
+    def test_build_tui_layout_children_returns_all_widgets_in_order(self):
+        cli = _make_cli()
+        children = cli._build_tui_layout_children(
+            sudo_widget="sudo",
+            secret_widget="secret",
+            approval_widget="approval",
+            clarify_widget="clarify",
+            spinner_widget="spinner",
+            spacer="spacer",
+            status_bar="status",
+            input_rule_top="top-rule",
+            image_bar="image-bar",
+            input_area="input-area",
+            input_rule_bot="bottom-rule",
+            voice_status_bar="voice-status",
+            completions_menu="completions-menu",
+        )
+        # First element is Window(height=0), rest are the named widgets
+        assert children[1:] == [
+            "sudo", "secret", "approval", "clarify", "spinner",
+            "spacer", "status", "top-rule", "image-bar", "input-area",
+            "bottom-rule", "voice-status", "completions-menu",
+        ]
+
+
+class TestExtensionHookSubclass:
+    def test_extra_widgets_inserted_before_status_bar(self):
+        cli = _make_cli()
+        # Monkey-patch to simulate subclass override
+        cli._get_extra_tui_widgets = lambda: ["radio-menu", "mini-player"]
+
+        children = cli._build_tui_layout_children(
+            sudo_widget="sudo",
+            secret_widget="secret",
+            approval_widget="approval",
+            clarify_widget="clarify",
+            spinner_widget="spinner",
+            spacer="spacer",
+            status_bar="status",
+            input_rule_top="top-rule",
+            image_bar="image-bar",
+            input_area="input-area",
+            input_rule_bot="bottom-rule",
+            voice_status_bar="voice-status",
+            completions_menu="completions-menu",
+        )
+        # Extra widgets should appear between spacer and status bar
+        spacer_idx = children.index("spacer")
+        status_idx = children.index("status")
+        assert children[spacer_idx + 1] == "radio-menu"
+        assert children[spacer_idx + 2] == "mini-player"
+        assert children[spacer_idx + 3] == "status"
+        assert status_idx == spacer_idx + 3
+
+    def test_extra_keybindings_can_add_bindings(self):
+        cli = _make_cli()
+        kb = KeyBindings()
+
+        def _custom_hook(kb, *, input_area):
+            @kb.add("f2")
+            def _toggle(event):
+                return None
+
+        cli._register_extra_tui_keybindings = _custom_hook
+        cli._register_extra_tui_keybindings(kb, input_area=None)
+        assert len(kb.bindings) == 1

tests/cli/test_cli_file_drop.py

@@ -0,0 +1,176 @@
+"""Tests for _detect_file_drop — file path detection that prevents
+dragged/pasted absolute paths from being mistaken for slash commands."""
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from cli import _detect_file_drop
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture()
+def tmp_image(tmp_path):
+    """Create a temporary .png file and return its path."""
+    img = tmp_path / "screenshot.png"
+    img.write_bytes(b"\x89PNG\r\n\x1a\n")  # minimal PNG header
+    return img
+
+
+@pytest.fixture()
+def tmp_text(tmp_path):
+    """Create a temporary .py file and return its path."""
+    f = tmp_path / "main.py"
+    f.write_text("print('hello')\n")
+    return f
+
+
+@pytest.fixture()
+def tmp_image_with_spaces(tmp_path):
+    """Create a file whose name contains spaces (like macOS screenshots)."""
+    img = tmp_path / "Screenshot 2026-04-01 at 7.25.32 PM.png"
+    img.write_bytes(b"\x89PNG\r\n\x1a\n")
+    return img
+
+
+# ---------------------------------------------------------------------------
+# Tests: returns None for non-file inputs
+# ---------------------------------------------------------------------------
+
+class TestNonFileInputs:
+    def test_regular_slash_command(self):
+        assert _detect_file_drop("/help") is None
+
+    def test_unknown_slash_command(self):
+        assert _detect_file_drop("/xyz") is None
+
+    def test_slash_command_with_args(self):
+        assert _detect_file_drop("/config set key value") is None
+
+    def test_empty_string(self):
+        assert _detect_file_drop("") is None
+
+    def test_non_slash_input(self):
+        assert _detect_file_drop("hello world") is None
+
+    def test_non_string_input(self):
+        assert _detect_file_drop(42) is None
+
+    def test_nonexistent_path(self):
+        assert _detect_file_drop("/nonexistent/path/to/file.png") is None
+
+    def test_directory_not_file(self, tmp_path):
+        """A directory path should not be treated as a file drop."""
+        assert _detect_file_drop(str(tmp_path)) is None
+
+
+# ---------------------------------------------------------------------------
+# Tests: image file detection
+# ---------------------------------------------------------------------------
+
+class TestImageFileDrop:
+    def test_simple_image_path(self, tmp_image):
+        result = _detect_file_drop(str(tmp_image))
+        assert result is not None
+        assert result["path"] == tmp_image
+        assert result["is_image"] is True
+        assert result["remainder"] == ""
+
+    def test_image_with_trailing_text(self, tmp_image):
+        user_input = f"{tmp_image} analyze this please"
+        result = _detect_file_drop(user_input)
+        assert result is not None
+        assert result["path"] == tmp_image
+        assert result["is_image"] is True
+        assert result["remainder"] == "analyze this please"
+
+    @pytest.mark.parametrize("ext", [".png", ".jpg", ".jpeg", ".gif", ".webp",
+                                      ".bmp", ".tiff", ".tif", ".svg", ".ico"])
+    def test_all_image_extensions(self, tmp_path, ext):
+        img = tmp_path / f"test{ext}"
+        img.write_bytes(b"fake")
+        result = _detect_file_drop(str(img))
+        assert result is not None
+        assert result["is_image"] is True
+
+    def test_uppercase_extension(self, tmp_path):
+        img = tmp_path / "photo.JPG"
+        img.write_bytes(b"fake")
+        result = _detect_file_drop(str(img))
+        assert result is not None
+        assert result["is_image"] is True
+
+
+# ---------------------------------------------------------------------------
+# Tests: non-image file detection
+# ---------------------------------------------------------------------------
+
+class TestNonImageFileDrop:
+    def test_python_file(self, tmp_text):
+        result = _detect_file_drop(str(tmp_text))
+        assert result is not None
+        assert result["path"] == tmp_text
+        assert result["is_image"] is False
+        assert result["remainder"] == ""
+
+    def test_non_image_with_trailing_text(self, tmp_text):
+        user_input = f"{tmp_text} review this code"
+        result = _detect_file_drop(user_input)
+        assert result is not None
+        assert result["is_image"] is False
+        assert result["remainder"] == "review this code"
+
+
+# ---------------------------------------------------------------------------
+# Tests: backslash-escaped spaces (macOS drag-and-drop)
+# ---------------------------------------------------------------------------
+
+class TestEscapedSpaces:
+    def test_escaped_spaces_in_path(self, tmp_image_with_spaces):
+        r"""macOS drags produce paths like /path/to/my\ file.png"""
+        escaped = str(tmp_image_with_spaces).replace(' ', '\\ ')
+        result = _detect_file_drop(escaped)
+        assert result is not None
+        assert result["path"] == tmp_image_with_spaces
+        assert result["is_image"] is True
+
+    def test_escaped_spaces_with_trailing_text(self, tmp_image_with_spaces):
+        escaped = str(tmp_image_with_spaces).replace(' ', '\\ ')
+        user_input = f"{escaped} what is this?"
+        result = _detect_file_drop(user_input)
+        assert result is not None
+        assert result["path"] == tmp_image_with_spaces
+        assert result["remainder"] == "what is this?"
+
+
+# ---------------------------------------------------------------------------
+# Tests: edge cases
+# ---------------------------------------------------------------------------
+
+class TestEdgeCases:
+    def test_path_with_no_extension(self, tmp_path):
+        f = tmp_path / "Makefile"
+        f.write_text("all:\n\techo hi\n")
+        result = _detect_file_drop(str(f))
+        assert result is not None
+        assert result["is_image"] is False
+
+    def test_path_that_looks_like_command_but_is_file(self, tmp_path):
+        """A file literally named 'help' inside a directory starting with /."""
+        f = tmp_path / "help"
+        f.write_text("not a command\n")
+        result = _detect_file_drop(str(f))
+        assert result is not None
+        assert result["is_image"] is False
+
+    def test_symlink_to_file(self, tmp_image, tmp_path):
+        link = tmp_path / "link.png"
+        link.symlink_to(tmp_image)
+        result = _detect_file_drop(str(link))
+        assert result is not None
+        assert result["is_image"] is True

tests/cli/test_cli_init.py

@@ -0,0 +1,347 @@
+"""Tests for HermesCLI initialization -- catches configuration bugs
+that only manifest at runtime (not in mocked unit tests)."""
+
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+
+def _make_cli(env_overrides=None, config_overrides=None, **kwargs):
+    """Create a HermesCLI instance with minimal mocking."""
+    import importlib
+
+    _clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+    if config_overrides:
+        _clean_config.update(config_overrides)
+    clean_env = {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}
+    if env_overrides:
+        clean_env.update(env_overrides)
+    prompt_toolkit_stubs = {
+        "prompt_toolkit": MagicMock(),
+        "prompt_toolkit.history": MagicMock(),
+        "prompt_toolkit.styles": MagicMock(),
+        "prompt_toolkit.patch_stdout": MagicMock(),
+        "prompt_toolkit.application": MagicMock(),
+        "prompt_toolkit.layout": MagicMock(),
+        "prompt_toolkit.layout.processors": MagicMock(),
+        "prompt_toolkit.filters": MagicMock(),
+        "prompt_toolkit.layout.dimension": MagicMock(),
+        "prompt_toolkit.layout.menus": MagicMock(),
+        "prompt_toolkit.widgets": MagicMock(),
+        "prompt_toolkit.key_binding": MagicMock(),
+        "prompt_toolkit.completion": MagicMock(),
+        "prompt_toolkit.formatted_text": MagicMock(),
+        "prompt_toolkit.auto_suggest": MagicMock(),
+    }
+    with patch.dict(sys.modules, prompt_toolkit_stubs), \
+         patch.dict("os.environ", clean_env, clear=False):
+        import cli as _cli_mod
+        _cli_mod = importlib.reload(_cli_mod)
+        with patch.object(_cli_mod, "get_tool_definitions", return_value=[]), \
+             patch.dict(_cli_mod.__dict__, {"CLI_CONFIG": _clean_config}):
+            return _cli_mod.HermesCLI(**kwargs)
+
+
+class TestMaxTurnsResolution:
+    """max_turns must always resolve to a positive integer, never None."""
+
+    def test_default_max_turns_is_integer(self):
+        cli = _make_cli()
+        assert isinstance(cli.max_turns, int)
+        assert cli.max_turns == 90
+
+    def test_explicit_max_turns_honored(self):
+        cli = _make_cli(max_turns=25)
+        assert cli.max_turns == 25
+
+    def test_none_max_turns_gets_default(self):
+        cli = _make_cli(max_turns=None)
+        assert isinstance(cli.max_turns, int)
+        assert cli.max_turns == 90
+
+    def test_env_var_max_turns(self):
+        """Env var is used when config file doesn't set max_turns."""
+        cli_obj = _make_cli(env_overrides={"HERMES_MAX_ITERATIONS": "42"})
+        assert cli_obj.max_turns == 42
+
+    def test_legacy_root_max_turns_is_used_when_agent_key_exists_without_value(self):
+        cli_obj = _make_cli(config_overrides={"agent": {}, "max_turns": 77})
+        assert cli_obj.max_turns == 77
+
+    def test_max_turns_never_none_for_agent(self):
+        """The value passed to AIAgent must never be None (causes TypeError in run_conversation)."""
+        cli = _make_cli()
+        assert isinstance(cli.max_turns, int) and cli.max_turns == 90
+
+
+class TestVerboseAndToolProgress:
+    def test_default_verbose_is_bool(self):
+        cli = _make_cli()
+        assert isinstance(cli.verbose, bool)
+
+    def test_tool_progress_mode_is_string(self):
+        cli = _make_cli()
+        assert isinstance(cli.tool_progress_mode, str)
+        assert cli.tool_progress_mode in ("off", "new", "all", "verbose")
+
+
+class TestBusyInputMode:
+    def test_default_busy_input_mode_is_interrupt(self):
+        cli = _make_cli()
+        assert cli.busy_input_mode == "interrupt"
+
+    def test_busy_input_mode_queue_is_honored(self):
+        cli = _make_cli(config_overrides={"display": {"busy_input_mode": "queue"}})
+        assert cli.busy_input_mode == "queue"
+
+    def test_unknown_busy_input_mode_falls_back_to_interrupt(self):
+        cli = _make_cli(config_overrides={"display": {"busy_input_mode": "bogus"}})
+        assert cli.busy_input_mode == "interrupt"
+
+    def test_queue_command_works_while_busy(self):
+        """When agent is running, /queue should still put the prompt in _pending_input."""
+        cli = _make_cli()
+        cli._agent_running = True
+        cli.process_command("/queue follow up")
+        assert cli._pending_input.get_nowait() == "follow up"
+
+    def test_queue_command_works_while_idle(self):
+        """When agent is idle, /queue should still queue (not reject)."""
+        cli = _make_cli()
+        cli._agent_running = False
+        cli.process_command("/queue follow up")
+        assert cli._pending_input.get_nowait() == "follow up"
+
+    def test_queue_mode_routes_busy_enter_to_pending(self):
+        """In queue mode, Enter while busy should go to _pending_input, not _interrupt_queue."""
+        cli = _make_cli(config_overrides={"display": {"busy_input_mode": "queue"}})
+        cli._agent_running = True
+        # Simulate what handle_enter does for non-command input while busy
+        text = "follow up"
+        if cli.busy_input_mode == "queue":
+            cli._pending_input.put(text)
+        else:
+            cli._interrupt_queue.put(text)
+        assert cli._pending_input.get_nowait() == "follow up"
+        assert cli._interrupt_queue.empty()
+
+    def test_interrupt_mode_routes_busy_enter_to_interrupt(self):
+        """In interrupt mode (default), Enter while busy goes to _interrupt_queue."""
+        cli = _make_cli()
+        cli._agent_running = True
+        text = "redirect"
+        if cli.busy_input_mode == "queue":
+            cli._pending_input.put(text)
+        else:
+            cli._interrupt_queue.put(text)
+        assert cli._interrupt_queue.get_nowait() == "redirect"
+        assert cli._pending_input.empty()
+
+
+class TestSingleQueryState:
+    def test_voice_and_interrupt_state_initialized_before_run(self):
+        """Single-query mode calls chat() without going through run()."""
+        cli = _make_cli()
+        assert cli._voice_tts is False
+        assert cli._voice_mode is False
+        assert cli._voice_tts_done.is_set()
+        assert hasattr(cli, "_interrupt_queue")
+        assert hasattr(cli, "_pending_input")
+
+
+class TestHistoryDisplay:
+    def test_history_numbers_only_visible_messages_and_summarizes_tools(self, capsys):
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "system", "content": "system prompt"},
+            {"role": "user", "content": "Hello"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [{"id": "call_1"}, {"id": "call_2"}],
+            },
+            {"role": "tool", "content": "tool output 1"},
+            {"role": "tool", "content": "tool output 2"},
+            {"role": "assistant", "content": "All set."},
+            {"role": "user", "content": "A" * 250},
+        ]
+
+        cli.show_history()
+        output = capsys.readouterr().out
+
+        assert "[You #1]" in output
+        assert "[Hermes #2]" in output
+        assert "(requested 2 tool calls)" in output
+        assert "[Tools]" in output
+        assert "(2 tool messages hidden)" in output
+        assert "[Hermes #3]" in output
+        assert "[You #4]" in output
+        assert "[You #5]" not in output
+        assert "A" * 250 in output
+        assert "A" * 250 + "..." not in output
+
+    def test_history_shows_recent_sessions_when_current_chat_is_empty(self, capsys):
+        cli = _make_cli()
+        cli.session_id = "current"
+        cli._session_db = MagicMock()
+        cli._session_db.list_sessions_rich.return_value = [
+            {
+                "id": "current",
+                "title": "Current",
+                "preview": "Current preview",
+                "last_active": 0,
+            },
+            {
+                "id": "20260401_201329_d85961",
+                "title": "Checking Running Hermes Agent",
+                "preview": "check running gateways for hermes agent",
+                "last_active": 0,
+            },
+        ]
+
+        cli.show_history()
+        output = capsys.readouterr().out
+
+        assert "No messages in the current chat yet" in output
+        assert "Checking Running Hermes Agent" in output
+        assert "20260401_201329_d85961" in output
+        assert "/resume" in output
+        assert "Current preview" not in output
+
+    def test_resume_without_target_lists_recent_sessions(self, capsys):
+        cli = _make_cli()
+        cli.session_id = "current"
+        cli._session_db = MagicMock()
+        cli._session_db.list_sessions_rich.return_value = [
+            {
+                "id": "current",
+                "title": "Current",
+                "preview": "Current preview",
+                "last_active": 0,
+            },
+            {
+                "id": "20260401_201329_d85961",
+                "title": "Checking Running Hermes Agent",
+                "preview": "check running gateways for hermes agent",
+                "last_active": 0,
+            },
+        ]
+
+        cli._handle_resume_command("/resume")
+        output = capsys.readouterr().out
+
+        assert "Recent sessions" in output
+        assert "Checking Running Hermes Agent" in output
+        assert "Use /resume <session id or title> to continue" in output
+
+
+class TestRootLevelProviderOverride:
+    """Root-level provider/base_url in config.yaml must NOT override model.provider."""
+
+    def test_model_provider_wins_over_root_provider(self, tmp_path, monkeypatch):
+        """model.provider takes priority — root-level provider is only a fallback."""
+        import yaml
+
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        config_path = hermes_home / "config.yaml"
+        config_path.write_text(yaml.safe_dump({
+            "provider": "opencode-go",  # stale root-level key
+            "model": {
+                "default": "google/gemini-3-flash-preview",
+                "provider": "openrouter",  # correct canonical key
+            },
+        }))
+
+        import cli
+        monkeypatch.setattr(cli, "_hermes_home", hermes_home)
+        cfg = cli.load_cli_config()
+
+        assert cfg["model"]["provider"] == "openrouter"
+
+    def test_root_provider_ignored_when_default_model_provider_exists(self, tmp_path, monkeypatch):
+        """Even when model.provider is the default 'auto', root-level provider is ignored."""
+        import yaml
+
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        config_path = hermes_home / "config.yaml"
+        config_path.write_text(yaml.safe_dump({
+            "provider": "opencode-go",  # stale root key
+            "model": {
+                "default": "google/gemini-3-flash-preview",
+                # no explicit model.provider — defaults provide "auto"
+            },
+        }))
+
+        import cli
+        monkeypatch.setattr(cli, "_hermes_home", hermes_home)
+        cfg = cli.load_cli_config()
+
+        # Root-level "opencode-go" must NOT leak through
+        assert cfg["model"]["provider"] != "opencode-go"
+
+    def test_normalize_root_model_keys_moves_to_model(self):
+        """_normalize_root_model_keys migrates root keys into model section."""
+        from hermes_cli.config import _normalize_root_model_keys
+
+        config = {
+            "provider": "opencode-go",
+            "base_url": "https://example.com/v1",
+            "model": {
+                "default": "some-model",
+            },
+        }
+        result = _normalize_root_model_keys(config)
+        # Root keys removed
+        assert "provider" not in result
+        assert "base_url" not in result
+        # Migrated into model section
+        assert result["model"]["provider"] == "opencode-go"
+        assert result["model"]["base_url"] == "https://example.com/v1"
+
+    def test_normalize_root_model_keys_does_not_override_existing(self):
+        """Existing model.provider is never overridden by root-level key."""
+        from hermes_cli.config import _normalize_root_model_keys
+
+        config = {
+            "provider": "stale-provider",
+            "model": {
+                "default": "some-model",
+                "provider": "correct-provider",
+            },
+        }
+        result = _normalize_root_model_keys(config)
+        assert result["model"]["provider"] == "correct-provider"
+        assert "provider" not in result  # root key still cleaned up
+
+
+class TestProviderResolution:
+    def test_api_key_is_string_or_none(self):
+        cli = _make_cli()
+        assert cli.api_key is None or isinstance(cli.api_key, str)
+
+    def test_base_url_is_string(self):
+        cli = _make_cli()
+        assert isinstance(cli.base_url, str)
+        assert cli.base_url.startswith("http")
+
+    def test_model_is_string(self):
+        cli = _make_cli()
+        assert isinstance(cli.model, str)
+        assert isinstance(cli.model, str) and '/' in cli.model

tests/cli/test_cli_interrupt_subagent.py

@@ -0,0 +1,172 @@
+"""End-to-end test simulating CLI interrupt during subagent execution.
+
+Reproduces the exact scenario:
+1. Parent agent calls delegate_task
+2. Child agent is running (simulated with a slow tool)
+3. User "types a message" (simulated by calling parent.interrupt from another thread)
+4. Child should detect the interrupt and stop
+
+This tests the COMPLETE path including _run_single_child, _active_children
+registration, interrupt propagation, and child detection.
+"""
+
+import json
+import os
+import queue
+import threading
+import time
+import unittest
+from unittest.mock import MagicMock, patch, PropertyMock
+
+from tools.interrupt import set_interrupt, is_interrupted
+
+
+class TestCLISubagentInterrupt(unittest.TestCase):
+    """Simulate exact CLI scenario."""
+
+    def setUp(self):
+        set_interrupt(False)
+
+    def tearDown(self):
+        set_interrupt(False)
+
+    def test_full_delegate_interrupt_flow(self):
+        """Full integration: parent runs delegate_task, main thread interrupts."""
+        from run_agent import AIAgent
+
+        interrupt_detected = threading.Event()
+        child_started = threading.Event()
+        child_api_call_count = 0
+
+        # Create a real-enough parent agent
+        parent = AIAgent.__new__(AIAgent)
+        parent._interrupt_requested = False
+        parent._interrupt_message = None
+        parent._active_children = []
+        parent._active_children_lock = threading.Lock()
+        parent.quiet_mode = True
+        parent.model = "test/model"
+        parent.base_url = "http://localhost:1"
+        parent.api_key = "test"
+        parent.provider = "test"
+        parent.api_mode = "chat_completions"
+        parent.platform = "cli"
+        parent.enabled_toolsets = ["terminal", "file"]
+        parent.providers_allowed = None
+        parent.providers_ignored = None
+        parent.providers_order = None
+        parent.provider_sort = None
+        parent.max_tokens = None
+        parent.reasoning_config = None
+        parent.prefill_messages = None
+        parent._session_db = None
+        parent._delegate_depth = 0
+        parent._delegate_spinner = None
+        parent.tool_progress_callback = None
+
+        # We'll track what happens with _active_children
+        original_children = parent._active_children
+
+        # Mock the child's run_conversation to simulate a slow operation
+        # that checks _interrupt_requested like the real one does
+        def mock_child_run_conversation(user_message, **kwargs):
+            child_started.set()
+            # Find the child in parent._active_children
+            child = parent._active_children[-1] if parent._active_children else None
+            
+            # Simulate the agent loop: poll _interrupt_requested like run_conversation does
+            for i in range(100):  # Up to 10 seconds (100 * 0.1s)
+                if child and child._interrupt_requested:
+                    interrupt_detected.set()
+                    return {
+                        "final_response": "Interrupted!",
+                        "messages": [],
+                        "api_calls": 1,
+                        "completed": False,
+                        "interrupted": True,
+                        "interrupt_message": child._interrupt_message,
+                    }
+                time.sleep(0.1)
+            
+            return {
+                "final_response": "Finished without interrupt",
+                "messages": [],
+                "api_calls": 5,
+                "completed": True,
+                "interrupted": False,
+            }
+
+        # Patch AIAgent to use our mock
+        from tools.delegate_tool import _run_single_child
+        from run_agent import IterationBudget
+
+        parent.iteration_budget = IterationBudget(max_total=100)
+
+        # Run delegate in a thread (simulates agent_thread)
+        delegate_result = [None]
+        delegate_error = [None]
+
+        def run_delegate():
+            try:
+                with patch('run_agent.AIAgent') as MockAgent:
+                    mock_instance = MagicMock()
+                    mock_instance._interrupt_requested = False
+                    mock_instance._interrupt_message = None
+                    mock_instance._active_children = []
+                    mock_instance._active_children_lock = threading.Lock()
+                    mock_instance.quiet_mode = True
+                    mock_instance.run_conversation = mock_child_run_conversation
+                    mock_instance.interrupt = lambda msg=None: setattr(mock_instance, '_interrupt_requested', True) or setattr(mock_instance, '_interrupt_message', msg)
+                    mock_instance.tools = []
+                    MockAgent.return_value = mock_instance
+
+                    # Register child manually (normally done by _build_child_agent)
+                    parent._active_children.append(mock_instance)
+
+                    result = _run_single_child(
+                        task_index=0,
+                        goal="Do something slow",
+                        child=mock_instance,
+                        parent_agent=parent,
+                    )
+                    delegate_result[0] = result
+            except Exception as e:
+                delegate_error[0] = e
+
+        agent_thread = threading.Thread(target=run_delegate, daemon=True)
+        agent_thread.start()
+
+        # Wait for child to start
+        assert child_started.wait(timeout=5), "Child never started!"
+
+        # Now simulate user interrupt (from main/process thread)
+        time.sleep(0.2)  # Give child a moment to be in its loop
+        
+        print(f"Parent has {len(parent._active_children)} active children")
+        assert len(parent._active_children) >= 1, f"Expected child in _active_children, got {len(parent._active_children)}"
+
+        # This is what the CLI does:
+        parent.interrupt("Hey stop that")
+        
+        print(f"Parent._interrupt_requested: {parent._interrupt_requested}")
+        for i, child in enumerate(parent._active_children):
+            print(f"Child {i}._interrupt_requested: {child._interrupt_requested}")
+
+        # Wait for child to detect interrupt
+        detected = interrupt_detected.wait(timeout=3.0)
+        
+        # Wait for delegate to finish
+        agent_thread.join(timeout=5)
+
+        if delegate_error[0]:
+            raise delegate_error[0]
+
+        assert detected, "Child never detected the interrupt!"
+        result = delegate_result[0]
+        assert result is not None, "Delegate returned no result"
+        assert result["status"] == "interrupted", f"Expected 'interrupted', got '{result['status']}'"
+        print(f"✓ Interrupt detected! Result: {result}")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/cli/test_cli_loading_indicator.py

@@ -0,0 +1,65 @@
+"""Regression tests for loading feedback on slow slash commands."""
+
+from unittest.mock import patch
+
+from cli import HermesCLI
+
+
+class TestCLILoadingIndicator:
+    def _make_cli(self):
+        cli_obj = HermesCLI.__new__(HermesCLI)
+        cli_obj._app = None
+        cli_obj._last_invalidate = 0.0
+        cli_obj._command_running = False
+        cli_obj._command_status = ""
+        return cli_obj
+
+    def test_skills_command_sets_busy_state_and_prints_status(self, capsys):
+        cli_obj = self._make_cli()
+        seen = {}
+
+        def fake_handle(cmd: str):
+            seen["cmd"] = cmd
+            seen["running"] = cli_obj._command_running
+            seen["status"] = cli_obj._command_status
+            print("skills done")
+
+        with patch.object(cli_obj, "_handle_skills_command", side_effect=fake_handle), \
+             patch.object(cli_obj, "_invalidate") as invalidate_mock:
+            assert cli_obj.process_command("/skills search kubernetes")
+
+        output = capsys.readouterr().out
+        assert "⏳ Searching skills..." in output
+        assert "skills done" in output
+        assert seen == {
+            "cmd": "/skills search kubernetes",
+            "running": True,
+            "status": "Searching skills...",
+        }
+        assert cli_obj._command_running is False
+        assert cli_obj._command_status == ""
+        assert invalidate_mock.call_count == 2
+
+    def test_reload_mcp_sets_busy_state_and_prints_status(self, capsys):
+        cli_obj = self._make_cli()
+        seen = {}
+
+        def fake_reload():
+            seen["running"] = cli_obj._command_running
+            seen["status"] = cli_obj._command_status
+            print("reload done")
+
+        with patch.object(cli_obj, "_reload_mcp", side_effect=fake_reload), \
+             patch.object(cli_obj, "_invalidate") as invalidate_mock:
+            assert cli_obj.process_command("/reload-mcp")
+
+        output = capsys.readouterr().out
+        assert "⏳ Reloading MCP servers..." in output
+        assert "reload done" in output
+        assert seen == {
+            "running": True,
+            "status": "Reloading MCP servers...",
+        }
+        assert cli_obj._command_running is False
+        assert cli_obj._command_status == ""
+        assert invalidate_mock.call_count == 2

tests/cli/test_cli_mcp_config_watch.py

@@ -0,0 +1,103 @@
+"""Tests for automatic MCP reload when config.yaml mcp_servers section changes."""
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+
+def _make_cli(tmp_path, mcp_servers=None):
+    """Create a minimal HermesCLI instance with mocked config."""
+    import cli as cli_mod
+    obj = object.__new__(cli_mod.HermesCLI)
+    obj.config = {"mcp_servers": mcp_servers or {}}
+    obj._agent_running = False
+    obj._last_config_check = 0.0
+    obj._config_mcp_servers = mcp_servers or {}
+
+    cfg_file = tmp_path / "config.yaml"
+    cfg_file.write_text("mcp_servers: {}\n")
+    obj._config_mtime = cfg_file.stat().st_mtime
+
+    obj._reload_mcp = MagicMock()
+    obj._busy_command = MagicMock()
+    obj._busy_command.return_value.__enter__ = MagicMock(return_value=None)
+    obj._busy_command.return_value.__exit__ = MagicMock(return_value=False)
+    obj._slow_command_status = MagicMock(return_value="reloading...")
+
+    return obj, cfg_file
+
+
+class TestMCPConfigWatch:
+
+    def test_no_change_does_not_reload(self, tmp_path):
+        """If mtime and mcp_servers unchanged, _reload_mcp is NOT called."""
+        obj, cfg_file = _make_cli(tmp_path)
+
+        with patch("hermes_cli.config.get_config_path", return_value=cfg_file):
+            obj._check_config_mcp_changes()
+
+        obj._reload_mcp.assert_not_called()
+
+    def test_mtime_change_with_same_mcp_servers_does_not_reload(self, tmp_path):
+        """If file mtime changes but mcp_servers is identical, no reload."""
+        import yaml
+        obj, cfg_file = _make_cli(tmp_path, mcp_servers={"fs": {"command": "npx"}})
+
+        # Write same mcp_servers but touch the file
+        cfg_file.write_text(yaml.dump({"mcp_servers": {"fs": {"command": "npx"}}}))
+        # Force mtime to appear changed
+        obj._config_mtime = 0.0
+
+        with patch("hermes_cli.config.get_config_path", return_value=cfg_file):
+            obj._check_config_mcp_changes()
+
+        obj._reload_mcp.assert_not_called()
+
+    def test_new_mcp_server_triggers_reload(self, tmp_path):
+        """Adding a new MCP server to config triggers auto-reload."""
+        import yaml
+        obj, cfg_file = _make_cli(tmp_path, mcp_servers={})
+
+        # Simulate user adding a new MCP server to config.yaml
+        cfg_file.write_text(yaml.dump({"mcp_servers": {"github": {"url": "https://mcp.github.com"}}}))
+        obj._config_mtime = 0.0  # force stale mtime
+
+        with patch("hermes_cli.config.get_config_path", return_value=cfg_file):
+            obj._check_config_mcp_changes()
+
+        obj._reload_mcp.assert_called_once()
+
+    def test_removed_mcp_server_triggers_reload(self, tmp_path):
+        """Removing an MCP server from config triggers auto-reload."""
+        import yaml
+        obj, cfg_file = _make_cli(tmp_path, mcp_servers={"github": {"url": "https://mcp.github.com"}})
+
+        # Simulate user removing the server
+        cfg_file.write_text(yaml.dump({"mcp_servers": {}}))
+        obj._config_mtime = 0.0
+
+        with patch("hermes_cli.config.get_config_path", return_value=cfg_file):
+            obj._check_config_mcp_changes()
+
+        obj._reload_mcp.assert_called_once()
+
+    def test_interval_throttle_skips_check(self, tmp_path):
+        """If called within CONFIG_WATCH_INTERVAL, stat() is skipped."""
+        obj, cfg_file = _make_cli(tmp_path)
+        obj._last_config_check = time.monotonic()  # just checked
+
+        with patch("hermes_cli.config.get_config_path", return_value=cfg_file), \
+             patch.object(Path, "stat") as mock_stat:
+            obj._check_config_mcp_changes()
+            mock_stat.assert_not_called()
+
+        obj._reload_mcp.assert_not_called()
+
+    def test_missing_config_file_does_not_crash(self, tmp_path):
+        """If config.yaml doesn't exist, _check_config_mcp_changes is a no-op."""
+        obj, cfg_file = _make_cli(tmp_path)
+        missing = tmp_path / "nonexistent.yaml"
+
+        with patch("hermes_cli.config.get_config_path", return_value=missing):
+            obj._check_config_mcp_changes()  # should not raise
+
+        obj._reload_mcp.assert_not_called()

tests/cli/test_cli_new_session.py

@@ -0,0 +1,222 @@
+"""Regression tests for CLI fresh-session commands."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from datetime import timedelta
+from unittest.mock import MagicMock, patch
+
+from hermes_state import SessionDB
+from tools.todo_tool import TodoStore
+
+
+class _FakeCompressor:
+    """Minimal stand-in for ContextCompressor."""
+
+    def __init__(self):
+        self.last_prompt_tokens = 500
+        self.last_completion_tokens = 200
+        self.last_total_tokens = 700
+        self.compression_count = 3
+        self._context_probed = True
+
+
+class _FakeAgent:
+    def __init__(self, session_id: str, session_start):
+        self.session_id = session_id
+        self.session_start = session_start
+        self.model = "anthropic/claude-opus-4.6"
+        self._last_flushed_db_idx = 7
+        self._todo_store = TodoStore()
+        self._todo_store.write(
+            [{"id": "t1", "content": "unfinished task", "status": "in_progress"}]
+        )
+        self.flush_memories = MagicMock()
+        self._invalidate_system_prompt = MagicMock()
+
+        # Token counters (non-zero to verify reset)
+        self.session_total_tokens = 1000
+        self.session_input_tokens = 600
+        self.session_output_tokens = 400
+        self.session_prompt_tokens = 550
+        self.session_completion_tokens = 350
+        self.session_cache_read_tokens = 100
+        self.session_cache_write_tokens = 50
+        self.session_reasoning_tokens = 80
+        self.session_api_calls = 5
+        self.session_estimated_cost_usd = 0.42
+        self.session_cost_status = "estimated"
+        self.session_cost_source = "openrouter"
+        self.context_compressor = _FakeCompressor()
+
+    def reset_session_state(self):
+        """Mirror the real AIAgent.reset_session_state()."""
+        self.session_total_tokens = 0
+        self.session_input_tokens = 0
+        self.session_output_tokens = 0
+        self.session_prompt_tokens = 0
+        self.session_completion_tokens = 0
+        self.session_cache_read_tokens = 0
+        self.session_cache_write_tokens = 0
+        self.session_reasoning_tokens = 0
+        self.session_api_calls = 0
+        self.session_estimated_cost_usd = 0.0
+        self.session_cost_status = "unknown"
+        self.session_cost_source = "none"
+        if hasattr(self, "context_compressor") and self.context_compressor:
+            self.context_compressor.last_prompt_tokens = 0
+            self.context_compressor.last_completion_tokens = 0
+            self.context_compressor.last_total_tokens = 0
+            self.context_compressor.compression_count = 0
+            self.context_compressor._context_probed = False
+
+
+def _make_cli(env_overrides=None, config_overrides=None, **kwargs):
+    """Create a HermesCLI instance with minimal mocking."""
+    _clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+    if config_overrides:
+        _clean_config.update(config_overrides)
+    clean_env = {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}
+    if env_overrides:
+        clean_env.update(env_overrides)
+    prompt_toolkit_stubs = {
+        "prompt_toolkit": MagicMock(),
+        "prompt_toolkit.history": MagicMock(),
+        "prompt_toolkit.styles": MagicMock(),
+        "prompt_toolkit.patch_stdout": MagicMock(),
+        "prompt_toolkit.application": MagicMock(),
+        "prompt_toolkit.layout": MagicMock(),
+        "prompt_toolkit.layout.processors": MagicMock(),
+        "prompt_toolkit.filters": MagicMock(),
+        "prompt_toolkit.layout.dimension": MagicMock(),
+        "prompt_toolkit.layout.menus": MagicMock(),
+        "prompt_toolkit.widgets": MagicMock(),
+        "prompt_toolkit.key_binding": MagicMock(),
+        "prompt_toolkit.completion": MagicMock(),
+        "prompt_toolkit.formatted_text": MagicMock(),
+        "prompt_toolkit.auto_suggest": MagicMock(),
+    }
+    with patch.dict(sys.modules, prompt_toolkit_stubs), patch.dict(
+        "os.environ", clean_env, clear=False
+    ):
+        import cli as _cli_mod
+
+        _cli_mod = importlib.reload(_cli_mod)
+        with patch.object(_cli_mod, "get_tool_definitions", return_value=[]), patch.dict(
+            _cli_mod.__dict__, {"CLI_CONFIG": _clean_config}
+        ):
+            return _cli_mod.HermesCLI(**kwargs)
+
+
+def _prepare_cli_with_active_session(tmp_path):
+    cli = _make_cli()
+    cli._session_db = SessionDB(db_path=tmp_path / "state.db")
+    cli._session_db.create_session(session_id=cli.session_id, source="cli", model=cli.model)
+
+    cli.agent = _FakeAgent(cli.session_id, cli.session_start)
+    cli.conversation_history = [{"role": "user", "content": "hello"}]
+
+    old_session_start = cli.session_start - timedelta(seconds=1)
+    cli.session_start = old_session_start
+    cli.agent.session_start = old_session_start
+    return cli
+
+
+def test_new_command_creates_real_fresh_session_and_resets_agent_state(tmp_path):
+    cli = _prepare_cli_with_active_session(tmp_path)
+    old_session_id = cli.session_id
+    old_session_start = cli.session_start
+
+    cli.process_command("/new")
+
+    assert cli.session_id != old_session_id
+
+    old_session = cli._session_db.get_session(old_session_id)
+    assert old_session is not None
+    assert old_session["end_reason"] == "new_session"
+
+    new_session = cli._session_db.get_session(cli.session_id)
+    assert new_session is not None
+
+    cli._session_db.append_message(cli.session_id, role="user", content="next turn")
+
+    assert cli.agent.session_id == cli.session_id
+    assert cli.agent._last_flushed_db_idx == 0
+    assert cli.agent._todo_store.read() == []
+    assert cli.session_start > old_session_start
+    assert cli.agent.session_start == cli.session_start
+    cli.agent.flush_memories.assert_called_once_with([{"role": "user", "content": "hello"}])
+    cli.agent._invalidate_system_prompt.assert_called_once()
+
+
+def test_reset_command_is_alias_for_new_session(tmp_path):
+    cli = _prepare_cli_with_active_session(tmp_path)
+    old_session_id = cli.session_id
+
+    cli.process_command("/reset")
+
+    assert cli.session_id != old_session_id
+    assert cli._session_db.get_session(old_session_id)["end_reason"] == "new_session"
+    assert cli._session_db.get_session(cli.session_id) is not None
+
+
+def test_clear_command_starts_new_session_before_redrawing(tmp_path):
+    cli = _prepare_cli_with_active_session(tmp_path)
+    cli.console = MagicMock()
+    cli.show_banner = MagicMock()
+
+    old_session_id = cli.session_id
+    cli.process_command("/clear")
+
+    assert cli.session_id != old_session_id
+    assert cli._session_db.get_session(old_session_id)["end_reason"] == "new_session"
+    assert cli._session_db.get_session(cli.session_id) is not None
+    cli.console.clear.assert_called_once()
+    cli.show_banner.assert_called_once()
+    assert cli.conversation_history == []
+
+
+def test_new_session_resets_token_counters(tmp_path):
+    """Regression test for #2099: /new must zero all token counters."""
+    cli = _prepare_cli_with_active_session(tmp_path)
+
+    # Verify counters are non-zero before reset
+    agent = cli.agent
+    assert agent.session_total_tokens > 0
+    assert agent.session_api_calls > 0
+    assert agent.context_compressor.compression_count > 0
+
+    cli.process_command("/new")
+
+    # All agent token counters must be zero
+    assert agent.session_total_tokens == 0
+    assert agent.session_input_tokens == 0
+    assert agent.session_output_tokens == 0
+    assert agent.session_prompt_tokens == 0
+    assert agent.session_completion_tokens == 0
+    assert agent.session_cache_read_tokens == 0
+    assert agent.session_cache_write_tokens == 0
+    assert agent.session_reasoning_tokens == 0
+    assert agent.session_api_calls == 0
+    assert agent.session_estimated_cost_usd == 0.0
+    assert agent.session_cost_status == "unknown"
+    assert agent.session_cost_source == "none"
+
+    # Context compressor counters must also be zero
+    comp = agent.context_compressor
+    assert comp.last_prompt_tokens == 0
+    assert comp.last_completion_tokens == 0
+    assert comp.last_total_tokens == 0
+    assert comp.compression_count == 0
+    assert comp._context_probed is False

tests/cli/test_cli_plan_command.py

@@ -0,0 +1,67 @@
+"""Tests for the /plan CLI slash command."""
+
+from unittest.mock import MagicMock, patch
+
+from agent.skill_commands import scan_skill_commands
+from cli import HermesCLI
+
+
+def _make_cli():
+    cli_obj = HermesCLI.__new__(HermesCLI)
+    cli_obj.config = {}
+    cli_obj.console = MagicMock()
+    cli_obj.agent = None
+    cli_obj.conversation_history = []
+    cli_obj.session_id = "sess-123"
+    cli_obj._pending_input = MagicMock()
+    return cli_obj
+
+
+def _make_plan_skill(skills_dir):
+    skill_dir = skills_dir / "plan"
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        """---
+name: plan
+description: Plan mode skill.
+---
+
+# Plan
+
+Use the current conversation context when no explicit instruction is provided.
+Save plans under the active workspace's .hermes/plans directory.
+"""
+    )
+
+
+class TestCLIPlanCommand:
+    def test_plan_command_queues_plan_skill_message(self, tmp_path, monkeypatch):
+        cli_obj = _make_cli()
+
+        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
+            _make_plan_skill(tmp_path)
+            scan_skill_commands()
+            result = cli_obj.process_command("/plan Add OAuth login")
+
+        assert result is True
+        cli_obj._pending_input.put.assert_called_once()
+        queued = cli_obj._pending_input.put.call_args[0][0]
+        assert "Plan mode skill" in queued
+        assert "Add OAuth login" in queued
+        assert ".hermes/plans" in queued
+        assert str(tmp_path / "plans") not in queued
+        assert "active workspace/backend cwd" in queued
+        assert "Runtime note:" in queued
+
+    def test_plan_without_args_uses_skill_context_guidance(self, tmp_path, monkeypatch):
+        cli_obj = _make_cli()
+
+        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
+            _make_plan_skill(tmp_path)
+            scan_skill_commands()
+            cli_obj.process_command("/plan")
+
+        queued = cli_obj._pending_input.put.call_args[0][0]
+        assert "current conversation context" in queued
+        assert ".hermes/plans/" in queued
+        assert "conversation-plan.md" in queued

tests/cli/test_cli_prefix_matching.py

@@ -0,0 +1,160 @@
+"""Tests for slash command prefix matching in HermesCLI.process_command."""
+from unittest.mock import MagicMock, patch
+from cli import HermesCLI
+
+
+def _make_cli():
+    cli_obj = HermesCLI.__new__(HermesCLI)
+    cli_obj.config = {}
+    cli_obj.console = MagicMock()
+    cli_obj.agent = None
+    cli_obj.conversation_history = []
+    cli_obj.session_id = None
+    cli_obj._pending_input = MagicMock()
+    return cli_obj
+
+
+class TestSlashCommandPrefixMatching:
+    def test_unique_prefix_dispatches_command(self):
+        """/con should dispatch to /config when it uniquely matches."""
+        cli_obj = _make_cli()
+        with patch.object(cli_obj, 'show_config') as mock_config:
+            cli_obj.process_command("/con")
+        mock_config.assert_called_once()
+
+    def test_unique_prefix_with_args_does_not_recurse(self):
+        """/con set key value should expand to /config set key value without infinite recursion."""
+        cli_obj = _make_cli()
+        dispatched = []
+
+        original = cli_obj.process_command.__func__
+
+        def counting_process_command(self_inner, cmd):
+            dispatched.append(cmd)
+            if len(dispatched) > 5:
+                raise RecursionError("process_command called too many times")
+            return original(self_inner, cmd)
+
+        # Mock show_config since the test is about recursion, not config display
+        with patch.object(type(cli_obj), 'process_command', counting_process_command), \
+             patch.object(cli_obj, 'show_config'):
+            try:
+                cli_obj.process_command("/con set key value")
+            except RecursionError:
+                assert False, "process_command recursed infinitely"
+
+        # Should have been called at most twice: once for /con set..., once for /config set...
+        assert len(dispatched) <= 2
+
+    def test_exact_command_with_args_does_not_recurse(self):
+        """/config set key value hits exact branch and does not loop back to prefix."""
+        cli_obj = _make_cli()
+        call_count = [0]
+
+        original_pc = HermesCLI.process_command
+
+        def guarded(self_inner, cmd):
+            call_count[0] += 1
+            if call_count[0] > 10:
+                raise RecursionError("Infinite recursion detected")
+            return original_pc(self_inner, cmd)
+
+        # Mock show_config since the test is about recursion, not config display
+        with patch.object(HermesCLI, 'process_command', guarded), \
+             patch.object(cli_obj, 'show_config'):
+            try:
+                cli_obj.process_command("/config set key value")
+            except RecursionError:
+                assert False, "Recursed infinitely on /config set key value"
+
+        assert call_count[0] <= 3
+
+    def test_ambiguous_prefix_shows_suggestions(self):
+        """/re matches multiple commands — should show ambiguous message."""
+        cli_obj = _make_cli()
+        with patch("cli._cprint") as mock_cprint:
+            cli_obj.process_command("/re")
+            printed = " ".join(str(c) for c in mock_cprint.call_args_list)
+        assert "Ambiguous" in printed or "Did you mean" in printed
+
+    def test_unknown_command_shows_error(self):
+        """/xyz should show unknown command error."""
+        cli_obj = _make_cli()
+        with patch("cli._cprint") as mock_cprint:
+            cli_obj.process_command("/xyz")
+            printed = " ".join(str(c) for c in mock_cprint.call_args_list)
+        assert "Unknown command" in printed
+
+    def test_exact_command_still_works(self):
+        """/help should still work as exact match."""
+        cli_obj = _make_cli()
+        with patch.object(cli_obj, 'show_help') as mock_help:
+            cli_obj.process_command("/help")
+        mock_help.assert_called_once()
+
+    def test_skill_command_prefix_matches(self):
+        """A prefix that uniquely matches a skill command should dispatch it."""
+        cli_obj = _make_cli()
+        fake_skill = {"/test-skill-xyz": {"name": "Test Skill", "description": "test"}}
+        printed = []
+        cli_obj.console.print = lambda *a, **kw: printed.append(str(a))
+
+        import cli as cli_mod
+        with patch.object(cli_mod, '_skill_commands', fake_skill):
+            cli_obj.process_command("/test-skill-xy")
+
+        # Should NOT show "Unknown command" — should have dispatched or attempted skill
+        unknown = any("Unknown command" in p for p in printed)
+        assert not unknown, f"Expected skill prefix to match, got: {printed}"
+
+    def test_ambiguous_between_builtin_and_skill(self):
+        """Ambiguous prefix spanning builtin + skill commands shows suggestions."""
+        cli_obj = _make_cli()
+        # /help-extra is a fake skill that shares /hel prefix with /help
+        fake_skill = {"/help-extra": {"name": "Help Extra", "description": "test"}}
+
+        import cli as cli_mod
+        with patch.object(cli_mod, '_skill_commands', fake_skill),              patch.object(cli_obj, 'show_help') as mock_help:
+            cli_obj.process_command("/help")
+
+        # /help is an exact match so should work normally, not show ambiguous
+        mock_help.assert_called_once()
+        printed = " ".join(str(c) for c in cli_obj.console.print.call_args_list)
+        assert "Ambiguous" not in printed
+
+    def test_shortest_match_preferred_over_longer_skill(self):
+        """/qui should dispatch to /quit (5 chars) not report ambiguous with /quint-pipeline (15 chars)."""
+        cli_obj = _make_cli()
+        fake_skill = {"/quint-pipeline": {"name": "Quint Pipeline", "description": "test"}}
+
+        import cli as cli_mod
+        with patch.object(cli_mod, '_skill_commands', fake_skill):
+            # /quit is caught by the exact "/quit" branch → process_command returns False
+            result = cli_obj.process_command("/qui")
+
+        # Returns False because /quit was dispatched (exits chat loop)
+        assert result is False
+        printed = " ".join(str(c) for c in cli_obj.console.print.call_args_list)
+        assert "Ambiguous" not in printed
+
+    def test_tied_shortest_matches_still_ambiguous(self):
+        """/re matches /reset and /retry (both 6 chars) — no unique shortest, stays ambiguous."""
+        cli_obj = _make_cli()
+        printed = []
+        import cli as cli_mod
+        with patch.object(cli_mod, '_cprint', side_effect=lambda t: printed.append(t)):
+            cli_obj.process_command("/re")
+        combined = " ".join(printed)
+        assert "Ambiguous" in combined or "Did you mean" in combined
+
+    def test_exact_typed_name_dispatches_over_longer_match(self):
+        """/help typed with /help-extra skill installed → exact match wins."""
+        cli_obj = _make_cli()
+        fake_skill = {"/help-extra": {"name": "Help Extra", "description": ""}}
+        import cli as cli_mod
+        with patch.object(cli_mod, '_skill_commands', fake_skill), \
+             patch.object(cli_obj, 'show_help') as mock_help:
+            cli_obj.process_command("/help")
+        mock_help.assert_called_once()
+        printed = " ".join(str(c) for c in cli_obj.console.print.call_args_list)
+        assert "Ambiguous" not in printed

tests/cli/test_cli_preloaded_skills.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _make_real_cli(**kwargs):
+    clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+    clean_env = {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}
+    prompt_toolkit_stubs = {
+        "prompt_toolkit": MagicMock(),
+        "prompt_toolkit.history": MagicMock(),
+        "prompt_toolkit.styles": MagicMock(),
+        "prompt_toolkit.patch_stdout": MagicMock(),
+        "prompt_toolkit.application": MagicMock(),
+        "prompt_toolkit.layout": MagicMock(),
+        "prompt_toolkit.layout.processors": MagicMock(),
+        "prompt_toolkit.filters": MagicMock(),
+        "prompt_toolkit.layout.dimension": MagicMock(),
+        "prompt_toolkit.layout.menus": MagicMock(),
+        "prompt_toolkit.widgets": MagicMock(),
+        "prompt_toolkit.key_binding": MagicMock(),
+        "prompt_toolkit.completion": MagicMock(),
+        "prompt_toolkit.formatted_text": MagicMock(),
+    }
+    with patch.dict(sys.modules, prompt_toolkit_stubs), patch.dict(
+        "os.environ", clean_env, clear=False
+    ):
+        import cli as cli_mod
+
+        cli_mod = importlib.reload(cli_mod)
+        with patch.object(cli_mod, "get_tool_definitions", return_value=[]), patch.dict(
+            cli_mod.__dict__, {"CLI_CONFIG": clean_config}
+        ):
+            return cli_mod.HermesCLI(**kwargs)
+
+
+class _DummyCLI:
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+        self.session_id = "session-123"
+        self.system_prompt = "base prompt"
+        self.preloaded_skills = []
+
+    def show_banner(self):
+        return None
+
+    def show_tools(self):
+        return None
+
+    def show_toolsets(self):
+        return None
+
+    def run(self):
+        return None
+
+
+def test_main_applies_preloaded_skills_to_system_prompt(monkeypatch):
+    import cli as cli_mod
+
+    created = {}
+
+    def fake_cli(**kwargs):
+        created["cli"] = _DummyCLI(**kwargs)
+        return created["cli"]
+
+    monkeypatch.setattr(cli_mod, "HermesCLI", fake_cli)
+    monkeypatch.setattr(
+        cli_mod,
+        "build_preloaded_skills_prompt",
+        lambda skills, task_id=None: ("skill prompt", ["hermes-agent-dev", "github-auth"], []),
+    )
+
+    with pytest.raises(SystemExit):
+        cli_mod.main(skills="hermes-agent-dev,github-auth", list_tools=True)
+
+    cli_obj = created["cli"]
+    assert cli_obj.system_prompt == "base prompt\n\nskill prompt"
+    assert cli_obj.preloaded_skills == ["hermes-agent-dev", "github-auth"]
+
+
+def test_main_raises_for_unknown_preloaded_skill(monkeypatch):
+    import cli as cli_mod
+
+    monkeypatch.setattr(cli_mod, "HermesCLI", lambda **kwargs: _DummyCLI(**kwargs))
+    monkeypatch.setattr(
+        cli_mod,
+        "build_preloaded_skills_prompt",
+        lambda skills, task_id=None: ("", [], ["missing-skill"]),
+    )
+
+    with pytest.raises(ValueError, match=r"Unknown skill\(s\): missing-skill"):
+        cli_mod.main(skills="missing-skill", list_tools=True)
+
+
+def test_show_banner_does_not_print_skills():
+    """show_banner() no longer prints the activated skills line — it moved to run()."""
+    cli_obj = _make_real_cli(compact=False)
+    cli_obj.preloaded_skills = ["hermes-agent-dev", "github-auth"]
+    cli_obj.console = MagicMock()
+
+    with patch("cli.build_welcome_banner") as mock_banner, patch(
+        "shutil.get_terminal_size", return_value=os.terminal_size((120, 40))
+    ):
+        cli_obj.show_banner()
+
+    print_calls = [
+        call.args[0]
+        for call in cli_obj.console.print.call_args_list
+        if call.args and isinstance(call.args[0], str)
+    ]
+    startup_lines = [line for line in print_calls if "Activated skills:" in line]
+    assert len(startup_lines) == 0
+    assert mock_banner.call_count == 1

tests/cli/test_cli_provider_resolution.py

@@ -0,0 +1,643 @@
+import importlib
+import sys
+import types
+from contextlib import nullcontext
+from types import SimpleNamespace
+
+import pytest
+
+from hermes_cli.auth import AuthError
+from hermes_cli import main as hermes_main
+
+
+# ---------------------------------------------------------------------------
+# Module isolation: _import_cli() wipes tools.* / cli / run_agent from
+# sys.modules so it can re-import cli fresh.  Without cleanup the wiped
+# modules leak into subsequent tests on the same xdist worker, breaking
+# mock patches that target "tools.file_tools._get_file_ops" etc.
+# ---------------------------------------------------------------------------
+
+def _reset_modules(prefixes: tuple[str, ...]):
+    for name in list(sys.modules):
+        if any(name == p or name.startswith(p + ".") for p in prefixes):
+            sys.modules.pop(name, None)
+
+
+@pytest.fixture(autouse=True)
+def _restore_cli_and_tool_modules():
+    """Save and restore tools/cli/run_agent modules around every test."""
+    prefixes = ("tools", "cli", "run_agent")
+    original_modules = {
+        name: module
+        for name, module in sys.modules.items()
+        if any(name == p or name.startswith(p + ".") for p in prefixes)
+    }
+    try:
+        yield
+    finally:
+        _reset_modules(prefixes)
+        sys.modules.update(original_modules)
+
+
+def _install_prompt_toolkit_stubs():
+    class _Dummy:
+        def __init__(self, *args, **kwargs):
+            pass
+
+    class _Condition:
+        def __init__(self, func):
+            self.func = func
+
+        def __bool__(self):
+            return bool(self.func())
+
+    class _ANSI(str):
+        pass
+
+    root = types.ModuleType("prompt_toolkit")
+    history = types.ModuleType("prompt_toolkit.history")
+    styles = types.ModuleType("prompt_toolkit.styles")
+    patch_stdout = types.ModuleType("prompt_toolkit.patch_stdout")
+    application = types.ModuleType("prompt_toolkit.application")
+    layout = types.ModuleType("prompt_toolkit.layout")
+    processors = types.ModuleType("prompt_toolkit.layout.processors")
+    filters = types.ModuleType("prompt_toolkit.filters")
+    dimension = types.ModuleType("prompt_toolkit.layout.dimension")
+    menus = types.ModuleType("prompt_toolkit.layout.menus")
+    widgets = types.ModuleType("prompt_toolkit.widgets")
+    key_binding = types.ModuleType("prompt_toolkit.key_binding")
+    completion = types.ModuleType("prompt_toolkit.completion")
+    formatted_text = types.ModuleType("prompt_toolkit.formatted_text")
+
+    history.FileHistory = _Dummy
+    styles.Style = _Dummy
+    patch_stdout.patch_stdout = lambda *args, **kwargs: nullcontext()
+    application.Application = _Dummy
+    layout.Layout = _Dummy
+    layout.HSplit = _Dummy
+    layout.Window = _Dummy
+    layout.FormattedTextControl = _Dummy
+    layout.ConditionalContainer = _Dummy
+    processors.Processor = _Dummy
+    processors.Transformation = _Dummy
+    processors.PasswordProcessor = _Dummy
+    processors.ConditionalProcessor = _Dummy
+    filters.Condition = _Condition
+    dimension.Dimension = _Dummy
+    menus.CompletionsMenu = _Dummy
+    widgets.TextArea = _Dummy
+    key_binding.KeyBindings = _Dummy
+    completion.Completer = _Dummy
+    completion.Completion = _Dummy
+    formatted_text.ANSI = _ANSI
+    root.print_formatted_text = lambda *args, **kwargs: None
+
+    sys.modules.setdefault("prompt_toolkit", root)
+    sys.modules.setdefault("prompt_toolkit.history", history)
+    sys.modules.setdefault("prompt_toolkit.styles", styles)
+    sys.modules.setdefault("prompt_toolkit.patch_stdout", patch_stdout)
+    sys.modules.setdefault("prompt_toolkit.application", application)
+    sys.modules.setdefault("prompt_toolkit.layout", layout)
+    sys.modules.setdefault("prompt_toolkit.layout.processors", processors)
+    sys.modules.setdefault("prompt_toolkit.filters", filters)
+    sys.modules.setdefault("prompt_toolkit.layout.dimension", dimension)
+    sys.modules.setdefault("prompt_toolkit.layout.menus", menus)
+    sys.modules.setdefault("prompt_toolkit.widgets", widgets)
+    sys.modules.setdefault("prompt_toolkit.key_binding", key_binding)
+    sys.modules.setdefault("prompt_toolkit.completion", completion)
+    sys.modules.setdefault("prompt_toolkit.formatted_text", formatted_text)
+
+
+def _import_cli():
+    for name in list(sys.modules):
+        if name == "cli" or name == "run_agent" or name == "tools" or name.startswith("tools."):
+            sys.modules.pop(name, None)
+
+    if "firecrawl" not in sys.modules:
+        sys.modules["firecrawl"] = types.SimpleNamespace(Firecrawl=object)
+
+    try:
+        importlib.import_module("prompt_toolkit")
+    except ModuleNotFoundError:
+        _install_prompt_toolkit_stubs()
+    return importlib.import_module("cli")
+
+
+def test_hermes_cli_init_does_not_eagerly_resolve_runtime_provider(monkeypatch):
+    cli = _import_cli()
+    calls = {"count": 0}
+
+    def _unexpected_runtime_resolve(**kwargs):
+        calls["count"] += 1
+        raise AssertionError("resolve_runtime_provider should not be called in HermesCLI.__init__")
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _unexpected_runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+
+    shell = cli.HermesCLI(model="gpt-5", compact=True, max_turns=1)
+
+    assert shell is not None
+    assert calls["count"] == 0
+
+
+def test_runtime_resolution_failure_is_not_sticky(monkeypatch):
+    cli = _import_cli()
+    calls = {"count": 0}
+
+    def _runtime_resolve(**kwargs):
+        calls["count"] += 1
+        if calls["count"] == 1:
+            raise RuntimeError("temporary auth failure")
+        return {
+            "provider": "openrouter",
+            "api_mode": "chat_completions",
+            "base_url": "https://openrouter.ai/api/v1",
+            "api_key": "test-key",
+            "source": "env/config",
+        }
+
+    class _DummyAgent:
+        def __init__(self, *args, **kwargs):
+            self.kwargs = kwargs
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+    monkeypatch.setattr(cli, "AIAgent", _DummyAgent)
+
+    shell = cli.HermesCLI(model="gpt-5", compact=True, max_turns=1)
+
+    assert shell._init_agent() is False
+    assert shell._init_agent() is True
+    assert calls["count"] == 2
+    assert shell.agent is not None
+
+
+def test_runtime_resolution_rebuilds_agent_on_routing_change(monkeypatch):
+    cli = _import_cli()
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://same-endpoint.example/v1",
+            "api_key": "same-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+
+    shell = cli.HermesCLI(model="gpt-5", compact=True, max_turns=1)
+    shell.provider = "openrouter"
+    shell.api_mode = "chat_completions"
+    shell.base_url = "https://same-endpoint.example/v1"
+    shell.api_key = "same-key"
+    shell.agent = object()
+
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.agent is None
+    assert shell.provider == "openai-codex"
+    assert shell.api_mode == "codex_responses"
+
+
+def test_cli_turn_routing_uses_primary_when_disabled(monkeypatch):
+    cli = _import_cli()
+    shell = cli.HermesCLI(model="gpt-5", compact=True, max_turns=1)
+    shell.provider = "openrouter"
+    shell.api_mode = "chat_completions"
+    shell.base_url = "https://openrouter.ai/api/v1"
+    shell.api_key = "sk-primary"
+    shell._smart_model_routing = {"enabled": False}
+
+    result = shell._resolve_turn_agent_config("what time is it in tokyo?")
+
+    assert result["model"] == "gpt-5"
+    assert result["runtime"]["provider"] == "openrouter"
+    assert result["label"] is None
+
+
+def test_cli_turn_routing_uses_cheap_model_when_simple(monkeypatch):
+    cli = _import_cli()
+
+    def _runtime_resolve(**kwargs):
+        assert kwargs["requested"] == "zai"
+        return {
+            "provider": "zai",
+            "api_mode": "chat_completions",
+            "base_url": "https://open.z.ai/api/v1",
+            "api_key": "cheap-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+
+    shell = cli.HermesCLI(model="anthropic/claude-sonnet-4", compact=True, max_turns=1)
+    shell.provider = "openrouter"
+    shell.api_mode = "chat_completions"
+    shell.base_url = "https://openrouter.ai/api/v1"
+    shell.api_key = "primary-key"
+    shell._smart_model_routing = {
+        "enabled": True,
+        "cheap_model": {"provider": "zai", "model": "glm-5-air"},
+        "max_simple_chars": 160,
+        "max_simple_words": 28,
+    }
+
+    result = shell._resolve_turn_agent_config("what time is it in tokyo?")
+
+    assert result["model"] == "glm-5-air"
+    assert result["runtime"]["provider"] == "zai"
+    assert result["runtime"]["api_key"] == "cheap-key"
+    assert result["label"] is not None
+
+
+def test_cli_prefers_config_provider_over_stale_env_override(monkeypatch):
+    cli = _import_cli()
+
+    monkeypatch.setenv("HERMES_INFERENCE_PROVIDER", "openrouter")
+    config_copy = dict(cli.CLI_CONFIG)
+    model_copy = dict(config_copy.get("model", {}))
+    model_copy["provider"] = "custom"
+    model_copy["base_url"] = "https://api.fireworks.ai/inference/v1"
+    config_copy["model"] = model_copy
+    monkeypatch.setattr(cli, "CLI_CONFIG", config_copy)
+
+    shell = cli.HermesCLI(model="fireworks/minimax-m2p5", compact=True, max_turns=1)
+
+    assert shell.requested_provider == "custom"
+
+
+def test_codex_provider_replaces_incompatible_default_model(monkeypatch):
+    """When provider resolves to openai-codex and no model was explicitly
+    chosen, the global config default (e.g. anthropic/claude-opus-4.6) must
+    be replaced with a Codex-compatible model.  Fixes #651."""
+    cli = _import_cli()
+
+    monkeypatch.delenv("LLM_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+    # Ensure local user config does not leak a model into the test
+    monkeypatch.setitem(cli.CLI_CONFIG, "model", {
+        "default": "",
+        "base_url": "https://openrouter.ai/api/v1",
+    })
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+            "api_key": "test-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+    monkeypatch.setattr(
+        "hermes_cli.codex_models.get_codex_model_ids",
+        lambda access_token=None: ["gpt-5.2-codex", "gpt-5.1-codex-mini"],
+    )
+
+    shell = cli.HermesCLI(compact=True, max_turns=1)
+
+    assert shell._model_is_default is True
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.provider == "openai-codex"
+    assert "anthropic" not in shell.model
+    assert "claude" not in shell.model
+    assert shell.model == "gpt-5.2-codex"
+
+
+def test_model_flow_nous_prints_subscription_guidance_without_mutating_explicit_tts(monkeypatch, capsys):
+    monkeypatch.setenv("HERMES_ENABLE_NOUS_MANAGED_TOOLS", "1")
+    config = {
+        "model": {"provider": "nous", "default": "claude-opus-4-6"},
+        "tts": {"provider": "elevenlabs"},
+        "browser": {"cloud_provider": "browser-use"},
+    }
+
+    monkeypatch.setattr(
+        "hermes_cli.auth.get_provider_auth_state",
+        lambda provider: {"access_token": "nous-token"},
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.resolve_nous_runtime_credentials",
+        lambda *args, **kwargs: {
+            "base_url": "https://inference.example.com/v1",
+            "api_key": "nous-key",
+        },
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.fetch_nous_models",
+        lambda *args, **kwargs: ["claude-opus-4-6"],
+    )
+    monkeypatch.setattr("hermes_cli.auth._prompt_model_selection", lambda model_ids, current_model="", pricing=None, **kw: "claude-opus-4-6")
+    monkeypatch.setattr("hermes_cli.auth._save_model_choice", lambda model: None)
+    monkeypatch.setattr("hermes_cli.auth._update_config_for_provider", lambda provider, url: None)
+    monkeypatch.setattr(
+        "hermes_cli.nous_subscription.get_nous_subscription_explainer_lines",
+        lambda: ["Nous subscription enables managed web tools."],
+    )
+
+    hermes_main._model_flow_nous(config, current_model="claude-opus-4-6")
+
+    out = capsys.readouterr().out
+    assert "Nous subscription enables managed web tools." in out
+    assert config["tts"]["provider"] == "elevenlabs"
+    assert config["browser"]["cloud_provider"] == "browser-use"
+
+
+def test_model_flow_nous_applies_managed_tts_default_when_unconfigured(monkeypatch, capsys):
+    monkeypatch.setenv("HERMES_ENABLE_NOUS_MANAGED_TOOLS", "1")
+    config = {
+        "model": {"provider": "nous", "default": "claude-opus-4-6"},
+        "tts": {"provider": "edge"},
+    }
+
+    monkeypatch.setattr(
+        "hermes_cli.auth.get_provider_auth_state",
+        lambda provider: {"access_token": "nous-token"},
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.resolve_nous_runtime_credentials",
+        lambda *args, **kwargs: {
+            "base_url": "https://inference.example.com/v1",
+            "api_key": "nous-key",
+        },
+    )
+    monkeypatch.setattr(
+        "hermes_cli.auth.fetch_nous_models",
+        lambda *args, **kwargs: ["claude-opus-4-6"],
+    )
+    monkeypatch.setattr("hermes_cli.auth._prompt_model_selection", lambda model_ids, current_model="", pricing=None, **kw: "claude-opus-4-6")
+    monkeypatch.setattr("hermes_cli.auth._save_model_choice", lambda model: None)
+    monkeypatch.setattr("hermes_cli.auth._update_config_for_provider", lambda provider, url: None)
+    monkeypatch.setattr(
+        "hermes_cli.nous_subscription.get_nous_subscription_explainer_lines",
+        lambda: ["Nous subscription enables managed web tools."],
+    )
+
+    hermes_main._model_flow_nous(config, current_model="claude-opus-4-6")
+
+    out = capsys.readouterr().out
+    assert "Nous subscription enables managed web tools." in out
+    assert "OpenAI TTS via your Nous subscription" in out
+    assert config["tts"]["provider"] == "openai"
+
+
+def test_codex_provider_uses_config_model(monkeypatch):
+    """Model comes from config.yaml, not LLM_MODEL env var.
+    Config.yaml is the single source of truth to avoid multi-agent conflicts."""
+    cli = _import_cli()
+
+    # LLM_MODEL env var should be IGNORED (even if set)
+    monkeypatch.setenv("LLM_MODEL", "should-be-ignored")
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+
+    # Set model via config
+    monkeypatch.setitem(cli.CLI_CONFIG, "model", {
+        "default": "gpt-5.2-codex",
+        "provider": "openai-codex",
+        "base_url": "https://chatgpt.com/backend-api/codex",
+    })
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+            "api_key": "fake-codex-token",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+    # Prevent live API call from overriding the config model
+    monkeypatch.setattr(
+        "hermes_cli.codex_models.get_codex_model_ids",
+        lambda access_token=None: ["gpt-5.2-codex"],
+    )
+
+    shell = cli.HermesCLI(compact=True, max_turns=1)
+
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.provider == "openai-codex"
+    # Model from config (may be normalized by codex provider logic)
+    assert "codex" in shell.model.lower()
+    # LLM_MODEL env var is NOT used
+    assert shell.model != "should-be-ignored"
+
+
+def test_codex_config_model_not_replaced_by_normalization(monkeypatch):
+    """When the user sets model.default in config.yaml to a specific codex
+    model, _normalize_model_for_provider must NOT replace it with the latest
+    available model from the API.  Regression test for #1887."""
+    cli = _import_cli()
+
+    monkeypatch.delenv("LLM_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+
+    # User explicitly configured gpt-5.3-codex in config.yaml
+    monkeypatch.setitem(cli.CLI_CONFIG, "model", {
+        "default": "gpt-5.3-codex",
+        "provider": "openai-codex",
+        "base_url": "https://chatgpt.com/backend-api/codex",
+    })
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+            "api_key": "fake-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+    # API returns a DIFFERENT model than what the user configured
+    monkeypatch.setattr(
+        "hermes_cli.codex_models.get_codex_model_ids",
+        lambda access_token=None: ["gpt-5.4", "gpt-5.3-codex"],
+    )
+
+    shell = cli.HermesCLI(compact=True, max_turns=1)
+
+    # Config model is NOT the global default — user made a deliberate choice
+    assert shell._model_is_default is False
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.provider == "openai-codex"
+    # Model must stay as user configured, not replaced by gpt-5.4
+    assert shell.model == "gpt-5.3-codex"
+
+
+def test_codex_provider_preserves_explicit_codex_model(monkeypatch):
+    """If the user explicitly passes a Codex-compatible model, it must be
+    preserved even when the provider resolves to openai-codex."""
+    cli = _import_cli()
+
+    monkeypatch.delenv("LLM_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+            "api_key": "test-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+
+    shell = cli.HermesCLI(model="gpt-5.1-codex-mini", compact=True, max_turns=1)
+
+    assert shell._model_is_default is False
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.model == "gpt-5.1-codex-mini"
+
+
+def test_codex_provider_strips_provider_prefix_from_model(monkeypatch):
+    """openai/gpt-5.3-codex should become gpt-5.3-codex — the Codex
+    Responses API does not accept provider-prefixed model slugs."""
+    cli = _import_cli()
+
+    monkeypatch.delenv("LLM_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+
+    def _runtime_resolve(**kwargs):
+        return {
+            "provider": "openai-codex",
+            "api_mode": "codex_responses",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+            "api_key": "test-key",
+            "source": "env/config",
+        }
+
+    monkeypatch.setattr("hermes_cli.runtime_provider.resolve_runtime_provider", _runtime_resolve)
+    monkeypatch.setattr("hermes_cli.runtime_provider.format_runtime_provider_error", lambda exc: str(exc))
+
+    shell = cli.HermesCLI(model="openai/gpt-5.3-codex", compact=True, max_turns=1)
+
+    assert shell._ensure_runtime_credentials() is True
+    assert shell.model == "gpt-5.3-codex"
+
+
+def test_cmd_model_falls_back_to_auto_on_invalid_provider(monkeypatch, capsys):
+    monkeypatch.setattr(
+        "hermes_cli.config.load_config",
+        lambda: {"model": {"default": "gpt-5", "provider": "invalid-provider"}},
+    )
+    monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: None)
+    monkeypatch.setattr("hermes_cli.config.get_env_value", lambda key: "")
+    monkeypatch.setattr("hermes_cli.config.save_env_value", lambda key, value: None)
+
+    def _resolve_provider(requested, **kwargs):
+        if requested == "invalid-provider":
+            raise AuthError("Unknown provider 'invalid-provider'.", code="invalid_provider")
+        return "openrouter"
+
+    monkeypatch.setattr("hermes_cli.auth.resolve_provider", _resolve_provider)
+    monkeypatch.setattr(hermes_main, "_prompt_provider_choice", lambda choices, **kwargs: len(choices) - 1)
+    monkeypatch.setattr("sys.stdin", type("FakeTTY", (), {"isatty": lambda self: True})())
+
+    hermes_main.cmd_model(SimpleNamespace())
+    output = capsys.readouterr().out
+
+    assert "Warning:" in output
+    assert "falling back to auto provider detection" in output.lower()
+    assert "No change." in output
+
+
+def test_model_flow_custom_saves_verified_v1_base_url(monkeypatch, capsys):
+    monkeypatch.setattr(
+        "hermes_cli.config.get_env_value",
+        lambda key: "" if key in {"OPENAI_BASE_URL", "OPENAI_API_KEY"} else "",
+    )
+    saved_env = {}
+    monkeypatch.setattr("hermes_cli.config.save_env_value", lambda key, value: saved_env.__setitem__(key, value))
+    monkeypatch.setattr("hermes_cli.auth._save_model_choice", lambda model: saved_env.__setitem__("MODEL", model))
+    monkeypatch.setattr("hermes_cli.auth.deactivate_provider", lambda: None)
+    monkeypatch.setattr("hermes_cli.main._save_custom_provider", lambda *args, **kwargs: None)
+    monkeypatch.setattr(
+        "hermes_cli.models.probe_api_models",
+        lambda api_key, base_url: {
+            "models": ["llm"],
+            "probed_url": "http://localhost:8000/v1/models",
+            "resolved_base_url": "http://localhost:8000/v1",
+            "suggested_base_url": "http://localhost:8000/v1",
+            "used_fallback": True,
+        },
+    )
+    monkeypatch.setattr(
+        "hermes_cli.config.load_config",
+        lambda: {"model": {"default": "", "provider": "custom", "base_url": ""}},
+    )
+    monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: None)
+
+    # After the probe detects a single model ("llm"), the flow asks
+    # "Use this model? [Y/n]:" — confirm with Enter, then context length.
+    answers = iter(["http://localhost:8000", "local-key", "", ""])
+    monkeypatch.setattr("builtins.input", lambda _prompt="": next(answers))
+    monkeypatch.setattr("getpass.getpass", lambda _prompt="": next(answers))
+
+    hermes_main._model_flow_custom({})
+    output = capsys.readouterr().out
+
+    assert "Saving the working base URL instead" in output
+    assert "Detected model: llm" in output
+    # OPENAI_BASE_URL is no longer saved to .env — config.yaml is authoritative
+    assert "OPENAI_BASE_URL" not in saved_env
+    assert saved_env["MODEL"] == "llm"
+
+
+def test_cmd_model_forwards_nous_login_tls_options(monkeypatch):
+    monkeypatch.setattr(hermes_main, "_require_tty", lambda *a: None)
+    monkeypatch.setattr(
+        "hermes_cli.config.load_config",
+        lambda: {"model": {"default": "gpt-5", "provider": "nous"}},
+    )
+    monkeypatch.setattr("hermes_cli.config.save_config", lambda cfg: None)
+    monkeypatch.setattr("hermes_cli.config.get_env_value", lambda key: "")
+    monkeypatch.setattr("hermes_cli.config.save_env_value", lambda key, value: None)
+    monkeypatch.setattr("hermes_cli.auth.resolve_provider", lambda requested, **kwargs: "nous")
+    monkeypatch.setattr("hermes_cli.auth.get_provider_auth_state", lambda provider_id: None)
+    monkeypatch.setattr(hermes_main, "_prompt_provider_choice", lambda choices, **kwargs: 0)
+
+    captured = {}
+
+    def _fake_login(login_args, provider_config):
+        captured["portal_url"] = login_args.portal_url
+        captured["inference_url"] = login_args.inference_url
+        captured["client_id"] = login_args.client_id
+        captured["scope"] = login_args.scope
+        captured["no_browser"] = login_args.no_browser
+        captured["timeout"] = login_args.timeout
+        captured["ca_bundle"] = login_args.ca_bundle
+        captured["insecure"] = login_args.insecure
+
+    monkeypatch.setattr("hermes_cli.auth._login_nous", _fake_login)
+
+    hermes_main.cmd_model(
+        SimpleNamespace(
+            portal_url="https://portal.nousresearch.com",
+            inference_url="https://inference.nousresearch.com/v1",
+            client_id="hermes-local",
+            scope="openid profile",
+            no_browser=True,
+            timeout=7.5,
+            ca_bundle="/tmp/local-ca.pem",
+            insecure=True,
+        )
+    )
+
+    assert captured == {
+        "portal_url": "https://portal.nousresearch.com",
+        "inference_url": "https://inference.nousresearch.com/v1",
+        "client_id": "hermes-local",
+        "scope": "openid profile",
+        "no_browser": True,
+        "timeout": 7.5,
+        "ca_bundle": "/tmp/local-ca.pem",
+        "insecure": True,
+    }

tests/cli/test_cli_retry.py

@@ -0,0 +1,49 @@
+"""Regression tests for CLI /retry history replacement semantics."""
+
+from tests.cli.test_cli_init import _make_cli
+
+
+def test_retry_last_truncates_history_before_requeueing_message():
+    cli = _make_cli()
+    cli.conversation_history = [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "one"},
+        {"role": "user", "content": "retry me"},
+        {"role": "assistant", "content": "old answer"},
+    ]
+
+    retry_msg = cli.retry_last()
+
+    assert retry_msg == "retry me"
+    assert cli.conversation_history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "one"},
+    ]
+
+    cli.conversation_history.append({"role": "user", "content": retry_msg})
+    cli.conversation_history.append({"role": "assistant", "content": "new answer"})
+
+    assert [m["content"] for m in cli.conversation_history if m["role"] == "user"] == [
+        "first",
+        "retry me",
+    ]
+
+
+def test_process_command_retry_requeues_original_message_not_retry_command():
+    cli = _make_cli()
+    queued = []
+
+    class _Queue:
+        def put(self, value):
+            queued.append(value)
+
+    cli._pending_input = _Queue()
+    cli.conversation_history = [
+        {"role": "user", "content": "retry me"},
+        {"role": "assistant", "content": "old answer"},
+    ]
+
+    cli.process_command("/retry")
+
+    assert queued == ["retry me"]
+    assert cli.conversation_history == []

tests/cli/test_cli_save_config_value.py

@@ -0,0 +1,80 @@
+"""Tests for save_config_value() in cli.py — atomic write behavior."""
+
+import os
+import yaml
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+
+class TestSaveConfigValueAtomic:
+    """save_config_value() must use atomic_yaml_write to avoid data loss."""
+
+    @pytest.fixture
+    def config_env(self, tmp_path, monkeypatch):
+        """Isolated config environment with a writable config.yaml."""
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        config_path = hermes_home / "config.yaml"
+        config_path.write_text(yaml.dump({
+            "model": {"default": "test-model", "provider": "openrouter"},
+            "display": {"skin": "default"},
+        }))
+        monkeypatch.setattr("cli._hermes_home", hermes_home)
+        return config_path
+
+    def test_calls_atomic_yaml_write(self, config_env, monkeypatch):
+        """save_config_value must route through atomic_yaml_write, not bare open()."""
+        mock_atomic = MagicMock()
+        monkeypatch.setattr("utils.atomic_yaml_write", mock_atomic)
+
+        from cli import save_config_value
+        save_config_value("display.skin", "mono")
+
+        mock_atomic.assert_called_once()
+        written_path, written_data = mock_atomic.call_args[0]
+        assert Path(written_path) == config_env
+        assert written_data["display"]["skin"] == "mono"
+
+    def test_preserves_existing_keys(self, config_env):
+        """Writing a new key must not clobber existing config entries."""
+        from cli import save_config_value
+        save_config_value("agent.max_turns", 50)
+
+        result = yaml.safe_load(config_env.read_text())
+        assert result["model"]["default"] == "test-model"
+        assert result["model"]["provider"] == "openrouter"
+        assert result["display"]["skin"] == "default"
+        assert result["agent"]["max_turns"] == 50
+
+    def test_creates_nested_keys(self, config_env):
+        """Dot-separated paths create intermediate dicts as needed."""
+        from cli import save_config_value
+        save_config_value("compression.summary_model", "google/gemini-3-flash-preview")
+
+        result = yaml.safe_load(config_env.read_text())
+        assert result["compression"]["summary_model"] == "google/gemini-3-flash-preview"
+
+    def test_overwrites_existing_value(self, config_env):
+        """Updating an existing key replaces the value."""
+        from cli import save_config_value
+        save_config_value("display.skin", "ares")
+
+        result = yaml.safe_load(config_env.read_text())
+        assert result["display"]["skin"] == "ares"
+
+    def test_file_not_truncated_on_error(self, config_env, monkeypatch):
+        """If atomic_yaml_write raises, the original file is untouched."""
+        original_content = config_env.read_text()
+
+        def exploding_write(*args, **kwargs):
+            raise OSError("disk full")
+
+        monkeypatch.setattr("utils.atomic_yaml_write", exploding_write)
+
+        from cli import save_config_value
+        result = save_config_value("display.skin", "broken")
+
+        assert result is False
+        assert config_env.read_text() == original_content

tests/cli/test_cli_secret_capture.py

@@ -0,0 +1,147 @@
+import queue
+import threading
+import time
+from unittest.mock import patch
+
+import cli as cli_module
+import tools.skills_tool as skills_tool_module
+from cli import HermesCLI
+from hermes_cli.callbacks import prompt_for_secret
+from tools.skills_tool import set_secret_capture_callback
+
+
+class _FakeBuffer:
+    def __init__(self):
+        self.reset_called = False
+
+    def reset(self):
+        self.reset_called = True
+
+
+class _FakeApp:
+    def __init__(self):
+        self.invalidated = False
+        self.current_buffer = _FakeBuffer()
+
+    def invalidate(self):
+        self.invalidated = True
+
+
+def _make_cli_stub(with_app=False):
+    cli = HermesCLI.__new__(HermesCLI)
+    cli._app = _FakeApp() if with_app else None
+    cli._last_invalidate = 0.0
+    cli._secret_state = None
+    cli._secret_deadline = 0
+    return cli
+
+
+def test_secret_capture_callback_can_be_completed_from_cli_state_machine():
+    cli = _make_cli_stub(with_app=True)
+    results = []
+
+    with patch("hermes_cli.callbacks.save_env_value_secure") as save_secret:
+        save_secret.return_value = {
+            "success": True,
+            "stored_as": "TENOR_API_KEY",
+            "validated": False,
+        }
+
+        thread = threading.Thread(
+            target=lambda: results.append(
+                cli._secret_capture_callback("TENOR_API_KEY", "Tenor API key")
+            )
+        )
+        thread.start()
+
+        deadline = time.time() + 2
+        while cli._secret_state is None and time.time() < deadline:
+            time.sleep(0.01)
+
+        assert cli._secret_state is not None
+        cli._submit_secret_response("super-secret-value")
+        thread.join(timeout=2)
+
+    assert results[0]["success"] is True
+    assert results[0]["stored_as"] == "TENOR_API_KEY"
+    assert results[0]["skipped"] is False
+
+
+def test_cancel_secret_capture_marks_setup_skipped():
+    cli = _make_cli_stub()
+    cli._secret_state = {
+        "response_queue": queue.Queue(),
+        "var_name": "TENOR_API_KEY",
+        "prompt": "Tenor API key",
+        "metadata": {},
+    }
+    cli._secret_deadline = 123
+
+    cli._cancel_secret_capture()
+
+    assert cli._secret_state is None
+    assert cli._secret_deadline == 0
+
+
+def test_secret_capture_uses_getpass_without_tui():
+    cli = _make_cli_stub()
+
+    with patch("hermes_cli.callbacks.getpass.getpass", return_value="secret-value"), patch(
+        "hermes_cli.callbacks.save_env_value_secure"
+    ) as save_secret:
+        save_secret.return_value = {
+            "success": True,
+            "stored_as": "TENOR_API_KEY",
+            "validated": False,
+        }
+        result = prompt_for_secret(cli, "TENOR_API_KEY", "Tenor API key")
+
+    assert result["success"] is True
+    assert result["stored_as"] == "TENOR_API_KEY"
+    assert result["skipped"] is False
+
+
+def test_secret_capture_timeout_clears_hidden_input_buffer():
+    cli = _make_cli_stub(with_app=True)
+    cleared = {"value": False}
+
+    def clear_buffer():
+        cleared["value"] = True
+
+    cli._clear_secret_input_buffer = clear_buffer
+
+    with patch("hermes_cli.callbacks.queue.Queue.get", side_effect=queue.Empty), patch(
+        "hermes_cli.callbacks._time.monotonic",
+        side_effect=[0, 121],
+    ):
+        result = prompt_for_secret(cli, "TENOR_API_KEY", "Tenor API key")
+
+    assert result["success"] is True
+    assert result["skipped"] is True
+    assert result["reason"] == "timeout"
+    assert cleared["value"] is True
+
+
+def test_cli_chat_registers_secret_capture_callback():
+    clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+
+    with patch("cli.get_tool_definitions", return_value=[]), patch.dict(
+        "os.environ", {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}, clear=False
+    ), patch.dict(cli_module.__dict__, {"CLI_CONFIG": clean_config}):
+        cli_obj = HermesCLI()
+        with patch.object(cli_obj, "_ensure_runtime_credentials", return_value=False):
+            cli_obj.chat("hello")
+
+    try:
+        assert skills_tool_module._secret_capture_callback == cli_obj._secret_capture_callback
+    finally:
+        set_secret_capture_callback(None)

tests/cli/test_cli_skin_integration.py

@@ -0,0 +1,98 @@
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from cli import HermesCLI, _rich_text_from_ansi
+from hermes_cli.skin_engine import get_active_skin, set_active_skin
+
+
+def _make_cli_stub():
+    cli = HermesCLI.__new__(HermesCLI)
+    cli._sudo_state = None
+    cli._secret_state = None
+    cli._approval_state = None
+    cli._clarify_state = None
+    cli._clarify_freetext = False
+    cli._command_running = False
+    cli._agent_running = False
+    cli._voice_recording = False
+    cli._voice_processing = False
+    cli._voice_mode = False
+    cli._command_spinner_frame = lambda: "⟳"
+    cli._tui_style_base = {
+        "prompt": "#fff",
+        "input-area": "#fff",
+        "input-rule": "#aaa",
+        "prompt-working": "#888 italic",
+    }
+    cli._app = SimpleNamespace(style=None)
+    cli._invalidate = MagicMock()
+    return cli
+
+
+class TestCliSkinPromptIntegration:
+    def test_default_prompt_fragments_use_default_symbol(self):
+        cli = _make_cli_stub()
+
+        set_active_skin("default")
+        assert cli._get_tui_prompt_fragments() == [("class:prompt", "❯ ")]
+
+    def test_ares_prompt_fragments_use_skin_symbol(self):
+        cli = _make_cli_stub()
+
+        set_active_skin("ares")
+        assert cli._get_tui_prompt_fragments() == [("class:prompt", "⚔ ❯ ")]
+
+    def test_secret_prompt_fragments_preserve_secret_state(self):
+        cli = _make_cli_stub()
+        cli._secret_state = {"response_queue": object()}
+
+        set_active_skin("ares")
+        assert cli._get_tui_prompt_fragments() == [("class:sudo-prompt", "🔑 ❯ ")]
+
+    def test_icon_only_skin_symbol_still_visible_in_special_states(self):
+        cli = _make_cli_stub()
+        cli._secret_state = {"response_queue": object()}
+
+        with patch("hermes_cli.skin_engine.get_active_prompt_symbol", return_value="⚔ "):
+            assert cli._get_tui_prompt_fragments() == [("class:sudo-prompt", "🔑 ⚔ ")]
+
+    def test_build_tui_style_dict_uses_skin_overrides(self):
+        cli = _make_cli_stub()
+
+        set_active_skin("ares")
+        skin = get_active_skin()
+        style_dict = cli._build_tui_style_dict()
+
+        assert style_dict["prompt"] == skin.get_color("prompt")
+        assert style_dict["input-rule"] == skin.get_color("input_rule")
+        assert style_dict["prompt-working"] == f"{skin.get_color('banner_dim')} italic"
+        assert style_dict["approval-title"] == f"{skin.get_color('ui_warn')} bold"
+
+    def test_apply_tui_skin_style_updates_running_app(self):
+        cli = _make_cli_stub()
+
+        set_active_skin("ares")
+        assert cli._apply_tui_skin_style() is True
+        assert cli._app.style is not None
+        cli._invalidate.assert_called_once_with(min_interval=0.0)
+
+    def test_handle_skin_command_refreshes_live_tui(self, capsys):
+        cli = _make_cli_stub()
+
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_skin_command("/skin ares")
+
+        output = capsys.readouterr().out
+        assert "Skin set to: ares (saved)" in output
+        assert "Prompt + TUI colors updated." in output
+        assert cli._app.style is not None
+
+
+class TestAnsiRichTextHelper:
+    def test_preserves_literal_brackets(self):
+        text = _rich_text_from_ansi("[notatag] literal")
+        assert text.plain == "[notatag] literal"
+
+    def test_strips_ansi_but_keeps_plain_text(self):
+        text = _rich_text_from_ansi("\x1b[31mred\x1b[0m")
+        assert text.plain == "red"

tests/cli/test_cli_status_bar.py

@@ -0,0 +1,363 @@
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from cli import HermesCLI
+
+
+def _make_cli(model: str = "anthropic/claude-sonnet-4-20250514"):
+    cli_obj = HermesCLI.__new__(HermesCLI)
+    cli_obj.model = model
+    cli_obj.session_start = datetime.now() - timedelta(minutes=14, seconds=32)
+    cli_obj.conversation_history = [{"role": "user", "content": "hi"}]
+    cli_obj.agent = None
+    return cli_obj
+
+
+def _attach_agent(
+    cli_obj,
+    *,
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    cache_read_tokens: int = 0,
+    cache_write_tokens: int = 0,
+    prompt_tokens: int,
+    completion_tokens: int,
+    total_tokens: int,
+    api_calls: int,
+    context_tokens: int,
+    context_length: int,
+    compressions: int = 0,
+):
+    cli_obj.agent = SimpleNamespace(
+        model=cli_obj.model,
+        provider="anthropic" if cli_obj.model.startswith("anthropic/") else None,
+        base_url="",
+        session_input_tokens=input_tokens if input_tokens is not None else prompt_tokens,
+        session_output_tokens=output_tokens if output_tokens is not None else completion_tokens,
+        session_cache_read_tokens=cache_read_tokens,
+        session_cache_write_tokens=cache_write_tokens,
+        session_prompt_tokens=prompt_tokens,
+        session_completion_tokens=completion_tokens,
+        session_total_tokens=total_tokens,
+        session_api_calls=api_calls,
+        context_compressor=SimpleNamespace(
+            last_prompt_tokens=context_tokens,
+            context_length=context_length,
+            compression_count=compressions,
+        ),
+    )
+    return cli_obj
+
+
+class TestCLIStatusBar:
+    def test_context_style_thresholds(self):
+        cli_obj = _make_cli()
+
+        assert cli_obj._status_bar_context_style(None) == "class:status-bar-dim"
+        assert cli_obj._status_bar_context_style(10) == "class:status-bar-good"
+        assert cli_obj._status_bar_context_style(50) == "class:status-bar-warn"
+        assert cli_obj._status_bar_context_style(81) == "class:status-bar-bad"
+        assert cli_obj._status_bar_context_style(95) == "class:status-bar-critical"
+
+    def test_build_status_bar_text_for_wide_terminal(self):
+        cli_obj = _attach_agent(
+            _make_cli(),
+            prompt_tokens=10_230,
+            completion_tokens=2_220,
+            total_tokens=12_450,
+            api_calls=7,
+            context_tokens=12_450,
+            context_length=200_000,
+        )
+
+        text = cli_obj._build_status_bar_text(width=120)
+
+        assert "claude-sonnet-4-20250514" in text
+        assert "12.4K/200K" in text
+        assert "6%" in text
+        assert "$0.06" not in text  # cost hidden by default
+        assert "15m" in text
+
+    def test_input_height_counts_wide_characters_using_cell_width(self):
+        cli_obj = _make_cli()
+
+        class _Doc:
+            lines = ["你" * 10]
+
+        class _Buffer:
+            document = _Doc()
+
+        input_area = SimpleNamespace(buffer=_Buffer())
+
+        def _input_height():
+            try:
+                from prompt_toolkit.application import get_app
+                from prompt_toolkit.utils import get_cwidth
+
+                doc = input_area.buffer.document
+                prompt_width = max(2, get_cwidth(cli_obj._get_tui_prompt_text()))
+                try:
+                    available_width = get_app().output.get_size().columns - prompt_width
+                except Exception:
+                    import shutil
+                    available_width = shutil.get_terminal_size((80, 24)).columns - prompt_width
+                if available_width < 10:
+                    available_width = 40
+                visual_lines = 0
+                for line in doc.lines:
+                    line_width = get_cwidth(line)
+                    if line_width <= 0:
+                        visual_lines += 1
+                    else:
+                        visual_lines += max(1, -(-line_width // available_width))
+                return min(max(visual_lines, 1), 8)
+            except Exception:
+                return 1
+
+        mock_app = MagicMock()
+        mock_app.output.get_size.return_value = MagicMock(columns=14)
+        with patch.object(HermesCLI, "_get_tui_prompt_text", return_value="❯ "), \
+             patch("prompt_toolkit.application.get_app", return_value=mock_app):
+            assert _input_height() == 2
+
+    def test_input_height_uses_prompt_toolkit_width_over_shutil(self):
+        cli_obj = _make_cli()
+
+        class _Doc:
+            lines = ["你" * 10]
+
+        class _Buffer:
+            document = _Doc()
+
+        input_area = SimpleNamespace(buffer=_Buffer())
+
+        def _input_height():
+            try:
+                from prompt_toolkit.application import get_app
+                from prompt_toolkit.utils import get_cwidth
+
+                doc = input_area.buffer.document
+                prompt_width = max(2, get_cwidth(cli_obj._get_tui_prompt_text()))
+                try:
+                    available_width = get_app().output.get_size().columns - prompt_width
+                except Exception:
+                    import shutil
+                    available_width = shutil.get_terminal_size((80, 24)).columns - prompt_width
+                if available_width < 10:
+                    available_width = 40
+                visual_lines = 0
+                for line in doc.lines:
+                    line_width = get_cwidth(line)
+                    if line_width <= 0:
+                        visual_lines += 1
+                    else:
+                        visual_lines += max(1, -(-line_width // available_width))
+                return min(max(visual_lines, 1), 8)
+            except Exception:
+                return 1
+
+        mock_app = MagicMock()
+        mock_app.output.get_size.return_value = MagicMock(columns=14)
+        with patch.object(HermesCLI, "_get_tui_prompt_text", return_value="❯ "), \
+             patch("prompt_toolkit.application.get_app", return_value=mock_app), \
+             patch("shutil.get_terminal_size") as mock_shutil:
+            assert _input_height() == 2
+        mock_shutil.assert_not_called()
+
+    def test_build_status_bar_text_no_cost_in_status_bar(self):
+        cli_obj = _attach_agent(
+            _make_cli(),
+            prompt_tokens=10000,
+            completion_tokens=5000,
+            total_tokens=15000,
+            api_calls=7,
+            context_tokens=50000,
+            context_length=200_000,
+        )
+
+        text = cli_obj._build_status_bar_text(width=120)
+        assert "$" not in text  # cost is never shown in status bar
+
+    def test_build_status_bar_text_collapses_for_narrow_terminal(self):
+        cli_obj = _attach_agent(
+            _make_cli(),
+            prompt_tokens=10000,
+            completion_tokens=2400,
+            total_tokens=12400,
+            api_calls=7,
+            context_tokens=12400,
+            context_length=200_000,
+        )
+
+        text = cli_obj._build_status_bar_text(width=60)
+
+        assert "⚕" in text
+        assert "$0.06" not in text  # cost hidden by default
+        assert "15m" in text
+        assert "200K" not in text
+
+    def test_build_status_bar_text_handles_missing_agent(self):
+        cli_obj = _make_cli()
+
+        text = cli_obj._build_status_bar_text(width=100)
+
+        assert "⚕" in text
+        assert "claude-sonnet-4-20250514" in text
+
+
+class TestCLIUsageReport:
+    def test_show_usage_includes_estimated_cost(self, capsys):
+        cli_obj = _attach_agent(
+            _make_cli(),
+            prompt_tokens=10_230,
+            completion_tokens=2_220,
+            total_tokens=12_450,
+            api_calls=7,
+            context_tokens=12_450,
+            context_length=200_000,
+            compressions=1,
+        )
+        cli_obj.verbose = False
+
+        cli_obj._show_usage()
+        output = capsys.readouterr().out
+
+        assert "Model:" in output
+        assert "Cost status:" in output
+        assert "Cost source:" in output
+        assert "Total cost:" in output
+        assert "$" in output
+        assert "0.064" in output
+        assert "Session duration:" in output
+        assert "Compressions:" in output
+
+    def test_show_usage_marks_unknown_pricing(self, capsys):
+        cli_obj = _attach_agent(
+            _make_cli(model="local/my-custom-model"),
+            prompt_tokens=1_000,
+            completion_tokens=500,
+            total_tokens=1_500,
+            api_calls=1,
+            context_tokens=1_000,
+            context_length=32_000,
+        )
+        cli_obj.verbose = False
+
+        cli_obj._show_usage()
+        output = capsys.readouterr().out
+
+        assert "Total cost:" in output
+        assert "n/a" in output
+        assert "Pricing unknown for local/my-custom-model" in output
+
+    def test_zero_priced_provider_models_stay_unknown(self, capsys):
+        cli_obj = _attach_agent(
+            _make_cli(model="glm-5"),
+            prompt_tokens=1_000,
+            completion_tokens=500,
+            total_tokens=1_500,
+            api_calls=1,
+            context_tokens=1_000,
+            context_length=32_000,
+        )
+        cli_obj.verbose = False
+
+        cli_obj._show_usage()
+        output = capsys.readouterr().out
+
+        assert "Total cost:" in output
+        assert "n/a" in output
+        assert "Pricing unknown for glm-5" in output
+
+
+class TestStatusBarWidthSource:
+    """Ensure status bar fragments don't overflow the terminal width."""
+
+    def _make_wide_cli(self):
+        from datetime import datetime, timedelta
+        cli_obj = _attach_agent(
+            _make_cli(),
+            prompt_tokens=100_000,
+            completion_tokens=5_000,
+            total_tokens=105_000,
+            api_calls=20,
+            context_tokens=100_000,
+            context_length=200_000,
+        )
+        cli_obj._status_bar_visible = True
+        return cli_obj
+
+    def test_fragments_fit_within_announced_width(self):
+        """Total fragment text length must not exceed the width used to build them."""
+        from unittest.mock import MagicMock, patch
+        cli_obj = self._make_wide_cli()
+
+        for width in (40, 52, 76, 80, 120, 200):
+            mock_app = MagicMock()
+            mock_app.output.get_size.return_value = MagicMock(columns=width)
+
+            with patch("prompt_toolkit.application.get_app", return_value=mock_app):
+                frags = cli_obj._get_status_bar_fragments()
+
+            total_text = "".join(text for _, text in frags)
+            display_width = cli_obj._status_bar_display_width(total_text)
+            assert display_width <= width + 4, (  # +4 for minor padding chars
+                f"At width={width}, fragment total {display_width} cells overflows "
+                f"({total_text!r})"
+            )
+
+    def test_fragments_use_pt_width_over_shutil(self):
+        """When prompt_toolkit reports a width, shutil.get_terminal_size must not be used."""
+        from unittest.mock import MagicMock, patch
+        cli_obj = self._make_wide_cli()
+
+        mock_app = MagicMock()
+        mock_app.output.get_size.return_value = MagicMock(columns=120)
+
+        with patch("prompt_toolkit.application.get_app", return_value=mock_app) as mock_get_app, \
+             patch("shutil.get_terminal_size") as mock_shutil:
+            cli_obj._get_status_bar_fragments()
+
+        mock_shutil.assert_not_called()
+
+    def test_fragments_fall_back_to_shutil_when_no_app(self):
+        """Outside a TUI context (no running app), shutil must be used as fallback."""
+        from unittest.mock import MagicMock, patch
+        cli_obj = self._make_wide_cli()
+
+        with patch("prompt_toolkit.application.get_app", side_effect=Exception("no app")), \
+             patch("shutil.get_terminal_size", return_value=MagicMock(columns=100)) as mock_shutil:
+            frags = cli_obj._get_status_bar_fragments()
+
+        mock_shutil.assert_called()
+        assert len(frags) > 0
+
+    def test_build_status_bar_text_uses_pt_width(self):
+        """_build_status_bar_text() must also prefer prompt_toolkit width."""
+        from unittest.mock import MagicMock, patch
+        cli_obj = self._make_wide_cli()
+
+        mock_app = MagicMock()
+        mock_app.output.get_size.return_value = MagicMock(columns=80)
+
+        with patch("prompt_toolkit.application.get_app", return_value=mock_app), \
+             patch("shutil.get_terminal_size") as mock_shutil:
+            text = cli_obj._build_status_bar_text()  # no explicit width
+
+        mock_shutil.assert_not_called()
+        assert isinstance(text, str)
+        assert len(text) > 0
+
+    def test_explicit_width_skips_pt_lookup(self):
+        """An explicit width= argument must bypass both PT and shutil lookups."""
+        from unittest.mock import patch
+        cli_obj = self._make_wide_cli()
+
+        with patch("prompt_toolkit.application.get_app") as mock_get_app, \
+             patch("shutil.get_terminal_size") as mock_shutil:
+            text = cli_obj._build_status_bar_text(width=100)
+
+        mock_get_app.assert_not_called()
+        mock_shutil.assert_not_called()
+        assert len(text) > 0

tests/cli/test_cli_tools_command.py

@@ -0,0 +1,130 @@
+"""Tests for /tools slash command handler in the interactive CLI."""
+
+from unittest.mock import MagicMock, patch, call
+
+from cli import HermesCLI
+
+
+def _make_cli(enabled_toolsets=None):
+    """Build a minimal HermesCLI stub without running __init__."""
+    cli_obj = HermesCLI.__new__(HermesCLI)
+    cli_obj.enabled_toolsets = set(enabled_toolsets or ["web", "memory"])
+    cli_obj._command_running = False
+    cli_obj.console = MagicMock()
+    return cli_obj
+
+
+# ── /tools (no subcommand) ──────────────────────────────────────────────────
+
+
+class TestToolsSlashNoSubcommand:
+
+    def test_bare_tools_shows_tool_list(self):
+        cli_obj = _make_cli()
+        with patch.object(cli_obj, "show_tools") as mock_show:
+            cli_obj._handle_tools_command("/tools")
+        mock_show.assert_called_once()
+
+    def test_unknown_subcommand_falls_back_to_show_tools(self):
+        cli_obj = _make_cli()
+        with patch.object(cli_obj, "show_tools") as mock_show:
+            cli_obj._handle_tools_command("/tools foobar")
+        mock_show.assert_called_once()
+
+
+# ── /tools list ─────────────────────────────────────────────────────────────
+
+
+class TestToolsSlashList:
+
+    def test_list_calls_backend(self, capsys):
+        cli_obj = _make_cli()
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["web"]}}), \
+             patch("hermes_cli.tools_config.save_config"):
+            cli_obj._handle_tools_command("/tools list")
+        out = capsys.readouterr().out
+        assert "web" in out
+
+    def test_list_does_not_modify_enabled_toolsets(self):
+        """List is read-only — self.enabled_toolsets must not change."""
+        cli_obj = _make_cli(["web", "memory"])
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["web"]}}):
+            cli_obj._handle_tools_command("/tools list")
+        assert cli_obj.enabled_toolsets == {"web", "memory"}
+
+
+# ── /tools disable (session reset) ──────────────────────────────────────────
+
+
+class TestToolsSlashDisableWithReset:
+
+    def test_disable_applies_directly_and_resets_session(self):
+        """Disable applies immediately (no confirmation prompt) and resets session."""
+        cli_obj = _make_cli(["web", "memory"])
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["web", "memory"]}}), \
+             patch("hermes_cli.tools_config.save_config"), \
+             patch("hermes_cli.tools_config._get_platform_tools", return_value={"memory"}), \
+             patch("hermes_cli.config.load_config", return_value={}), \
+             patch.object(cli_obj, "new_session") as mock_reset:
+            cli_obj._handle_tools_command("/tools disable web")
+        mock_reset.assert_called_once()
+        assert "web" not in cli_obj.enabled_toolsets
+
+    def test_disable_does_not_prompt_for_confirmation(self):
+        """Disable no longer uses input() — it applies directly."""
+        cli_obj = _make_cli(["web", "memory"])
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["web", "memory"]}}), \
+             patch("hermes_cli.tools_config.save_config"), \
+             patch("hermes_cli.tools_config._get_platform_tools", return_value={"memory"}), \
+             patch("hermes_cli.config.load_config", return_value={}), \
+             patch.object(cli_obj, "new_session"), \
+             patch("builtins.input") as mock_input:
+            cli_obj._handle_tools_command("/tools disable web")
+        mock_input.assert_not_called()
+
+    def test_disable_always_resets_session(self):
+        """Even without a confirmation prompt, disable always resets the session."""
+        cli_obj = _make_cli(["web", "memory"])
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["web", "memory"]}}), \
+             patch("hermes_cli.tools_config.save_config"), \
+             patch("hermes_cli.tools_config._get_platform_tools", return_value={"memory"}), \
+             patch("hermes_cli.config.load_config", return_value={}), \
+             patch.object(cli_obj, "new_session") as mock_reset:
+            cli_obj._handle_tools_command("/tools disable web")
+        mock_reset.assert_called_once()
+
+    def test_disable_missing_name_prints_usage(self, capsys):
+        cli_obj = _make_cli()
+        cli_obj._handle_tools_command("/tools disable")
+        out = capsys.readouterr().out
+        assert "Usage" in out
+
+
+# ── /tools enable (session reset) ───────────────────────────────────────────
+
+
+class TestToolsSlashEnableWithReset:
+
+    def test_enable_applies_directly_and_resets_session(self):
+        """Enable applies immediately (no confirmation prompt) and resets session."""
+        cli_obj = _make_cli(["memory"])
+        with patch("hermes_cli.tools_config.load_config",
+                   return_value={"platform_toolsets": {"cli": ["memory"]}}), \
+             patch("hermes_cli.tools_config.save_config"), \
+             patch("hermes_cli.tools_config._get_platform_tools", return_value={"memory", "web"}), \
+             patch("hermes_cli.config.load_config", return_value={}), \
+             patch.object(cli_obj, "new_session") as mock_reset:
+            cli_obj._handle_tools_command("/tools enable web")
+        mock_reset.assert_called_once()
+        assert "web" in cli_obj.enabled_toolsets
+
+    def test_enable_missing_name_prints_usage(self, capsys):
+        cli_obj = _make_cli()
+        cli_obj._handle_tools_command("/tools enable")
+        out = capsys.readouterr().out
+        assert "Usage" in out

tests/cli/test_personality_none.py

@@ -0,0 +1,212 @@
+"""Tests for /personality none — clearing personality overlay."""
+import pytest
+from unittest.mock import MagicMock, patch, mock_open
+import yaml
+
+
+# ── CLI tests ──────────────────────────────────────────────────────────────
+
+class TestCLIPersonalityNone:
+
+    def _make_cli(self, personalities=None):
+        from cli import HermesCLI
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.personalities = personalities or {
+            "helpful": "You are helpful.",
+            "concise": "You are concise.",
+        }
+        cli.system_prompt = "You are kawaii~"
+        cli.agent = MagicMock()
+        cli.console = MagicMock()
+        return cli
+
+    def test_none_clears_system_prompt(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality none")
+        assert cli.system_prompt == ""
+
+    def test_default_clears_system_prompt(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality default")
+        assert cli.system_prompt == ""
+
+    def test_neutral_clears_system_prompt(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality neutral")
+        assert cli.system_prompt == ""
+
+    def test_none_forces_agent_reinit(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality none")
+        assert cli.agent is None
+
+    def test_none_saves_to_config(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True) as mock_save:
+            cli._handle_personality_command("/personality none")
+        mock_save.assert_called_once_with("agent.system_prompt", "")
+
+    def test_known_personality_still_works(self):
+        cli = self._make_cli()
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality helpful")
+        assert cli.system_prompt == "You are helpful."
+
+    def test_unknown_personality_shows_none_in_available(self, capsys):
+        cli = self._make_cli()
+        cli._handle_personality_command("/personality nonexistent")
+        output = capsys.readouterr().out
+        assert "none" in output.lower()
+
+    def test_list_shows_none_option(self):
+        cli = self._make_cli()
+        with patch("builtins.print") as mock_print:
+            cli._handle_personality_command("/personality")
+        output = " ".join(str(c) for c in mock_print.call_args_list)
+        assert "none" in output.lower()
+
+
+# ── Gateway tests ──────────────────────────────────────────────────────────
+
+class TestGatewayPersonalityNone:
+
+    def _make_event(self, args=""):
+        event = MagicMock()
+        event.get_command.return_value = "personality"
+        event.get_command_args.return_value = args
+        return event
+
+    def _make_runner(self, personalities=None):
+        from gateway.run import GatewayRunner
+        runner = GatewayRunner.__new__(GatewayRunner)
+        runner._ephemeral_system_prompt = "You are kawaii~"
+        runner.config = {
+            "agent": {
+                "personalities": personalities or {"helpful": "You are helpful."}
+            }
+        }
+        return runner
+
+    @pytest.mark.asyncio
+    async def test_none_clears_ephemeral_prompt(self, tmp_path):
+        runner = self._make_runner()
+        config_data = {"agent": {"personalities": {"helpful": "You are helpful."}, "system_prompt": "kawaii"}}
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(yaml.dump(config_data))
+
+        with patch("gateway.run._hermes_home", tmp_path):
+            event = self._make_event("none")
+            result = await runner._handle_personality_command(event)
+
+        assert runner._ephemeral_system_prompt == ""
+        assert "cleared" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_default_clears_ephemeral_prompt(self, tmp_path):
+        runner = self._make_runner()
+        config_data = {"agent": {"personalities": {"helpful": "You are helpful."}}}
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(yaml.dump(config_data))
+
+        with patch("gateway.run._hermes_home", tmp_path):
+            event = self._make_event("default")
+            result = await runner._handle_personality_command(event)
+
+        assert runner._ephemeral_system_prompt == ""
+
+    @pytest.mark.asyncio
+    async def test_list_includes_none(self, tmp_path):
+        runner = self._make_runner()
+        config_data = {"agent": {"personalities": {"helpful": "You are helpful."}}}
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(yaml.dump(config_data))
+
+        with patch("gateway.run._hermes_home", tmp_path):
+            event = self._make_event("")
+            result = await runner._handle_personality_command(event)
+
+        assert "none" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_unknown_shows_none_in_available(self, tmp_path):
+        runner = self._make_runner()
+        config_data = {"agent": {"personalities": {"helpful": "You are helpful."}}}
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(yaml.dump(config_data))
+
+        with patch("gateway.run._hermes_home", tmp_path):
+            event = self._make_event("nonexistent")
+            result = await runner._handle_personality_command(event)
+
+        assert "none" in result.lower()
+
+
+class TestPersonalityDictFormat:
+    """Test dict-format custom personalities with description, tone, style."""
+
+    def _make_cli(self, personalities):
+        from cli import HermesCLI
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.personalities = personalities
+        cli.system_prompt = ""
+        cli.agent = None
+        cli.console = MagicMock()
+        return cli
+
+    def test_dict_personality_uses_system_prompt(self):
+        cli = self._make_cli({
+            "coder": {
+                "description": "Expert programmer",
+                "system_prompt": "You are an expert programmer.",
+                "tone": "technical",
+                "style": "concise",
+            }
+        })
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality coder")
+        assert "You are an expert programmer." in cli.system_prompt
+
+    def test_dict_personality_includes_tone(self):
+        cli = self._make_cli({
+            "coder": {
+                "system_prompt": "You are an expert programmer.",
+                "tone": "technical and precise",
+            }
+        })
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality coder")
+        assert "Tone: technical and precise" in cli.system_prompt
+
+    def test_dict_personality_includes_style(self):
+        cli = self._make_cli({
+            "coder": {
+                "system_prompt": "You are an expert programmer.",
+                "style": "use code examples",
+            }
+        })
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality coder")
+        assert "Style: use code examples" in cli.system_prompt
+
+    def test_string_personality_still_works(self):
+        cli = self._make_cli({"helper": "You are helpful."})
+        with patch("cli.save_config_value", return_value=True):
+            cli._handle_personality_command("/personality helper")
+        assert cli.system_prompt == "You are helpful."
+
+    def test_resolve_prompt_dict_no_tone_no_style(self):
+        from cli import HermesCLI
+        result = HermesCLI._resolve_personality_prompt({
+            "description": "A helper",
+            "system_prompt": "You are helpful.",
+        })
+        assert result == "You are helpful."
+
+    def test_resolve_prompt_string(self):
+        from cli import HermesCLI
+        result = HermesCLI._resolve_personality_prompt("You are helpful.")
+        assert result == "You are helpful."

tests/cli/test_quick_commands.py

@@ -0,0 +1,188 @@
+"""Tests for user-defined quick commands that bypass the agent loop."""
+import subprocess
+from unittest.mock import MagicMock, patch, AsyncMock
+from rich.text import Text
+import pytest
+
+
+# ── CLI tests ──────────────────────────────────────────────────────────────
+
+class TestCLIQuickCommands:
+    """Test quick command dispatch in HermesCLI.process_command."""
+
+    @staticmethod
+    def _printed_plain(call_arg):
+        if isinstance(call_arg, Text):
+            return call_arg.plain
+        return str(call_arg)
+
+    def _make_cli(self, quick_commands):
+        from cli import HermesCLI
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.config = {"quick_commands": quick_commands}
+        cli.console = MagicMock()
+        cli.agent = None
+        cli.conversation_history = []
+        return cli
+
+    def test_exec_command_runs_and_prints_output(self):
+        cli = self._make_cli({"dn": {"type": "exec", "command": "echo daily-note"}})
+        result = cli.process_command("/dn")
+        assert result is True
+        cli.console.print.assert_called_once()
+        printed = self._printed_plain(cli.console.print.call_args[0][0])
+        assert printed == "daily-note"
+
+    def test_exec_command_stderr_shown_on_no_stdout(self):
+        cli = self._make_cli({"err": {"type": "exec", "command": "echo error >&2"}})
+        result = cli.process_command("/err")
+        assert result is True
+        # stderr fallback — should print something
+        cli.console.print.assert_called_once()
+
+    def test_exec_command_no_output_shows_fallback(self):
+        cli = self._make_cli({"empty": {"type": "exec", "command": "true"}})
+        cli.process_command("/empty")
+        cli.console.print.assert_called_once()
+        args = cli.console.print.call_args[0][0]
+        assert "no output" in args.lower()
+
+    def test_alias_command_routes_to_target(self):
+        """Alias quick commands rewrite to the target command."""
+        cli = self._make_cli({"shortcut": {"type": "alias", "target": "/help"}})
+        with patch.object(cli, "process_command", wraps=cli.process_command) as spy:
+            cli.process_command("/shortcut")
+            # Should recursively call process_command with /help
+            spy.assert_any_call("/help")
+
+    def test_alias_command_passes_args(self):
+        """Alias quick commands forward user arguments to the target."""
+        cli = self._make_cli({"sc": {"type": "alias", "target": "/context"}})
+        with patch.object(cli, "process_command", wraps=cli.process_command) as spy:
+            cli.process_command("/sc some args")
+            spy.assert_any_call("/context some args")
+
+    def test_alias_no_target_shows_error(self):
+        cli = self._make_cli({"broken": {"type": "alias", "target": ""}})
+        cli.process_command("/broken")
+        cli.console.print.assert_called_once()
+        args = cli.console.print.call_args[0][0]
+        assert "no target defined" in args.lower()
+
+    def test_unsupported_type_shows_error(self):
+        cli = self._make_cli({"bad": {"type": "prompt", "command": "echo hi"}})
+        cli.process_command("/bad")
+        cli.console.print.assert_called_once()
+        args = cli.console.print.call_args[0][0]
+        assert "unsupported type" in args.lower()
+
+    def test_missing_command_field_shows_error(self):
+        cli = self._make_cli({"oops": {"type": "exec"}})
+        cli.process_command("/oops")
+        cli.console.print.assert_called_once()
+        args = cli.console.print.call_args[0][0]
+        assert "no command defined" in args.lower()
+
+    def test_quick_command_takes_priority_over_skill_commands(self):
+        """Quick commands must be checked before skill slash commands."""
+        cli = self._make_cli({"mygif": {"type": "exec", "command": "echo overridden"}})
+        with patch("cli._skill_commands", {"/mygif": {"name": "gif-search"}}):
+            cli.process_command("/mygif")
+        cli.console.print.assert_called_once()
+        printed = self._printed_plain(cli.console.print.call_args[0][0])
+        assert printed == "overridden"
+
+    def test_unknown_command_still_shows_error(self):
+        cli = self._make_cli({})
+        with patch("cli._cprint") as mock_cprint:
+            cli.process_command("/nonexistent")
+            mock_cprint.assert_called()
+            printed = " ".join(str(c) for c in mock_cprint.call_args_list)
+            assert "unknown command" in printed.lower()
+
+    def test_timeout_shows_error(self):
+        cli = self._make_cli({"slow": {"type": "exec", "command": "sleep 100"}})
+        with patch("subprocess.run", side_effect=subprocess.TimeoutExpired("sleep", 30)):
+            cli.process_command("/slow")
+        cli.console.print.assert_called_once()
+        args = cli.console.print.call_args[0][0]
+        assert "timed out" in args.lower()
+
+
+# ── Gateway tests ──────────────────────────────────────────────────────────
+
+class TestGatewayQuickCommands:
+    """Test quick command dispatch in GatewayRunner._handle_message."""
+
+    def _make_event(self, command, args=""):
+        event = MagicMock()
+        event.get_command.return_value = command
+        event.get_command_args.return_value = args
+        event.text = f"/{command} {args}".strip()
+        event.source = MagicMock()
+        event.source.user_id = "test_user"
+        event.source.user_name = "Test User"
+        event.source.platform.value = "telegram"
+        event.source.chat_type = "dm"
+        event.source.chat_id = "123"
+        return event
+
+    @pytest.mark.asyncio
+    async def test_exec_command_returns_output(self):
+        from gateway.run import GatewayRunner
+        runner = GatewayRunner.__new__(GatewayRunner)
+        runner.config = {"quick_commands": {"limits": {"type": "exec", "command": "echo ok"}}}
+        runner._running_agents = {}
+        runner._pending_messages = {}
+        runner._is_user_authorized = MagicMock(return_value=True)
+
+        event = self._make_event("limits")
+        result = await runner._handle_message(event)
+        assert result == "ok"
+
+    @pytest.mark.asyncio
+    async def test_unsupported_type_returns_error(self):
+        from gateway.run import GatewayRunner
+        runner = GatewayRunner.__new__(GatewayRunner)
+        runner.config = {"quick_commands": {"bad": {"type": "prompt", "command": "echo hi"}}}
+        runner._running_agents = {}
+        runner._pending_messages = {}
+        runner._is_user_authorized = MagicMock(return_value=True)
+
+        event = self._make_event("bad")
+        result = await runner._handle_message(event)
+        assert result is not None
+        assert "unsupported type" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_timeout_returns_error(self):
+        from gateway.run import GatewayRunner
+        import asyncio
+        runner = GatewayRunner.__new__(GatewayRunner)
+        runner.config = {"quick_commands": {"slow": {"type": "exec", "command": "sleep 100"}}}
+        runner._running_agents = {}
+        runner._pending_messages = {}
+        runner._is_user_authorized = MagicMock(return_value=True)
+
+        event = self._make_event("slow")
+        with patch("asyncio.wait_for", side_effect=asyncio.TimeoutError):
+            result = await runner._handle_message(event)
+        assert result is not None
+        assert "timed out" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_gateway_config_object_supports_quick_commands(self):
+        from gateway.config import GatewayConfig
+        from gateway.run import GatewayRunner
+
+        runner = GatewayRunner.__new__(GatewayRunner)
+        runner.config = GatewayConfig(
+            quick_commands={"limits": {"type": "exec", "command": "echo ok"}}
+        )
+        runner._running_agents = {}
+        runner._pending_messages = {}
+        runner._is_user_authorized = MagicMock(return_value=True)
+
+        event = self._make_event("limits")
+        result = await runner._handle_message(event)
+        assert result == "ok"

tests/cli/test_reasoning_command.py

@@ -0,0 +1,764 @@
+"""Tests for the combined /reasoning command.
+
+Covers both reasoning effort level management and reasoning display toggle,
+plus the reasoning extraction and display pipeline from run_agent through CLI.
+
+Combines functionality from:
+- PR #789 (Aum08Desai): reasoning effort level management
+- PR #790 (0xbyt4): reasoning display toggle and rendering
+"""
+
+import unittest
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+import re
+
+
+# ---------------------------------------------------------------------------
+# Effort level parsing
+# ---------------------------------------------------------------------------
+
+class TestParseReasoningConfig(unittest.TestCase):
+    """Verify _parse_reasoning_config handles all effort levels."""
+
+    def _parse(self, effort):
+        from cli import _parse_reasoning_config
+        return _parse_reasoning_config(effort)
+
+    def test_none_disables(self):
+        result = self._parse("none")
+        self.assertEqual(result, {"enabled": False})
+
+    def test_valid_levels(self):
+        for level in ("low", "medium", "high", "xhigh", "minimal"):
+            result = self._parse(level)
+            self.assertIsNotNone(result)
+            self.assertTrue(result.get("enabled"))
+            self.assertEqual(result["effort"], level)
+
+    def test_empty_returns_none(self):
+        self.assertIsNone(self._parse(""))
+        self.assertIsNone(self._parse("  "))
+
+    def test_unknown_returns_none(self):
+        self.assertIsNone(self._parse("ultra"))
+        self.assertIsNone(self._parse("turbo"))
+
+    def test_case_insensitive(self):
+        result = self._parse("HIGH")
+        self.assertIsNotNone(result)
+        self.assertEqual(result["effort"], "high")
+
+
+# ---------------------------------------------------------------------------
+# /reasoning command handler (combined effort + display)
+# ---------------------------------------------------------------------------
+
+class TestHandleReasoningCommand(unittest.TestCase):
+    """Test the combined _handle_reasoning_command method."""
+
+    def _make_cli(self, reasoning_config=None, show_reasoning=False):
+        """Create a minimal CLI stub with the reasoning attributes."""
+        stub = SimpleNamespace(
+            reasoning_config=reasoning_config,
+            show_reasoning=show_reasoning,
+            agent=MagicMock(),
+        )
+        return stub
+
+    def test_show_enables_display(self):
+        stub = self._make_cli(show_reasoning=False)
+        # Simulate /reasoning show
+        arg = "show"
+        if arg in ("show", "on"):
+            stub.show_reasoning = True
+            stub.agent.reasoning_callback = lambda x: None
+        self.assertTrue(stub.show_reasoning)
+
+    def test_hide_disables_display(self):
+        stub = self._make_cli(show_reasoning=True)
+        # Simulate /reasoning hide
+        arg = "hide"
+        if arg in ("hide", "off"):
+            stub.show_reasoning = False
+            stub.agent.reasoning_callback = None
+        self.assertFalse(stub.show_reasoning)
+        self.assertIsNone(stub.agent.reasoning_callback)
+
+    def test_on_enables_display(self):
+        stub = self._make_cli(show_reasoning=False)
+        arg = "on"
+        if arg in ("show", "on"):
+            stub.show_reasoning = True
+        self.assertTrue(stub.show_reasoning)
+
+    def test_off_disables_display(self):
+        stub = self._make_cli(show_reasoning=True)
+        arg = "off"
+        if arg in ("hide", "off"):
+            stub.show_reasoning = False
+        self.assertFalse(stub.show_reasoning)
+
+    def test_effort_level_sets_config(self):
+        """Setting an effort level should update reasoning_config."""
+        from cli import _parse_reasoning_config
+        stub = self._make_cli()
+        arg = "high"
+        parsed = _parse_reasoning_config(arg)
+        stub.reasoning_config = parsed
+        self.assertEqual(stub.reasoning_config, {"enabled": True, "effort": "high"})
+
+    def test_effort_none_disables_reasoning(self):
+        from cli import _parse_reasoning_config
+        stub = self._make_cli()
+        parsed = _parse_reasoning_config("none")
+        stub.reasoning_config = parsed
+        self.assertEqual(stub.reasoning_config, {"enabled": False})
+
+    def test_invalid_argument_rejected(self):
+        """Invalid arguments should be rejected (parsed returns None)."""
+        from cli import _parse_reasoning_config
+        parsed = _parse_reasoning_config("turbo")
+        self.assertIsNone(parsed)
+
+    def test_no_args_shows_status(self):
+        """With no args, should show current state (no crash)."""
+        stub = self._make_cli(reasoning_config=None, show_reasoning=False)
+        rc = stub.reasoning_config
+        if rc is None:
+            level = "medium (default)"
+        elif rc.get("enabled") is False:
+            level = "none (disabled)"
+        else:
+            level = rc.get("effort", "medium")
+        display_state = "on" if stub.show_reasoning else "off"
+        self.assertEqual(level, "medium (default)")
+        self.assertEqual(display_state, "off")
+
+    def test_status_with_disabled_reasoning(self):
+        stub = self._make_cli(reasoning_config={"enabled": False}, show_reasoning=True)
+        rc = stub.reasoning_config
+        if rc is None:
+            level = "medium (default)"
+        elif rc.get("enabled") is False:
+            level = "none (disabled)"
+        else:
+            level = rc.get("effort", "medium")
+        self.assertEqual(level, "none (disabled)")
+
+    def test_status_with_explicit_level(self):
+        stub = self._make_cli(
+            reasoning_config={"enabled": True, "effort": "xhigh"},
+            show_reasoning=True,
+        )
+        rc = stub.reasoning_config
+        level = rc.get("effort", "medium")
+        self.assertEqual(level, "xhigh")
+
+
+# ---------------------------------------------------------------------------
+# Reasoning extraction and result dict
+# ---------------------------------------------------------------------------
+
+class TestLastReasoningInResult(unittest.TestCase):
+    """Verify reasoning extraction from the messages list."""
+
+    def _build_messages(self, reasoning=None):
+        return [
+            {"role": "user", "content": "hello"},
+            {
+                "role": "assistant",
+                "content": "Hi there!",
+                "reasoning": reasoning,
+                "finish_reason": "stop",
+            },
+        ]
+
+    def test_reasoning_present(self):
+        messages = self._build_messages(reasoning="Let me think...")
+        last_reasoning = None
+        for msg in reversed(messages):
+            if msg.get("role") == "assistant" and msg.get("reasoning"):
+                last_reasoning = msg["reasoning"]
+                break
+        self.assertEqual(last_reasoning, "Let me think...")
+
+    def test_reasoning_none(self):
+        messages = self._build_messages(reasoning=None)
+        last_reasoning = None
+        for msg in reversed(messages):
+            if msg.get("role") == "assistant" and msg.get("reasoning"):
+                last_reasoning = msg["reasoning"]
+                break
+        self.assertIsNone(last_reasoning)
+
+    def test_picks_last_assistant(self):
+        messages = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "...", "reasoning": "first thought"},
+            {"role": "tool", "content": "result"},
+            {"role": "assistant", "content": "done!", "reasoning": "final thought"},
+        ]
+        last_reasoning = None
+        for msg in reversed(messages):
+            if msg.get("role") == "assistant" and msg.get("reasoning"):
+                last_reasoning = msg["reasoning"]
+                break
+        self.assertEqual(last_reasoning, "final thought")
+
+    def test_empty_reasoning_treated_as_none(self):
+        messages = self._build_messages(reasoning="")
+        last_reasoning = None
+        for msg in reversed(messages):
+            if msg.get("role") == "assistant" and msg.get("reasoning"):
+                last_reasoning = msg["reasoning"]
+                break
+        self.assertIsNone(last_reasoning)
+
+
+# ---------------------------------------------------------------------------
+# Reasoning display collapse
+# ---------------------------------------------------------------------------
+
+class TestReasoningCollapse(unittest.TestCase):
+    """Verify long reasoning is collapsed to 10 lines in the box."""
+
+    def test_short_reasoning_not_collapsed(self):
+        reasoning = "\n".join(f"Line {i}" for i in range(5))
+        lines = reasoning.strip().splitlines()
+        self.assertLessEqual(len(lines), 10)
+
+    def test_long_reasoning_collapsed(self):
+        reasoning = "\n".join(f"Line {i}" for i in range(25))
+        lines = reasoning.strip().splitlines()
+        self.assertTrue(len(lines) > 10)
+        if len(lines) > 10:
+            display = "\n".join(lines[:10])
+            display += f"\n  ... ({len(lines) - 10} more lines)"
+        display_lines = display.splitlines()
+        self.assertEqual(len(display_lines), 11)
+        self.assertIn("15 more lines", display_lines[-1])
+
+    def test_exactly_10_lines_not_collapsed(self):
+        reasoning = "\n".join(f"Line {i}" for i in range(10))
+        lines = reasoning.strip().splitlines()
+        self.assertEqual(len(lines), 10)
+        self.assertFalse(len(lines) > 10)
+
+    def test_intermediate_callback_collapses_to_5(self):
+        """_on_reasoning shows max 5 lines."""
+        reasoning = "\n".join(f"Step {i}" for i in range(12))
+        lines = reasoning.strip().splitlines()
+        if len(lines) > 5:
+            preview = "\n".join(lines[:5])
+            preview += f"\n  ... ({len(lines) - 5} more lines)"
+        else:
+            preview = reasoning.strip()
+        preview_lines = preview.splitlines()
+        self.assertEqual(len(preview_lines), 6)
+        self.assertIn("7 more lines", preview_lines[-1])
+
+
+# ---------------------------------------------------------------------------
+# Reasoning callback
+# ---------------------------------------------------------------------------
+
+class TestReasoningCallback(unittest.TestCase):
+    """Verify reasoning_callback invocation."""
+
+    def test_callback_invoked_with_reasoning(self):
+        captured = []
+        agent = MagicMock()
+        agent.reasoning_callback = lambda t: captured.append(t)
+        agent._extract_reasoning = MagicMock(return_value="deep thought")
+
+        reasoning_text = agent._extract_reasoning(MagicMock())
+        if reasoning_text and agent.reasoning_callback:
+            agent.reasoning_callback(reasoning_text)
+        self.assertEqual(captured, ["deep thought"])
+
+    def test_callback_not_invoked_without_reasoning(self):
+        captured = []
+        agent = MagicMock()
+        agent.reasoning_callback = lambda t: captured.append(t)
+        agent._extract_reasoning = MagicMock(return_value=None)
+
+        reasoning_text = agent._extract_reasoning(MagicMock())
+        if reasoning_text and agent.reasoning_callback:
+            agent.reasoning_callback(reasoning_text)
+        self.assertEqual(captured, [])
+
+    def test_callback_none_does_not_crash(self):
+        reasoning_text = "some thought"
+        callback = None
+        if reasoning_text and callback:
+            callback(reasoning_text)
+        # No exception = pass
+
+
+class TestReasoningPreviewBuffering(unittest.TestCase):
+    def _make_cli(self):
+        from cli import HermesCLI
+
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.verbose = True
+        cli._spinner_text = ""
+        cli._reasoning_preview_buf = ""
+        cli._invalidate = lambda *args, **kwargs: None
+        return cli
+
+    @patch("cli._cprint")
+    def test_streamed_reasoning_chunks_wait_for_boundary(self, mock_cprint):
+        cli = self._make_cli()
+
+        cli._on_reasoning("Let")
+        cli._on_reasoning(" me")
+        cli._on_reasoning(" think")
+
+        self.assertEqual(mock_cprint.call_count, 0)
+
+        cli._on_reasoning(" about this.\n")
+
+        self.assertEqual(mock_cprint.call_count, 1)
+        rendered = mock_cprint.call_args[0][0]
+        self.assertIn("[thinking] Let me think about this.", rendered)
+
+    @patch("cli._cprint")
+    def test_pending_reasoning_flushes_when_thinking_stops(self, mock_cprint):
+        cli = self._make_cli()
+
+        cli._on_reasoning("see")
+        cli._on_reasoning(" how")
+        cli._on_reasoning(" this")
+        cli._on_reasoning(" plays")
+        cli._on_reasoning(" out")
+
+        self.assertEqual(mock_cprint.call_count, 0)
+
+        cli._on_thinking("")
+
+        self.assertEqual(mock_cprint.call_count, 1)
+        rendered = mock_cprint.call_args[0][0]
+        self.assertIn("[thinking] see how this plays out", rendered)
+
+    @patch("cli._cprint")
+    @patch("cli.shutil.get_terminal_size", return_value=SimpleNamespace(columns=50))
+    def test_reasoning_preview_compacts_newlines_and_wraps_to_terminal(self, _mock_term, mock_cprint):
+        cli = self._make_cli()
+
+        cli._emit_reasoning_preview(
+            "First line\nstill same thought\n\n\nSecond paragraph with more detail here."
+        )
+
+        rendered = mock_cprint.call_args[0][0]
+        plain = re.sub(r"\x1b\[[0-9;]*m", "", rendered)
+        normalized = " ".join(plain.split())
+        self.assertIn("[thinking] First line still same thought", plain)
+        self.assertIn("Second paragraph with more detail here.", normalized)
+        self.assertNotIn("\n\n\n", plain)
+
+    @patch("cli.shutil.get_terminal_size", return_value=SimpleNamespace(columns=60))
+    def test_reasoning_flush_threshold_tracks_terminal_width(self, _mock_term):
+        cli = self._make_cli()
+
+        cli._reasoning_preview_buf = "a" * 30
+        cli._flush_reasoning_preview(force=False)
+        self.assertEqual(cli._reasoning_preview_buf, "a" * 30)
+
+
+class TestReasoningDisplayModeSelection(unittest.TestCase):
+    def _make_cli(self, *, show_reasoning=False, streaming_enabled=False, verbose=False):
+        from cli import HermesCLI
+
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.show_reasoning = show_reasoning
+        cli.streaming_enabled = streaming_enabled
+        cli.verbose = verbose
+        cli._stream_reasoning_delta = lambda text: ("stream", text)
+        cli._on_reasoning = lambda text: ("preview", text)
+        return cli
+
+    def test_show_reasoning_non_streaming_uses_final_box_only(self):
+        cli = self._make_cli(show_reasoning=True, streaming_enabled=False, verbose=False)
+
+        self.assertIsNone(cli._current_reasoning_callback())
+
+    def test_show_reasoning_streaming_uses_live_reasoning_box(self):
+        cli = self._make_cli(show_reasoning=True, streaming_enabled=True, verbose=False)
+
+        callback = cli._current_reasoning_callback()
+        self.assertIsNotNone(callback)
+        self.assertEqual(callback("x"), ("stream", "x"))
+
+    def test_verbose_without_show_reasoning_uses_preview_callback(self):
+        cli = self._make_cli(show_reasoning=False, streaming_enabled=False, verbose=True)
+
+        callback = cli._current_reasoning_callback()
+        self.assertIsNotNone(callback)
+        self.assertEqual(callback("x"), ("preview", "x"))
+
+
+# ---------------------------------------------------------------------------
+# Real provider format extraction
+# ---------------------------------------------------------------------------
+
+class TestExtractReasoningFormats(unittest.TestCase):
+    """Test _extract_reasoning with real provider response formats."""
+
+    def _get_extractor(self):
+        from run_agent import AIAgent
+        return AIAgent._extract_reasoning
+
+    def test_openrouter_reasoning_details(self):
+        extract = self._get_extractor()
+        msg = SimpleNamespace(
+            reasoning=None,
+            reasoning_content=None,
+            reasoning_details=[
+                {"type": "reasoning.summary", "summary": "Analyzing Python lists."},
+            ],
+        )
+        result = extract(None, msg)
+        self.assertIn("Python lists", result)
+
+    def test_deepseek_reasoning_field(self):
+        extract = self._get_extractor()
+        msg = SimpleNamespace(
+            reasoning="Solving step by step.\nx + y = 8.",
+            reasoning_content=None,
+        )
+        result = extract(None, msg)
+        self.assertIn("x + y = 8", result)
+
+    def test_moonshot_reasoning_content(self):
+        extract = self._get_extractor()
+        msg = SimpleNamespace(
+            reasoning_content="Explaining async/await.",
+        )
+        result = extract(None, msg)
+        self.assertIn("async/await", result)
+
+    def test_no_reasoning_returns_none(self):
+        extract = self._get_extractor()
+        msg = SimpleNamespace(content="Hello!")
+        result = extract(None, msg)
+        self.assertIsNone(result)
+
+
+# ---------------------------------------------------------------------------
+# Inline <think> block extraction fallback
+# ---------------------------------------------------------------------------
+
+class TestInlineThinkBlockExtraction(unittest.TestCase):
+    """Test _build_assistant_message extracts inline <think> blocks as reasoning
+    when no structured API-level reasoning fields are present."""
+
+    def _build_msg(self, content, reasoning=None, reasoning_content=None, reasoning_details=None, tool_calls=None):
+        """Create a mock API response message."""
+        msg = SimpleNamespace(content=content, tool_calls=tool_calls)
+        if reasoning is not None:
+            msg.reasoning = reasoning
+        if reasoning_content is not None:
+            msg.reasoning_content = reasoning_content
+        if reasoning_details is not None:
+            msg.reasoning_details = reasoning_details
+        return msg
+
+    def _make_agent(self):
+        """Create a minimal agent with _build_assistant_message."""
+        from run_agent import AIAgent
+        agent = MagicMock(spec=AIAgent)
+        agent._build_assistant_message = AIAgent._build_assistant_message.__get__(agent)
+        agent._extract_reasoning = AIAgent._extract_reasoning.__get__(agent)
+        agent.verbose_logging = False
+        agent.reasoning_callback = None
+        agent.stream_delta_callback = None  # non-streaming by default
+        return agent
+
+    def test_single_think_block_extracted(self):
+        agent = self._make_agent()
+        api_msg = self._build_msg("<think>Let me calculate 2+2=4.</think>The answer is 4.")
+        result = agent._build_assistant_message(api_msg, "stop")
+        self.assertEqual(result["reasoning"], "Let me calculate 2+2=4.")
+
+    def test_multiple_think_blocks_extracted(self):
+        agent = self._make_agent()
+        api_msg = self._build_msg("<think>First thought.</think>Some text<think>Second thought.</think>More text")
+        result = agent._build_assistant_message(api_msg, "stop")
+        self.assertIn("First thought.", result["reasoning"])
+        self.assertIn("Second thought.", result["reasoning"])
+
+    def test_no_think_blocks_no_reasoning(self):
+        agent = self._make_agent()
+        api_msg = self._build_msg("Just a plain response.")
+        result = agent._build_assistant_message(api_msg, "stop")
+        # No structured reasoning AND no inline think blocks → None
+        self.assertIsNone(result["reasoning"])
+
+    def test_structured_reasoning_takes_priority(self):
+        """When structured API reasoning exists, inline think blocks should NOT override."""
+        agent = self._make_agent()
+        api_msg = self._build_msg(
+            "<think>Inline thought.</think>Response text.",
+            reasoning="Structured reasoning from API.",
+        )
+        result = agent._build_assistant_message(api_msg, "stop")
+        self.assertEqual(result["reasoning"], "Structured reasoning from API.")
+
+    def test_empty_think_block_ignored(self):
+        agent = self._make_agent()
+        api_msg = self._build_msg("<think></think>Hello!")
+        result = agent._build_assistant_message(api_msg, "stop")
+        # Empty think block should not produce reasoning
+        self.assertIsNone(result["reasoning"])
+
+    def test_multiline_think_block(self):
+        agent = self._make_agent()
+        api_msg = self._build_msg("<think>\nStep 1: Analyze.\nStep 2: Solve.\n</think>Done.")
+        result = agent._build_assistant_message(api_msg, "stop")
+        self.assertIn("Step 1: Analyze.", result["reasoning"])
+        self.assertIn("Step 2: Solve.", result["reasoning"])
+
+    def test_callback_fires_for_inline_think(self):
+        """Reasoning callback should fire when reasoning is extracted from inline think blocks."""
+        agent = self._make_agent()
+        captured = []
+        agent.reasoning_callback = lambda t: captured.append(t)
+        api_msg = self._build_msg("<think>Deep analysis here.</think>Answer.")
+        agent._build_assistant_message(api_msg, "stop")
+        self.assertEqual(len(captured), 1)
+        self.assertIn("Deep analysis", captured[0])
+
+
+# ---------------------------------------------------------------------------
+# Config defaults
+# ---------------------------------------------------------------------------
+
+class TestConfigDefault(unittest.TestCase):
+    """Verify config default for show_reasoning."""
+
+    def test_default_config_has_show_reasoning(self):
+        from hermes_cli.config import DEFAULT_CONFIG
+        display = DEFAULT_CONFIG.get("display", {})
+        self.assertIn("show_reasoning", display)
+        self.assertFalse(display["show_reasoning"])
+
+
+class TestCommandRegistered(unittest.TestCase):
+    """Verify /reasoning is in the COMMANDS dict."""
+
+    def test_reasoning_in_commands(self):
+        from hermes_cli.commands import COMMANDS
+        self.assertIn("/reasoning", COMMANDS)
+
+
+# ---------------------------------------------------------------------------
+# End-to-end pipeline
+# ---------------------------------------------------------------------------
+
+class TestEndToEndPipeline(unittest.TestCase):
+    """Simulate the full pipeline: extraction -> result dict -> display."""
+
+    def test_openrouter_claude_pipeline(self):
+        from run_agent import AIAgent
+
+        api_message = SimpleNamespace(
+            role="assistant",
+            content="Lists support append().",
+            tool_calls=None,
+            reasoning=None,
+            reasoning_content=None,
+            reasoning_details=[
+                {"type": "reasoning.summary", "summary": "Python list methods."},
+            ],
+        )
+
+        reasoning = AIAgent._extract_reasoning(None, api_message)
+        self.assertIsNotNone(reasoning)
+
+        messages = [
+            {"role": "user", "content": "How do I add items?"},
+            {"role": "assistant", "content": api_message.content, "reasoning": reasoning},
+        ]
+
+        last_reasoning = None
+        for msg in reversed(messages):
+            if msg.get("role") == "assistant" and msg.get("reasoning"):
+                last_reasoning = msg["reasoning"]
+                break
+
+        result = {
+            "final_response": api_message.content,
+            "last_reasoning": last_reasoning,
+        }
+
+        self.assertIn("last_reasoning", result)
+        self.assertIn("Python list methods", result["last_reasoning"])
+
+    def test_no_reasoning_model_pipeline(self):
+        from run_agent import AIAgent
+
+        api_message = SimpleNamespace(content="Paris.", tool_calls=None)
+        reasoning = AIAgent._extract_reasoning(None, api_message)
+        self.assertIsNone(reasoning)
+
+        result = {"final_response": api_message.content, "last_reasoning": reasoning}
+        self.assertIsNone(result["last_reasoning"])
+
+
+# ---------------------------------------------------------------------------
+# Duplicate reasoning box prevention (Bug fix: 3 boxes for 1 reasoning)
+# ---------------------------------------------------------------------------
+
+class TestReasoningDeltasFiredFlag(unittest.TestCase):
+    """_build_assistant_message should not re-fire reasoning_callback when
+    reasoning was already streamed via _fire_reasoning_delta."""
+
+    def _make_agent(self):
+        from run_agent import AIAgent
+        agent = AIAgent.__new__(AIAgent)
+        agent.reasoning_callback = None
+        agent.stream_delta_callback = None
+        agent._reasoning_deltas_fired = False
+        agent.verbose_logging = False
+        return agent
+
+    def test_fire_reasoning_delta_sets_flag(self):
+        agent = self._make_agent()
+        captured = []
+        agent.reasoning_callback = lambda t: captured.append(t)
+        self.assertFalse(agent._reasoning_deltas_fired)
+        agent._fire_reasoning_delta("thinking...")
+        self.assertTrue(agent._reasoning_deltas_fired)
+        self.assertEqual(captured, ["thinking..."])
+
+    def test_build_assistant_message_skips_callback_when_already_streamed(self):
+        """When streaming already fired reasoning deltas, the post-stream
+        _build_assistant_message should NOT re-fire the callback."""
+        agent = self._make_agent()
+        captured = []
+        agent.reasoning_callback = lambda t: captured.append(t)
+        agent.stream_delta_callback = lambda t: None  # streaming is active
+
+        # Simulate streaming having fired reasoning
+        agent._reasoning_deltas_fired = True
+
+        msg = SimpleNamespace(
+            content="I'll merge that.",
+            tool_calls=None,
+            reasoning_content="Let me merge the PR.",
+            reasoning=None,
+            reasoning_details=None,
+        )
+        agent._build_assistant_message(msg, "stop")
+
+        # Callback should NOT have been fired again
+        self.assertEqual(captured, [])
+
+    def test_build_assistant_message_skips_callback_when_streaming_active(self):
+        """When streaming is active, callback should NEVER fire from
+        _build_assistant_message — reasoning was already displayed during the
+        stream (either via reasoning_content deltas or content tag extraction).
+        Any missed reasoning is caught by the CLI post-response fallback."""
+        agent = self._make_agent()
+        captured = []
+        agent.reasoning_callback = lambda t: captured.append(t)
+        agent.stream_delta_callback = lambda t: None  # streaming active
+
+        # Even though _reasoning_deltas_fired is False (reasoning came through
+        # content tags, not reasoning_content deltas), callback should not fire
+        agent._reasoning_deltas_fired = False
+
+        msg = SimpleNamespace(
+            content="I'll merge that.",
+            tool_calls=None,
+            reasoning_content="Let me merge the PR.",
+            reasoning=None,
+            reasoning_details=None,
+        )
+        agent._build_assistant_message(msg, "stop")
+
+        # Callback should NOT fire — streaming is active
+        self.assertEqual(captured, [])
+
+    def test_build_assistant_message_fires_callback_without_streaming(self):
+        """When no streaming is active, callback always fires for structured
+        reasoning."""
+        agent = self._make_agent()
+        captured = []
+        agent.reasoning_callback = lambda t: captured.append(t)
+        # No streaming
+        agent.stream_delta_callback = None
+        agent._reasoning_deltas_fired = False
+
+        msg = SimpleNamespace(
+            content="I'll merge that.",
+            tool_calls=None,
+            reasoning_content="Let me merge the PR.",
+            reasoning=None,
+            reasoning_details=None,
+        )
+        agent._build_assistant_message(msg, "stop")
+
+        self.assertEqual(captured, ["Let me merge the PR."])
+
+
+class TestReasoningShownThisTurnFlag(unittest.TestCase):
+    """Post-response reasoning display should be suppressed when reasoning
+    was already shown during streaming in a tool-calling loop."""
+
+    def _make_cli(self):
+        from cli import HermesCLI
+        cli = HermesCLI.__new__(HermesCLI)
+        cli.show_reasoning = True
+        cli.streaming_enabled = True
+        cli._stream_box_opened = False
+        cli._reasoning_box_opened = False
+        cli._reasoning_stream_started = False
+        cli._reasoning_shown_this_turn = False
+        cli._reasoning_buf = ""
+        cli._stream_buf = ""
+        cli._stream_started = False
+        cli._stream_text_ansi = ""
+        cli._stream_prefilt = ""
+        cli._in_reasoning_block = False
+        cli._reasoning_preview_buf = ""
+        return cli
+
+    @patch("cli._cprint")
+    def test_streaming_reasoning_sets_turn_flag(self, mock_cprint):
+        cli = self._make_cli()
+        self.assertFalse(cli._reasoning_shown_this_turn)
+        cli._stream_reasoning_delta("Thinking about it...")
+        self.assertTrue(cli._reasoning_shown_this_turn)
+
+    @patch("cli._cprint")
+    def test_turn_flag_survives_reset_stream_state(self, mock_cprint):
+        """_reasoning_shown_this_turn must NOT be cleared by
+        _reset_stream_state (called at intermediate turn boundaries)."""
+        cli = self._make_cli()
+        cli._stream_reasoning_delta("Thinking...")
+        self.assertTrue(cli._reasoning_shown_this_turn)
+
+        # Simulate intermediate turn boundary (tool call)
+        cli._reset_stream_state()
+
+        # Flag must persist
+        self.assertTrue(cli._reasoning_shown_this_turn)
+
+    @patch("cli._cprint")
+    def test_turn_flag_cleared_before_new_turn(self, mock_cprint):
+        """The turn flag should be reset at the start of a new user turn.
+        This happens outside _reset_stream_state, at the call site."""
+        cli = self._make_cli()
+        cli._reasoning_shown_this_turn = True
+
+        # Simulate new user turn setup
+        cli._reset_stream_state()
+        cli._reasoning_shown_this_turn = False  # done by process_input
+
+        self.assertFalse(cli._reasoning_shown_this_turn)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/cli/test_resume_display.py

@@ -0,0 +1,488 @@
+"""Tests for session resume history display — _display_resumed_history() and
+_preload_resumed_session().
+
+Verifies that resuming a session shows a compact recap of the previous
+conversation with correct formatting, truncation, and config behavior.
+"""
+
+import os
+import sys
+from io import StringIO
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+
+def _make_cli(config_overrides=None, env_overrides=None, **kwargs):
+    """Create a HermesCLI instance with minimal mocking."""
+    import cli as _cli_mod
+    from cli import HermesCLI
+
+    _clean_config = {
+        "model": {
+            "default": "anthropic/claude-opus-4.6",
+            "base_url": "https://openrouter.ai/api/v1",
+            "provider": "auto",
+        },
+        "display": {"compact": False, "tool_progress": "all", "resume_display": "full"},
+        "agent": {},
+        "terminal": {"env_type": "local"},
+    }
+    if config_overrides:
+        for k, v in config_overrides.items():
+            if isinstance(v, dict) and k in _clean_config and isinstance(_clean_config[k], dict):
+                _clean_config[k].update(v)
+            else:
+                _clean_config[k] = v
+
+    clean_env = {"LLM_MODEL": "", "HERMES_MAX_ITERATIONS": ""}
+    if env_overrides:
+        clean_env.update(env_overrides)
+    with (
+        patch("cli.get_tool_definitions", return_value=[]),
+        patch.dict("os.environ", clean_env, clear=False),
+        patch.dict(_cli_mod.__dict__, {"CLI_CONFIG": _clean_config}),
+    ):
+        return HermesCLI(**kwargs)
+
+
+# ── Sample conversation histories for tests ──────────────────────────
+
+
+def _simple_history():
+    """Two-turn conversation: user → assistant → user → assistant."""
+    return [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is Python?"},
+        {"role": "assistant", "content": "Python is a high-level programming language."},
+        {"role": "user", "content": "How do I install it?"},
+        {"role": "assistant", "content": "You can install Python from python.org."},
+    ]
+
+
+def _tool_call_history():
+    """Conversation with tool calls and tool results."""
+    return [
+        {"role": "system", "content": "system prompt"},
+        {"role": "user", "content": "Search for Python tutorials"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {"name": "web_search", "arguments": '{"query":"python tutorials"}'},
+                },
+                {
+                    "id": "call_2",
+                    "type": "function",
+                    "function": {"name": "web_extract", "arguments": '{"urls":["https://example.com"]}'},
+                },
+            ],
+        },
+        {"role": "tool", "tool_call_id": "call_1", "content": "Found 5 results..."},
+        {"role": "tool", "tool_call_id": "call_2", "content": "Page content..."},
+        {"role": "assistant", "content": "Here are some great Python tutorials I found."},
+    ]
+
+
+def _large_history(n_exchanges=15):
+    """Build a history with many exchanges to test truncation."""
+    msgs = [{"role": "system", "content": "system prompt"}]
+    for i in range(n_exchanges):
+        msgs.append({"role": "user", "content": f"Question #{i + 1}: What is item {i + 1}?"})
+        msgs.append({"role": "assistant", "content": f"Answer #{i + 1}: Item {i + 1} is great."})
+    return msgs
+
+
+def _multimodal_history():
+    """Conversation with multimodal (image) content."""
+    return [
+        {"role": "system", "content": "system prompt"},
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "What's in this image?"},
+                {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}},
+            ],
+        },
+        {"role": "assistant", "content": "I see a cat in the image."},
+    ]
+
+
+# ── Tests for _display_resumed_history ───────────────────────────────
+
+
+class TestDisplayResumedHistory:
+    """_display_resumed_history() renders a Rich panel with conversation recap."""
+
+    def _capture_display(self, cli_obj):
+        """Run _display_resumed_history and capture the Rich console output."""
+        buf = StringIO()
+        cli_obj.console.file = buf
+        cli_obj._display_resumed_history()
+        return buf.getvalue()
+
+    def test_simple_history_shows_user_and_assistant(self):
+        cli = _make_cli()
+        cli.conversation_history = _simple_history()
+        output = self._capture_display(cli)
+
+        assert "You:" in output
+        assert "Hermes:" in output
+        assert "What is Python?" in output
+        assert "Python is a high-level programming language." in output
+        assert "How do I install it?" in output
+
+    def test_system_messages_hidden(self):
+        cli = _make_cli()
+        cli.conversation_history = _simple_history()
+        output = self._capture_display(cli)
+
+        assert "You are a helpful assistant" not in output
+
+    def test_tool_messages_hidden(self):
+        cli = _make_cli()
+        cli.conversation_history = _tool_call_history()
+        output = self._capture_display(cli)
+
+        # Tool result content should NOT appear
+        assert "Found 5 results" not in output
+        assert "Page content" not in output
+
+    def test_tool_calls_shown_as_summary(self):
+        cli = _make_cli()
+        cli.conversation_history = _tool_call_history()
+        output = self._capture_display(cli)
+
+        assert "2 tool calls" in output
+        assert "web_search" in output
+        assert "web_extract" in output
+
+    def test_long_user_message_truncated(self):
+        cli = _make_cli()
+        long_text = "A" * 500
+        cli.conversation_history = [
+            {"role": "user", "content": long_text},
+            {"role": "assistant", "content": "OK."},
+        ]
+        output = self._capture_display(cli)
+
+        # Should have truncation indicator and NOT contain the full 500 chars
+        assert "..." in output
+        assert "A" * 500 not in output
+        # The 300-char truncated text is present but may be line-wrapped by
+        # Rich's panel renderer, so check the total A count in the output
+        a_count = output.count("A")
+        assert 200 <= a_count <= 310  # roughly 300 chars (±panel padding)
+
+    def test_long_assistant_message_truncated(self):
+        cli = _make_cli()
+        long_text = "B" * 400
+        cli.conversation_history = [
+            {"role": "user", "content": "Tell me a lot."},
+            {"role": "assistant", "content": long_text},
+        ]
+        output = self._capture_display(cli)
+
+        assert "..." in output
+        assert "B" * 400 not in output
+
+    def test_multiline_assistant_truncated(self):
+        cli = _make_cli()
+        multi = "\n".join([f"Line {i}" for i in range(20)])
+        cli.conversation_history = [
+            {"role": "user", "content": "Show me lines."},
+            {"role": "assistant", "content": multi},
+        ]
+        output = self._capture_display(cli)
+
+        # First 3 lines should be there
+        assert "Line 0" in output
+        assert "Line 1" in output
+        assert "Line 2" in output
+        # Line 19 should NOT be there (truncated after 3 lines)
+        assert "Line 19" not in output
+
+    def test_large_history_shows_truncation_indicator(self):
+        cli = _make_cli()
+        cli.conversation_history = _large_history(n_exchanges=15)
+        output = self._capture_display(cli)
+
+        # Should show "earlier messages" indicator
+        assert "earlier messages" in output
+        # Last question should still be visible
+        assert "Question #15" in output
+
+    def test_multimodal_content_handled(self):
+        cli = _make_cli()
+        cli.conversation_history = _multimodal_history()
+        output = self._capture_display(cli)
+
+        assert "What's in this image?" in output
+        assert "[image]" in output
+
+    def test_empty_history_no_output(self):
+        cli = _make_cli()
+        cli.conversation_history = []
+        output = self._capture_display(cli)
+
+        assert output.strip() == ""
+
+    def test_minimal_config_suppresses_display(self):
+        cli = _make_cli(config_overrides={"display": {"resume_display": "minimal"}})
+        # resume_display is captured as an instance variable during __init__
+        assert cli.resume_display == "minimal"
+        cli.conversation_history = _simple_history()
+        output = self._capture_display(cli)
+
+        assert output.strip() == ""
+
+    def test_panel_has_title(self):
+        cli = _make_cli()
+        cli.conversation_history = _simple_history()
+        output = self._capture_display(cli)
+
+        assert "Previous Conversation" in output
+
+    def test_assistant_with_no_content_no_tools_skipped(self):
+        """Assistant messages with no visible output (e.g. pure reasoning)
+        are skipped in the recap."""
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": None},
+        ]
+        output = self._capture_display(cli)
+
+        # The assistant entry should be skipped, only the user message shown
+        assert "You:" in output
+        assert "Hermes:" not in output
+
+    def test_only_system_messages_no_output(self):
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "system", "content": "You are helpful."},
+        ]
+        output = self._capture_display(cli)
+
+        assert output.strip() == ""
+
+    def test_reasoning_scratchpad_stripped(self):
+        """<REASONING_SCRATCHPAD> blocks should be stripped from display."""
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "user", "content": "Think about this"},
+            {
+                "role": "assistant",
+                "content": (
+                    "<REASONING_SCRATCHPAD>\nLet me think step by step.\n"
+                    "</REASONING_SCRATCHPAD>\n\nThe answer is 42."
+                ),
+            },
+        ]
+        output = self._capture_display(cli)
+
+        assert "REASONING_SCRATCHPAD" not in output
+        assert "Let me think step by step" not in output
+        assert "The answer is 42" in output
+
+    def test_pure_reasoning_message_skipped(self):
+        """Assistant messages that are only reasoning should be skipped."""
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "user", "content": "Hello"},
+            {
+                "role": "assistant",
+                "content": "<REASONING_SCRATCHPAD>\nJust thinking...\n</REASONING_SCRATCHPAD>",
+            },
+            {"role": "assistant", "content": "Hi there!"},
+        ]
+        output = self._capture_display(cli)
+
+        assert "Just thinking" not in output
+        assert "Hi there!" in output
+
+    def test_assistant_with_text_and_tool_calls(self):
+        """When an assistant message has both text content AND tool_calls."""
+        cli = _make_cli()
+        cli.conversation_history = [
+            {"role": "user", "content": "Do something complex"},
+            {
+                "role": "assistant",
+                "content": "Let me search for that.",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "terminal", "arguments": '{"command":"ls"}'},
+                    }
+                ],
+            },
+        ]
+        output = self._capture_display(cli)
+
+        assert "Let me search for that." in output
+        assert "1 tool call" in output
+        assert "terminal" in output
+
+
+# ── Tests for _preload_resumed_session ──────────────────────────────
+
+
+class TestPreloadResumedSession:
+    """_preload_resumed_session() loads session from DB early."""
+
+    def test_returns_false_when_not_resumed(self):
+        cli = _make_cli()
+        assert cli._preload_resumed_session() is False
+
+    def test_returns_false_when_no_session_db(self):
+        cli = _make_cli(resume="test_session_id")
+        cli._session_db = None
+        assert cli._preload_resumed_session() is False
+
+    def test_returns_false_when_session_not_found(self):
+        cli = _make_cli(resume="nonexistent_session")
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = None
+        cli._session_db = mock_db
+
+        buf = StringIO()
+        cli.console.file = buf
+        result = cli._preload_resumed_session()
+
+        assert result is False
+        output = buf.getvalue()
+        assert "Session not found" in output
+
+    def test_returns_false_when_session_has_no_messages(self):
+        cli = _make_cli(resume="empty_session")
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"id": "empty_session", "title": None}
+        mock_db.get_messages_as_conversation.return_value = []
+        cli._session_db = mock_db
+
+        buf = StringIO()
+        cli.console.file = buf
+        result = cli._preload_resumed_session()
+
+        assert result is False
+        output = buf.getvalue()
+        assert "no messages" in output
+
+    def test_loads_session_successfully(self):
+        cli = _make_cli(resume="good_session")
+        messages = _simple_history()
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"id": "good_session", "title": "Test Session"}
+        mock_db.get_messages_as_conversation.return_value = messages
+        cli._session_db = mock_db
+
+        buf = StringIO()
+        cli.console.file = buf
+        result = cli._preload_resumed_session()
+
+        assert result is True
+        assert cli.conversation_history == messages
+        output = buf.getvalue()
+        assert "Resumed session" in output
+        assert "good_session" in output
+        assert "Test Session" in output
+        assert "2 user messages" in output
+
+    def test_reopens_session_in_db(self):
+        cli = _make_cli(resume="reopen_session")
+        messages = [{"role": "user", "content": "hi"}]
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"id": "reopen_session", "title": None}
+        mock_db.get_messages_as_conversation.return_value = messages
+        mock_conn = MagicMock()
+        mock_db._conn = mock_conn
+        cli._session_db = mock_db
+
+        buf = StringIO()
+        cli.console.file = buf
+        cli._preload_resumed_session()
+
+        # Should have executed UPDATE to clear ended_at
+        mock_conn.execute.assert_called_once()
+        call_args = mock_conn.execute.call_args
+        assert "ended_at = NULL" in call_args[0][0]
+        mock_conn.commit.assert_called_once()
+
+    def test_singular_user_message_grammar(self):
+        """1 user message should say 'message' not 'messages'."""
+        cli = _make_cli(resume="one_msg_session")
+        messages = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+        ]
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"id": "one_msg_session", "title": None}
+        mock_db.get_messages_as_conversation.return_value = messages
+        mock_db._conn = MagicMock()
+        cli._session_db = mock_db
+
+        buf = StringIO()
+        cli.console.file = buf
+        cli._preload_resumed_session()
+
+        output = buf.getvalue()
+        assert "1 user message," in output
+        assert "1 user messages" not in output
+
+
+# ── Integration: _init_agent skips when preloaded ────────────────────
+
+
+class TestInitAgentSkipsPreloaded:
+    """_init_agent() should skip DB load when history is already populated."""
+
+    def test_init_agent_skips_db_when_preloaded(self):
+        """If conversation_history is already set, _init_agent should not
+        reload from the DB."""
+        cli = _make_cli(resume="preloaded_session")
+        cli.conversation_history = _simple_history()
+
+        mock_db = MagicMock()
+        cli._session_db = mock_db
+
+        # _init_agent will fail at credential resolution (no real API key),
+        # but the session-loading block should be skipped entirely
+        with patch.object(cli, "_ensure_runtime_credentials", return_value=False):
+            cli._init_agent()
+
+        # get_messages_as_conversation should NOT have been called
+        mock_db.get_messages_as_conversation.assert_not_called()
+
+
+# ── Config default tests ─────────────────────────────────────────────
+
+
+class TestResumeDisplayConfig:
+    """resume_display config option defaults and behavior."""
+
+    def test_default_config_has_resume_display(self):
+        """DEFAULT_CONFIG in hermes_cli/config.py includes resume_display."""
+        from hermes_cli.config import DEFAULT_CONFIG
+        display = DEFAULT_CONFIG.get("display", {})
+        assert "resume_display" in display
+        assert display["resume_display"] == "full"
+
+    def test_cli_defaults_have_resume_display(self):
+        """cli.py load_cli_config defaults include resume_display."""
+        import cli as _cli_mod
+        from cli import load_cli_config
+
+        with (
+            patch("pathlib.Path.exists", return_value=False),
+            patch.dict("os.environ", {"LLM_MODEL": ""}, clear=False),
+        ):
+            config = load_cli_config()
+
+        display = config.get("display", {})
+        assert display.get("resume_display") == "full"

tests/cli/test_surrogate_sanitization.py

@@ -0,0 +1,154 @@
+"""Tests for surrogate character sanitization in user input.
+
+Surrogates (U+D800..U+DFFF) are invalid in UTF-8 and crash json.dumps()
+inside the OpenAI SDK. They can appear via clipboard paste from rich-text
+editors like Google Docs.
+"""
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+
+from run_agent import (
+    _sanitize_surrogates,
+    _sanitize_messages_surrogates,
+    _SURROGATE_RE,
+)
+
+
+class TestSanitizeSurrogates:
+    """Test the _sanitize_surrogates() helper."""
+
+    def test_normal_text_unchanged(self):
+        text = "Hello, this is normal text with unicode: café ñ 日本語 🎉"
+        assert _sanitize_surrogates(text) == text
+
+    def test_empty_string(self):
+        assert _sanitize_surrogates("") == ""
+
+    def test_single_surrogate_replaced(self):
+        result = _sanitize_surrogates("Hello \udce2 world")
+        assert result == "Hello \ufffd world"
+
+    def test_multiple_surrogates_replaced(self):
+        result = _sanitize_surrogates("a\ud800b\udc00c\udfff")
+        assert result == "a\ufffdb\ufffdc\ufffd"
+
+    def test_all_surrogate_range(self):
+        """Verify the regex catches the full surrogate range."""
+        for cp in [0xD800, 0xD900, 0xDA00, 0xDB00, 0xDC00, 0xDD00, 0xDE00, 0xDF00, 0xDFFF]:
+            text = f"test{chr(cp)}end"
+            result = _sanitize_surrogates(text)
+            assert '\ufffd' in result, f"Surrogate U+{cp:04X} not caught"
+
+    def test_result_is_json_serializable(self):
+        """Sanitized text must survive json.dumps + utf-8 encoding."""
+        dirty = "data \udce2\udcb0 from clipboard"
+        clean = _sanitize_surrogates(dirty)
+        serialized = json.dumps({"content": clean}, ensure_ascii=False)
+        # Must not raise UnicodeEncodeError
+        serialized.encode("utf-8")
+
+    def test_original_surrogates_fail_encoding(self):
+        """Confirm the original bug: surrogates crash utf-8 encoding."""
+        dirty = "data \udce2 from clipboard"
+        serialized = json.dumps({"content": dirty}, ensure_ascii=False)
+        with pytest.raises(UnicodeEncodeError):
+            serialized.encode("utf-8")
+
+
+class TestSanitizeMessagesSurrogates:
+    """Test the _sanitize_messages_surrogates() helper for message lists."""
+
+    def test_clean_messages_returns_false(self):
+        msgs = [
+            {"role": "user", "content": "all clean"},
+            {"role": "assistant", "content": "me too"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is False
+
+    def test_dirty_string_content_sanitized(self):
+        msgs = [
+            {"role": "user", "content": "text with \udce2 surrogate"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"]
+        assert "\udce2" not in msgs[0]["content"]
+
+    def test_dirty_multimodal_content_sanitized(self):
+        msgs = [
+            {"role": "user", "content": [
+                {"type": "text", "text": "multimodal \udce2 content"},
+                {"type": "image_url", "image_url": {"url": "http://example.com"}},
+            ]},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"][0]["text"]
+        assert "\udce2" not in msgs[0]["content"][0]["text"]
+
+    def test_mixed_clean_and_dirty(self):
+        msgs = [
+            {"role": "user", "content": "clean text"},
+            {"role": "user", "content": "dirty \udce2 text"},
+            {"role": "assistant", "content": "clean response"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert msgs[0]["content"] == "clean text"
+        assert "\ufffd" in msgs[1]["content"]
+        assert msgs[2]["content"] == "clean response"
+
+    def test_non_dict_items_skipped(self):
+        msgs = ["not a dict", {"role": "user", "content": "ok"}]
+        assert _sanitize_messages_surrogates(msgs) is False
+
+    def test_tool_messages_sanitized(self):
+        """Tool results could also contain surrogates from file reads etc."""
+        msgs = [
+            {"role": "tool", "content": "result with \udce2 data", "tool_call_id": "x"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"]
+
+
+class TestRunConversationSurrogateSanitization:
+    """Integration: verify run_conversation sanitizes user_message."""
+
+    @patch("run_agent.AIAgent._build_system_prompt")
+    @patch("run_agent.AIAgent._interruptible_streaming_api_call")
+    @patch("run_agent.AIAgent._interruptible_api_call")
+    def test_user_message_surrogates_sanitized(self, mock_api, mock_stream, mock_sys):
+        """Surrogates in user_message are stripped before API call."""
+        from run_agent import AIAgent
+
+        mock_sys.return_value = "system prompt"
+
+        # Mock streaming to return a simple response
+        mock_choice = MagicMock()
+        mock_choice.message.content = "response"
+        mock_choice.message.tool_calls = None
+        mock_choice.message.refusal = None
+        mock_choice.finish_reason = "stop"
+        mock_choice.message.reasoning_content = None
+
+        mock_response = MagicMock()
+        mock_response.choices = [mock_choice]
+        mock_response.usage = MagicMock(prompt_tokens=10, completion_tokens=5, total_tokens=15)
+        mock_response.model = "test-model"
+        mock_response.id = "test-id"
+
+        mock_stream.return_value = mock_response
+        mock_api.return_value = mock_response
+
+        agent = AIAgent(model="test/model", quiet_mode=True, skip_memory=True, skip_context_files=True)
+        agent.client = MagicMock()
+
+        # Pass a message with surrogates
+        result = agent.run_conversation(
+            user_message="test \udce2 message",
+            conversation_history=[],
+        )
+
+        # The message stored in history should have surrogates replaced
+        for msg in result.get("messages", []):
+            if msg.get("role") == "user":
+                assert "\udce2" not in msg["content"], "Surrogate leaked into stored message"
+                assert "\ufffd" in msg["content"], "Replacement char not in stored message"

tests/cli/test_worktree.py

@@ -0,0 +1,635 @@
+"""Tests for git worktree isolation (CLI --worktree / -w flag).
+
+Verifies worktree creation, cleanup, .worktreeinclude handling,
+.gitignore management, and integration with the CLI.  (#652)
+"""
+
+import os
+import shutil
+import subprocess
+import pytest
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+@pytest.fixture
+def git_repo(tmp_path):
+    """Create a temporary git repo for testing."""
+    repo = tmp_path / "test-repo"
+    repo.mkdir()
+    subprocess.run(["git", "init"], cwd=repo, capture_output=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@test.com"],
+        cwd=repo, capture_output=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test"],
+        cwd=repo, capture_output=True,
+    )
+    # Create initial commit (worktrees need at least one commit)
+    (repo / "README.md").write_text("# Test Repo\n")
+    subprocess.run(["git", "add", "."], cwd=repo, capture_output=True)
+    subprocess.run(
+        ["git", "commit", "-m", "Initial commit"],
+        cwd=repo, capture_output=True,
+    )
+    return repo
+
+
+# ---------------------------------------------------------------------------
+# Lightweight reimplementations for testing (avoid importing cli.py)
+# ---------------------------------------------------------------------------
+
+def _git_repo_root(cwd=None):
+    """Test version of _git_repo_root."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+            cwd=cwd,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def _setup_worktree(repo_root):
+    """Test version of _setup_worktree — creates a worktree."""
+    import uuid
+    short_id = uuid.uuid4().hex[:8]
+    wt_name = f"hermes-{short_id}"
+    branch_name = f"hermes/{wt_name}"
+
+    worktrees_dir = Path(repo_root) / ".worktrees"
+    worktrees_dir.mkdir(parents=True, exist_ok=True)
+    wt_path = worktrees_dir / wt_name
+
+    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:
+        return None
+
+    return {
+        "path": str(wt_path),
+        "branch": branch_name,
+        "repo_root": repo_root,
+    }
+
+
+def _cleanup_worktree(info):
+    """Test version of _cleanup_worktree."""
+    wt_path = info["path"]
+    branch = info["branch"]
+    repo_root = info["repo_root"]
+
+    if not Path(wt_path).exists():
+        return
+
+    # Check for uncommitted changes
+    status = subprocess.run(
+        ["git", "status", "--porcelain"],
+        capture_output=True, text=True, timeout=10, cwd=wt_path,
+    )
+    has_changes = bool(status.stdout.strip())
+
+    if has_changes:
+        return False  # Did not clean up
+
+    subprocess.run(
+        ["git", "worktree", "remove", wt_path, "--force"],
+        capture_output=True, text=True, timeout=15, cwd=repo_root,
+    )
+    subprocess.run(
+        ["git", "branch", "-D", branch],
+        capture_output=True, text=True, timeout=10, cwd=repo_root,
+    )
+    return True  # Cleaned up
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestGitRepoDetection:
+    """Test git repo root detection."""
+
+    def test_detects_git_repo(self, git_repo):
+        root = _git_repo_root(cwd=str(git_repo))
+        assert root is not None
+        assert Path(root).resolve() == git_repo.resolve()
+
+    def test_detects_subdirectory(self, git_repo):
+        subdir = git_repo / "src" / "lib"
+        subdir.mkdir(parents=True)
+        root = _git_repo_root(cwd=str(subdir))
+        assert root is not None
+        assert Path(root).resolve() == git_repo.resolve()
+
+    def test_returns_none_outside_repo(self, tmp_path):
+        # tmp_path itself is not a git repo
+        bare_dir = tmp_path / "not-a-repo"
+        bare_dir.mkdir()
+        root = _git_repo_root(cwd=str(bare_dir))
+        assert root is None
+
+
+class TestWorktreeCreation:
+    """Test worktree setup."""
+
+    def test_creates_worktree(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert Path(info["path"]).exists()
+        assert info["branch"].startswith("hermes/hermes-")
+        assert info["repo_root"] == str(git_repo)
+
+        # Verify it's a valid git worktree
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True, text=True, cwd=info["path"],
+        )
+        assert result.stdout.strip() == "true"
+
+    def test_worktree_has_own_branch(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Check branch name in worktree
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, cwd=info["path"],
+        )
+        assert result.stdout.strip() == info["branch"]
+
+    def test_worktree_is_independent(self, git_repo):
+        """Two worktrees from the same repo are independent."""
+        info1 = _setup_worktree(str(git_repo))
+        info2 = _setup_worktree(str(git_repo))
+        assert info1 is not None
+        assert info2 is not None
+        assert info1["path"] != info2["path"]
+        assert info1["branch"] != info2["branch"]
+
+        # Create a file in worktree 1
+        (Path(info1["path"]) / "only-in-wt1.txt").write_text("hello")
+
+        # It should NOT appear in worktree 2
+        assert not (Path(info2["path"]) / "only-in-wt1.txt").exists()
+
+    def test_worktrees_dir_created(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert (git_repo / ".worktrees").is_dir()
+
+    def test_worktree_has_repo_files(self, git_repo):
+        """Worktree should contain the repo's tracked files."""
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert (Path(info["path"]) / "README.md").exists()
+
+
+class TestWorktreeCleanup:
+    """Test worktree cleanup on exit."""
+
+    def test_clean_worktree_removed(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert Path(info["path"]).exists()
+
+        result = _cleanup_worktree(info)
+        assert result is True
+        assert not Path(info["path"]).exists()
+
+    def test_dirty_worktree_kept(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Make uncommitted changes
+        (Path(info["path"]) / "new-file.txt").write_text("uncommitted")
+        subprocess.run(
+            ["git", "add", "new-file.txt"],
+            cwd=info["path"], capture_output=True,
+        )
+
+        result = _cleanup_worktree(info)
+        assert result is False
+        assert Path(info["path"]).exists()  # Still there
+
+    def test_branch_deleted_on_cleanup(self, git_repo):
+        info = _setup_worktree(str(git_repo))
+        branch = info["branch"]
+
+        _cleanup_worktree(info)
+
+        # Branch should be gone
+        result = subprocess.run(
+            ["git", "branch", "--list", branch],
+            capture_output=True, text=True, cwd=str(git_repo),
+        )
+        assert branch not in result.stdout
+
+    def test_cleanup_nonexistent_worktree(self, git_repo):
+        """Cleanup should handle already-removed worktrees gracefully."""
+        info = {
+            "path": str(git_repo / ".worktrees" / "nonexistent"),
+            "branch": "hermes/nonexistent",
+            "repo_root": str(git_repo),
+        }
+        # Should not raise
+        _cleanup_worktree(info)
+
+
+class TestWorktreeInclude:
+    """Test .worktreeinclude file handling."""
+
+    def test_copies_included_files(self, git_repo):
+        """Files listed in .worktreeinclude should be copied to the worktree."""
+        # Create a .env file (gitignored)
+        (git_repo / ".env").write_text("SECRET=abc123")
+        (git_repo / ".gitignore").write_text(".env\n.worktrees/\n")
+        subprocess.run(
+            ["git", "add", ".gitignore"],
+            cwd=str(git_repo), capture_output=True,
+        )
+        subprocess.run(
+            ["git", "commit", "-m", "Add gitignore"],
+            cwd=str(git_repo), capture_output=True,
+        )
+
+        # Create .worktreeinclude
+        (git_repo / ".worktreeinclude").write_text(".env\n")
+
+        # Import and use the real _setup_worktree logic for include handling
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Manually copy .worktreeinclude entries (mirrors cli.py logic)
+        import shutil
+        include_file = git_repo / ".worktreeinclude"
+        wt_path = Path(info["path"])
+        for line in include_file.read_text().splitlines():
+            entry = line.strip()
+            if not entry or entry.startswith("#"):
+                continue
+            src = git_repo / entry
+            dst = wt_path / entry
+            if src.is_file():
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(str(src), str(dst))
+
+        # Verify .env was copied
+        assert (wt_path / ".env").exists()
+        assert (wt_path / ".env").read_text() == "SECRET=abc123"
+
+    def test_ignores_comments_and_blanks(self, git_repo):
+        """Comments and blank lines in .worktreeinclude should be skipped."""
+        (git_repo / ".worktreeinclude").write_text(
+            "# This is a comment\n"
+            "\n"
+            "  # Another comment\n"
+        )
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        # Should not crash — just skip all lines
+
+
+class TestGitignoreManagement:
+    """Test that .worktrees/ is added to .gitignore."""
+
+    def test_adds_to_gitignore(self, git_repo):
+        """Creating a worktree should add .worktrees/ to .gitignore."""
+        # Remove any existing .gitignore
+        gitignore = git_repo / ".gitignore"
+        if gitignore.exists():
+            gitignore.unlink()
+
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Now manually add .worktrees/ to .gitignore (mirrors cli.py logic)
+        _ignore_entry = ".worktrees/"
+        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")
+
+        content = gitignore.read_text()
+        assert ".worktrees/" in content
+
+    def test_does_not_duplicate_gitignore_entry(self, git_repo):
+        """If .worktrees/ is already in .gitignore, don't add again."""
+        gitignore = git_repo / ".gitignore"
+        gitignore.write_text(".worktrees/\n")
+
+        # The check should see it's already there
+        existing = gitignore.read_text()
+        assert ".worktrees/" in existing.splitlines()
+
+
+class TestMultipleWorktrees:
+    """Test running multiple worktrees concurrently (the core use case)."""
+
+    def test_ten_concurrent_worktrees(self, git_repo):
+        """Create 10 worktrees — simulating 10 parallel agents."""
+        worktrees = []
+        for _ in range(10):
+            info = _setup_worktree(str(git_repo))
+            assert info is not None
+            worktrees.append(info)
+
+        # All should exist and be independent
+        paths = [info["path"] for info in worktrees]
+        assert len(set(paths)) == 10  # All unique
+
+        # Each should have the repo files
+        for info in worktrees:
+            assert (Path(info["path"]) / "README.md").exists()
+
+        # Edit a file in one worktree
+        (Path(worktrees[0]["path"]) / "README.md").write_text("Modified in wt0")
+
+        # Others should be unaffected
+        for info in worktrees[1:]:
+            assert (Path(info["path"]) / "README.md").read_text() == "# Test Repo\n"
+
+        # List worktrees via git
+        result = subprocess.run(
+            ["git", "worktree", "list"],
+            capture_output=True, text=True, cwd=str(git_repo),
+        )
+        # Should have 11 entries: main + 10 worktrees
+        lines = [l for l in result.stdout.strip().splitlines() if l.strip()]
+        assert len(lines) == 11
+
+        # Cleanup all
+        for info in worktrees:
+            # Discard changes first so cleanup works
+            subprocess.run(
+                ["git", "checkout", "--", "."],
+                cwd=info["path"], capture_output=True,
+            )
+            _cleanup_worktree(info)
+
+        # All should be removed
+        for info in worktrees:
+            assert not Path(info["path"]).exists()
+
+
+class TestWorktreeDirectorySymlink:
+    """Test .worktreeinclude with directories (symlinked)."""
+
+    def test_symlinks_directory(self, git_repo):
+        """Directories in .worktreeinclude should be symlinked."""
+        # Create a .venv directory
+        venv_dir = git_repo / ".venv" / "lib"
+        venv_dir.mkdir(parents=True)
+        (venv_dir / "marker.txt").write_text("venv marker")
+        (git_repo / ".gitignore").write_text(".venv/\n.worktrees/\n")
+        subprocess.run(
+            ["git", "add", ".gitignore"], cwd=str(git_repo), capture_output=True
+        )
+        subprocess.run(
+            ["git", "commit", "-m", "gitignore"], cwd=str(git_repo), capture_output=True
+        )
+
+        (git_repo / ".worktreeinclude").write_text(".venv/\n")
+
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        wt_path = Path(info["path"])
+        src = git_repo / ".venv"
+        dst = wt_path / ".venv"
+
+        # Manually symlink (mirrors cli.py logic)
+        if not dst.exists():
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            os.symlink(str(src.resolve()), str(dst))
+
+        assert dst.is_symlink()
+        assert (dst / "lib" / "marker.txt").read_text() == "venv marker"
+
+
+class TestStaleWorktreePruning:
+    """Test _prune_stale_worktrees garbage collection."""
+
+    def test_prunes_old_clean_worktree(self, git_repo):
+        """Old clean worktrees should be removed on prune."""
+        import time
+
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert Path(info["path"]).exists()
+
+        # Make the worktree look old (set mtime to 25h ago)
+        old_time = time.time() - (25 * 3600)
+        os.utime(info["path"], (old_time, old_time))
+
+        # Reimplementation of prune logic (matches cli.py)
+        worktrees_dir = git_repo / ".worktrees"
+        cutoff = time.time() - (24 * 3600)
+
+        for entry in worktrees_dir.iterdir():
+            if not entry.is_dir() or not entry.name.startswith("hermes-"):
+                continue
+            try:
+                mtime = entry.stat().st_mtime
+                if mtime > cutoff:
+                    continue
+            except Exception:
+                continue
+
+            status = subprocess.run(
+                ["git", "status", "--porcelain"],
+                capture_output=True, text=True, timeout=5, cwd=str(entry),
+            )
+            if status.stdout.strip():
+                continue
+
+            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=str(git_repo),
+            )
+            if branch:
+                subprocess.run(
+                    ["git", "branch", "-D", branch],
+                    capture_output=True, text=True, timeout=10, cwd=str(git_repo),
+                )
+
+        assert not Path(info["path"]).exists()
+
+    def test_keeps_recent_worktree(self, git_repo):
+        """Recent worktrees should NOT be pruned."""
+        import time
+
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Don't modify mtime — it's recent
+        worktrees_dir = git_repo / ".worktrees"
+        cutoff = time.time() - (24 * 3600)
+
+        pruned = False
+        for entry in worktrees_dir.iterdir():
+            if not entry.is_dir() or not entry.name.startswith("hermes-"):
+                continue
+            mtime = entry.stat().st_mtime
+            if mtime > cutoff:
+                continue  # Too recent
+            pruned = True
+
+        assert not pruned
+        assert Path(info["path"]).exists()
+
+    def test_keeps_dirty_old_worktree(self, git_repo):
+        """Old worktrees with uncommitted changes should NOT be pruned."""
+        import time
+
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # Make it dirty
+        (Path(info["path"]) / "dirty.txt").write_text("uncommitted")
+        subprocess.run(
+            ["git", "add", "dirty.txt"],
+            cwd=info["path"], capture_output=True,
+        )
+
+        # Make it old
+        old_time = time.time() - (25 * 3600)
+        os.utime(info["path"], (old_time, old_time))
+
+        # Check if it would be pruned
+        status = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True, text=True, cwd=info["path"],
+        )
+        has_changes = bool(status.stdout.strip())
+        assert has_changes  # Should be dirty → not pruned
+        assert Path(info["path"]).exists()
+
+
+class TestEdgeCases:
+    """Test edge cases for robustness."""
+
+    def test_no_commits_repo(self, tmp_path):
+        """Worktree creation should fail gracefully on a repo with no commits."""
+        repo = tmp_path / "empty-repo"
+        repo.mkdir()
+        subprocess.run(["git", "init"], cwd=str(repo), capture_output=True)
+
+        info = _setup_worktree(str(repo))
+        assert info is None  # Should fail gracefully
+
+    def test_not_a_git_repo(self, tmp_path):
+        """Repo detection should return None for non-git directories."""
+        bare = tmp_path / "not-git"
+        bare.mkdir()
+        root = _git_repo_root(cwd=str(bare))
+        assert root is None
+
+    def test_worktrees_dir_already_exists(self, git_repo):
+        """Should work fine if .worktrees/ already exists."""
+        (git_repo / ".worktrees").mkdir(exist_ok=True)
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+        assert Path(info["path"]).exists()
+
+
+class TestCLIFlagLogic:
+    """Test the flag/config OR logic from main()."""
+
+    def test_worktree_flag_triggers(self):
+        """--worktree flag should trigger worktree creation."""
+        worktree = True
+        w = False
+        config_worktree = False
+        use_worktree = worktree or w or config_worktree
+        assert use_worktree
+
+    def test_w_flag_triggers(self):
+        """-w flag should trigger worktree creation."""
+        worktree = False
+        w = True
+        config_worktree = False
+        use_worktree = worktree or w or config_worktree
+        assert use_worktree
+
+    def test_config_triggers(self):
+        """worktree: true in config should trigger worktree creation."""
+        worktree = False
+        w = False
+        config_worktree = True
+        use_worktree = worktree or w or config_worktree
+        assert use_worktree
+
+    def test_none_set_no_trigger(self):
+        """No flags and no config should not trigger."""
+        worktree = False
+        w = False
+        config_worktree = False
+        use_worktree = worktree or w or config_worktree
+        assert not use_worktree
+
+
+class TestTerminalCWDIntegration:
+    """Test that TERMINAL_CWD is correctly set to the worktree path."""
+
+    def test_terminal_cwd_set(self, git_repo):
+        """After worktree setup, TERMINAL_CWD should point to the worktree."""
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # This is what main() does:
+        os.environ["TERMINAL_CWD"] = info["path"]
+        assert os.environ["TERMINAL_CWD"] == info["path"]
+        assert Path(os.environ["TERMINAL_CWD"]).exists()
+
+        # Clean up env
+        del os.environ["TERMINAL_CWD"]
+
+    def test_terminal_cwd_is_valid_git_repo(self, git_repo):
+        """The TERMINAL_CWD worktree should be a valid git working tree."""
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True, text=True, cwd=info["path"],
+        )
+        assert result.stdout.strip() == "true"
+
+
+class TestSystemPromptInjection:
+    """Test that the agent gets worktree context in its system prompt."""
+
+    def test_prompt_note_format(self, git_repo):
+        """Verify the system prompt note contains all required info."""
+        info = _setup_worktree(str(git_repo))
+        assert info is not None
+
+        # This is what main() does:
+        wt_note = (
+            f"\n\n[System note: You are working in an isolated git worktree at "
+            f"{info['path']}. Your branch is `{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 {info['repo_root']}.]"
+        )
+
+        assert info["path"] in wt_note
+        assert info["branch"] in wt_note
+        assert info["repo_root"] in wt_note
+        assert "isolated git worktree" in wt_note
+        assert "commit and push" in wt_note

tests/cli/test_worktree_security.py

@@ -0,0 +1,130 @@
+"""Security-focused integration tests for CLI worktree setup."""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def git_repo(tmp_path):
+    """Create a temporary git repo for testing real cli._setup_worktree behavior."""
+    repo = tmp_path / "test-repo"
+    repo.mkdir()
+    subprocess.run(["git", "init"], cwd=repo, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=repo, check=True, capture_output=True)
+    (repo / "README.md").write_text("# Test Repo\n")
+    subprocess.run(["git", "add", "."], cwd=repo, check=True, capture_output=True)
+    subprocess.run(["git", "commit", "-m", "Initial commit"], cwd=repo, check=True, capture_output=True)
+    return repo
+
+
+def _force_remove_worktree(info: dict | None) -> None:
+    if not info:
+        return
+    subprocess.run(
+        ["git", "worktree", "remove", info["path"], "--force"],
+        cwd=info["repo_root"],
+        capture_output=True,
+        check=False,
+    )
+    subprocess.run(
+        ["git", "branch", "-D", info["branch"]],
+        cwd=info["repo_root"],
+        capture_output=True,
+        check=False,
+    )
+
+
+class TestWorktreeIncludeSecurity:
+    def test_rejects_parent_directory_file_traversal(self, git_repo):
+        import cli as cli_mod
+
+        outside_file = git_repo.parent / "sensitive.txt"
+        outside_file.write_text("SENSITIVE DATA")
+        (git_repo / ".worktreeinclude").write_text("../sensitive.txt\n")
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+
+            wt_path = Path(info["path"])
+            assert not (wt_path.parent / "sensitive.txt").exists()
+            assert not (wt_path / "../sensitive.txt").resolve().exists()
+        finally:
+            _force_remove_worktree(info)
+
+    def test_rejects_parent_directory_directory_traversal(self, git_repo):
+        import cli as cli_mod
+
+        outside_dir = git_repo.parent / "outside-dir"
+        outside_dir.mkdir()
+        (outside_dir / "secret.txt").write_text("SENSITIVE DIR DATA")
+        (git_repo / ".worktreeinclude").write_text("../outside-dir\n")
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+
+            wt_path = Path(info["path"])
+            escaped_dir = wt_path.parent / "outside-dir"
+            assert not escaped_dir.exists()
+            assert not escaped_dir.is_symlink()
+        finally:
+            _force_remove_worktree(info)
+
+    def test_rejects_symlink_that_resolves_outside_repo(self, git_repo):
+        import cli as cli_mod
+
+        outside_file = git_repo.parent / "linked-secret.txt"
+        outside_file.write_text("LINKED SECRET")
+        (git_repo / "leak.txt").symlink_to(outside_file)
+        (git_repo / ".worktreeinclude").write_text("leak.txt\n")
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+
+            assert not (Path(info["path"]) / "leak.txt").exists()
+        finally:
+            _force_remove_worktree(info)
+
+    def test_allows_valid_file_include(self, git_repo):
+        import cli as cli_mod
+
+        (git_repo / ".env").write_text("SECRET=***\n")
+        (git_repo / ".worktreeinclude").write_text(".env\n")
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+
+            copied = Path(info["path"]) / ".env"
+            assert copied.exists()
+            assert copied.read_text() == "SECRET=***\n"
+        finally:
+            _force_remove_worktree(info)
+
+    def test_allows_valid_directory_include(self, git_repo):
+        import cli as cli_mod
+
+        assets_dir = git_repo / ".venv" / "lib"
+        assets_dir.mkdir(parents=True)
+        (assets_dir / "marker.txt").write_text("venv marker")
+        (git_repo / ".worktreeinclude").write_text(".venv\n")
+
+        info = None
+        try:
+            info = cli_mod._setup_worktree(str(git_repo))
+            assert info is not None
+
+            linked_dir = Path(info["path"]) / ".venv"
+            assert linked_dir.is_symlink()
+            assert (linked_dir / "lib" / "marker.txt").read_text() == "venv marker"
+        finally:
+            _force_remove_worktree(info)