shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/tui/screens/chat/chat_screen.py

@@ -5,8 +5,12 @@ 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 import BinaryContent
 from pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
@@ -30,11 +34,13 @@ from shotgun.agents.agent_manager import (
     ClarifyingQuestionsMessage,
     CompactionCompletedMessage,
     CompactionStartedMessage,
+    FileRequestPendingMessage,
     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 import ConversationManager
 from shotgun.agents.conversation.history.compaction import apply_persistent_compaction
@@ -46,7 +52,25 @@ from shotgun.agents.models import (
     AgentType,
     FileOperationTracker,
 )
+from shotgun.agents.router.models import (
+    CascadeScope,
+    ExecutionPlan,
+    PlanApprovalStatus,
+    RouterDeps,
+    RouterMode,
+)
 from shotgun.agents.runner import AgentRunner
+from shotgun.attachments import (
+    FileAttachment,
+    parse_attachment_reference,
+    process_attachment,
+)
+from shotgun.codebase.core.errors import (
+    DatabaseIssue,
+    KuzuErrorType,
+    classify_kuzu_error,
+)
+from shotgun.codebase.core.kuzu_compat import KuzuImportError
 from shotgun.codebase.core.manager import (
     CodebaseAlreadyIndexedError,
     CodebaseGraphManager,
@@ -54,6 +78,7 @@ from shotgun.codebase.core.manager import (
 from shotgun.codebase.models import IndexProgress, ProgressPhase
 from shotgun.exceptions import (
     SHOTGUN_CONTACT_EMAIL,
+    AgentCancelledException,
     ErrorNotPickedUpBySentry,
     ShotgunAccountException,
 )
@@ -61,6 +86,7 @@ from shotgun.posthog_telemetry import track_event
 from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
 from shotgun.tui.commands import CommandHandler
+from shotgun.tui.components.attachment_bar import AttachmentBar
 from shotgun.tui.components.context_indicator import ContextIndicator
 from shotgun.tui.components.mode_indicator import ModeIndicator
 from shotgun.tui.components.prompt_input import PromptInput
@@ -83,8 +109,27 @@ 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.database_locked_dialog import DatabaseLockedDialog
+from shotgun.tui.screens.database_timeout_dialog import DatabaseTimeoutDialog
+from shotgun.tui.screens.kuzu_error_dialog import KuzuErrorDialog
+from shotgun.tui.screens.models import LockedDialogAction
 from shotgun.tui.screens.shared_specs import (
     CreateSpecDialog,
     ShareSpecsAction,
@@ -94,6 +139,10 @@ from shotgun.tui.screens.shared_specs import (
 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
@@ -133,7 +182,6 @@ class ChatScreen(Screen[None]):
     CSS_PATH = "chat.tcss"
 
     BINDINGS = [
-        ("ctrl+p", "command_palette", "Command Palette"),
         ("shift+tab", "toggle_mode", "Toggle mode"),
         ("ctrl+u", "show_usage", "Show usage"),
     ]
@@ -161,6 +209,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,
@@ -199,6 +259,11 @@ class ChatScreen(Screen[None]):
 
         # 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
@@ -211,6 +276,10 @@ class ChatScreen(Screen[None]):
         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
         self.widget_coordinator.update_prompt_input(focus=True)
@@ -233,9 +302,6 @@ class ChatScreen(Screen[None]):
         # Initial update of context indicator
         self.update_context_indicator()
 
-        # Show onboarding popup if not shown before
-        self.call_later(self._check_and_show_onboarding)
-
     async def on_key(self, event: events.Key) -> None:
         """Handle key presses for cancellation."""
         # If escape is pressed during Q&A mode, exit Q&A
@@ -257,8 +323,152 @@ class ChatScreen(Screen[None]):
                 # Prevent the event from propagating (don't quit the app)
                 event.stop()
 
+    async def _handle_pending_database_issues(self) -> bool:
+        """Handle any database issues detected at startup.
+
+        This method processes pending database issues (locked, corrupted, timeout)
+        and shows appropriate dialogs to the user.
+
+        Returns:
+            True if should continue with normal startup, False if should abort
+        """
+        from shotgun.codebase.core.manager import CodebaseGraphManager
+        from shotgun.utils import get_shotgun_home
+
+        # Get pending issues from app
+        pending_issues: list[DatabaseIssue] = getattr(self.app, "pending_db_issues", [])
+        if not pending_issues:
+            return True
+
+        storage_dir = get_shotgun_home() / "codebases"
+        manager = CodebaseGraphManager(storage_dir)
+
+        # Handle locked databases first - show ONE dialog for all locked DBs
+        locked_issues = [
+            i for i in pending_issues if i.error_type == KuzuErrorType.LOCKED
+        ]
+        if locked_issues:
+            # Show single locked dialog
+            locked_action = await self.app.push_screen_wait(DatabaseLockedDialog())
+
+            if locked_action == LockedDialogAction.QUIT:
+                # User cancelled - exit the app gracefully
+                await self.app.action_quit()
+                return False
+
+            if locked_action == LockedDialogAction.DELETE:
+                # User confirmed deletion of locked databases
+                for issue in locked_issues:
+                    deleted = await manager.delete_database(issue.graph_id)
+                    if deleted:
+                        logger.info(f"Deleted locked database: {issue.graph_id}")
+                        self.agent_manager.add_hint_message(
+                            HintMessage(
+                                message=f"Deleted locked database '{issue.graph_id}'. "
+                                "You can re-index using /index."
+                            )
+                        )
+                    else:
+                        logger.error(
+                            f"Failed to delete locked database: {issue.graph_id}"
+                        )
+                # Continue with startup after deletion
+                return True
+
+            # locked_action == LockedDialogAction.RETRY - re-detect to see if locks are cleared
+            new_issues = await manager.detect_database_issues(timeout_seconds=10.0)
+            still_locked = [
+                i for i in new_issues if i.error_type == KuzuErrorType.LOCKED
+            ]
+            if still_locked:
+                # Still locked - show hint message
+                self.agent_manager.add_hint_message(
+                    HintMessage(
+                        message="Database is still locked. "
+                        "Please close the other shotgun instance and restart."
+                    )
+                )
+                await self.app.action_quit()
+                return False
+
+        # Process non-locked issues
+        for issue in pending_issues:
+            if issue.error_type == KuzuErrorType.LOCKED:
+                continue  # Already handled above
+
+            if issue.error_type == KuzuErrorType.TIMEOUT:
+                # Show timeout dialog
+                action = await self.app.push_screen_wait(
+                    DatabaseTimeoutDialog(
+                        codebase_name=issue.graph_id,
+                        timeout_seconds=10.0,
+                    )
+                )
+                if action == "retry":
+                    # Retry with longer timeout (90s)
+                    new_issues = await manager.detect_database_issues(
+                        timeout_seconds=90.0
+                    )
+                    still_timeout = any(
+                        i.graph_id == issue.graph_id
+                        and i.error_type == KuzuErrorType.TIMEOUT
+                        for i in new_issues
+                    )
+                    if still_timeout:
+                        self.agent_manager.add_hint_message(
+                            HintMessage(
+                                message=f"Database '{issue.graph_id}' still not responding. "
+                                "It may be corrupted or the codebase is extremely large."
+                            )
+                        )
+                elif action == "skip":
+                    # User chose to skip this database
+                    logger.info(f"User skipped timeout database: {issue.graph_id}")
+                # "cancel" - do nothing
+
+            elif issue.error_type == KuzuErrorType.CORRUPTION:
+                # Show corruption confirmation dialog
+                should_delete = await self.app.push_screen_wait(
+                    ConfirmationDialog(
+                        title="Database Corrupted",
+                        message=(
+                            f"The codebase index '{issue.graph_id}' appears to be corrupted.\n\n"
+                            f"Error: {issue.message}\n\n"
+                            "Would you like to delete it? You will need to re-index the codebase."
+                        ),
+                        confirm_label="Delete & Re-index",
+                        cancel_label="Keep (Skip)",
+                        confirm_variant="warning",
+                        danger=True,
+                    )
+                )
+                if should_delete:
+                    deleted = await manager.delete_database(issue.graph_id)
+                    if deleted:
+                        self.agent_manager.add_hint_message(
+                            HintMessage(
+                                message=f"Deleted corrupted database '{issue.graph_id}'. "
+                                "You can re-index using /index."
+                            )
+                        )
+                    else:
+                        logger.error(
+                            f"Failed to delete corrupted database: {issue.graph_id}"
+                        )
+
+        # Clear the pending issues after processing
+        if hasattr(self.app, "pending_db_issues"):
+            self.app.pending_db_issues = []
+
+        return True
+
     @work
     async def check_if_codebase_is_indexed(self) -> None:
+        # Handle any pending database issues from startup first
+        should_continue = await self._handle_pending_database_issues()
+        if not should_continue:
+            return
+
         cur_dir = Path.cwd().resolve()
         is_empty = all(
             dir.is_dir() and dir.name in ["__pycache__", ".git", ".shotgun"]
@@ -331,24 +541,81 @@ 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:
-        # Prevent mode switching during Q&A
+        """Toggle between Planning and Drafting modes for Router."""
+        from shotgun.agents.router.models import RouterDeps, RouterMode
+
+        # If in Q&A mode, exit it first (SHIFT+TAB escapes Q&A mode)
         if self.qa_mode:
+            self._exit_qa_mode()
             self.agent_manager.add_hint_message(
-                HintMessage(message="⚠️ Cannot switch modes while answering questions")
+                HintMessage(message="Exited Q&A mode via Shift+Tab")
             )
             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
+
+        # 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))
 
     async def action_show_usage(self) -> None:
@@ -436,10 +703,6 @@ class ChatScreen(Screen[None]):
                 HintMessage(message="⚠️ No context analysis available")
             )
 
-    def action_view_onboarding(self) -> None:
-        """Show the onboarding modal."""
-        self.app.push_screen(OnboardingModal())
-
     @work
     async def action_compact_conversation(self) -> None:
         """Compact the conversation history to reduce size."""
@@ -682,6 +945,7 @@ class ChatScreen(Screen[None]):
                     classes="" if self.working else "hidden",
                 )
                 yield StatusBar(working=self.working)
+                yield AttachmentBar(id="attachment-bar")
                 yield PromptInput(
                     text=self.value,
                     highlight_cursor_line=False,
@@ -745,6 +1009,72 @@ class ChatScreen(Screen[None]):
         )
         self.agent_manager.add_hint_message(hint)
 
+    async def execute_shell_command(self, command: str) -> None:
+        """Execute a shell command and display output.
+
+        This implements the `!`-to-shell behavior for interactive mode.
+        Commands are executed in the current working directory with
+        full shell features (pipes, redirection, etc.).
+
+        Args:
+            command: The shell command to execute (after stripping the leading `!`)
+
+        Note:
+            - Commands are executed with shell=True for full shell features
+            - Output is streamed to the TUI via hint messages
+            - Errors are displayed but do not crash the application
+            - Commands are NOT added to conversation history
+        """
+        # Handle empty command (just `!` with nothing after it)
+        if not command or command.isspace():
+            self.mount_hint("⚠️ Empty shell command. Usage: `!<command>`")
+            return
+
+        # Show what command is being executed
+        # Use code block for better visibility
+        self.mount_hint(f"**Running:** `{command}`")
+
+        try:
+            # Execute with shell=True to support pipes, redirection, etc.
+            # Run in current working directory
+            process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=Path.cwd(),
+            )
+
+            # Wait for command to complete and capture output
+            stdout_bytes, stderr_bytes = await process.communicate()
+            stdout = stdout_bytes.decode("utf-8", errors="replace")
+            stderr = stderr_bytes.decode("utf-8", errors="replace")
+            return_code = process.returncode or 0
+
+            # Build output message
+            output_parts = []
+
+            if stdout:
+                # Show stdout in a code block for proper formatting
+                output_parts.append(f"```\n{stdout.rstrip()}\n```")
+
+            if stderr:
+                # Show stderr with a warning indicator
+                output_parts.append(f"**stderr:**\n```\n{stderr.rstrip()}\n```")
+
+            if return_code != 0:
+                # Show non-zero exit code as error
+                output_parts.append(f"**Exit code:** {return_code}")
+
+            # Display output (or success message if no output)
+            if output_parts:
+                self.mount_hint("\n\n".join(output_parts))
+            elif return_code == 0:
+                self.mount_hint("✓ Command completed successfully (no output)")
+
+        except Exception as e:
+            # Show error message
+            self.mount_hint(f"❌ **Shell command failed:**\n```\n{str(e)}\n```")
+
     @on(PartialResponseMessage)
     def handle_partial_response(self, event: PartialResponseMessage) -> None:
         # Filter event.messages to exclude ModelRequest with only ToolReturnPart
@@ -786,6 +1116,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()
@@ -832,17 +1168,88 @@ class ChatScreen(Screen[None]):
         # Clear any streaming partial response (removes final_result JSON)
         self._clear_partial_response()
 
+        # Safety check: don't enter Q&A mode if questions array is empty
+        if not event.questions:
+            logger.warning("ClarifyingQuestionsMessage received with empty questions")
+            return
+
         # Enter Q&A mode
         self.qa_mode = True
         self.qa_questions = event.questions
         self.qa_current_index = 0
         self.qa_answers = []
 
+    @on(FileRequestPendingMessage)
+    def handle_file_request_pending(self, event: FileRequestPendingMessage) -> None:
+        """Handle file request from agent structured output.
+
+        When the agent returns file_requests in its response, we load the files
+        and resume the agent with the file contents.
+        """
+        logger.debug(
+            "[FILE_REQUEST] FileRequestPendingMessage received - %d files",
+            len(event.file_paths),
+        )
+        # Clear any streaming partial response
+        self._clear_partial_response()
+
+        # Process files and resume agent (run as background task)
+        self._process_files_and_resume(event.file_paths)
+
+    @work(exclusive=True, name="process_files_and_resume")
+    async def _process_files_and_resume(self, file_paths: list[str]) -> None:
+        """Load requested files and resume agent with content.
+
+        This runs as a background worker to avoid blocking the UI.
+        """
+        logger.debug("[FILE_REQUEST] Processing %d file requests", len(file_paths))
+
+        # Set working state
+        self.working = True
+        self.widget_coordinator.update_spinner_text("Loading files...")
+
+        try:
+            # Load files via agent manager
+            file_contents = self.agent_manager.process_file_requests()
+
+            if not file_contents:
+                logger.warning("[FILE_REQUEST] No files were successfully loaded")
+                self.mount_hint("⚠️ Could not load any of the requested files.")
+                self.working = False
+                return
+
+            logger.info(
+                "[FILE_REQUEST] Loaded %d files, resuming agent",
+                len(file_contents),
+            )
+
+            # Resume agent with file contents
+            # Note: We call run_agent directly since we're already in a worker
+            runner = AgentRunner(self.agent_manager)
+            await runner.run(
+                prompt=(
+                    "The files you requested are now loaded and included below. "
+                    "Analyze the file contents and respond to the user's original question. "
+                    "DO NOT use file_requests - the files are already provided in this message."
+                ),
+                file_contents=file_contents,
+            )
+            # Mark work as complete after successful file processing
+            self.working = False
+        except Exception as e:
+            logger.error("[FILE_REQUEST] Error processing files: %s", e)
+            self.mount_hint(f"⚠️ Error loading files: {e}")
+            self.working = False
+
     @on(MessageHistoryUpdated)
     async def handle_message_history_updated(
         self, event: MessageHistoryUpdated
     ) -> None:
         """Handle message history updates from the agent manager."""
+        logger.debug(
+            "[MSG_HISTORY] MessageHistoryUpdated received - %d messages",
+            len(event.messages),
+        )
         self._clear_partial_response()
         self.messages = event.messages
 
@@ -913,6 +1320,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.
 
@@ -984,8 +1414,27 @@ class ChatScreen(Screen[None]):
                 HintMessage(message=f"⚠ Failed to update model configuration: {e}")
             )
 
+    @on(PromptInput.OpenCommandPalette)
+    def _on_open_command_palette(self, event: PromptInput.OpenCommandPalette) -> None:
+        """Open command palette when triggered by '/' prefix."""
+        self.app.action_command_palette()
+
     @on(PromptInput.Submitted)
     async def handle_submit(self, message: PromptInput.Submitted) -> None:
+        """Handle user input submission from the prompt.
+
+        This is the main interactive loop entrypoint for shotgun-cli TUI.
+        Input classification:
+        1. Lines starting with `!` (after trimming whitespace) are shell commands
+        2. Lines starting with `/` are internal commands
+        3. All other lines are sent to the LLM
+
+        Shell command behavior (`!`-to-shell):
+        - Lines like `!ls` or `  !git status` execute as shell commands
+        - Shell commands are NOT sent to LLM
+        - Shell commands are NOT added to conversation history
+        - Implementation: v1 limitation - no history expansion (!!, !$, etc.)
+        """
         text = message.text.strip()
 
         # If empty text, just clear input and return
@@ -994,6 +1443,23 @@ class ChatScreen(Screen[None]):
             self.value = ""
             return
 
+        # Stage 1: Classify input - check if line starts with `!` (shell command)
+        # Trim leading whitespace and check first character
+        trimmed = message.text.lstrip()
+        if trimmed.startswith("!"):
+            # This is a shell command - extract the command by removing exactly one `!`
+            # Note: `!!ls` becomes `!ls` in v1 (no special history expansion)
+            shell_command = trimmed[1:]  # Remove the leading `!`
+
+            # Execute shell command (do NOT forward to LLM or add to history)
+            await self.execute_shell_command(shell_command)
+
+            # Clear input and return (do not proceed to LLM handling)
+            # This ensures shell commands are never added to conversation history
+            self.widget_coordinator.update_prompt_input(clear=True)
+            self.value = ""
+            return
+
         # Handle Q&A mode (from structured output clarifying questions)
         if self.qa_mode and self.qa_questions:
             # Collect answer
@@ -1069,6 +1535,33 @@ class ChatScreen(Screen[None]):
             return
 
         # Not a command, process as normal
+
+        # Parse for @path attachment references
+        parse_result = parse_attachment_reference(text)
+
+        if parse_result.error_message:
+            self.mount_hint(parse_result.error_message)
+            self.widget_coordinator.update_prompt_input(clear=True)
+            self.value = ""
+            return
+
+        # Process attachment if found (encode to base64, validate size)
+        attachment: FileAttachment | None = None
+        if parse_result.attachment:
+            processed_attachment, error = await process_attachment(
+                parse_result.attachment,
+                self.deps.llm_model.provider,
+            )
+            if error:
+                self.mount_hint(error)
+                self.widget_coordinator.update_prompt_input(clear=True)
+                self.value = ""
+                return
+            attachment = processed_attachment
+
+            # Show attachment in the attachment bar
+            self.widget_coordinator.update_attachment_bar(attachment)
+
         self.history.append(message.text)
 
         # Add user message to agent_manager's history BEFORE running the agent
@@ -1077,9 +1570,10 @@ class ChatScreen(Screen[None]):
         self.agent_manager.ui_message_history.append(user_message)
         self.messages = self.agent_manager.ui_message_history.copy()
 
-        # Clear the input
+        # Clear the input and attachment bar
         self.value = ""
-        self.run_agent(text)  # Use stripped text
+        self.widget_coordinator.update_attachment_bar(None)
+        self.run_agent(text, attachment=attachment)  # Use stripped text
 
         self.widget_coordinator.update_prompt_input(clear=True)
 
@@ -1196,6 +1690,17 @@ class ChatScreen(Screen[None]):
                 HintMessage(message=f"❌ Failed to delete codebase: {exc}")
             )
 
+    def _classify_kuzu_error(self, exception: Exception) -> KuzuErrorType:
+        """Classify a Kuzu database error.
+
+        Args:
+            exception: The exception to classify
+
+        Returns:
+            KuzuErrorType indicating the category of error
+        """
+        return classify_kuzu_error(exception)
+
     def _is_kuzu_corruption_error(self, exception: Exception) -> bool:
         """Check if error is related to kuzu database corruption.
 
@@ -1203,221 +1708,275 @@ class ChatScreen(Screen[None]):
             exception: The exception to check
 
         Returns:
-            True if the error indicates kuzu database corruption
+            True if the error indicates kuzu database corruption or lock issues
         """
-        error_str = str(exception).lower()
-        error_indicators = [
-            "not a directory",
-            "errno 20",
-            "corrupted",
-            ".kuzu",
-            "ioexception",
-            "unordered_map",  # C++ STL map errors from kuzu
-            "key not found",  # unordered_map::at errors
-            "std::exception",  # Generic C++ exceptions from kuzu
-        ]
-        return any(indicator in error_str for indicator in error_indicators)
+        error_type = classify_kuzu_error(exception)
+        # Consider corruption and lock errors as "kuzu errors" that need special handling
+        return error_type in (
+            KuzuErrorType.CORRUPTION,
+            KuzuErrorType.LOCKED,
+            KuzuErrorType.SCHEMA,
+        )
 
-    @work
+    @work(group="indexing", exit_on_error=False)
     async def index_codebase(self, selection: CodebaseIndexSelection) -> None:
+        logger.debug(f"index_codebase worker starting for {selection.repo_path}")
         index_start_time = time.time()
 
+        # Compute graph_id to track indexing state
+        graph_id = self.codebase_sdk.service.compute_graph_id(selection.repo_path)
+
+        # Mark indexing as started and show hint
+        await self.codebase_sdk.service.indexing.start(graph_id)
+        self.agent_manager.add_hint_message(
+            HintMessage(
+                message="Indexing has started. The codebase graph will be "
+                "inaccessible to the AI Agents until this is completed."
+            )
+        )
+
         label = self.query_one("#indexing-job-display", Static)
         label.update(
             f"[$foreground-muted]Indexing codebase: [bold $text-accent]{selection.name}[/][/]"
         )
         label.refresh()
 
-        def create_progress_bar(percentage: float, width: int = 20) -> str:
-            """Create a visual progress bar using Unicode block characters."""
-            filled = int((percentage / 100) * width)
-            empty = width - filled
-            return "▓" * filled + "░" * empty
-
-        # Spinner animation frames
-        spinner_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
-
-        # Progress state (shared between timer and progress callback)
-        progress_state: dict[str, int | float] = {
-            "frame_index": 0,
-            "percentage": 0.0,
-        }
-
-        def update_progress_display() -> None:
-            """Update progress bar on timer - runs every 100ms."""
-            # Advance spinner frame
-            frame_idx = int(progress_state["frame_index"])
-            progress_state["frame_index"] = (frame_idx + 1) % len(spinner_frames)
-            spinner = spinner_frames[frame_idx]
-
-            # Get current state
-            pct = float(progress_state["percentage"])
-            bar = create_progress_bar(pct)
-
-            # Update label
-            label.update(
-                f"[$foreground-muted]Indexing codebase: {spinner} {bar} {pct:.0f}%[/]"
-            )
+        # Track progress timer for cleanup
+        progress_timer = None
 
-        def progress_callback(progress_info: IndexProgress) -> None:
-            """Update progress state (timer renders it independently)."""
-            # 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-2% (actual: ~0%)
-                overall_pct = 2.0 if progress_info.phase_complete else 1.0
-            elif progress_info.phase == ProgressPhase.DEFINITIONS:
-                # 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) * 16.0
-                    overall_pct = 2.0 + phase_pct
-                else:
-                    overall_pct = 2.0
-            elif progress_info.phase == ProgressPhase.RELATIONSHIPS:
-                # 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) * 2.0
-                    overall_pct = 18.0 + phase_pct
-                else:
-                    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
+        try:
+
+            def create_progress_bar(percentage: float, width: int = 20) -> str:
+                """Create a visual progress bar using Unicode block characters."""
+                filled = int((percentage / 100) * width)
+                empty = width - filled
+                return "▓" * filled + "░" * empty
+
+            # Spinner animation frames
+            spinner_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+            # Progress state (shared between timer and progress callback)
+            progress_state: dict[str, int | float] = {
+                "frame_index": 0,
+                "percentage": 0.0,
+            }
+
+            def update_progress_display() -> None:
+                """Update progress bar on timer - runs every 100ms."""
+                # Advance spinner frame
+                frame_idx = int(progress_state["frame_index"])
+                progress_state["frame_index"] = (frame_idx + 1) % len(spinner_frames)
+                spinner = spinner_frames[frame_idx]
+
+                # Get current state
+                pct = float(progress_state["percentage"])
+                bar = create_progress_bar(pct)
+
+                # Update label
+                label.update(
+                    f"[$foreground-muted]Indexing codebase: {spinner} {bar} {pct:.0f}%[/]"
+                )
+
+            def progress_callback(progress_info: IndexProgress) -> None:
+                """Update progress state (timer renders it independently)."""
+                # 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-2% (actual: ~0%)
+                    overall_pct = 2.0 if progress_info.phase_complete else 1.0
+                elif progress_info.phase == ProgressPhase.DEFINITIONS:
+                    # 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) * 16.0
+                        overall_pct = 2.0 + phase_pct
+                    else:
+                        overall_pct = 2.0
+                elif progress_info.phase == ProgressPhase.RELATIONSHIPS:
+                    # 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) * 2.0
+                        overall_pct = 18.0 + phase_pct
+                    else:
+                        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 = 28.0
-            else:
-                overall_pct = 0.0
+                    overall_pct = 0.0
 
-            # Update shared state (timer will render it)
-            progress_state["percentage"] = overall_pct
+                # Update shared state (timer will render it)
+                progress_state["percentage"] = overall_pct
 
-        # Start progress animation timer (10 fps = 100ms interval)
-        progress_timer = self.set_interval(0.1, update_progress_display)
+            # Start progress animation timer (10 fps = 100ms interval)
+            progress_timer = self.set_interval(0.1, update_progress_display)
 
-        # Retry logic for handling kuzu corruption
-        max_retries = 3
+            # Retry logic for handling kuzu corruption
+            max_retries = 3
 
-        for attempt in range(max_retries):
-            try:
-                # Clean up corrupted DBs before retry (skip on first attempt)
-                if attempt > 0:
-                    logger.info(
-                        f"Retry attempt {attempt + 1}/{max_retries} - cleaning up corrupted databases"
-                    )
-                    manager = CodebaseGraphManager(
-                        self.codebase_sdk.service.storage_dir
-                    )
-                    cleaned = await manager.cleanup_corrupted_databases()
-                    logger.info(f"Cleaned up {len(cleaned)} corrupted database(s)")
-                    self.agent_manager.add_hint_message(
-                        HintMessage(
-                            message=f"🔄 Retrying indexing after cleanup (attempt {attempt + 1}/{max_retries})..."
+            for attempt in range(max_retries):
+                try:
+                    # Clean up corrupted DBs before retry (skip on first attempt)
+                    if attempt > 0:
+                        logger.info(
+                            f"Retry attempt {attempt + 1}/{max_retries} - cleaning up corrupted databases"
+                        )
+                        manager = CodebaseGraphManager(
+                            self.codebase_sdk.service.storage_dir
+                        )
+                        cleaned = await manager.cleanup_corrupted_databases()
+                        logger.info(f"Cleaned up {len(cleaned)} corrupted database(s)")
+                        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
+                    logger.debug(
+                        f"Starting indexing - repo_path: {selection.repo_path}, "
+                        f"name: {selection.name}, cwd: {Path.cwd().resolve()}"
+                    )
+                    result = await self.codebase_sdk.index_codebase(
+                        selection.repo_path,
+                        selection.name,
+                        indexed_from_cwd=str(Path.cwd().resolve()),
+                        progress_callback=progress_callback,
                     )
+                    logger.debug("index_codebase SDK call completed successfully")
 
-                # Pass the current working directory as the indexed_from_cwd
-                logger.debug(
-                    f"Starting indexing - repo_path: {selection.repo_path}, "
-                    f"name: {selection.name}, cwd: {Path.cwd().resolve()}"
-                )
-                result = await self.codebase_sdk.index_codebase(
-                    selection.repo_path,
-                    selection.name,
-                    indexed_from_cwd=str(Path.cwd().resolve()),
-                    progress_callback=progress_callback,
-                )
+                    # Success! Stop progress animation
+                    progress_timer.stop()
 
-                # Success! Stop progress animation
-                progress_timer.stop()
-
-                # Show 100% completion after indexing finishes
-                final_bar = create_progress_bar(100.0)
-                label.update(
-                    f"[$foreground-muted]Indexing codebase: {final_bar} 100%[/]"
-                )
-                label.refresh()
+                    # Show 100% completion after indexing finishes
+                    final_bar = create_progress_bar(100.0)
+                    label.update(
+                        f"[$foreground-muted]Indexing codebase: {final_bar} 100%[/]"
+                    )
+                    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)
+                    # 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}' in {duration_str} "
-                    f"({entity_count} entities)"
-                )
-                self.agent_manager.add_hint_message(
-                    HintMessage(
-                        message=f"✓ Indexed '{result.name}' in {duration_str} ({entity_str} entities)"
+                    logger.info(
+                        f"Successfully indexed codebase '{result.name}' in {duration_str} "
+                        f"({entity_count} entities)"
                     )
-                )
-                break  # Success - exit retry loop
-
-            except CodebaseAlreadyIndexedError as exc:
-                progress_timer.stop()
-                logger.warning(f"Codebase already indexed: {exc}")
-                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.agent_manager.add_hint_message(HintMessage(message=f"❌ {exc}"))
-                return
+                    self.agent_manager.add_hint_message(
+                        HintMessage(
+                            message=f"✓ Indexed '{result.name}' in {duration_str} ({entity_str} entities). "
+                            "Codebase graph is now accessible."
+                        )
+                    )
+                    break  # Success - exit retry loop
 
-            except Exception as exc:  # pragma: no cover - defensive UI path
-                # Check if this is a kuzu corruption error and we have retries left
-                if attempt < max_retries - 1 and self._is_kuzu_corruption_error(exc):
+                except asyncio.CancelledError:
                     logger.warning(
-                        f"Kuzu corruption detected on attempt {attempt + 1}/{max_retries}: {exc}. "
-                        f"Will retry after cleanup..."
+                        "index_codebase worker was cancelled - this should not happen"
                     )
-                    # Exponential backoff: 1s, 2s
-                    await asyncio.sleep(2**attempt)
-                    continue
-
-                # Either final retry failed OR not a corruption error - show error
-                logger.exception(
-                    f"Failed to index codebase after {attempt + 1} attempts - "
-                    f"repo_path: {selection.repo_path}, name: {selection.name}, error: {exc}"
-                )
-                self.agent_manager.add_hint_message(
-                    HintMessage(
-                        message=f"❌ Failed to index codebase after {attempt + 1} attempts: {exc}"
+                    raise  # Re-raise to let finally block clean up
+
+                except CodebaseAlreadyIndexedError as exc:
+                    progress_timer.stop()
+                    logger.warning(f"Codebase already indexed: {exc}")
+                    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.agent_manager.add_hint_message(
+                        HintMessage(message=f"❌ {exc}")
+                    )
+                    return
+                except KuzuImportError as exc:
+                    progress_timer.stop()
+                    logger.error(f"Kuzu import error (Windows DLL issue): {exc}")
+                    # Show dialog with copy button for Windows users
+                    await self.app.push_screen_wait(KuzuErrorDialog())
+                    return
+
+                except Exception as exc:  # pragma: no cover - defensive UI path
+                    # Check if this is a kuzu corruption error and we have retries left
+                    if attempt < max_retries - 1 and self._is_kuzu_corruption_error(
+                        exc
+                    ):
+                        logger.warning(
+                            f"Kuzu corruption detected on attempt {attempt + 1}/{max_retries}: {exc}. "
+                            f"Will retry after cleanup..."
+                        )
+                        # Exponential backoff: 1s, 2s
+                        await asyncio.sleep(2**attempt)
+                        continue
+
+                    # Either final retry failed OR not a corruption error - show error
+                    logger.exception(
+                        f"Failed to index codebase after {attempt + 1} attempts - "
+                        f"repo_path: {selection.repo_path}, name: {selection.name}, error: {exc}"
                     )
-                )
-                break
 
-        # Always stop the progress timer and clean up label
-        progress_timer.stop()
-        label.update("")
-        label.refresh()
+                    # Provide helpful error message with correct path for kuzu errors
+                    if self._is_kuzu_corruption_error(exc):
+                        storage_dir = self.codebase_sdk.service.storage_dir
+                        self.agent_manager.add_hint_message(
+                            HintMessage(
+                                message=(
+                                    f"❌ Database error during indexing. "
+                                    f"Try deleting files in: {storage_dir}"
+                                )
+                            )
+                        )
+                    else:
+                        self.agent_manager.add_hint_message(
+                            HintMessage(message=f"❌ Failed to index codebase: {exc}")
+                        )
+                    break
+        finally:
+            # Always stop the progress timer, clean up label, and mark indexing complete
+            if progress_timer:
+                progress_timer.stop()
+            label.update("")
+            label.refresh()
+            await self.codebase_sdk.service.indexing.complete(graph_id)
 
     @work
-    async def run_agent(self, message: str) -> None:
+    async def run_agent(
+        self,
+        message: str,
+        attachment: FileAttachment | None = None,
+        file_contents: list[tuple[str, BinaryContent]] | None = None,
+    ) -> None:
         # Start processing with spinner
         from textual.worker import get_current_worker
 
         self.processing_state.start_processing("Processing...")
         self.processing_state.bind_worker(get_current_worker())
 
+        # Pass cancellation event to deps for responsive ESC handling
+        self.deps.cancellation_event = self.processing_state.cancellation_event
+
         # Start context indicator animation immediately
         self.widget_coordinator.set_context_streaming(True)
 
         try:
             # Use unified agent runner - exceptions propagate for handling
             runner = AgentRunner(self.agent_manager)
-            await runner.run(message)
+            await runner.run(
+                message, attachment=attachment, file_contents=file_contents
+            )
         except ShotgunAccountException as e:
             # Shotgun Account errors show contact email UI
             message_parts = e.to_markdown().split("**Need help?**")
@@ -1432,6 +1991,12 @@ class ChatScreen(Screen[None]):
             else:
                 # Fallback if message format is unexpected
                 self.mount_hint(e.to_markdown())
+        except AgentCancelledException as e:
+            # Reset execution state on cancellation so user can switch modes
+            if isinstance(self.deps, RouterDeps):
+                self.deps.is_executing = False
+                self.deps.active_sub_agent = None
+            self.mount_hint(e.to_markdown())
         except ErrorNotPickedUpBySentry as e:
             # All other user-actionable errors - display with markdown
             self.mount_hint(e.to_markdown())
@@ -1449,6 +2014,18 @@ class ChatScreen(Screen[None]):
             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()
+
+        # Check for plan completion (Drafting mode)
+        self._check_plan_completion()
+
+        # Check if agent stopped with incomplete plan (failsafe)
+        self._check_incomplete_plan()
+
         # Save conversation after each interaction
         self._save_conversation()
 
@@ -1515,17 +2092,603 @@ class ChatScreen(Screen[None]):
 
         self.run_worker(_do_load(), exclusive=False)
 
-    @work
-    async def _check_and_show_onboarding(self) -> None:
-        """Check if onboarding should be shown and display modal if needed."""
-        config_manager = get_config_manager()
-        config = await config_manager.load()
-
-        # Only show onboarding if it hasn't been shown before
-        if config.shown_onboarding_popup is None:
-            # Show the onboarding modal
-            await self.app.push_screen_wait(OnboardingModal())
-
-            # 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)
+
+    def _track_checkpoint_event(self, event_name: str) -> None:
+        """Track a checkpoint-related PostHog event.
+
+        Args:
+            event_name: The name of the event to track.
+        """
+        if isinstance(self.deps, RouterDeps) and self.deps.current_plan:
+            plan = self.deps.current_plan
+            completed_count = sum(1 for s in plan.steps if s.done)
+            track_event(
+                event_name,
+                {
+                    "completed_step_position": completed_count,
+                    "steps_remaining": len(plan.steps) - completed_count,
+                },
+            )
+
+    @on(CheckpointContinue)
+    def handle_checkpoint_continue(self) -> None:
+        """Continue to next step when user approves at checkpoint."""
+        self._track_checkpoint_event("checkpoint_continued")
+        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._track_checkpoint_event("checkpoint_stopped")
+        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
+            )
+        )
+
+    def _check_plan_completion(self) -> None:
+        """Check if a plan was completed in Drafting mode and show completion message.
+
+        This is called after each agent run to check if mark_step_done
+        set pending_completion in Drafting mode.
+        """
+        logger.debug("[PLAN] _check_plan_completion called")
+        if not isinstance(self.deps, RouterDeps):
+            logger.debug("[PLAN] Not RouterDeps, skipping plan completion check")
+            return
+
+        if not self.deps.pending_completion:
+            logger.debug("[PLAN] No pending completion")
+            return
+
+        # Don't show completion message if Q&A mode is active.
+        # The user needs to answer the clarifying questions first.
+        # Keep pending_completion=True so it shows after Q&A is done.
+        if self.qa_mode:
+            logger.debug("[PLAN] Q&A mode active, deferring plan completion message")
+            return
+
+        # Clear the pending state
+        self.deps.pending_completion = False
+
+        # Show completion message
+        logger.debug("[PLAN] Showing plan completion message for drafting mode")
+        self.mount_hint("✅ All plan steps completed!")
+
+        # Hide the plan panel since the plan is done
+        self._hide_plan_panel()
+
+    def _check_incomplete_plan(self) -> None:
+        """Check if agent returned with an incomplete plan in Drafting mode.
+
+        This is a failsafe to notify the user if the agent stopped
+        mid-plan without completing all steps.
+        """
+        logger.debug("[PLAN] _check_incomplete_plan called")
+
+        if not isinstance(self.deps, RouterDeps):
+            logger.debug("[PLAN] Not RouterDeps, skipping incomplete plan check")
+            return
+
+        logger.debug(
+            "[PLAN] router_mode=%s, current_plan=%s",
+            self.deps.router_mode,
+            self.deps.current_plan.goal if self.deps.current_plan else None,
+        )
+
+        if self.deps.router_mode != RouterMode.DRAFTING:
+            logger.debug("[PLAN] Not in DRAFTING mode, skipping incomplete plan check")
+            return
+
+        plan = self.deps.current_plan
+        if plan is None:
+            logger.debug("[PLAN] No current plan")
+            return
+
+        if plan.is_complete():
+            logger.debug("[PLAN] Plan is complete, no incomplete plan hint needed")
+            return
+
+        # Don't show the "continue to resume" hint if Q&A mode is active.
+        # The user needs to answer the clarifying questions first.
+        if self.qa_mode:
+            logger.debug(
+                "[PLAN] Q&A mode active, deferring incomplete plan hint until "
+                "questions are answered"
+            )
+            return
+
+        # Plan exists and is incomplete - show status hint
+        completed = sum(1 for s in plan.steps if s.done)
+        total = len(plan.steps)
+        remaining = [s.title for s in plan.steps if not s.done]
+
+        logger.info(
+            "[PLAN] Agent stopped with incomplete plan: %d/%d steps done, "
+            "remaining: %s",
+            completed,
+            total,
+            remaining,
+        )
+
+        hint = (
+            f"📋 **Plan Status: {completed}/{total} steps complete**\n\n"
+            f"Remaining: {', '.join(remaining)}\n\n"
+            f"_Type 'continue' to resume the plan._"
+        )
+        self.mount_hint(hint)
+
+    # =========================================================================
+    # 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):
+            # Track plan approved metric
+            if self.deps.current_plan:
+                track_event(
+                    "plan_approved",
+                    {
+                        "step_count": len(self.deps.current_plan.steps),
+                    },
+                )
+
+            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.widget_coordinator.update_for_mode_change(self.mode)
+
+            # Show plan panel now that plan is approved and executing
+            plan = self.deps.current_plan
+            if plan:
+                self._show_plan_panel(plan)
+
+            # Begin execution of the first step
+            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):
+            # Track plan rejected metric
+            if self.deps.current_plan:
+                track_event(
+                    "plan_rejected",
+                    {
+                        "step_count": len(self.deps.current_plan.steps),
+                    },
+                )
+
+            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.
+        """
+        # Hide plan panel to avoid showing duplicate plan info
+        # (ApprovalWidget already shows the full plan details)
+        self._hide_plan_panel()
+
+        # 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
+
+        # Don't show plan approval while user is answering questions.
+        # The pending approval will remain set and be checked again
+        # after Q&A completes (when run_agent is called with answers).
+        if self.qa_mode:
+            logger.debug("[PLAN] Q&A mode active, deferring plan approval")
+            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))