feat(plugins): add ActionResult flow control for menu navigation

ESC now goes back one level instead of exiting the entire menu tree.
Plugin actions (toggle, install, rebuild) close the menu immediately
with a notification instead of showing intermediate "Done" screens.

Plugins return ActionResult.CLOSE or ActionResult.BACK from run() to
control navigation flow. None return is treated as CLOSE for backwards
compatibility with external plugins.

Author: markhedleyjones

src/menu_kit/core/runner.py

@@ -10,6 +10,7 @@
 from menu_kit.core.database import Database, ItemType, MenuItem
 from menu_kit.core.display_mode import DisplayMode, DisplayModeManager
 from menu_kit.menu.base import GUI_BACKENDS, get_backend
+from menu_kit.plugins.base import ActionResult
 from menu_kit.plugins.loader import PluginLoader
 
 if TYPE_CHECKING:
@@ -221,34 +222,33 @@ def _run_menu(self) -> int:
 
             result = self.backend.show(items, prompt="menu-kit")
 
-            # Exit only when cancelled from main menu
+            # ESC at main menu level exits the app
             if result.cancelled or result.selected is None:
                 return EXIT_CANCELLED
 
             item = result.selected
 
             # Handle submenu entry selection
             if item.id.startswith("_submenu:"):
-                from menu_kit.plugins.base import MenuCancelled
-
                 plugin_name = item.id[9:]  # Remove "_submenu:" prefix
-                try:
-                    if self._show_plugin_submenu(plugin_name, display_manager):
-                        return EXIT_SUCCESS  # Plugin was executed, exit
-                except MenuCancelled:
-                    return EXIT_CANCELLED  # ESC pressed, exit
+                submenu_result = self._show_plugin_submenu(plugin_name, display_manager)
+                if submenu_result == ActionResult.CLOSE:
+                    return EXIT_SUCCESS
+                # BACK or None: continue loop (show main menu again)
                 continue
 
             # Record usage
             if self.config.frequency_tracking:
                 self.database.record_use(item.id)
 
-            # Execute plugin and exit (launcher behavior)
+            # Execute plugin
             if item.plugin:
                 action = ""
                 if ":" in item.id:
                     _, action = item.id.split(":", 1)
-                self.loader.run_plugin(item.plugin, action)
+                action_result = self.loader.run_plugin(item.plugin, action)
+                if action_result == ActionResult.BACK:
+                    continue  # Show main menu again
                 return EXIT_SUCCESS
 
     def _build_main_menu(self, display_manager: DisplayModeManager) -> list[MenuItem]:
@@ -287,7 +287,9 @@ def _build_main_menu(self, display_manager: DisplayModeManager) -> list[MenuItem
                 result.append(
                     MenuItem(
                         id=item.id,
-                        title=display_manager.format_inline_title(item.plugin, item.title),
+                        title=display_manager.format_inline_title(
+                            item.plugin, item.title
+                        ),
                         item_type=item.item_type,
                         path=item.path,
                         plugin=item.plugin,
@@ -341,18 +343,15 @@ def _sort_menu_items(self, items: list[MenuItem], sort: str) -> list[MenuItem]:
         else:
             return items
 
-    def _show_plugin_submenu(self, plugin_name: str, display_manager: DisplayModeManager) -> bool:
+    def _show_plugin_submenu(
+        self, plugin_name: str, display_manager: DisplayModeManager
+    ) -> ActionResult:
         """Show items for a plugin in submenu mode.
 
         Returns:
-            True if a plugin was executed (caller should exit),
-            False if back button selected (caller should continue).
-
-        Raises:
-            MenuCancelled: If user presses ESC (should exit entire menu).
+            ActionResult.CLOSE if a plugin action completed (caller should exit).
+            ActionResult.BACK if user navigated back (caller should continue).
         """
-        from menu_kit.plugins.base import MenuCancelled
-
         assert self.database is not None
         assert self.backend is not None
         assert self.config is not None
@@ -365,35 +364,38 @@ def _show_plugin_submenu(self, plugin_name: str, display_manager: DisplayModeMan
             items = self.database.get_items(plugin=plugin_name, order_by_frequency=True)
 
             if not items:
-                return False
+                return ActionResult.BACK
 
             # Add back button
             items.append(MenuItem(id="_back", title="Back", item_type=ItemType.ACTION))
 
             result = self.backend.show(items, prompt=prompt)
 
-            # ESC pressed - propagate up to exit entire menu
-            if result.cancelled:
-                raise MenuCancelled()
-
-            if result.selected is None or result.selected.id == "_back":
-                return False
+            # ESC or Back: go back to main menu
+            if (
+                result.cancelled
+                or result.selected is None
+                or result.selected.id == "_back"
+            ):
+                return ActionResult.BACK
 
             item = result.selected
 
             # Record usage
             if self.config.frequency_tracking:
                 self.database.record_use(item.id)
 
-            # Execute and exit
+            # Execute plugin action
             if item.plugin:
                 action = ""
                 if ":" in item.id:
                     _, action = item.id.split(":", 1)
-                self.loader.run_plugin(item.plugin, action)
-                return True  # Signal to exit menu
+                action_result = self.loader.run_plugin(item.plugin, action)
+                if action_result == ActionResult.BACK:
+                    continue  # Show submenu again
+                return ActionResult.CLOSE
 
-            return False
+            return ActionResult.BACK
 
     def _format_item(self, item: MenuItem, prefix: str) -> str:
         """Format an item for display."""

src/menu_kit/plugins/base.py

@@ -4,6 +4,7 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import TYPE_CHECKING, Any
 
 from menu_kit.core.database import ItemType, MenuItem
@@ -15,15 +16,27 @@
     from menu_kit.plugins.loader import PluginLoader
 
 
+class ActionResult(Enum):
+    """Flow control signal returned by plugin actions.
+
+    Plugins return this from run() to tell the runner what to do next:
+    - CLOSE: Action completed, close the entire menu (launcher behaviour).
+    - BACK: Go back to the previous menu level.
+    """
+
+    CLOSE = "close"
+    BACK = "back"
+
+
 # Sentinel for back navigation
 BACK_SELECTED = object()
 
 
 class MenuCancelled(Exception):
     """Raised when user cancels (ESC) the menu.
 
-    This exception propagates up to exit the entire plugin menu tree,
-    rather than just going back one level like the Back button.
+    Deprecated: ESC now returns None (same as Back) from ctx.menu().
+    Kept for backwards compatibility with plugins that catch this exception.
     """
 
 
@@ -49,10 +62,7 @@ def menu(
             show_back: Whether to show a back button (default True)
 
         Returns:
-            Selected MenuItem, or None if back button selected
-
-        Raises:
-            MenuCancelled: If user presses ESC (cancels the menu)
+            Selected MenuItem, or None if back/ESC selected
         """
         display_items = list(items)
 
@@ -67,8 +77,9 @@ def menu(
 
         result = self.menu_backend.show(display_items, prompt)
 
+        # ESC and Back both mean "go back one level"
         if result.cancelled:
-            raise MenuCancelled()
+            return None
 
         if result.selected and result.selected.id == "_back":
             return None
@@ -201,12 +212,18 @@ def teardown(self, ctx: PluginContext) -> None:  # noqa: B027
         """Called when plugin is unloaded. Optional override."""
 
     @abstractmethod
-    def run(self, ctx: PluginContext, action: str = "") -> None:
+    def run(self, ctx: PluginContext, action: str = "") -> ActionResult | None:
         """Called when user selects this plugin.
 
         Args:
             ctx: Plugin context for accessing core functionality
             action: Sub-action if invoked via -p plugin:action
+
+        Returns:
+            ActionResult controlling menu flow:
+            - CLOSE: action completed, close the entire menu
+            - BACK: go back to the previous menu level
+            - None: treated as CLOSE (backwards compatible default)
         """
         ...