shotgun-sh 0.2.17__py3-none-any.whl → 0.4.0.dev1__py3-none-any.whl

shotgun/tui/screens/chat/chat_screen.py

@@ -5,7 +5,10 @@ import logging
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import cast
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from shotgun.agents.router.models import ExecutionStep
 
 from pydantic_ai.messages import (
     ModelMessage,
@@ -33,23 +36,39 @@ from shotgun.agents.agent_manager import (
     MessageHistoryUpdated,
     ModelConfigUpdated,
     PartialResponseMessage,
+    ToolExecutionStartedMessage,
+    ToolStreamingProgressMessage,
 )
 from shotgun.agents.config import get_config_manager
 from shotgun.agents.config.models import MODEL_SPECS
-from shotgun.agents.conversation_manager import ConversationManager
-from shotgun.agents.history.compaction import apply_persistent_compaction
-from shotgun.agents.history.token_estimation import estimate_tokens_from_messages
+from shotgun.agents.conversation import ConversationManager
+from shotgun.agents.conversation.history.compaction import apply_persistent_compaction
+from shotgun.agents.conversation.history.token_estimation import (
+    estimate_tokens_from_messages,
+)
 from shotgun.agents.models import (
     AgentDeps,
     AgentType,
     FileOperationTracker,
 )
+from shotgun.agents.router.models import (
+    CascadeScope,
+    ExecutionPlan,
+    PlanApprovalStatus,
+    RouterDeps,
+    RouterMode,
+)
+from shotgun.agents.runner import AgentRunner
 from shotgun.codebase.core.manager import (
     CodebaseAlreadyIndexedError,
     CodebaseGraphManager,
 )
 from shotgun.codebase.models import IndexProgress, ProgressPhase
-from shotgun.exceptions import ContextSizeLimitExceeded
+from shotgun.exceptions import (
+    SHOTGUN_CONTACT_EMAIL,
+    ErrorNotPickedUpBySentry,
+    ShotgunAccountException,
+)
 from shotgun.posthog_telemetry import track_event
 from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
@@ -59,6 +78,8 @@ from shotgun.tui.components.mode_indicator import ModeIndicator
 from shotgun.tui.components.prompt_input import PromptInput
 from shotgun.tui.components.spinner import Spinner
 from shotgun.tui.components.status_bar import StatusBar
+
+# TUIErrorHandler removed - exceptions now caught directly
 from shotgun.tui.screens.chat.codebase_index_prompt_screen import (
     CodebaseIndexPromptScreen,
 )
@@ -74,18 +95,72 @@ from shotgun.tui.screens.chat_screen.command_providers import (
 )
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.tui.screens.chat_screen.history import ChatHistory
+from shotgun.tui.screens.chat_screen.messages import (
+    CascadeConfirmationRequired,
+    CascadeConfirmed,
+    CascadeDeclined,
+    CheckpointContinue,
+    CheckpointModify,
+    CheckpointStop,
+    PlanApprovalRequired,
+    PlanApproved,
+    PlanPanelClosed,
+    PlanRejected,
+    PlanUpdated,
+    StepCompleted,
+    SubAgentCompleted,
+    SubAgentStarted,
+)
 from shotgun.tui.screens.confirmation_dialog import ConfirmationDialog
 from shotgun.tui.screens.onboarding import OnboardingModal
+from shotgun.tui.screens.shared_specs import (
+    CreateSpecDialog,
+    ShareSpecsAction,
+    ShareSpecsDialog,
+    UploadProgressScreen,
+)
 from shotgun.tui.services.conversation_service import ConversationService
 from shotgun.tui.state.processing_state import ProcessingStateManager
 from shotgun.tui.utils.mode_progress import PlaceholderHints
+from shotgun.tui.widgets.approval_widget import PlanApprovalWidget
+from shotgun.tui.widgets.cascade_confirmation_widget import CascadeConfirmationWidget
+from shotgun.tui.widgets.plan_panel import PlanPanelWidget
+from shotgun.tui.widgets.step_checkpoint_widget import StepCheckpointWidget
 from shotgun.tui.widgets.widget_coordinator import WidgetCoordinator
 from shotgun.utils import get_shotgun_home
+from shotgun.utils.file_system_utils import get_shotgun_base_path
 from shotgun.utils.marketing import MarketingManager
 
 logger = logging.getLogger(__name__)
 
 
+def _format_duration(seconds: float) -> str:
+    """Format duration in natural language."""
+    if seconds < 60:
+        return f"{int(seconds)} seconds"
+    minutes = int(seconds // 60)
+    secs = int(seconds % 60)
+    if secs == 0:
+        return f"{minutes} minute{'s' if minutes != 1 else ''}"
+    return f"{minutes} minute{'s' if minutes != 1 else ''} {secs} seconds"
+
+
+def _format_count(count: int) -> str:
+    """Format count in natural language (e.g., '5 thousand')."""
+    if count < 1000:
+        return str(count)
+    elif count < 1_000_000:
+        thousands = count / 1000
+        if thousands == int(thousands):
+            return f"{int(thousands)} thousand"
+        return f"{thousands:.1f} thousand"
+    else:
+        millions = count / 1_000_000
+        if millions == int(millions):
+            return f"{int(millions)} million"
+        return f"{millions:.1f} million"
+
+
 class ChatScreen(Screen[None]):
     CSS_PATH = "chat.tcss"
 
@@ -118,6 +193,18 @@ class ChatScreen(Screen[None]):
     _last_context_update: float = 0.0
     _context_update_throttle: float = 5.0  # 5 seconds
 
+    # Step checkpoint widget (Planning mode)
+    _checkpoint_widget: StepCheckpointWidget | None = None
+
+    # Cascade confirmation widget (Planning mode)
+    _cascade_widget: CascadeConfirmationWidget | None = None
+
+    # Plan approval widget (Planning mode)
+    _approval_widget: PlanApprovalWidget | None = None
+
+    # Plan panel widget (Stage 11)
+    _plan_panel: PlanPanelWidget | None = None
+
     def __init__(
         self,
         agent_manager: AgentManager,
@@ -131,6 +218,7 @@ class ChatScreen(Screen[None]):
         deps: AgentDeps,
         continue_session: bool = False,
         force_reindex: bool = False,
+        show_pull_hint: bool = False,
     ) -> None:
         """Initialize the ChatScreen.
 
@@ -149,11 +237,17 @@ class ChatScreen(Screen[None]):
             deps: AgentDeps configuration for agent dependencies
             continue_session: Whether to continue a previous session
             force_reindex: Whether to force reindexing of codebases
+            show_pull_hint: Whether to show hint about recently pulled spec
         """
         super().__init__()
 
         # All dependencies are now required and injected
         self.deps = deps
+
+        # Wire up plan change callback for Plan Panel (Stage 11)
+        if isinstance(deps, RouterDeps):
+            deps.on_plan_changed = self._on_plan_changed
+
         self.codebase_sdk = codebase_sdk
         self.agent_manager = agent_manager
         self.command_handler = command_handler
@@ -164,6 +258,11 @@ class ChatScreen(Screen[None]):
         self.processing_state = processing_state
         self.continue_session = continue_session
         self.force_reindex = force_reindex
+        self.show_pull_hint = show_pull_hint
+
+        # Initialize mode from agent_manager before compose() runs
+        # This ensures ModeIndicator shows correct mode on first render
+        self.mode = agent_manager._current_agent_type
 
     def on_mount(self) -> None:
         # Use widget coordinator to focus input
@@ -174,11 +273,18 @@ class ChatScreen(Screen[None]):
         # Bind spinner to processing state manager
         self.processing_state.bind_spinner(self.query_one("#spinner", Spinner))
 
+        # Load saved router mode if using Router agent
+        self.call_later(self._load_saved_router_mode)
+
         # Load conversation history if --continue flag was provided
         # Use call_later to handle async exists() check
         if self.continue_session:
             self.call_later(self._check_and_load_conversation)
 
+        # Show pull hint if launching after spec pull
+        if self.show_pull_hint:
+            self.call_later(self._show_pull_hint)
+
         self.call_later(self.check_if_codebase_is_indexed)
         # Initial update of context indicator
         self.update_context_indicator()
@@ -281,42 +387,193 @@ class ChatScreen(Screen[None]):
             # Use widget coordinator for all widget updates
             self.widget_coordinator.update_messages(messages)
 
+    # =========================================================================
+    # Router State Properties (for Protocol compliance)
+    # =========================================================================
+
+    @property
+    def router_mode(self) -> str | None:
+        """Get the current router mode for RouterModeProvider protocol.
+
+        Returns:
+            'planning' or 'drafting' if using router agent, None otherwise.
+        """
+        if isinstance(self.deps, RouterDeps):
+            return self.deps.router_mode.value
+        return None
+
+    @property
+    def active_sub_agent(self) -> str | None:
+        """Get the active sub-agent for ActiveSubAgentProvider protocol.
+
+        Returns:
+            The sub-agent type string if executing, None otherwise.
+        """
+        if isinstance(self.deps, RouterDeps) and self.deps.active_sub_agent:
+            return self.deps.active_sub_agent.value
+        return None
+
     def action_toggle_mode(self) -> None:
+        """Toggle between Planning and Drafting modes for Router."""
+        from shotgun.agents.router.models import RouterDeps, RouterMode
+
         # Prevent mode switching during Q&A
         if self.qa_mode:
-            self.notify(
-                "Cannot switch modes while answering questions",
-                severity="warning",
-                timeout=3,
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ Cannot switch modes while answering questions")
             )
             return
 
-        modes = [
-            AgentType.RESEARCH,
-            AgentType.SPECIFY,
-            AgentType.PLAN,
-            AgentType.TASKS,
-            AgentType.EXPORT,
-        ]
-        self.mode = modes[(modes.index(self.mode) + 1) % len(modes)]
-        self.agent_manager.set_agent(self.mode)
-        # Re-focus input after mode change
+        if not isinstance(self.deps, RouterDeps):
+            return
+
+        # Prevent mode switching during execution
+        if self.deps.is_executing:
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ Cannot switch modes during plan execution")
+            )
+            return
+
+        # Prevent mode switching while sub-agent is active
+        if self.deps.active_sub_agent is not None:
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ Cannot switch modes while sub-agent is running")
+            )
+            return
+
+        # Toggle mode
+        if self.deps.router_mode == RouterMode.PLANNING:
+            self.deps.router_mode = RouterMode.DRAFTING
+            mode_name = "Drafting"
+        else:
+            self.deps.router_mode = RouterMode.PLANNING
+            mode_name = "Planning"
+            # Clear plan when switching back to Planning mode
+            # This forces the agent to create a new plan for the next request
+            self.deps.current_plan = None
+            self.deps.approval_status = PlanApprovalStatus.SKIPPED
+            self.deps.is_executing = False
+
+        # Persist mode (fire-and-forget)
+        self._save_router_mode(self.deps.router_mode.value)
+
+        # Show mode change feedback
+        self.agent_manager.add_hint_message(
+            HintMessage(message=f"Switched to {mode_name} mode")
+        )
+
+        # Update UI
+        self.widget_coordinator.update_for_mode_change(self.mode)
         self.call_later(lambda: self.widget_coordinator.update_prompt_input(focus=True))
 
-    def action_show_usage(self) -> None:
+    def _save_router_mode(self, mode: str) -> None:
+        """Save router mode to config (fire-and-forget)."""
+
+        async def _save() -> None:
+            config_manager = get_config_manager()
+            await config_manager.set_router_mode(mode)
+
+        asyncio.create_task(_save())
+
+    async def _load_saved_router_mode(self) -> None:
+        """Load saved router mode from config."""
+        from shotgun.agents.router.models import RouterDeps, RouterMode
+
+        if isinstance(self.deps, RouterDeps):
+            config_manager = get_config_manager()
+            saved_mode = await config_manager.get_router_mode()
+
+            if saved_mode == "drafting":
+                self.deps.router_mode = RouterMode.DRAFTING
+            else:
+                self.deps.router_mode = RouterMode.PLANNING
+
+            logger.debug("Loaded router mode from config: %s", saved_mode)
+
+    async def action_show_usage(self) -> None:
         usage_hint = self.agent_manager.get_usage_hint()
         logger.info(f"Usage hint: {usage_hint}")
+
+        # Add budget info for Shotgun Account users
+        if self.deps.llm_model.is_shotgun_account:
+            try:
+                from shotgun.llm_proxy import LiteLLMProxyClient
+
+                logger.debug("Fetching budget info for Shotgun Account")
+                client = LiteLLMProxyClient(self.deps.llm_model.api_key)
+                budget_info = await client.get_budget_info()
+
+                # Format budget section
+                source_label = "Key" if budget_info.source == "key" else "Team"
+                budget_section = f"""## Shotgun Account Budget
+
+* Max Budget:     ${budget_info.max_budget:.2f}
+* Current Spend:  ${budget_info.spend:.2f}
+* Remaining:      ${budget_info.remaining:.2f} ({100 - budget_info.percentage_used:.1f}%)
+* Budget Source:  {source_label}-level
+
+**Questions or need help?**"""
+
+                # Build markdown_before (usage + budget info before email)
+                if usage_hint:
+                    markdown_before = f"{usage_hint}\n\n{budget_section}"
+                else:
+                    markdown_before = budget_section
+
+                markdown_after = (
+                    "\n\n_Reach out anytime for billing questions "
+                    "or to increase your budget._"
+                )
+
+                # Mount with email copy button
+                self.mount_hint_with_email(
+                    markdown_before=markdown_before,
+                    email="contact@shotgun.sh",
+                    markdown_after=markdown_after,
+                )
+                logger.debug("Successfully added budget info to usage hint")
+                return  # Exit early since we've already mounted
+
+            except Exception as e:
+                logger.warning(f"Failed to fetch budget info: {e}")
+                # For Shotgun Account, show budget fetch error
+                # If we have usage data, still show it
+                if usage_hint:
+                    # Show usage even though budget fetch failed
+                    self.mount_hint(usage_hint)
+                else:
+                    # No usage and budget fetch failed - show specific error with email
+                    markdown_before = (
+                        "⚠️ **Unable to fetch budget information**\n\n"
+                        "There was an error retrieving your budget data."
+                    )
+                    markdown_after = (
+                        "\n\n_Try the command again in a moment. "
+                        "If the issue persists, reach out for help._"
+                    )
+                    self.mount_hint_with_email(
+                        markdown_before=markdown_before,
+                        email="contact@shotgun.sh",
+                        markdown_after=markdown_after,
+                    )
+                return  # Exit early
+
+        # Fallback for non-Shotgun Account users
         if usage_hint:
             self.mount_hint(usage_hint)
         else:
-            self.notify("No usage hint available", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ No usage hint available")
+            )
 
     async def action_show_context(self) -> None:
         context_hint = await self.agent_manager.get_context_hint()
         if context_hint:
             self.mount_hint(context_hint)
         else:
-            self.notify("No context analysis available", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ No context analysis available")
+            )
 
     def action_view_onboarding(self) -> None:
         """Show the onboarding modal."""
@@ -441,7 +698,9 @@ class ChatScreen(Screen[None]):
 
         except Exception as e:
             logger.error(f"Failed to compact conversation: {e}", exc_info=True)
-            self.notify(f"Failed to compact: {e}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to compact: {e}")
+            )
         finally:
             # Hide spinner
             self.processing_state.stop_processing()
@@ -489,7 +748,9 @@ class ChatScreen(Screen[None]):
 
         except Exception as e:
             logger.error(f"Failed to clear conversation: {e}", exc_info=True)
-            self.notify(f"Failed to clear: {e}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to clear: {e}")
+            )
 
     @work(exclusive=False)
     async def update_context_indicator(self) -> None:
@@ -576,6 +837,53 @@ class ChatScreen(Screen[None]):
         hint = HintMessage(message=markdown)
         self.agent_manager.add_hint_message(hint)
 
+    def _show_pull_hint(self) -> None:
+        """Show hint about recently pulled spec from meta.json."""
+        # Import at runtime to avoid circular import (CLI -> TUI dependency)
+        from shotgun.cli.spec.models import SpecMeta
+
+        shotgun_dir = get_shotgun_base_path()
+        meta_path = shotgun_dir / "meta.json"
+        if not meta_path.exists():
+            return
+
+        try:
+            meta: SpecMeta = SpecMeta.model_validate_json(meta_path.read_text())
+            # Only show if pulled within last 60 seconds
+            age_seconds = (datetime.now(timezone.utc) - meta.pulled_at).total_seconds()
+            if age_seconds > 60:
+                return
+
+            hint_parts = [f"You just pulled **{meta.spec_name}** from the cloud."]
+            if meta.web_url:
+                hint_parts.append(f"[View in browser]({meta.web_url})")
+            hint_parts.append(
+                f"The specs are now located at `{shotgun_dir}` so Shotgun has access to them."
+            )
+            if meta.backup_path:
+                hint_parts.append(
+                    f"Previous files were backed up to: `{meta.backup_path}`"
+                )
+            self.mount_hint("\n\n".join(hint_parts))
+        except Exception:
+            # Ignore errors reading meta.json - this is optional UI feedback
+            logger.debug("Failed to read meta.json for pull hint", exc_info=True)
+
+    def mount_hint_with_email(
+        self, markdown_before: str, email: str, markdown_after: str = ""
+    ) -> None:
+        """Mount a hint with inline email copy button.
+
+        Args:
+            markdown_before: Markdown content to display before the email line
+            email: Email address to display with copy button
+            markdown_after: Optional markdown content to display after the email line
+        """
+        hint = HintMessage(
+            message=markdown_before, email=email, markdown_after=markdown_after
+        )
+        self.agent_manager.add_hint_message(hint)
+
     @on(PartialResponseMessage)
     def handle_partial_response(self, event: PartialResponseMessage) -> None:
         # Filter event.messages to exclude ModelRequest with only ToolReturnPart
@@ -617,6 +925,12 @@ class ChatScreen(Screen[None]):
         if has_file_write:
             return  # Skip context update for file writes
 
+        # Skip context updates when a sub-agent is streaming
+        # Sub-agents run with isolated message history, so their streaming doesn't
+        # represent the router's actual context usage
+        if isinstance(self.deps, RouterDeps) and self.deps.active_sub_agent is not None:
+            return  # Skip context update for sub-agent streaming
+
         # Throttle context indicator updates to improve performance during streaming
         # Only update at most once per 5 seconds to avoid excessive token calculations
         current_time = time.time()
@@ -744,6 +1058,29 @@ class ChatScreen(Screen[None]):
         # Use widget coordinator to update spinner text
         self.widget_coordinator.update_spinner_text("Processing...")
 
+    @on(ToolExecutionStartedMessage)
+    def handle_tool_execution_started(self, event: ToolExecutionStartedMessage) -> None:
+        """Update spinner text when a tool starts executing.
+
+        This provides visual feedback during long-running tool executions
+        like web search, so the UI doesn't appear frozen.
+        """
+        self.widget_coordinator.update_spinner_text(event.spinner_text)
+
+    @on(ToolStreamingProgressMessage)
+    def handle_tool_streaming_progress(
+        self, event: ToolStreamingProgressMessage
+    ) -> None:
+        """Update spinner text with token count during tool streaming.
+
+        Shows progress while tool arguments are streaming in,
+        particularly useful for long file writes.
+        """
+        text = f"{event.spinner_text} (~{event.streamed_tokens:,} tokens)"
+        self.widget_coordinator.update_spinner_text(text)
+        # Force immediate refresh to show progress
+        self.refresh()
+
     async def handle_model_selected(self, result: ModelConfigUpdated | None) -> None:
         """Handle model selection from ModelPickerScreen.
 
@@ -762,6 +1099,19 @@ class ChatScreen(Screen[None]):
             # Update the agent manager's model configuration
             self.agent_manager.deps.llm_model = result.model_config
 
+            # Reset agents so they get recreated with new model
+            self.agent_manager._agents_initialized = False
+            self.agent_manager._research_agent = None
+            self.agent_manager._plan_agent = None
+            self.agent_manager._tasks_agent = None
+            self.agent_manager._specify_agent = None
+            self.agent_manager._export_agent = None
+            self.agent_manager._research_deps = None
+            self.agent_manager._plan_deps = None
+            self.agent_manager._tasks_deps = None
+            self.agent_manager._specify_deps = None
+            self.agent_manager._export_deps = None
+
             # Get current analysis and update context indicator via coordinator
             analysis = await self.agent_manager.get_context_analysis()
             self.widget_coordinator.update_context_indicator(analysis, result.new_model)
@@ -928,6 +1278,71 @@ class ChatScreen(Screen[None]):
             )
         )
 
+    def share_specs_command(self) -> None:
+        """Launch the share specs workflow."""
+        self.call_later(lambda: self._start_share_specs_flow())
+
+    @work
+    async def _start_share_specs_flow(self) -> None:
+        """Main workflow for sharing specs to workspace."""
+        # 1. Check preconditions (instant check, no API call)
+        shotgun_dir = Path.cwd() / ".shotgun"
+        if not shotgun_dir.exists():
+            self.mount_hint("No .shotgun/ directory found in current directory")
+            return
+
+        # 2. Show spec selection dialog (handles workspace fetch, permissions, and spec loading)
+        result = await self.app.push_screen_wait(ShareSpecsDialog())
+        if result is None or result.action is None:
+            return  # User cancelled or error
+
+        workspace_id = result.workspace_id
+        if not workspace_id:
+            self.mount_hint("Failed to get workspace")
+            return
+
+        # 3. Handle create vs add version
+        if result.action == ShareSpecsAction.CREATE:
+            # Show create spec dialog
+            create_result = await self.app.push_screen_wait(CreateSpecDialog())
+            if create_result is None:
+                return  # User cancelled
+
+            # Pass spec creation info to UploadProgressScreen
+            # It will create the spec/version and then upload
+            upload_result = await self.app.push_screen_wait(
+                UploadProgressScreen(
+                    workspace_id,
+                    spec_name=create_result.name,
+                    spec_description=create_result.description,
+                    spec_is_public=create_result.is_public,
+                )
+            )
+
+        else:  # add_version
+            spec_id = result.spec_id
+            if not spec_id:
+                self.mount_hint("No spec selected")
+                return
+
+            # Pass spec_id to UploadProgressScreen
+            # It will create the version and then upload
+            upload_result = await self.app.push_screen_wait(
+                UploadProgressScreen(workspace_id, spec_id=spec_id)
+            )
+
+        # 7. Show result
+        if upload_result and upload_result.success:
+            if upload_result.web_url:
+                self.mount_hint(
+                    f"Specs shared successfully!\n\nView at: {upload_result.web_url}"
+                )
+            else:
+                self.mount_hint("Specs shared successfully!")
+        elif upload_result and upload_result.cancelled:
+            self.mount_hint("Upload cancelled")
+        # Error case is handled by the upload screen
+
     def delete_codebase_from_palette(self, graph_id: str) -> None:
         stack = getattr(self.app, "screen_stack", None)
         if stack and isinstance(stack[-1], CommandPalette):
@@ -939,11 +1354,15 @@ class ChatScreen(Screen[None]):
     async def delete_codebase(self, graph_id: str) -> None:
         try:
             await self.codebase_sdk.delete_codebase(graph_id)
-            self.notify(f"Deleted codebase: {graph_id}", severity="information")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"✓ Deleted codebase: {graph_id}")
+            )
         except CodebaseNotFoundError as exc:
-            self.notify(str(exc), severity="error")
+            self.agent_manager.add_hint_message(HintMessage(message=f"❌ {exc}"))
         except Exception as exc:  # pragma: no cover - defensive UI path
-            self.notify(f"Failed to delete codebase: {exc}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to delete codebase: {exc}")
+            )
 
     def _is_kuzu_corruption_error(self, exception: Exception) -> bool:
         """Check if error is related to kuzu database corruption.
@@ -969,6 +1388,8 @@ class ChatScreen(Screen[None]):
 
     @work
     async def index_codebase(self, selection: CodebaseIndexSelection) -> None:
+        index_start_time = time.time()
+
         label = self.query_one("#indexing-job-display", Static)
         label.update(
             f"[$foreground-muted]Indexing codebase: [bold $text-accent]{selection.name}[/][/]"
@@ -1008,24 +1429,40 @@ class ChatScreen(Screen[None]):
 
         def progress_callback(progress_info: IndexProgress) -> None:
             """Update progress state (timer renders it independently)."""
-            # Calculate overall percentage (0-95%, reserve 95-100% for finalization)
+            # Calculate overall percentage with weights based on actual timing:
+            # Structure: 0-2%, Definitions: 2-18%, Relationships: 18-20%
+            # Flush nodes: 20-28%, Flush relationships: 28-100%
             if progress_info.phase == ProgressPhase.STRUCTURE:
-                # Phase 1: 0-10%, always show 5% while running, 10% when complete
-                overall_pct = 10.0 if progress_info.phase_complete else 5.0
+                # Phase 1: 0-2% (actual: ~0%)
+                overall_pct = 2.0 if progress_info.phase_complete else 1.0
             elif progress_info.phase == ProgressPhase.DEFINITIONS:
-                # Phase 2: 10-80% based on files processed
+                # Phase 2: 2-18% based on files processed (actual: ~16%)
                 if progress_info.total and progress_info.total > 0:
-                    phase_pct = (progress_info.current / progress_info.total) * 70.0
-                    overall_pct = 10.0 + phase_pct
+                    phase_pct = (progress_info.current / progress_info.total) * 16.0
+                    overall_pct = 2.0 + phase_pct
                 else:
-                    overall_pct = 10.0
+                    overall_pct = 2.0
             elif progress_info.phase == ProgressPhase.RELATIONSHIPS:
-                # Phase 3: 80-95% based on relationships processed (cap at 95%)
+                # Phase 3: 18-20% based on relationships processed (actual: ~0.3%)
                 if progress_info.total and progress_info.total > 0:
-                    phase_pct = (progress_info.current / progress_info.total) * 15.0
-                    overall_pct = 80.0 + phase_pct
+                    phase_pct = (progress_info.current / progress_info.total) * 2.0
+                    overall_pct = 18.0 + phase_pct
                 else:
-                    overall_pct = 80.0
+                    overall_pct = 18.0
+            elif progress_info.phase == ProgressPhase.FLUSH_NODES:
+                # Phase 4: 20-28% based on nodes flushed (actual: ~7.5%)
+                if progress_info.total and progress_info.total > 0:
+                    phase_pct = (progress_info.current / progress_info.total) * 8.0
+                    overall_pct = 20.0 + phase_pct
+                else:
+                    overall_pct = 20.0
+            elif progress_info.phase == ProgressPhase.FLUSH_RELATIONSHIPS:
+                # Phase 5: 28-100% based on relationships flushed (actual: ~76%)
+                if progress_info.total and progress_info.total > 0:
+                    phase_pct = (progress_info.current / progress_info.total) * 72.0
+                    overall_pct = 28.0 + phase_pct
+                else:
+                    overall_pct = 28.0
             else:
                 overall_pct = 0.0
 
@@ -1050,9 +1487,10 @@ class ChatScreen(Screen[None]):
                     )
                     cleaned = await manager.cleanup_corrupted_databases()
                     logger.info(f"Cleaned up {len(cleaned)} corrupted database(s)")
-                    self.notify(
-                        f"Retrying indexing after cleanup (attempt {attempt + 1}/{max_retries})...",
-                        severity="information",
+                    self.agent_manager.add_hint_message(
+                        HintMessage(
+                            message=f"🔄 Retrying indexing after cleanup (attempt {attempt + 1}/{max_retries})..."
+                        )
                     )
 
                 # Pass the current working directory as the indexed_from_cwd
@@ -1077,25 +1515,32 @@ class ChatScreen(Screen[None]):
                 )
                 label.refresh()
 
+                # Calculate duration and format message
+                duration = time.time() - index_start_time
+                duration_str = _format_duration(duration)
+                entity_count = result.node_count + result.relationship_count
+                entity_str = _format_count(entity_count)
+
                 logger.info(
-                    f"Successfully indexed codebase '{result.name}' (ID: {result.graph_id})"
+                    f"Successfully indexed codebase '{result.name}' in {duration_str} "
+                    f"({entity_count} entities)"
                 )
-                self.notify(
-                    f"Indexed codebase '{result.name}' (ID: {result.graph_id})",
-                    severity="information",
-                    timeout=8,
+                self.agent_manager.add_hint_message(
+                    HintMessage(
+                        message=f"✓ Indexed '{result.name}' in {duration_str} ({entity_str} entities)"
+                    )
                 )
                 break  # Success - exit retry loop
 
             except CodebaseAlreadyIndexedError as exc:
                 progress_timer.stop()
                 logger.warning(f"Codebase already indexed: {exc}")
-                self.notify(str(exc), severity="warning")
+                self.agent_manager.add_hint_message(HintMessage(message=f"⚠️ {exc}"))
                 return
             except InvalidPathError as exc:
                 progress_timer.stop()
                 logger.error(f"Invalid path error: {exc}")
-                self.notify(str(exc), severity="error")
+                self.agent_manager.add_hint_message(HintMessage(message=f"❌ {exc}"))
                 return
 
             except Exception as exc:  # pragma: no cover - defensive UI path
@@ -1114,10 +1559,10 @@ class ChatScreen(Screen[None]):
                     f"Failed to index codebase after {attempt + 1} attempts - "
                     f"repo_path: {selection.repo_path}, name: {selection.name}, error: {exc}"
                 )
-                self.notify(
-                    f"Failed to index codebase after {attempt + 1} attempts: {exc}",
-                    severity="error",
-                    timeout=30,  # Keep error visible for 30 seconds
+                self.agent_manager.add_hint_message(
+                    HintMessage(
+                        message=f"❌ Failed to index codebase after {attempt + 1} attempts: {exc}"
+                    )
                 )
                 break
 
@@ -1128,8 +1573,6 @@ class ChatScreen(Screen[None]):
 
     @work
     async def run_agent(self, message: str) -> None:
-        prompt = None
-
         # Start processing with spinner
         from textual.worker import get_current_worker
 
@@ -1139,65 +1582,47 @@ class ChatScreen(Screen[None]):
         # Start context indicator animation immediately
         self.widget_coordinator.set_context_streaming(True)
 
-        prompt = message
-
         try:
-            await self.agent_manager.run(
-                prompt=prompt,
-            )
-        except asyncio.CancelledError:
-            # Handle cancellation gracefully - DO NOT re-raise
-            self.mount_hint("⚠️ Operation cancelled by user")
-        except ContextSizeLimitExceeded as e:
-            # User-friendly error with actionable options
-            hint = (
-                f"⚠️ **Context too large for {e.model_name}**\n\n"
-                f"Your conversation history exceeds this model's limit ({e.max_tokens:,} tokens).\n\n"
-                f"**Choose an action:**\n\n"
-                f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
-                f"2. Switch to a larger model, compact (`/compact`), then switch back to {e.model_name}\n"
-                f"3. Clear conversation (`/clear`)\n"
-            )
-
-            self.mount_hint(hint)
-
-            # Log for debugging (won't send to Sentry due to ErrorNotPickedUpBySentry)
-            logger.info(
-                "Context size limit exceeded",
-                extra={
-                    "max_tokens": e.max_tokens,
-                    "model_name": e.model_name,
-                },
-            )
-        except Exception as e:
-            # Log with full stack trace to shotgun.log
-            logger.exception(
-                "Agent run failed",
-                extra={
-                    "agent_mode": self.mode.value,
-                    "error_type": type(e).__name__,
-                },
-            )
-
-            # Determine user-friendly message based on error type
-            error_name = type(e).__name__
-            error_message = str(e)
-
-            if "APIStatusError" in error_name and "overload" in error_message.lower():
-                hint = "⚠️ The AI service is temporarily overloaded. Please wait a moment and try again."
-            elif "APIStatusError" in error_name and "rate" in error_message.lower():
-                hint = "⚠️ Rate limit reached. Please wait before trying again."
-            elif "APIStatusError" in error_name:
-                hint = f"⚠️ AI service error: {error_message}"
+            # Use unified agent runner - exceptions propagate for handling
+            runner = AgentRunner(self.agent_manager)
+            await runner.run(message)
+        except ShotgunAccountException as e:
+            # Shotgun Account errors show contact email UI
+            message_parts = e.to_markdown().split("**Need help?**")
+            if len(message_parts) == 2:
+                markdown_before = message_parts[0] + "**Need help?**"
+                markdown_after = message_parts[1].strip()
+                self.mount_hint_with_email(
+                    markdown_before=markdown_before,
+                    email=SHOTGUN_CONTACT_EMAIL,
+                    markdown_after=markdown_after,
+                )
             else:
-                hint = f"⚠️ An error occurred: {error_message}\n\nCheck logs at ~/.shotgun-sh/logs/shotgun.log"
-
-            self.mount_hint(hint)
+                # Fallback if message format is unexpected
+                self.mount_hint(e.to_markdown())
+        except ErrorNotPickedUpBySentry as e:
+            # All other user-actionable errors - display with markdown
+            self.mount_hint(e.to_markdown())
+        except Exception as e:
+            # Unexpected errors that weren't wrapped (shouldn't happen)
+            logger.exception("Unexpected error in run_agent")
+            self.mount_hint(f"⚠️ An unexpected error occurred: {str(e)}")
         finally:
             self.processing_state.stop_processing()
             # Stop context indicator animation
             self.widget_coordinator.set_context_streaming(False)
 
+            # Check for low balance after agent loop completes (only for Shotgun Account)
+            # This runs after processing but doesn't interfere with Q&A mode
+            if self.deps.llm_model.is_shotgun_account:
+                await self._check_low_balance_warning()
+
+        # Check for pending approval (Planning mode multi-step plan creation)
+        self._check_pending_approval()
+
+        # Check for pending checkpoint (Planning mode step completion)
+        self._check_pending_checkpoint()
+
         # Save conversation after each interaction
         self._save_conversation()
 
@@ -1212,6 +1637,32 @@ class ChatScreen(Screen[None]):
             exclusive=True,
         )
 
+    async def _check_low_balance_warning(self) -> None:
+        """Check account balance and show warning if $2.50 or less remaining.
+
+        This runs after every agent loop completion for Shotgun Account users.
+        Errors are silently caught to avoid disrupting user workflow.
+        """
+        try:
+            from shotgun.llm_proxy import LiteLLMProxyClient
+
+            client = LiteLLMProxyClient(self.deps.llm_model.api_key)
+            budget_info = await client.get_budget_info()
+
+            # Show warning if remaining balance is $2.50 or less
+            if budget_info.remaining <= 2.50:
+                warning_message = (
+                    f"⚠️ **Low Balance Warning**\n\n"
+                    f"Your Shotgun Account has **${budget_info.remaining:.2f}** remaining.\n\n"
+                    f"👉 **[Top Up Now at https://app.shotgun.sh/dashboard](https://app.shotgun.sh/dashboard)**"
+                )
+                self.agent_manager.add_hint_message(
+                    HintMessage(message=warning_message)
+                )
+        except Exception as e:
+            # Silently log and continue - don't block user workflow
+            logger.debug(f"Failed to check low balance warning: {e}")
+
     async def _check_and_load_conversation(self) -> None:
         """Check if conversation exists and load it if it does."""
         if await self.conversation_manager.exists():
@@ -1252,3 +1703,461 @@ class ChatScreen(Screen[None]):
             # Mark as shown in config with current timestamp
             config.shown_onboarding_popup = datetime.now(timezone.utc)
             await config_manager.save(config)
+
+    # =========================================================================
+    # Step Checkpoint Handlers (Planning Mode)
+    # =========================================================================
+
+    @on(StepCompleted)
+    def handle_step_completed(self, event: StepCompleted) -> None:
+        """Show checkpoint widget when a step completes in Planning mode.
+
+        This handler is triggered after mark_step_done is called and sets
+        up a pending checkpoint. It shows the StepCheckpointWidget to let
+        the user decide whether to continue, modify, or stop.
+        """
+        if not isinstance(self.deps, RouterDeps):
+            return
+        if self.deps.router_mode != RouterMode.PLANNING:
+            return
+
+        # Show checkpoint widget
+        self._show_checkpoint_widget(event.step, event.next_step)
+
+    @on(CheckpointContinue)
+    def handle_checkpoint_continue(self) -> None:
+        """Continue to next step when user approves at checkpoint."""
+        self._hide_checkpoint_widget()
+        self._execute_next_step()
+
+    @on(CheckpointModify)
+    def handle_checkpoint_modify(self) -> None:
+        """Return to prompt input for plan modification."""
+        self._hide_checkpoint_widget()
+
+        if isinstance(self.deps, RouterDeps):
+            self.deps.is_executing = False
+
+        self.widget_coordinator.update_prompt_input(focus=True)
+
+    @on(CheckpointStop)
+    def handle_checkpoint_stop(self) -> None:
+        """Stop execution, keep remaining steps as pending."""
+        self._hide_checkpoint_widget()
+
+        if isinstance(self.deps, RouterDeps):
+            self.deps.is_executing = False
+
+        # Show confirmation message
+        self.mount_hint("⏸️ Execution stopped. Remaining steps are still in the plan.")
+        self.widget_coordinator.update_prompt_input(focus=True)
+
+    def _show_checkpoint_widget(
+        self,
+        step: "ExecutionStep",
+        next_step: "ExecutionStep | None",
+    ) -> None:
+        """Replace PromptInput with StepCheckpointWidget.
+
+        Args:
+            step: The step that was just completed.
+            next_step: The next step to execute, or None if last step.
+        """
+        # Create the checkpoint widget
+        self._checkpoint_widget = StepCheckpointWidget(step, next_step)
+
+        # Hide PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = False
+
+        # Mount checkpoint widget in footer
+        footer = self.query_one("#footer")
+        footer.mount(self._checkpoint_widget, after=prompt_input)
+
+    def _hide_checkpoint_widget(self) -> None:
+        """Remove checkpoint widget, restore PromptInput."""
+        if hasattr(self, "_checkpoint_widget") and self._checkpoint_widget:
+            self._checkpoint_widget.remove()
+            self._checkpoint_widget = None
+
+        # Show PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = True
+
+    def _execute_next_step(self) -> None:
+        """Execute the next step in the plan."""
+        if not isinstance(self.deps, RouterDeps) or not self.deps.current_plan:
+            return
+
+        # Advance to next step
+        plan = self.deps.current_plan
+        plan.current_step_index += 1
+
+        next_step = plan.current_step()
+        if next_step:
+            # Resume router execution for the next step
+            self.run_agent(f"Continue with next step: {next_step.title}")
+        else:
+            # Plan complete
+            self.deps.is_executing = False
+            self.mount_hint("✅ All plan steps completed!")
+            self.widget_coordinator.update_prompt_input(focus=True)
+
+    def _check_pending_checkpoint(self) -> None:
+        """Check if there's a pending checkpoint and post StepCompleted if so.
+
+        This is called after each agent run to check if mark_step_done
+        set a pending checkpoint in Planning mode.
+        """
+        if not isinstance(self.deps, RouterDeps):
+            return
+
+        if self.deps.pending_checkpoint is None:
+            return
+
+        # Extract checkpoint data and clear the pending state
+        checkpoint = self.deps.pending_checkpoint
+        self.deps.pending_checkpoint = None
+
+        # Post the StepCompleted message to trigger the checkpoint UI
+        self.post_message(
+            StepCompleted(
+                step=checkpoint.completed_step, next_step=checkpoint.next_step
+            )
+        )
+
+    # =========================================================================
+    # Sub-Agent Lifecycle Handlers (Stage 8)
+    # =========================================================================
+
+    @on(SubAgentStarted)
+    def handle_sub_agent_started(self, event: SubAgentStarted) -> None:
+        """Update mode indicator when router delegates to a sub-agent.
+
+        Sets the active_sub_agent in RouterDeps and refreshes the mode
+        indicator to show "📋 Planning → Research" format.
+        """
+        if isinstance(self.deps, RouterDeps):
+            self.deps.active_sub_agent = event.agent_type
+            self.widget_coordinator.refresh_mode_indicator()
+
+    @on(SubAgentCompleted)
+    def handle_sub_agent_completed(self, event: SubAgentCompleted) -> None:
+        """Clear sub-agent display when delegation completes.
+
+        Clears the active_sub_agent in RouterDeps and refreshes the mode
+        indicator to show just the mode name.
+        """
+        if isinstance(self.deps, RouterDeps):
+            self.deps.active_sub_agent = None
+            self.widget_coordinator.refresh_mode_indicator()
+
+    # =========================================================================
+    # Cascade Confirmation Handlers (Planning Mode)
+    # =========================================================================
+
+    @on(CascadeConfirmationRequired)
+    def handle_cascade_confirmation_required(
+        self, event: CascadeConfirmationRequired
+    ) -> None:
+        """Show cascade confirmation widget when a file with dependents is updated.
+
+        In Planning mode, after updating a file like specification.md that has
+        dependent files, this shows the CascadeConfirmationWidget to let the
+        user decide which dependent files should also be updated.
+        """
+        if not isinstance(self.deps, RouterDeps):
+            return
+        if self.deps.router_mode != RouterMode.PLANNING:
+            # In Drafting mode, auto-cascade without confirmation
+            self._execute_cascade(CascadeScope.ALL, event.dependent_files)
+            return
+
+        # Show cascade confirmation widget
+        self._show_cascade_widget(event.updated_file, event.dependent_files)
+
+    @on(CascadeConfirmed)
+    def handle_cascade_confirmed(self, event: CascadeConfirmed) -> None:
+        """Execute cascade update based on user's selected scope."""
+        # Get dependent files from the widget before hiding it
+        dependent_files: list[str] = []
+        if self._cascade_widget:
+            dependent_files = self._cascade_widget.dependent_files
+
+        self._hide_cascade_widget()
+        self._execute_cascade(event.scope, dependent_files)
+
+    @on(CascadeDeclined)
+    def handle_cascade_declined(self) -> None:
+        """Handle user declining cascade update."""
+        self._hide_cascade_widget()
+        self.mount_hint(
+            "ℹ️ Cascade update skipped. You can update dependent files manually."
+        )
+        self.widget_coordinator.update_prompt_input(focus=True)
+
+    def _show_cascade_widget(
+        self,
+        updated_file: str,
+        dependent_files: list[str],
+    ) -> None:
+        """Replace PromptInput with CascadeConfirmationWidget.
+
+        Args:
+            updated_file: The file that was just updated.
+            dependent_files: List of files that depend on the updated file.
+        """
+        # Create the cascade confirmation widget
+        self._cascade_widget = CascadeConfirmationWidget(updated_file, dependent_files)
+
+        # Hide PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = False
+
+        # Mount cascade widget in footer
+        footer = self.query_one("#footer")
+        footer.mount(self._cascade_widget, after=prompt_input)
+
+    def _hide_cascade_widget(self) -> None:
+        """Remove cascade widget, restore PromptInput."""
+        if self._cascade_widget:
+            self._cascade_widget.remove()
+            self._cascade_widget = None
+
+        # Show PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = True
+
+    def _execute_cascade(self, scope: CascadeScope, dependent_files: list[str]) -> None:
+        """Execute cascade updates based on the selected scope.
+
+        Args:
+            scope: The scope of files to update.
+            dependent_files: List of dependent files that could be updated.
+
+        Note:
+            Actual cascade execution (calling sub-agents) requires Stage 9's
+            delegation tools. For now, this shows a hint about what would happen.
+        """
+        if scope == CascadeScope.NONE:
+            return
+
+        # Determine which files will be updated based on scope
+        files_to_update: list[str] = []
+        if scope == CascadeScope.ALL:
+            files_to_update = dependent_files
+        elif scope == CascadeScope.PLAN_ONLY:
+            files_to_update = [f for f in dependent_files if "plan.md" in f]
+        elif scope == CascadeScope.TASKS_ONLY:
+            files_to_update = [f for f in dependent_files if "tasks.md" in f]
+
+        if files_to_update:
+            file_names = ", ".join(f.split("/")[-1] for f in files_to_update)
+            # TODO: Stage 9 will implement actual delegation to sub-agents
+            self.mount_hint(f"📋 Cascade update queued for: {file_names}")
+
+        self.widget_coordinator.update_prompt_input(focus=True)
+
+    def _check_pending_cascade(self) -> None:
+        """Check if there's a pending cascade and post CascadeConfirmationRequired if so.
+
+        This is called after each agent run to check if a file modification
+        set a pending cascade in Planning mode.
+        """
+        if not isinstance(self.deps, RouterDeps):
+            return
+
+        if self.deps.pending_cascade is None:
+            return
+
+        # Extract cascade data and clear the pending state
+        cascade = self.deps.pending_cascade
+        self.deps.pending_cascade = None
+
+        # Post the CascadeConfirmationRequired message to trigger the cascade UI
+        self.post_message(
+            CascadeConfirmationRequired(
+                updated_file=cascade.updated_file,
+                dependent_files=cascade.dependent_files,
+            )
+        )
+
+    # =========================================================================
+    # Plan Approval Handlers (Planning Mode - Stage 7)
+    # =========================================================================
+
+    @on(PlanApprovalRequired)
+    def handle_plan_approval_required(self, event: PlanApprovalRequired) -> None:
+        """Show approval widget when a multi-step plan is created.
+
+        In Planning mode, after creating a plan with multiple steps,
+        this shows the PlanApprovalWidget to let the user decide
+        whether to proceed or clarify.
+        """
+        logger.debug(
+            "[PLAN] handle_plan_approval_required - plan=%s",
+            f"'{event.plan.goal}' with {len(event.plan.steps)} steps",
+        )
+        if not isinstance(self.deps, RouterDeps):
+            logger.debug("[PLAN] Not RouterDeps, skipping approval widget")
+            return
+        if self.deps.router_mode != RouterMode.PLANNING:
+            logger.debug(
+                "[PLAN] Not in PLANNING mode (%s), skipping approval widget",
+                self.deps.router_mode,
+            )
+            return
+
+        # Show approval widget
+        logger.debug("[PLAN] Showing approval widget")
+        self._show_approval_widget(event.plan)
+
+    @on(PlanApproved)
+    def handle_plan_approved(self) -> None:
+        """Begin plan execution when user approves."""
+        self._hide_approval_widget()
+
+        if isinstance(self.deps, RouterDeps):
+            self.deps.approval_status = PlanApprovalStatus.APPROVED
+            self.deps.is_executing = True
+
+            # Switch to Drafting mode when plan is approved
+            self.deps.router_mode = RouterMode.DRAFTING
+            self._save_router_mode(RouterMode.DRAFTING.value)
+            self.widget_coordinator.update_for_mode_change(self.mode)
+
+            # Begin execution of the first step
+            plan = self.deps.current_plan
+            if plan and plan.current_step():
+                first_step = plan.current_step()
+                if first_step:
+                    self.run_agent(f"Execute step: {first_step.title}")
+            else:
+                self.widget_coordinator.update_prompt_input(focus=True)
+
+    @on(PlanRejected)
+    def handle_plan_rejected(self) -> None:
+        """Return to prompt input for clarification when user rejects plan."""
+        self._hide_approval_widget()
+
+        if isinstance(self.deps, RouterDeps):
+            self.deps.approval_status = PlanApprovalStatus.REJECTED
+            # Clear the plan since user wants to modify
+            self.deps.current_plan = None
+
+        self.mount_hint("ℹ️ Plan cancelled. Please clarify what you'd like to do.")
+        self.widget_coordinator.update_prompt_input(focus=True)
+
+    def _show_approval_widget(self, plan: ExecutionPlan) -> None:
+        """Replace PromptInput with PlanApprovalWidget.
+
+        Args:
+            plan: The execution plan that needs user approval.
+        """
+        # Create the approval widget
+        self._approval_widget = PlanApprovalWidget(plan)
+
+        # Hide PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = False
+
+        # Mount approval widget in footer
+        footer = self.query_one("#footer")
+        footer.mount(self._approval_widget, after=prompt_input)
+
+    def _hide_approval_widget(self) -> None:
+        """Remove approval widget, restore PromptInput."""
+        if self._approval_widget:
+            self._approval_widget.remove()
+            self._approval_widget = None
+
+        # Show PromptInput
+        prompt_input = self.query_one(PromptInput)
+        prompt_input.display = True
+
+    def _check_pending_approval(self) -> None:
+        """Check if there's a pending approval and post PlanApprovalRequired if so.
+
+        This is called after each agent run to check if create_plan
+        set a pending approval in Planning mode.
+        """
+        logger.debug("[PLAN] _check_pending_approval called")
+        if not isinstance(self.deps, RouterDeps):
+            logger.debug("[PLAN] Not RouterDeps, skipping pending approval check")
+            return
+
+        if self.deps.pending_approval is None:
+            logger.debug("[PLAN] No pending approval")
+            return
+
+        # Extract approval data and clear the pending state
+        approval = self.deps.pending_approval
+        self.deps.pending_approval = None
+
+        logger.debug(
+            "[PLAN] Found pending approval for plan: '%s' with %d steps",
+            approval.plan.goal,
+            len(approval.plan.steps),
+        )
+
+        # Post the PlanApprovalRequired message to trigger the approval UI
+        self.post_message(PlanApprovalRequired(plan=approval.plan))
+
+    # =========================================================================
+    # Plan Panel (Stage 11)
+    # =========================================================================
+
+    @on(PlanUpdated)
+    def handle_plan_updated(self, event: PlanUpdated) -> None:
+        """Auto-show/hide plan panel when plan changes.
+
+        The plan panel automatically shows when a plan is created or
+        modified, and hides when the plan is cleared.
+        """
+        if event.plan is not None:
+            # Show panel (auto-reopens when plan changes)
+            self._show_plan_panel(event.plan)
+        else:
+            # Plan cleared - hide panel
+            self._hide_plan_panel()
+
+    @on(PlanPanelClosed)
+    def handle_plan_panel_closed(self, event: PlanPanelClosed) -> None:
+        """Handle user closing the plan panel with × button."""
+        self._hide_plan_panel()
+
+    def _show_plan_panel(self, plan: ExecutionPlan) -> None:
+        """Show the plan panel with the given plan.
+
+        Args:
+            plan: The execution plan to display.
+        """
+        if self._plan_panel is None:
+            self._plan_panel = PlanPanelWidget(plan)
+            # Mount in window container, before footer
+            window = self.query_one("#window")
+            footer = self.query_one("#footer")
+            window.mount(self._plan_panel, before=footer)
+        else:
+            self._plan_panel.update_plan(plan)
+
+    def _hide_plan_panel(self) -> None:
+        """Hide the plan panel."""
+        if self._plan_panel:
+            self._plan_panel.remove()
+            self._plan_panel = None
+
+    def _on_plan_changed(self, plan: ExecutionPlan | None) -> None:
+        """Handle plan changes from router tools.
+
+        This callback is set on RouterDeps to receive plan updates
+        and post PlanUpdated messages to update the plan panel.
+
+        Args:
+            plan: The updated plan or None if plan was cleared.
+        """
+        logger.debug(
+            "[PLAN] _on_plan_changed called - plan=%s",
+            f"'{plan.goal}' with {len(plan.steps)} steps" if plan else "None",
+        )
+        self.post_message(PlanUpdated(plan))