comate-cli 0.10.0__tar.gz → 0.10.2__tar.gz

{comate_cli-0.10.0 → comate_cli-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.10.0
+Version: 0.10.2
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/main.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import atexit
 import asyncio
+from contextlib import nullcontext
 import logging
 import os
 import signal
@@ -403,6 +404,27 @@ def _read_stdin_if_ready(
         return str(read()) if callable(read) else ""
 
 
+def _build_wellformed_input():
+    """Build terminal input that replaces malformed bytes instead of surrogates."""
+    from prompt_toolkit.input import create_input
+
+    inp = create_input()
+    # Only POSIX 的 Vt100Input 用 PosixStdinReader。Windows 返回 Win32Input，
+    # 且 prompt_toolkit.input.vt100 顶层 `assert sys.platform != "win32"`，
+    # 因此必须先判平台再 import，否则 Windows 交互启动会崩。
+    if sys.platform == "win32":
+        return inp
+
+    from prompt_toolkit.input.posix_utils import PosixStdinReader
+    from prompt_toolkit.input.vt100 import Vt100Input
+
+    if isinstance(inp, Vt100Input):
+        inp.stdin_reader = PosixStdinReader(
+            inp.fileno(), errors="replace", encoding=inp.stdin.encoding
+        )
+    return inp
+
+
 def main(argv: list[str] | None = None, *, profile=None) -> None:
     from comate_cli.distribution import DEFAULT_PROFILE
 
@@ -460,22 +482,31 @@ def main(argv: list[str] | None = None, *, profile=None) -> None:
             raise SystemExit(1)
         print_message = "\n\n".join(parts)
 
+    interactive = not rpc_stdio and print_message is None
+    if interactive:
+        from prompt_toolkit.application import create_app_session
+
+        input_session = create_app_session(input=_build_wellformed_input())
+    else:
+        input_session = nullcontext()
+
     try:
-        asyncio.run(
-            run(
-                rpc_stdio=rpc_stdio,
-                resume_session_id=resume_session_id,
-                resume_select=resume_select,
-                print_message=print_message,
-                print_output_format=print_output_format,
-                add_dirs=add_dirs,
-                yolo=yolo,
-                process_start_perf=_PROCESS_START_PERF,
-                app_import_start_perf=_app_import_start_perf,
-                app_import_done_perf=_app_import_done_perf,
-                profile=profile,
+        with input_session:
+            asyncio.run(
+                run(
+                    rpc_stdio=rpc_stdio,
+                    resume_session_id=resume_session_id,
+                    resume_select=resume_select,
+                    print_message=print_message,
+                    print_output_format=print_output_format,
+                    add_dirs=add_dirs,
+                    yolo=yolo,
+                    process_start_perf=_PROCESS_START_PERF,
+                    app_import_start_perf=_app_import_start_perf,
+                    app_import_done_perf=_app_import_done_perf,
+                    profile=profile,
+                )
             )
-        )
     except KeyboardInterrupt:
         noise_guard.begin_shutdown()
     finally:

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/app.py

@@ -310,7 +310,7 @@ def _import_sdk_agent_components(
     profiler: StartupProfiler | None = None,
 ) -> tuple[type, type, type, type]:
     with _profile_section(profiler, "main.import.sdk_agent"):
-        from comate_agent_sdk.agent.compaction import CompactionConfig
+        from comate_agent_sdk.agent.compaction.models import CompactionConfig
         from comate_agent_sdk.agent.options import AgentConfig
         from comate_agent_sdk.agent.service import Agent
         from comate_agent_sdk.context import EnvOptions

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/codenames.py

@@ -3,15 +3,23 @@
 from __future__ import annotations
 
 CODENAMES: dict[str, str] = {
-    "0.11.1": "Fable 5 Verified",
-    "0.11.0": "Fable 5 Verified",
     "0.3.4": "",
     "0.3.3": "Update for My Brothers",
     "0.3.2": "We are with Ukraine",
 }
 
+SERIES_CODENAMES: dict[str, str] = {
+    "0.10.": "Fable 5 Verified",
+}
+
 
 def get_codename(ver: str) -> str | None:
     """Return codename for a version string like '0.3.2' or 'v0.3.2'."""
     stripped = ver.lstrip("v")
-    return CODENAMES.get(stripped)
+    exact = CODENAMES.get(stripped)
+    if exact is not None:
+        return exact
+    for prefix, codename in SERIES_CODENAMES.items():
+        if stripped.startswith(prefix):
+            return codename
+    return None

comate_cli-0.10.2/comate_cli/terminal_agent/goal_edit_view.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from prompt_toolkit.document import Document
+from prompt_toolkit.layout import HSplit, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.layout.dimension import Dimension
+from prompt_toolkit.widgets import TextArea
+
+from comate_cli.terminal_agent.figures import HEAVY_HORIZONTAL
+
+
+class GoalEditView:
+    def __init__(self) -> None:
+        self._goal_id: str | None = None
+        self._error: str = ""
+        self._text_area = TextArea(
+            text="",
+            multiline=True,
+            wrap_lines=True,
+            height=Dimension(min=3, max=8),
+            style="class:goal_edit.body",
+        )
+        self._root = HSplit(
+            [
+                Window(
+                    content=FormattedTextControl(text=self._title_fragments),
+                    height=1,
+                    dont_extend_height=True,
+                    style="class:goal_edit.title",
+                ),
+                self._text_area,
+                Window(height=1, char=HEAVY_HORIZONTAL, style="class:goal_edit.divider"),
+                Window(
+                    content=FormattedTextControl(text=self._footer_fragments),
+                    height=1,
+                    dont_extend_height=True,
+                    style="class:goal_edit.footer",
+                ),
+            ]
+        )
+
+    @property
+    def container(self) -> HSplit:
+        return self._root
+
+    def focus_target(self) -> Window:
+        return self._text_area.window
+
+    @property
+    def goal_id(self) -> str | None:
+        return self._goal_id
+
+    def enter(self, *, goal_id: str, objective: str) -> None:
+        self._goal_id = goal_id
+        self._error = ""
+        self._text_area.buffer.set_document(
+            Document(objective, cursor_position=len(objective)),
+            bypass_readonly=True,
+        )
+
+    def clear(self) -> None:
+        self._goal_id = None
+        self._error = ""
+        self._text_area.buffer.set_document(
+            Document("", cursor_position=0),
+            bypass_readonly=True,
+        )
+
+    def current_text(self) -> str:
+        return self._text_area.buffer.text
+
+    def set_error(self, message: str) -> None:
+        self._error = str(message)
+
+    def _title_fragments(self) -> list[tuple[str, str]]:
+        return [("class:goal_edit.title", "  Edit Goal")]
+
+    def _footer_fragments(self) -> list[tuple[str, str]]:
+        if self._error:
+            return [("class:goal_edit.error", f"  {self._error}")]
+        return [
+            (
+                "class:goal_edit.hint",
+                "  enter save  |  ctrl+j newline  |  esc cancel",
+            )
+        ]

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/logo.py

@@ -210,8 +210,7 @@ def _append_codename(text: Text, codename: str) -> None:
         text.append(codename, style=_CODENAME_STYLE)
         return
 
-    text.append("Fable ", style=_CODENAME_STYLE)
-    text.append("5", style=_FABLE_VERIFIED_NUMBER_STYLE)
+    text.append("Fable 5", style=_FABLE_VERIFIED_NUMBER_STYLE)
     text.append(" Verified", style=_CODENAME_STYLE)
 
 

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/slash_commands.py

@@ -150,6 +150,21 @@ SLASH_COMMAND_SPECS: tuple[SlashCommandSpec, ...] = (
     ),
 )
 SLASH_COMMANDS: tuple[str, ...] = tuple(f"/{cmd.name}" for cmd in SLASH_COMMAND_SPECS)
+ALLOW_WHEN_BUSY_SLASH_COMMANDS: frozenset[str] = frozenset(
+    {
+        "help",
+        "session",
+        "usage",
+        "context",
+        "skills",
+        "mcp",
+        "exit",
+        "plugin",
+        "reload-plugins",
+        "btw",
+        "goal",
+    }
+)
 
 
 class SlashCommandCompleter(Completer):

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/theme.py

@@ -170,6 +170,12 @@ def main_tui_style_dict() -> dict[str, str]:
         "goal_resume.description.selected": f"fg:{ACCENT_SOFT}",
         "goal_resume.footer": f"bg:default {TEXT_MUTED}",
         "goal_resume.hint": f"fg:{TEXT_FAINT}",
+        "goal_edit.body": f"bg:default {TEXT}",
+        "goal_edit.title": f"bg:default {TEXT_BRIGHT} bold",
+        "goal_edit.divider": f"fg:{LINE}",
+        "goal_edit.footer": f"bg:default {TEXT_MUTED}",
+        "goal_edit.hint": f"fg:{TEXT_FAINT}",
+        "goal_edit.error": f"fg:{ERROR}",
         # completion
         "completion.status": f"bg:default {TEXT_MUTED}",
         "completion.status.item": f"bg:default {TEXT_MUTED}",

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui.py

@@ -62,6 +62,7 @@ from comate_cli.terminal_agent.goal_resume_view import (
     GoalResumeActionKind,
     GoalResumePromptUI,
 )
+from comate_cli.terminal_agent.goal_edit_view import GoalEditView
 from comate_cli.terminal_agent.mention_completer import LocalFileMentionCompleter
 from comate_cli.terminal_agent.path_context_hint import build_path_context_hint
 from comate_cli.terminal_agent.custom_slash_commands import (
@@ -86,6 +87,7 @@ from comate_cli.terminal_agent.selection_menu import (
     SelectionMenuUI,
 )
 from comate_cli.terminal_agent.slash_commands import (
+    ALLOW_WHEN_BUSY_SLASH_COMMANDS,
     SLASH_COMMAND_SPECS,
     SlashArgumentHintAutoSuggest,
     SlashCommandCompleter,
@@ -466,6 +468,7 @@ class TerminalAgentTUI(
         self._statusline_ui = StatuslinePickerUI()
         self._goal_resume_ui = GoalResumePromptUI()
         self._goal_resume_action_pending = False
+        self._goal_edit_view = GoalEditView()
         self._install_view = MarketplaceInstallView()
         self._mcp_connecting_view = McpConnectingView()
         self._btw_view = BtwView()
@@ -650,6 +653,10 @@ class TerminalAgentTUI(
             content=self._goal_resume_ui.container,
             filter=Condition(lambda: self._ui_mode == UIMode.GOAL_RESUME),
         )
+        self._goal_edit_container = ConditionalContainer(
+            content=self._goal_edit_view.container,
+            filter=Condition(lambda: self._ui_mode == UIMode.GOAL_EDIT),
+        )
 
         # idle 时 todo/queue 全部隐藏，它们之间的分隔空行也应该一并消失，
         # 否则多余的固定高度会导致 prompt_toolkit 非全屏渲染时高度波动 → scrollback 污染。
@@ -716,6 +723,7 @@ class TerminalAgentTUI(
                 self._config_container,
                 self._statusline_container,
                 self._goal_resume_container,
+                self._goal_edit_container,
                 Window(height=1, char=HEAVY_HORIZONTAL, style="class:input.separator"),
                 self._bottom_container,
             ],
@@ -1032,25 +1040,15 @@ class TerminalAgentTUI(
             "config": self._slash_config,
             "statusline": self._slash_statusline,
         }
-        allow_when_busy = {
-            "help",
-            "session",
-            "usage",
-            "context",
-            "skills",
-            "mcp",
-            "exit",
-            "plugin",
-            "reload-plugins",
-            "btw",
-        }
-
         for spec in SLASH_COMMAND_SPECS:
             handler = handlers.get(spec.name)
             if handler is None:
                 logger.warning(f"missing slash command handler: {spec.name}")
                 continue
-            if spec.name in allow_when_busy and spec.execution_kind != "local":
+            if (
+                spec.name in ALLOW_WHEN_BUSY_SLASH_COMMANDS
+                and spec.execution_kind != "local"
+            ):
                 raise ValueError(
                     f"slash command /{spec.name} cannot be allow_when_busy when "
                     f"execution_kind={spec.execution_kind}"
@@ -1058,7 +1056,7 @@ class TerminalAgentTUI(
             self._slash_registry.register(
                 spec=spec,
                 handler=handler,
-                allow_when_busy=spec.name in allow_when_busy,
+                allow_when_busy=spec.name in ALLOW_WHEN_BUSY_SLASH_COMMANDS,
                 source="builtin",
                 argument_hint=spec.argument_hint,
             )

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui_parts/commands.py

@@ -97,12 +97,6 @@ class CommandsMixin:
         self._renderer.append_system_message(normalized, severity=severity)
 
     def _cycle_agent_mode(self) -> None:
-        if self._busy:
-            self._renderer.append_system_message(
-                "A task is currently running. Please switch modes after this turn completes.",
-            )
-            self._refresh_layers()
-            return
         try:
             cycle_permission_mode = getattr(self._session, "cycle_permission_mode", None)
             if not callable(cycle_permission_mode):
@@ -251,10 +245,7 @@ class CommandsMixin:
         if command == "edit":
             objective = remainder.strip()
             if not objective:
-                self._append_slash_command_result(
-                    "Usage: /goal edit <objective>",
-                    severity="error",
-                )
+                self._open_goal_edit_view()
                 return
             await self._run_goal_mutation(
                 self._session.edit_goal(objective),
@@ -336,6 +327,59 @@ class CommandsMixin:
             success_prefix="Goal budget updated",
         )
 
+    def _open_goal_edit_view(self) -> None:
+        snapshot = self._session.current_goal_snapshot()
+        if snapshot is None:
+            self._append_slash_command_result(
+                "No goal to edit. Use /goal <objective> to create one.",
+                severity="error",
+            )
+            return
+        self._goal_edit_view.enter(
+            goal_id=snapshot.goal_id,
+            objective=snapshot.objective,
+        )
+        self._set_ui_mode(UIMode.GOAL_EDIT)
+        self._sync_focus_for_mode()
+        self._invalidate()
+
+    def _handle_goal_edit_save(self) -> None:
+        objective = self._goal_edit_view.current_text().strip()
+        if not objective:
+            self._goal_edit_view.set_error("Objective cannot be empty.")
+            self._invalidate()
+            return
+        self._schedule_background(self._apply_goal_edit(objective))
+
+    def _handle_goal_edit_cancel(self) -> None:
+        self._goal_edit_view.clear()
+        self._set_ui_mode(UIMode.NORMAL)
+        self._sync_focus_for_mode()
+        self._renderer.seed_user_message("/goal edit")
+        self._renderer.append_subtitle("Goal edit cancelled.")
+        self._refresh_layers()
+
+    async def _apply_goal_edit(self, objective: str) -> None:
+        try:
+            snapshot = await self._session.edit_goal(objective)
+        except (ChatSessionError, ValueError, RuntimeError) as exc:
+            self._goal_edit_view.clear()
+            self._set_ui_mode(UIMode.NORMAL)
+            self._sync_focus_for_mode()
+            self._renderer.seed_user_message("/goal edit")
+            self._renderer.append_subtitle(str(exc), severity="error")
+            self._refresh_layers()
+            return
+        await self._refresh_status_after_goal_update()
+        self._goal_edit_view.clear()
+        self._set_ui_mode(UIMode.NORMAL)
+        self._sync_focus_for_mode()
+        self._renderer.seed_user_message("/goal edit")
+        self._renderer.append_subtitle(
+            f"Goal updated: {self._format_goal_summary(snapshot)}"
+        )
+        self._refresh_layers()
+
     async def _run_goal_mutation(self, awaitable: Any, *, success_prefix: str) -> None:
         try:
             snapshot = await awaitable

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui_parts/history_sync.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Any
 
 from prompt_toolkit.application import run_in_terminal
-from rich.console import Console
+from rich.console import Console, detect_legacy_windows
 
 from comate_agent_sdk.agent.runner_engine.projection.tool_result_projection import (
     extract_read_metadata,
@@ -410,21 +410,34 @@ class HistorySyncMixin:
             pending[-1].entry_type == "thinking" and busy
         )
 
-        # 预渲染：Rich markdown 渲染 + ANSI 生成在 UI 仍在屏上时完成，
-        # run_in_terminal 的 erase->redraw 间隙内只剩纯 write+flush。
-        prerender_buffer = io.StringIO()
-        prerender_console = Console(
-            file=prerender_buffer,
-            force_terminal=True,
-            width=self._terminal_width(),
-        )
-        print_history_group_sync(prerender_console, group)
-        ansi_payload = prerender_buffer.getvalue()
+        # scrollback 渲染目标按终端 VT 能力分流：
+        # - 非 legacy 终端保留 StringIO 预渲染，缩短 run_in_terminal 的擦屏窗口。
+        # - legacy Windows conhost 必须直渲真 stdout，才能命中 Rich 的 Win32 上色分支。
+        ansi_payload: str | None
+        if detect_legacy_windows():
+            ansi_payload = None
+        else:
+            prerender_buffer = io.StringIO()
+            prerender_console = Console(
+                file=prerender_buffer,
+                force_terminal=True,
+                width=self._terminal_width(),
+            )
+            print_history_group_sync(prerender_console, group)
+            ansi_payload = prerender_buffer.getvalue()
 
         def _print() -> None:
             out = sys.__stdout__ or sys.stdout
-            out.write(ansi_payload)
-            out.flush()
+            if ansi_payload is None:
+                scrollback_console = Console(
+                    file=out,
+                    force_terminal=True,
+                    width=self._terminal_width(),
+                )
+                print_history_group_sync(scrollback_console, group)
+            else:
+                out.write(ansi_payload)
+                out.flush()
             # 如果刚 print 了 user entry 且 staging 仍在，在同一个
             # run_in_terminal 原子窗口内清除 staging，让 Layout 重渲染时
             # staging 行已经消失——erase + print + repaint 零时间差。

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui_parts/input_behavior.py

@@ -171,6 +171,9 @@ class InputBehaviorMixin:
         if self._ui_mode == UIMode.GOAL_RESUME:
             self._app.layout.focus(self._goal_resume_ui.focus_target())
             return
+        if self._ui_mode == UIMode.GOAL_EDIT:
+            self._app.layout.focus(self._goal_edit_view.focus_target())
+            return
         self._app.layout.focus(self._input_area.window)
 
     def _handle_question_action(self, action: QuestionAction | None) -> None:

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui_parts/key_bindings.py

@@ -119,6 +119,7 @@ class KeyBindingsMixin:
         config_mode = Condition(lambda: self._ui_mode == UIMode.CONFIG)
         statusline_mode = Condition(lambda: self._ui_mode == UIMode.STATUSLINE)
         goal_resume_mode = Condition(lambda: self._ui_mode == UIMode.GOAL_RESUME)
+        goal_edit_mode = Condition(lambda: self._ui_mode == UIMode.GOAL_EDIT)
         todo_panel_expanded = Condition(
             lambda: self._todo_panel_expanded and self._renderer.has_active_todos()
         )
@@ -282,6 +283,15 @@ class KeyBindingsMixin:
             self._sync_focus_for_mode()
             self._invalidate()
 
+        @bindings.add(
+            "s-tab",
+            filter=tool_approval_mode & ~tool_approval_feedback_focused,
+            eager=True,
+        )
+        def _tool_approval_cycle_mode(event) -> None:
+            del event
+            self._cycle_agent_mode()
+
         @bindings.add("enter", filter=plugin_mode, eager=True)
         def _plugin_enter(event) -> None:
             del event
@@ -596,6 +606,21 @@ class KeyBindingsMixin:
             self._handle_goal_resume_action(self._goal_resume_ui.handle_escape())
             self._invalidate()
 
+        # ---- GOAL_EDIT mode key bindings ----
+        @bindings.add("enter", filter=goal_edit_mode, eager=True)
+        def _goal_edit_save(event) -> None:
+            del event
+            self._handle_goal_edit_save()
+
+        @bindings.add("c-j", filter=goal_edit_mode, eager=True)
+        def _goal_edit_newline(event) -> None:
+            event.current_buffer.insert_text("\n")
+
+        @bindings.add("escape", filter=goal_edit_mode)
+        def _goal_edit_cancel(event) -> None:
+            del event
+            self._handle_goal_edit_cancel()
+
         @bindings.add("enter", filter=question_mode)
         def _question_enter(event) -> None:
             del event

{comate_cli-0.10.0 → comate_cli-0.10.2}/comate_cli/terminal_agent/tui_parts/ui_mode.py

@@ -15,3 +15,4 @@ class UIMode(Enum):
     CONFIG = "config"
     STATUSLINE = "statusline"
     GOAL_RESUME = "goal_resume"
+    GOAL_EDIT = "goal_edit"

{comate_cli-0.10.0 → comate_cli-0.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "comate-cli"
-version = "0.10.0"
+version = "0.10.2"
 description = "Comate terminal CLI built on comate-agent-sdk"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

comate_cli-0.10.2/tests/test_busy_slash_gating.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import unittest
+
+from comate_cli.terminal_agent.slash_commands import (
+    ALLOW_WHEN_BUSY_SLASH_COMMANDS,
+    SLASH_COMMAND_SPECS,
+    SlashCommandSpec,
+)
+from comate_cli.terminal_agent.tui_parts.commands import CommandsMixin
+from comate_cli.terminal_agent.tui_parts.slash_command_registry import (
+    SlashCommandRegistry,
+)
+
+
+class TestBusyWhitelistContract(unittest.TestCase):
+    def test_goal_allowed_when_busy(self) -> None:
+        self.assertIn("goal", ALLOW_WHEN_BUSY_SLASH_COMMANDS)
+
+    def test_destructive_commands_stay_blocked_when_busy(self) -> None:
+        for name in ("clear", "rewind", "compact"):
+            self.assertNotIn(name, ALLOW_WHEN_BUSY_SLASH_COMMANDS)
+
+    def test_model_and_config_stay_blocked_when_busy(self) -> None:
+        for name in ("model", "config", "statusline"):
+            self.assertNotIn(name, ALLOW_WHEN_BUSY_SLASH_COMMANDS)
+
+    def test_whitelist_only_contains_local_builtin_commands(self) -> None:
+        spec_by_name = {spec.name: spec for spec in SLASH_COMMAND_SPECS}
+        for name in ALLOW_WHEN_BUSY_SLASH_COMMANDS:
+            self.assertIn(name, spec_by_name)
+            self.assertEqual(spec_by_name[name].execution_kind, "local")
+
+
+class _FakeRenderer:
+    def __init__(self) -> None:
+        self.messages: list[tuple[str, str]] = []
+
+    def seed_user_message(self, text: str) -> None:
+        del text
+
+    def append_subtitle(self, text: str, *, severity: str = "info") -> None:
+        self.messages.append((text, severity))
+
+    def append_system_message(self, text: str, *, severity: str = "info") -> None:
+        self.messages.append((text, severity))
+
+
+class _Harness(CommandsMixin):
+    def __init__(self) -> None:
+        self._busy = True
+        self._renderer = _FakeRenderer()
+        self._slash_registry = SlashCommandRegistry()
+        self.calls: list[str] = []
+
+    def _refresh_layers(self) -> None:
+        return None
+
+
+class TestExecuteCommandBusyGate(unittest.IsolatedAsyncioTestCase):
+    async def test_busy_blocks_non_whitelisted_command(self) -> None:
+        host = _Harness()
+        host._slash_registry.register(
+            spec=SlashCommandSpec(name="clear", description="", execution_kind="local"),
+            handler=lambda args: host.calls.append(f"clear:{args}"),
+            allow_when_busy=False,
+        )
+
+        await host._execute_command("/clear")
+
+        self.assertEqual(host.calls, [])
+        self.assertIn("not available right now", host._renderer.messages[-1][0])
+        self.assertEqual(host._renderer.messages[-1][1], "error")
+
+    async def test_busy_allows_whitelisted_command(self) -> None:
+        host = _Harness()
+        host._slash_registry.register(
+            spec=SlashCommandSpec(name="goal", description="", execution_kind="local"),
+            handler=lambda args: host.calls.append(f"goal:{args}"),
+            allow_when_busy=True,
+        )
+
+        await host._execute_command("/goal pause")
+
+        self.assertEqual(host.calls, ["goal:pause"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)