zjcode 0.0.1__py3-none-any.whl

deepagents_code/tui/widgets/chat_input.py

@@ -0,0 +1,3181 @@
+"""Chat input widget for deepagents-code with autocomplete and history support."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, assert_never
+
+from rich.cells import cell_len
+from rich.segment import Segment
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.content import Content
+from textual.css.query import NoMatches
+from textual.geometry import Offset, Size
+from textual.message import Message
+from textual.reactive import reactive
+from textual.strip import Strip
+from textual.widgets import Static, TextArea
+
+from deepagents_code import theme
+from deepagents_code.command_registry import SLASH_COMMANDS, CommandEntry
+from deepagents_code.config import (
+    MODE_DISPLAY_GLYPHS,
+    MODE_PREFIXES,
+    detect_mode_prefix,
+    is_ascii_mode,
+)
+from deepagents_code.input import IMAGE_PLACEHOLDER_PATTERN, VIDEO_PLACEHOLDER_PATTERN
+from deepagents_code.media_utils import get_clipboard_image
+from deepagents_code.paste_collapse import (
+    PASTE_PLACEHOLDER_PATTERN,
+    PastedContent,
+    count_lines,
+    expand_paste_refs,
+    format_paste_ref,
+    should_collapse_paste,
+)
+from deepagents_code.tui.widgets.autocomplete import (
+    CompletionResult,
+    FuzzyFileController,
+    MultiCompletionManager,
+    SlashCommandController,
+)
+from deepagents_code.tui.widgets.history import HistoryManager
+
+logger = logging.getLogger(__name__)
+
+
+def _default_history_path() -> Path:
+    """Return the default history file path.
+
+    Extracted as a function so tests can monkeypatch it to a temp path,
+    preventing test runs from polluting `~/.deepagents/.state/history.jsonl`.
+    """
+    from deepagents_code.model_config import DEFAULT_STATE_DIR
+
+    return DEFAULT_STATE_DIR / "history.jsonl"
+
+
+_LOCK_KEYS = frozenset({"caps_lock", "num_lock", "scroll_lock"})
+"""Lock keys that must never insert text.
+
+Under the kitty keyboard protocol with associated-text reporting (VS Code's
+xterm.js and others), pressing a lock key arrives as a `Key` event whose
+`character` is the text that *would* have been produced by the next key —
+e.g. pressing Caps Lock reports `key='caps_lock'`, `character='A'`. Textual's
+parser does not strip this, so `TextArea` inserts a stray letter. We drop
+these events entirely. Terminals encode lock keys in several shapes (iTerm2
+notably differs from kitty/Ghostty); `_textual_patches.py` is the canonical
+reference and neutralizes every shape at the parser. See the kitty keyboard
+protocol spec (functional key definitions) for background.
+"""
+
+_PASTE_BURST_CHAR_GAP_SECONDS = 0.03
+"""Maximum time between chars to treat input as a paste-like burst."""
+
+_PASTE_BURST_FLUSH_DELAY_SECONDS = 0.08
+"""Idle timeout before flushing buffered burst text."""
+
+_PASTE_BURST_START_CHARS = {"'", '"'}
+"""Characters that can start dropped-path payloads."""
+
+_PASTE_BURST_MIN_CHARS = 3
+"""Consecutive fast keystrokes before a stream is treated as a paste burst.
+
+Terminals that lack bracketed paste replay a paste as individual key events.
+Counting a short run of rapid chars distinguishes that from human typing,
+which has much larger inter-key gaps.
+"""
+
+_PASTE_ENTER_SUPPRESS_WINDOW_SECONDS = 0.12
+"""Window after recent burst activity during which `enter` inserts a newline.
+
+Keeps multi-line pastes grouped as one input even when newlines arrive as
+`enter` key events slightly after the surrounding characters (e.g. across
+terminal read boundaries), instead of submitting mid-paste.
+"""
+
+_FILE_CACHE_WORKER_GROUP = "file-cache"
+"""Textual worker group for all `@` file-completion cache warmers."""
+
+_BACKSLASH_ENTER_GAP_SECONDS = 0.15
+"""Maximum gap between a `\\` key and a following `enter` key to treat the
+pair as a terminal-emitted shift+enter sequence.
+
+Some terminals (e.g. VSCode's built-in terminal) send a literal backslash
+followed by enter when the user presses shift+enter.  The gap is
+generous (150 ms) because the terminal emits both characters nearly
+simultaneously; a human deliberately typing `\\` then pressing Enter would
+have a much larger gap."""
+
+_REFOCUS_CLICK_SUPPRESS_WINDOW_SECONDS = 0.3
+"""Window after a terminal focus regain during which a click only refocuses.
+
+When the terminal window is unfocused and the user clicks back in, we rely on
+the OS delivering a `FocusIn` (Textual `AppFocus`) before the mouse report —
+the same FocusIn support `on_app_focus` documents. Terminals without it never
+arm suppression, so clicks just behave normally (the cursor moves). A
+mouse-down landing within this window after the focus regain is treated as
+focus-only so the cursor stays put instead of jumping to the click location.
+
+The window trades off two failure modes: too small and a genuine refocus click
+leaks through and moves the cursor (the bug this guards against); too large and
+an intentional click made shortly after refocusing is wrongly suppressed. 0.3s
+comfortably covers the FocusIn-to-mouse-report latency while staying below a
+deliberate click-pause-click interaction.
+"""
+
+_FILE_CACHE_REFRESH_INTERVAL_SECONDS = 30.0
+"""How often to refresh the `@` file-completion cache in the background.
+
+The cache is pre-warmed on mount and re-warmed on cwd switches, but files
+created or deleted mid-session would otherwise stay stale until the next switch.
+A periodic refresh keeps `@` suggestions current; the walk runs off the event
+loop and swaps in atomically, so it never blocks typing."""
+
+if TYPE_CHECKING:
+    from textual import events
+    from textual.app import ComposeResult
+    from textual.events import Click
+    from textual.timer import Timer
+
+    from deepagents_code.config_manifest import CursorStyle
+    from deepagents_code.input import MediaTracker, ParsedPastedPathPayload
+
+
+def _should_collapse_chat_paste(text: str) -> bool:
+    """Return whether pasted chat text should be collapsed."""
+    return detect_mode_prefix(text) is None and should_collapse_paste(text)
+
+
+def _load_collapse_pastes() -> bool:
+    """Resolve whether large chat-input pastes are collapsed into placeholders.
+
+    Reads `DEEPAGENTS_CODE_COLLAPSE_PASTES`, then `[ui].collapse_pastes` in
+    `~/.deepagents/config.toml`, defaulting to enabled.
+
+    Returns:
+        The resolved preference (defaults to `True`).
+    """
+    from deepagents_code.config_manifest import (
+        get_option,
+        load_config_toml,
+        resolve_scalar,
+    )
+
+    option = get_option("display.collapse_pastes")
+    if option is None:
+        # Unreachable unless the manifest key is renamed without updating this
+        # literal; log so that mismatch surfaces instead of silently defaulting.
+        logger.warning(
+            "Unknown config option %r; defaulting to enabled", "display.collapse_pastes"
+        )
+        return True
+    value, _ = resolve_scalar(option, toml_data=load_config_toml())
+    return bool(value)
+
+
+class CompletionOption(Static):
+    """A clickable completion option in the autocomplete popup."""
+
+    DEFAULT_CSS = """
+    CompletionOption {
+        height: 1;
+        padding: 0 1;
+    }
+
+    CompletionOption:hover {
+        background: $surface-lighten-1;
+    }
+
+    CompletionOption.completion-option-selected {
+        background: $primary;
+        color: $background;
+        text-style: bold;
+    }
+
+    CompletionOption.completion-option-selected:hover {
+        background: $primary-lighten-1;
+    }
+    """
+
+    class Clicked(Message):
+        """Message sent when a completion option is clicked."""
+
+        def __init__(self, index: int) -> None:
+            """Initialize with the clicked option index."""
+            super().__init__()
+            self.index = index
+
+    def __init__(
+        self,
+        label: str,
+        description: str,
+        index: int,
+        is_selected: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the completion option.
+
+        Args:
+            label: The main label text (e.g., command name or file path)
+            description: Secondary description text
+            index: Index of this option in the suggestions list
+            is_selected: Whether this option is currently selected
+            **kwargs: Additional arguments for parent
+        """
+        super().__init__(**kwargs)
+        self._label = label
+        self._description = description
+        self._index = index
+        self._is_selected = is_selected
+
+    def on_mount(self) -> None:
+        """Set up the option display on mount."""
+        self._update_display()
+
+    def _update_display(self) -> None:
+        """Update the display text and styling."""
+        display_label = self._label.removeprefix("/")
+        if self._description:
+            content = Content.from_markup(
+                "[bold]$label[/bold]  [dim]$desc[/dim]",
+                label=display_label,
+                desc=self._description,
+            )
+        else:
+            content = Content.from_markup("[bold]$label[/bold]", label=display_label)
+
+        self.update(content)
+
+        if self._is_selected:
+            self.add_class("completion-option-selected")
+        else:
+            self.remove_class("completion-option-selected")
+
+    def set_selected(self, *, selected: bool) -> None:
+        """Update the selected state of this option."""
+        if self._is_selected != selected:
+            self._is_selected = selected
+            self._update_display()
+
+    def set_content(
+        self, label: str, description: str, index: int, *, is_selected: bool
+    ) -> None:
+        """Replace label, description, index, and selection in-place."""
+        self._label = label
+        self._description = description
+        self._index = index
+        self._is_selected = is_selected
+        self._update_display()
+
+    def on_click(self, event: Click) -> None:
+        """Handle click on this option."""
+        event.stop()
+        self.post_message(self.Clicked(self._index))
+
+
+InputAction = Literal["clear", "copy"]
+"""Closed set of actions an `InputActionButton` can dispatch."""
+
+
+class InputActionButton(Static):
+    """Small clickable button shown at the right edge of the chat input row.
+
+    Provides discoverable mouse alternatives to keyboard shortcuts for
+    clearing (`[ X ]`) and copying (`[ COPY ]`) the current draft.
+    """
+
+    DEFAULT_CSS = """
+    InputActionButton {
+        height: 1;
+        margin: 0 0 0 1;
+        text-style: bold;
+    }
+
+    InputActionButton.input-action-clear {
+        width: 5;
+        color: $error;
+    }
+
+    InputActionButton.input-action-copy {
+        width: 8;
+        color: $primary;
+    }
+
+    InputActionButton.input-action-clear:hover {
+        background: $error;
+        color: auto;
+    }
+
+    InputActionButton.input-action-copy:hover {
+        background: $primary;
+        color: auto;
+    }
+    """
+
+    class Clicked(Message):
+        """Message sent when an input action button is clicked."""
+
+        def __init__(self, action: InputAction) -> None:
+            """Initialize with the action identifier (`clear` or `copy`)."""
+            super().__init__()
+            self.action = action
+
+    @property
+    def allow_select(self) -> bool:
+        """Disable terminal text selection for the action label."""
+        return False
+
+    def __init__(self, label: str, action: InputAction, **kwargs: Any) -> None:
+        """Initialize the button with a label and an action identifier."""
+        super().__init__(label, markup=False, **kwargs)
+        self._action = action
+
+    def on_click(self, event: Click) -> None:
+        """Relay the click as a typed `Clicked` message."""
+        event.stop()
+        self.post_message(self.Clicked(self._action))
+
+
+class CompletionPopup(VerticalScroll):
+    """Popup widget that displays completion suggestions as clickable options."""
+
+    DEFAULT_CSS = """
+    CompletionPopup {
+        display: none;
+        height: auto;
+        max-height: 12;
+    }
+    """
+
+    class OptionClicked(Message):
+        """Message sent when a completion option is clicked."""
+
+        def __init__(self, index: int) -> None:
+            """Initialize with the clicked option index."""
+            super().__init__()
+            self.index = index
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the completion popup."""
+        super().__init__(**kwargs)
+        self.can_focus = False
+        self._options: list[CompletionOption] = []
+        self._selected_index = 0
+        self._pending_suggestions: list[tuple[str, str]] = []
+        self._pending_selected: int = 0
+        self._rebuild_generation: int = 0
+
+    def update_suggestions(
+        self, suggestions: list[tuple[str, str]], selected_index: int
+    ) -> None:
+        """Update the popup with new suggestions."""
+        if not suggestions:
+            self.hide()
+            return
+
+        self._selected_index = selected_index
+        self._pending_suggestions = suggestions
+        self._pending_selected = selected_index
+        # Increment generation so stale callbacks from prior calls are skipped.
+        self._rebuild_generation += 1
+        gen = self._rebuild_generation
+        # show() is still deferred to _rebuild_options to avoid stale content,
+        # but the rebuild runs before the next paint so prompt and popup changes
+        # appear in the same frame.
+        self.call_next(lambda: self._rebuild_options(gen))
+
+    async def _rebuild_options(self, generation: int) -> None:
+        """Rebuild option widgets from pending suggestions.
+
+        Reuses existing DOM nodes where possible to avoid flicker from
+        a full teardown/mount cycle while the popup is visible.
+
+        Args:
+            generation: Caller's generation counter; skipped if superseded.
+        """
+        if generation != self._rebuild_generation:
+            return
+
+        suggestions = self._pending_suggestions
+        selected_index = self._pending_selected
+
+        if not suggestions:
+            self.hide()
+            return
+
+        existing = len(self._options)
+        needed = len(suggestions)
+
+        # Update existing widgets in-place
+        for i in range(min(existing, needed)):
+            label, desc = suggestions[i]
+            self._options[i].set_content(
+                label, desc, i, is_selected=(i == selected_index)
+            )
+
+        # DOM mutations: trim extras / mount new widgets
+        try:
+            if existing > needed:
+                for option in self._options[needed:]:
+                    await option.remove()
+                del self._options[needed:]
+
+            if needed > existing:
+                new_widgets: list[CompletionOption] = []
+                for idx in range(existing, needed):
+                    label, desc = suggestions[idx]
+                    option = CompletionOption(
+                        label=label,
+                        description=desc,
+                        index=idx,
+                        is_selected=(idx == selected_index),
+                    )
+                    new_widgets.append(option)
+                self._options.extend(new_widgets)
+                await self.mount(*new_widgets)
+        except Exception:
+            logger.exception("Failed to rebuild completion popup; hiding to recover")
+            self._options = []
+            with contextlib.suppress(Exception):
+                await self.remove_children()
+            self.hide()
+            return
+
+        # The DOM mutations above can await, during which a hide() (or a newer
+        # rebuild) bumps the generation to cancel this one. The top-of-function
+        # guard ran before that await, so re-check here: without it a stale
+        # rebuild would re-show a popup that was dismissed mid-flight (e.g. when
+        # a completion is applied and the popup hidden in the same key press).
+        if generation != self._rebuild_generation:
+            return
+
+        self.show()
+
+        if 0 <= selected_index < len(self._options):
+            self._options[selected_index].scroll_visible()
+
+    def update_selection(self, selected_index: int) -> None:
+        """Update which option is selected without rebuilding the list."""
+        # Keep pending state in sync so an in-flight _rebuild_options uses
+        # the latest selection.
+        self._pending_selected = selected_index
+
+        if self._selected_index == selected_index:
+            return
+
+        # Deselect previous
+        if 0 <= self._selected_index < len(self._options):
+            self._options[self._selected_index].set_selected(selected=False)
+
+        # Select new
+        self._selected_index = selected_index
+        if 0 <= selected_index < len(self._options):
+            self._options[selected_index].set_selected(selected=True)
+            self._options[selected_index].scroll_visible()
+
+    def on_completion_option_clicked(self, event: CompletionOption.Clicked) -> None:
+        """Handle click on a completion option."""
+        event.stop()
+        self.post_message(self.OptionClicked(event.index))
+
+    def hide(self) -> None:
+        """Hide the popup."""
+        self._pending_suggestions = []
+        self._rebuild_generation += 1  # Cancel any in-flight rebuild
+        self.styles.display = "none"  # ty: ignore[invalid-assignment]  # Textual accepts string display values at runtime
+
+    def show(self) -> None:
+        """Show the popup."""
+        self.styles.display = "block"
+
+
+class ChatTextArea(TextArea):
+    """TextArea subclass with custom key handling for chat input."""
+
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding(
+            "shift+enter,alt+enter,ctrl+enter,ctrl+j",
+            "insert_newline",
+            "New Line",
+            show=False,
+            priority=True,
+        ),
+        Binding(
+            "ctrl+backspace,alt+backspace",
+            "delete_word_left",
+            "Delete left to start of word",
+            show=False,
+        ),
+    ]
+    """Key bindings for the chat text area.
+
+    These are the single source of truth for shortcut keys. `_NEWLINE_KEYS`
+    is derived from this list so that `_on_key` stays in sync automatically.
+    """
+
+    _NEWLINE_KEYS: ClassVar[frozenset[str]] = frozenset(
+        key
+        for b in BINDINGS
+        if b.action == "insert_newline"
+        for key in b.key.split(",")
+    )
+    """Flattened set of keys that insert a newline, derived from `BINDINGS`."""
+
+    _skip_history_change_events: int
+    """Counter incremented before a history-driven text replacement so the
+    resulting `TextArea.Changed` event (which fires on the next message-loop
+    iteration) can be suppressed.  `ChatInput.on_text_area_changed` decrements
+    the counter.
+    """
+
+    class Submitted(Message):
+        """Message sent when text is submitted."""
+
+        def __init__(self, value: str) -> None:
+            """Initialize with submitted value."""
+            self.value = value
+            super().__init__()
+
+    class HistoryPrevious(Message):
+        """Request previous history entry."""
+
+        def __init__(self, current_text: str) -> None:
+            """Initialize with current text for saving."""
+            self.current_text = current_text
+            super().__init__()
+
+    class HistoryNext(Message):
+        """Request next history entry."""
+
+    class PastedPaths(Message):
+        """Message sent when paste payload resolves to file paths."""
+
+        def __init__(self, raw_text: str, paths: list[Path]) -> None:
+            """Initialize with raw pasted text and parsed file paths."""
+            self.raw_text = raw_text
+            self.paths = paths
+            super().__init__()
+
+    class PastedText(Message):
+        """Message sent when a paste is large enough to be collapsed.
+
+        The full text is carried in the message so `ChatInput` can store it
+        and insert a compact placeholder into the text area instead.
+        """
+
+        def __init__(self, text: str) -> None:
+            """Initialize with the full pasted text.
+
+            Args:
+                text: The complete pasted text content.
+            """
+            self.text = text
+            super().__init__()
+
+    class Typing(Message):
+        """Posted when the user presses a printable key or backspace.
+
+        Relayed by `ChatInput` as `ChatInput.Typing` for the app to track
+        typing activity.
+        """
+
+    argument_hint: reactive[str] = reactive("")
+    """Inline slash-command argument hint rendered at the end of the line."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the chat text area."""
+        # Remove placeholder if passed, TextArea doesn't support it the same way
+        kwargs.pop("placeholder", None)
+        super().__init__(**kwargs)
+        self._chat_input_owner: ChatInput | None = None
+        self._skip_history_change_events = 0
+        self._completion_active = False
+        # Buffer high-frequency key bursts from terminals that emulate paste via
+        # rapid key events instead of dispatching a paste event.
+        self._paste_burst_buffer = ""
+        self._paste_burst_last_char_time: float | None = None
+        self._paste_burst_timer: Timer | None = None
+        # Counts consecutive rapid keystrokes so a paste-like stream can be
+        # detected even when it doesn't begin with a quote.
+        self._paste_burst_run = 0
+        self._paste_burst_last_key_time: float | None = None
+        self._paste_burst_last_suppressed_enter_time: float | None = None
+        # Deadline until which `enter` inserts a newline rather than submitting,
+        # keeping multi-line pastes grouped across read boundaries.
+        self._paste_burst_window_until: float | None = None
+        # See _BACKSLASH_ENTER_GAP_SECONDS for context.
+        self._backslash_pending_time: float | None = None
+        # Tracks terminal focus so a click that re-focuses the window only
+        # restores focus instead of also moving the cursor. See
+        # `_REFOCUS_CLICK_SUPPRESS_WINDOW_SECONDS`.
+        self._app_blurred = False
+        self._refocus_time: float | None = None
+
+    def render_line(self, y: int) -> Strip:
+        """Render a single line, appending any argument hint at line end.
+
+        The built-in `TextArea.suggestion` renders at the cursor position,
+        but slash-command argument hints should stay attached to the end of the
+        command text regardless of cursor movement.
+
+        Args:
+            y: Y Coordinate of line relative to the widget region.
+
+        Returns:
+            A rendered line.
+        """
+        strip = super().render_line(y)
+        if not self._should_render_argument_hint():
+            return strip
+
+        line_info = self._get_visual_line_info(y)
+        if line_info is None:
+            return strip
+
+        line_index, section_offset = line_info
+        if not self._is_argument_hint_section(line_index, section_offset):
+            return strip
+
+        content_cells = self._get_section_cell_length(line_index, section_offset)
+        if content_cells >= strip.cell_length:
+            return strip
+
+        prefix = strip.crop(0, content_cells)
+        suffix = strip.crop(content_cells, strip.cell_length)
+        suffix_width = suffix.cell_length
+        cursor_on_hint = self._cursor_at_argument_hint_anchor(line_index)
+        if cursor_on_hint and suffix_width > 0:
+            suffix = suffix.crop(1, suffix.cell_length)
+
+        hint_strip = self._build_argument_hint_strip(cursor_on_hint=cursor_on_hint)
+        tail = Strip.join([hint_strip, suffix]).crop(0, suffix_width)
+        return Strip.join([prefix, tail])
+
+    def _should_render_argument_hint(self) -> bool:
+        """Return whether the inline argument hint should be rendered."""
+        return bool(
+            self.argument_hint and (self.has_focus or not self.hide_suggestion_on_blur)
+        )
+
+    def _get_visual_line_info(self, y: int) -> tuple[int, int] | None:
+        """Map a widget-relative y coordinate to wrapped line metadata.
+
+        Returns:
+            Tuple of `(line_index, section_offset)` for the wrapped line at `y`,
+            otherwise `None` when `y` is outside the wrapped document.
+        """
+        _scroll_x, scroll_y = self.scroll_offset
+        absolute_y = scroll_y + y
+        # Private Textual API (verified against textual 3.x); revisit on
+        # major Textual upgrades.
+        try:
+            offset_map = self.wrapped_document._offset_to_line_info
+        except AttributeError:
+            logger.warning(
+                "WrappedDocument._offset_to_line_info not found; "
+                "argument hint rendering disabled (Textual API change?)"
+            )
+            return None
+        if absolute_y < 0 or absolute_y >= len(offset_map):
+            return None
+        entry = offset_map[absolute_y]
+        expected_length = 2  # (line_index, section_offset)
+        if not isinstance(entry, tuple) or len(entry) != expected_length:
+            logger.warning("Unexpected offset_map entry: %r", entry)
+            return None
+        return entry
+
+    def _is_argument_hint_section(self, line_index: int, section_offset: int) -> bool:
+        """Return whether a wrapped section owns the end-of-line hint."""
+        if line_index != self.document.line_count - 1:
+            return False
+        return section_offset == len(self.wrapped_document.get_offsets(line_index))
+
+    def _get_section_cell_length(self, line_index: int, section_offset: int) -> int:
+        """Return the rendered cell width of a wrapped text section."""
+        wrapped_sections = self.wrapped_document.get_sections(line_index)
+        if section_offset < 0 or section_offset >= len(wrapped_sections):
+            return 0
+        section_text = wrapped_sections[section_offset].expandtabs(self.indent_width)
+        return cell_len(section_text)
+
+    def _cursor_at_argument_hint_anchor(self, line_index: int) -> bool:
+        """Return whether the cursor currently sits on the hint anchor."""
+        if not self._draw_cursor or not self.show_cursor or not self.has_focus:
+            return False
+        cursor_row, cursor_column = self.selection.end
+        if cursor_row != line_index:
+            return False
+        return cursor_column == len(self.document.get_line(line_index))
+
+    def _build_argument_hint_strip(self, *, cursor_on_hint: bool) -> Strip:
+        """Build a strip for the current argument hint text.
+
+        Returns:
+            A `Strip` containing the current argument hint, with cursor styling
+            applied to the first hint character when the cursor sits on the
+            hint anchor.
+        """
+        hint = self.argument_hint
+        hint_style = self.get_component_rich_style("text-area--suggestion")
+        if not cursor_on_hint or not hint:
+            return Strip([Segment(hint, hint_style)], cell_length=cell_len(hint))
+
+        ta_theme = self._theme
+        cursor_style = ta_theme.cursor_style if ta_theme else None
+        first_style = hint_style if cursor_style is None else hint_style + cursor_style
+        segments = [Segment(hint[0], first_style)]
+        if len(hint) > 1:
+            segments.append(Segment(hint[1:], hint_style))
+        return Strip(segments, cell_length=cell_len(hint))
+
+    def scroll_cursor_visible(
+        self, center: bool = False, animate: bool = False
+    ) -> Offset:
+        """Scroll to make the cursor visible, guarding against cursor/document desync.
+
+        Textual's `WrappedDocument.location_to_offset` has an off-by-one in its
+        line-index clamp (`len(...)` instead of `len(...) - 1`). When a reactive
+        watcher (e.g. `_watch_show_vertical_scrollbar`) fires between a document
+        replacement and cursor update, the stale cursor location triggers a
+        `ValueError`. Guard here since `scroll_cursor_visible` is the sole
+        caller of `_recompute_cursor_offset`.
+
+        Args:
+            center: Whether the cursor should be scrolled to the center.
+            animate: Whether to animate while scrolling.
+
+        Returns:
+            The scroll offset applied, or `Offset(0, 0)` on desync.
+        """
+        try:
+            return super().scroll_cursor_visible(center=center, animate=animate)
+        except (
+            ValueError
+        ):  # WrappedDocument.get_offsets off-by-one clamp in location_to_offset
+            logger.warning(
+                "Cursor/document desync in scroll_cursor_visible "
+                "(cursor=%s, doc_lines=%d); skipping scroll",
+                self.cursor_location,
+                self.document.line_count,
+            )
+            return Offset(0, 0)
+
+    def set_app_focus(self, *, has_focus: bool) -> None:
+        """Set whether the app should show the cursor as active.
+
+        Args:
+            has_focus: Whether the app input should be focused.
+        """
+        self._backslash_pending_time = None
+        if has_focus and not self.has_focus:
+            self.call_after_refresh(self.focus)
+
+    def _notify_app_blur(self) -> None:
+        """Record that the terminal window lost OS focus."""
+        self._app_blurred = True
+
+    def _notify_app_focus(self) -> None:
+        """Record that the terminal window regained OS focus via a focus event.
+
+        Stamps the regain time so the click that re-focused the window (which
+        arrives just after the focus event) can be treated as focus-only.
+        """
+        if self._app_blurred:
+            self._refocus_time = time.monotonic()
+            self._app_blurred = False
+
+    def _consume_refocus_click(self) -> bool:
+        """Return whether the current mouse-down only re-focuses the window.
+
+        `_refocus_time` is only cleared here, so a focus regain that is never
+        followed by a text-area click leaves the stamp set. The gap check
+        bounds that staleness: an old stamp exceeds the window and returns
+        `False` (clearing it), so a much later click is never suppressed.
+        """
+        refocus_time = self._refocus_time
+        if refocus_time is None:
+            return False
+        self._refocus_time = None
+        gap = time.monotonic() - refocus_time
+        return gap <= _REFOCUS_CLICK_SUPPRESS_WINDOW_SECONDS
+
+    async def _on_mouse_down(self, event: events.MouseDown) -> None:
+        """Position the cursor on click, except when the click re-focuses the app.
+
+        A mouse-down landing within a short window after a terminal focus
+        regain only restores focus and leaves the cursor where it was.
+
+        Deliberately shadows Textual's private `TextArea._on_mouse_down` to gate
+        cursor positioning; verified against Textual 8.2.7. If the base handler
+        changes, re-verify that early-returning before `super()` still leaves no
+        selection/capture state set.
+        """
+        if self._consume_refocus_click():
+            event.stop()
+            event.prevent_default()
+            return
+        await super()._on_mouse_down(event)
+
+    def set_completion_active(self, *, active: bool) -> None:
+        """Set whether completion suggestions are visible."""
+        self._completion_active = active
+
+    def action_insert_newline(self) -> None:
+        """Insert a newline character."""
+        self.insert("\n")
+        # TextArea's built-in cursor-visible scroll runs before the widget
+        # reflows for the new row, so it sees stale dimensions and is a no-op
+        # when the cursor would land below `max-height`. Re-issue after
+        # refresh so it stays in view.
+        self.call_after_refresh(self.scroll_cursor_visible)
+
+    def _refresh_scrollbars(self) -> None:
+        """Refresh scrollbars without flashing a transient vertical bar.
+
+        `TextArea` grows its `virtual_size` height the moment a row is inserted,
+        a frame before this `height: auto` widget's container reflows to match.
+        The base `_refresh_scrollbars` decides vertical visibility by comparing
+        `virtual_size.height` against the stale `self._container_size.height`,
+        so for that one frame the freshly inserted row looks like overflow and
+        the scrollbar flashes on, then off once the container catches up.
+
+        The widget only ever truly overflows once its content exceeds the height
+        it settles at — its resolved `max-height` (the layout chain above it is
+        all `height: auto`, so it always grows to `min(content, max-height)`).
+        Feed the base method that settled height instead of the mid-reflow one,
+        so the bar appears only on genuine overflow and never flashes. All other
+        base behavior (horizontal bar, anti-oscillation, scroll updates) is left
+        untouched.
+
+        Deliberately overrides Textual's private `_refresh_scrollbars` and
+        swaps the private `_container_size`; verified against Textual 8.2.7.
+        Re-verify on major Textual upgrades.
+        """
+        bound = self._settled_content_height()
+        if bound is None:
+            super()._refresh_scrollbars()
+            return
+
+        original = self._container_size
+        # Never report a viewport smaller than the settled height; `max(...)`
+        # also guards the unlikely case where the real container is already
+        # larger than the bound, so we only ever raise the comparison height.
+        corrected_height = max(original.height, min(self.virtual_size.height, bound))
+        if corrected_height == original.height:
+            super()._refresh_scrollbars()
+            return
+
+        self._container_size = Size(original.width, corrected_height)
+        try:
+            super()._refresh_scrollbars()
+        finally:
+            self._container_size = original
+
+    def _settled_content_height(self) -> int | None:
+        """Return the content-row height this widget settles at, if knowable.
+
+        Returns `None` (so the caller defers to the base behavior) unless the
+        vertical overflow is `auto` and `max-height` resolves to a fixed cell
+        count, the only case where the flash-suppression bound is well-defined.
+        """
+        styles = self.styles
+        if styles.overflow_y != "auto" or not styles.has_rule("max_height"):
+            return None
+        max_height = styles.max_height
+        cells = max_height.cells if max_height is not None else None
+        if cells is None:
+            return None
+        # box-sizing is border-box by default, so subtract border/padding to get
+        # the content-row count the base method compares `virtual_size` against.
+        return max(1, cells - self.gutter.height)
+
+    def _cursor_at_visual_top(self) -> bool:
+        """Return whether the cursor cannot move up further."""
+        try:
+            return self.get_cursor_up_location() == self.cursor_location
+        except ValueError:
+            # `WrappedDocument.location_to_offset` can raise during a brief
+            # text/cursor desync window (see `scroll_cursor_visible` guard).
+            # Treat as "not at top" so TextArea moves the cursor instead of
+            # firing history navigation on a transient state.
+            return False
+
+    def _cursor_at_visual_bottom(self) -> bool:
+        """Return whether the cursor cannot move down further."""
+        try:
+            return self.get_cursor_down_location() == self.cursor_location
+        except ValueError:
+            return False
+
+    def action_cursor_up(self, select: bool = False) -> None:
+        """Move cursor up, or navigate to the previous history entry at top.
+
+        When `select` is true or a selection is active, falls through to
+        TextArea's default so shift+up extends selection rather than
+        triggering navigation. History fires only when moving up cannot
+        advance the cursor — handled via the wrapped-document navigator so
+        soft-wrap is respected.
+        """
+        if not select and self.selection.is_empty and self._cursor_at_visual_top():
+            self.post_message(self.HistoryPrevious(self.text))
+            return
+        super().action_cursor_up(select)
+
+    def action_cursor_down(self, select: bool = False) -> None:
+        """Move cursor down, or navigate to the next history entry at bottom.
+
+        Mirrors `action_cursor_up`: defers to TextArea on selection or when
+        the cursor still has somewhere to move; otherwise fires history.
+        """
+        if not select and self.selection.is_empty and self._cursor_at_visual_bottom():
+            self.post_message(self.HistoryNext())
+            return
+        super().action_cursor_down(select)
+
+    def _cancel_paste_burst_timer(self) -> None:
+        """Cancel any scheduled paste-burst flush timer."""
+        if self._paste_burst_timer is None:
+            return
+        self._paste_burst_timer.stop()
+        self._paste_burst_timer = None
+
+    def _schedule_paste_burst_flush(self) -> None:
+        """Schedule idle-time flush for buffered paste-burst text."""
+        self._cancel_paste_burst_timer()
+        self._paste_burst_timer = self.set_timer(
+            _PASTE_BURST_FLUSH_DELAY_SECONDS, self._flush_paste_burst
+        )
+
+    def _start_paste_burst(self, char: str, now: float) -> None:
+        """Start buffering a paste-like keystroke burst."""
+        self._paste_burst_buffer = char
+        self._paste_burst_last_char_time = now
+        self._paste_burst_window_until = now + _PASTE_ENTER_SUPPRESS_WINDOW_SECONDS
+        self._schedule_paste_burst_flush()
+
+    def _append_paste_burst(self, text: str, now: float) -> None:
+        """Append text to an active paste-burst buffer."""
+        if not self._paste_burst_buffer:
+            self._start_paste_burst(text, now)
+            return
+        self._paste_burst_buffer += text
+        self._paste_burst_last_char_time = now
+        self._paste_burst_window_until = now + _PASTE_ENTER_SUPPRESS_WINDOW_SECONDS
+        self._schedule_paste_burst_flush()
+
+    def _note_paste_burst_keystroke(self, now: float) -> None:
+        """Track inter-key timing to count consecutive rapid keystrokes."""
+        last = self._paste_burst_last_key_time
+        if last is not None and (now - last) <= _PASTE_BURST_CHAR_GAP_SECONDS:
+            self._paste_burst_run += 1
+        else:
+            self._paste_burst_run = 1
+        self._paste_burst_last_key_time = now
+
+    def _reset_paste_burst_run(self) -> None:
+        """Clear consecutive-keystroke tracking after non-burst input."""
+        self._paste_burst_run = 0
+        self._paste_burst_last_key_time = None
+        self._paste_burst_last_suppressed_enter_time = None
+
+    def _reset_paste_burst_state(self) -> None:
+        """Reset all paste-burst and backslash tracking to a clean slate.
+
+        Shared by the text-replacing entry points (`set_text_from_history`,
+        `clear_text`, `discard_text`) so a wholesale text swap never leaves
+        stale burst/backslash timing that would misclassify the next keystroke.
+        """
+        self._paste_burst_buffer = ""
+        self._paste_burst_last_char_time = None
+        self._paste_burst_window_until = None
+        self._reset_paste_burst_run()
+        self._cancel_paste_burst_timer()
+        self._backslash_pending_time = None
+
+    def _enter_inserts_newline_during_burst(self, now: float) -> bool:
+        """Return whether `enter` should insert a newline rather than submit.
+
+        True when the preceding keystroke was part of a rapid run or the
+        previous `enter` was already suppressed, and the suppression window is
+        still open. The char-gap check keeps a deliberate `enter` pressed after
+        a burst settles from being swallowed; the window bounds how long a
+        replayed paste's newlines stay grouped. Slash-command context always
+        keeps `enter`'s submit/dispatch semantics.
+        """
+        if self._in_slash_command_context():
+            return False
+        # Defensive: the plain-Enter caller appends-and-returns or flushes any
+        # active buffer before this helper runs, so this branch is unreachable
+        # today. It keeps the helper's contract self-contained.
+        if self._paste_burst_buffer:
+            return True
+        until = self._paste_burst_window_until
+        if until is None or now > until:
+            return False
+        last_enter = self._paste_burst_last_suppressed_enter_time
+        if last_enter is not None:
+            return True
+        last_key = self._paste_burst_last_key_time
+        return (
+            last_key is not None and (now - last_key) <= _PASTE_BURST_CHAR_GAP_SECONDS
+        )
+
+    def _in_slash_command_context(self) -> bool:
+        """Return whether the current input is composing a slash command."""
+        owner = self._chat_input_owner
+        if owner is not None and owner.mode == "command":
+            return True
+        return self.text.startswith("/")
+
+    def _paste_collapse_enabled(self) -> bool:
+        """Return whether large pastes should be collapsed into placeholders.
+
+        Reads the owning `ChatInput`'s resolved preference, defaulting to
+        enabled when the owner is not yet attached.
+        """
+        owner = self._chat_input_owner
+        return owner is None or owner._collapse_pastes
+
+    def _should_start_paste_burst(self, char: str) -> bool:
+        """Return whether a keypress should start paste-burst buffering.
+
+        Restricting to quote-prefixed input at an empty cursor reduces false
+        positives for normal typing and slash-command entry. General multi-line
+        pastes are handled by the Enter-suppression window instead, which keeps
+        their newlines from submitting without rerouting text insertion.
+        """
+        if char not in _PASTE_BURST_START_CHARS:
+            return False
+        if self.text or not self.selection.is_empty:
+            return False
+        row, col = self.cursor_location
+        return row == 0 and col == 0
+
+    async def _flush_paste_burst(self) -> None:
+        """Flush buffered burst text through dropped-path and large-paste checks.
+
+        When parsing fails, the buffered text is inserted unchanged so regular
+        typing behavior is preserved.
+        """
+        payload = self._paste_burst_buffer
+        self._paste_burst_buffer = ""
+        self._paste_burst_last_char_time = None
+        self._cancel_paste_burst_timer()
+        if not payload:
+            return
+
+        from deepagents_code.input import parse_pasted_path_payload
+
+        try:
+            parsed = await asyncio.to_thread(parse_pasted_path_payload, payload)
+        except Exception:
+            # The parser absorbs OSError/RuntimeError internally, so reaching
+            # here signals an unexpected regression.  Leave a breadcrumb (never
+            # the paste content) instead of swallowing it, then fall through to
+            # normal text handling.
+            logger.debug(
+                "Path-payload parsing failed; treating burst as text",
+                exc_info=True,
+            )
+            parsed = None
+        if parsed is not None:
+            self.post_message(self.PastedPaths(payload, parsed.paths))
+            return
+
+        if self._paste_collapse_enabled() and _should_collapse_chat_paste(payload):
+            self.post_message(self.PastedText(payload))
+            return
+
+        self.insert(payload)
+
+    def _delete_preceding_backslash(self) -> bool:
+        """Delete the backslash character immediately before the cursor.
+
+        Caller must ensure a backslash is expected at this position. The
+        method verifies the character before deleting it.
+
+        Returns:
+            `True` if a backslash was found and deleted, `False` otherwise.
+        """
+        row, col = self.cursor_location
+        if col > 0:
+            start = (row, col - 1)
+            if self.document.get_text_range(start, self.cursor_location) == "\\":
+                self.delete(start, self.cursor_location)
+                return True
+        elif row > 0:
+            prev_line = self.document.get_line(row - 1)
+            start = (row - 1, len(prev_line) - 1)
+            end = (row - 1, len(prev_line))
+            if self.document.get_text_range(start, end) == "\\":
+                self.delete(start, self.cursor_location)
+                return True
+        return False
+
+    async def _on_key(self, event: events.Key) -> None:
+        """Handle key events."""
+        # Lock keys (Caps Lock, Num Lock, Scroll Lock) must never type. The
+        # kitty parser patch in `_textual_patches.py` already neutralizes these
+        # at the source; this is defense-in-depth in case a lock key still
+        # arrives with associated text (e.g. if that patch failed to install or
+        # a future terminal bypasses it). Note this only shields the chat input
+        # — if the parser patch silently no-ops, other widgets stay broken. The
+        # key may carry modifier prefixes (e.g. 'ctrl+caps_lock'), so match on
+        # the final '+'-delimited token.
+        if event.key.rsplit("+", 1)[-1] in _LOCK_KEYS:
+            event.prevent_default()
+            event.stop()
+            return
+
+        # VS Code 1.110 incorrectly sends space as a CSI u escape code
+        # (`\x1b[32u`) instead of a plain ` ` character.  Textual parses
+        # this as Key(key='space', character=None, is_printable=False), so
+        # the TextArea never inserts the space.  Per the kitty keyboard
+        # protocol spec, keys that generate text (like space) should NOT
+        # use CSI u encoding — VS Code is the outlier here.
+        #
+        # This workaround should be safe to keep indefinitely: once VS Code or
+        # Textual fixes the issue upstream, `character` will be `' '` and
+        # this branch simply won't match.
+        #
+        # Upstream: https://github.com/Textualize/textual/issues/6408
+        if event.key == "space" and event.character is None:
+            event.prevent_default()
+            event.stop()
+            self.insert(" ")
+            self.post_message(self.Typing())
+            return
+
+        now = time.monotonic()
+
+        # Signal typing activity for printable keys and backspace so the app
+        # can defer approval widgets while the user is actively editing.
+        if event.is_printable or event.key == "backspace":
+            self.post_message(self.Typing())
+
+        if self._paste_burst_buffer:
+            if event.key == "enter":
+                self._append_paste_burst("\n", now)
+                event.prevent_default()
+                event.stop()
+                return
+
+            if event.is_printable and event.character is not None:
+                last_time = self._paste_burst_last_char_time
+                if (
+                    last_time is not None
+                    and (now - last_time) <= _PASTE_BURST_CHAR_GAP_SECONDS
+                ):
+                    self._append_paste_burst(event.character, now)
+                    event.prevent_default()
+                    event.stop()
+                    return
+
+            await self._flush_paste_burst()
+
+        if (
+            event.is_printable
+            and event.character is not None
+            and self._should_start_paste_burst(event.character)
+        ):
+            self._start_paste_burst(event.character, now)
+            event.prevent_default()
+            event.stop()
+            return
+
+        # Track rapid keystroke runs so a terminal replaying a paste as key
+        # events (no bracketed paste) arms the Enter-suppression window, keeping
+        # the paste's newlines from submitting mid-stream. `enter` is exempt so
+        # newlines within a paste don't break the run.
+        if event.is_printable and event.character is not None:
+            self._paste_burst_last_suppressed_enter_time = None
+            self._note_paste_burst_keystroke(now)
+            if (
+                self._paste_burst_run >= _PASTE_BURST_MIN_CHARS
+                and not self._in_slash_command_context()
+            ):
+                self._paste_burst_window_until = (
+                    now + _PASTE_ENTER_SUPPRESS_WINDOW_SECONDS
+                )
+        elif event.key != "enter":
+            self._reset_paste_burst_run()
+
+        # A mode trigger (`!`, `!!`, `/`) typed at the very start of an
+        # unselected input switches modes. Handle it before TextArea inserts the
+        # character so the trigger never flashes on screen for a frame before
+        # the change handler would strip it.
+        if (
+            event.is_printable
+            and event.character is not None
+            and self.cursor_location == (0, 0)
+            and self.selection.is_empty
+            and self._chat_input_owner is not None
+            and self._chat_input_owner.handle_mode_prefix_keystroke(event.character)
+        ):
+            event.prevent_default()
+            event.stop()
+            return
+
+        # Some terminals (e.g. VSCode built-in) send a literal backslash
+        # followed by enter for shift+enter.  When enter arrives shortly
+        # after a backslash, delete the backslash and insert a newline.
+        if (
+            event.key == "enter"
+            and not self._completion_active
+            and self._backslash_pending_time is not None
+            and (now - self._backslash_pending_time) <= _BACKSLASH_ENTER_GAP_SECONDS
+        ):
+            self._backslash_pending_time = None
+            if self._delete_preceding_backslash():
+                event.prevent_default()
+                event.stop()
+                self.action_insert_newline()
+                return
+        self._backslash_pending_time = None
+
+        if event.key == "backslash" and event.character == "\\":
+            self._backslash_pending_time = now
+
+        # Modifier+Enter inserts newline — keys derived from BINDINGS
+        if event.key in self._NEWLINE_KEYS:
+            event.prevent_default()
+            event.stop()
+            self.action_insert_newline()
+            return
+
+        if event.key == "backspace" and self._delete_placeholder_token(backwards=True):
+            event.prevent_default()
+            event.stop()
+            return
+
+        # If completion is active, let parent handle navigation keys.
+        # Space is included so that slash-command completion can accept the
+        # selected suggestion via the same code path as Tab (avoiding a
+        # frame-lag between the popup hiding and the argument hint appearing).
+        # When the active controller ignores the space (e.g. file completion),
+        # ChatInput.on_key inserts it manually.
+        if self._completion_active and event.key in {
+            "up",
+            "down",
+            "tab",
+            "enter",
+            "space",
+        }:
+            # Prevent TextArea's default behavior (e.g., Enter inserting newline)
+            # but let event bubble to ChatInput for completion handling
+            event.prevent_default()
+            return
+
+        # Plain Enter submits, unless a recent keystroke burst suggests this
+        # newline is part of a paste replayed as key events; then insert a
+        # newline and keep the window alive so the rest of the paste stays
+        # grouped instead of submitting mid-stream.
+        if event.key == "enter":
+            event.prevent_default()
+            event.stop()
+            if self._enter_inserts_newline_during_burst(now):
+                self._paste_burst_window_until = (
+                    now + _PASTE_ENTER_SUPPRESS_WINDOW_SECONDS
+                )
+                self._paste_burst_last_suppressed_enter_time = now
+                self.action_insert_newline()
+                return
+            self._paste_burst_last_suppressed_enter_time = None
+            if (
+                self._chat_input_owner is not None
+                and self._chat_input_owner._handle_stale_slash_enter()
+            ):
+                return
+            value = self.text.strip()
+            if value:
+                self.post_message(self.Submitted(value))
+            return
+
+        await super()._on_key(event)
+
+    def action_delete_right(self) -> None:
+        """Delete a bound placeholder atomically or the next character."""
+        if not self._delete_placeholder_token(backwards=False):
+            super().action_delete_right()
+
+    def _delete_placeholder_token(self, *, backwards: bool) -> bool:
+        """Delete a full placeholder token (image, video, or paste) in one keypress.
+
+        Args:
+            backwards: Whether the delete action is backwards (`backspace`) or
+                forwards (`delete`).
+
+        Returns:
+            `True` when a placeholder token was deleted.
+        """
+        if not self.text or not self.selection.is_empty:
+            return False
+
+        cursor_offset = self.document.get_index_from_location(self.cursor_location)  # ty: ignore[unresolved-attribute]  # Document has this method; DocumentBase stub is narrower
+        span = self._find_placeholder_span(cursor_offset, backwards=backwards)
+        if span is None:
+            return False
+
+        start, end = span
+        start_location = self.document.get_location_from_index(start)  # ty: ignore[unresolved-attribute]  # Document has this method; DocumentBase stub is narrower
+        end_location = self.document.get_location_from_index(end)  # ty: ignore[unresolved-attribute]
+        self.delete(start_location, end_location)
+        self.move_cursor(start_location)
+        return True
+
+    def _bound_media_placeholders(self) -> set[str]:
+        """Return placeholder tokens bound to currently tracked media.
+
+        Returns:
+            The set of `[image N]`/`[video N]` tokens for media the tracker is
+                actually holding. Empty when there is no owner/tracker.
+        """
+        owner = self._chat_input_owner
+        tracker = owner._image_tracker if owner is not None else None
+        if tracker is None:
+            return set()
+        placeholders = {img.placeholder for img in tracker.images}
+        placeholders.update(video.placeholder for video in tracker.videos)
+        return placeholders
+
+    def _bound_paste_ids(self) -> set[int]:
+        """Return paste ids that have backing content in the owner.
+
+        Returns:
+            The set of paste ids present in `ChatInput._pasted_contents`. Empty
+                when there is no owner.
+        """
+        owner = self._chat_input_owner
+        if owner is None:
+            return set()
+        return set(owner._pasted_contents)
+
+    def _find_placeholder_span(
+        self, cursor_offset: int, *, backwards: bool
+    ) -> tuple[int, int] | None:
+        """Return placeholder span to delete for current cursor and key direction.
+
+        Covers image, video, and collapsed-paste placeholders so each deletes as
+        a single atomic token.  Paste placeholders carry backing content in
+        `ChatInput._pasted_contents`; that map is intentionally left untouched
+        here so an undo can restore the token with its content (it is cleared
+        only at submit).
+
+        Only tokens bound to real attachments are treated as atomic: image/video
+        placeholders must correspond to a tracked media item and paste
+        placeholders to an entry in `ChatInput._pasted_contents`. Placeholder-
+        shaped text the user typed by hand (e.g. literally typing ``[image 2]``)
+        is left as ordinary text and edits character by character.
+
+        Args:
+            cursor_offset: Character offset of the cursor from the start of text.
+            backwards: Whether the delete action is backwards (backspace) or
+                forwards (delete).
+
+        Returns:
+            The `(start, end)` character span of the placeholder to delete, or
+                `None` when the cursor is not adjacent to a bound placeholder
+                token.
+        """
+        text = self.text
+        media_placeholders = self._bound_media_placeholders()
+        pasted_ids = self._bound_paste_ids()
+        for pattern in (
+            IMAGE_PLACEHOLDER_PATTERN,
+            VIDEO_PLACEHOLDER_PATTERN,
+            PASTE_PLACEHOLDER_PATTERN,
+        ):
+            for match in pattern.finditer(text):
+                if pattern is PASTE_PLACEHOLDER_PATTERN:
+                    if int(match.group(1)) not in pasted_ids:
+                        continue
+                elif match.group(0) not in media_placeholders:
+                    continue
+                start, end = match.span()
+                if backwards:
+                    # Cursor is inside token or right after a trailing space inserted
+                    # with the token.
+                    if start < cursor_offset <= end:
+                        return start, end
+                    if cursor_offset > 0:
+                        previous_index = cursor_offset - 1
+                        if (
+                            previous_index < len(text)
+                            and previous_index == end
+                            and text[previous_index].isspace()
+                        ):
+                            return start, cursor_offset
+                elif start <= cursor_offset < end:
+                    return start, end
+        return None
+
+    def replace_placeholder_with_text(self, paste_id: int, content: str) -> bool:
+        """Replace a `[Pasted text #id]` placeholder with full text in place.
+
+        Used when the same content is pasted again: the compact placeholder is
+        expanded back to the original text where it sits, preserving surrounding
+        input.
+
+        Args:
+            paste_id: The paste id whose placeholder should be expanded.
+            content: The full text to insert where the placeholder was.
+
+        Returns:
+            `True` when a matching placeholder was found and replaced.
+        """
+        for match in PASTE_PLACEHOLDER_PATTERN.finditer(self.text):
+            if int(match.group(1)) != paste_id:
+                continue
+            start, end = match.span()
+            start_location = self.document.get_location_from_index(start)  # ty: ignore[unresolved-attribute]  # Document has this method; DocumentBase stub is narrower
+            end_location = self.document.get_location_from_index(end)  # ty: ignore[unresolved-attribute]
+            self.delete(start_location, end_location)
+            self.insert(content, start_location)
+            return True
+        return False
+
+    async def _on_paste(self, event: events.Paste) -> None:
+        """Handle paste events, detecting images, file paths, and large pastes."""
+        # First check if clipboard has an image
+        image = await asyncio.to_thread(get_clipboard_image)
+        if image is not None:
+            event.prevent_default()
+            event.stop()
+            # Add image to media tracker to get numbered placeholder
+            placeholder = self._chat_input_owner._image_tracker.add_image(image)
+            # Insert placeholder at cursor position
+            self.insert(placeholder)
+            return
+
+        # Original text paste logic
+        self._backslash_pending_time = None
+        if self._paste_burst_buffer:
+            await self._flush_paste_burst()
+
+        from deepagents_code.input import parse_pasted_path_payload
+
+        try:
+            parsed = await asyncio.to_thread(parse_pasted_path_payload, event.text)
+        except Exception:
+            # See _flush_paste_burst: swallowing here would silently break the
+            # drag-drop-file path, so log a breadcrumb and fall through to text.
+            logger.debug(
+                "Path-payload parsing failed; treating paste as text",
+                exc_info=True,
+            )
+            parsed = None
+        if parsed is not None:
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.PastedPaths(event.text, parsed.paths))
+            return
+
+        if self._paste_collapse_enabled() and _should_collapse_chat_paste(event.text):
+            # Intercept the paste so Textual's default _on_paste doesn't insert
+            # the full text. ChatInput stores the content and inserts a compact
+            # placeholder instead.
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.PastedText(event.text))
+            return
+
+        # Don't call super() here — Textual's MRO dispatch already calls
+        # TextArea._on_paste after this handler returns. Calling super()
+        # would insert the text a second time, duplicating the paste.
+
+    def set_text_from_history(self, text: str, *, cursor_at_end: bool = True) -> None:
+        """Set text from history navigation.
+
+        Args:
+            text: The history entry text to load.
+            cursor_at_end: Place the cursor at the end of the loaded text
+                (use for down-navigation, so the next down press continues
+                forward through history). When `False`, place at the start
+                so the next up press continues backward. Defaults to `True`
+                to preserve historical cursor-at-end behavior for callers
+                that don't specify a direction.
+        """
+        self._reset_paste_burst_state()
+        self._skip_history_change_events += 1
+        self.text = text
+        # The suppressed Changed event (see above) is what would normally toggle
+        # the clear/copy buttons, so sync them now to hide/show in the same frame
+        # the text swaps — otherwise an emptied draft keeps the buttons for a frame.
+        self._sync_owner_action_buttons(text)
+        if cursor_at_end:
+            self.move_cursor_to_end()
+        else:
+            self.move_cursor((0, 0))
+
+    def move_cursor_to_end(self) -> None:
+        """Move the cursor to the end of the current text."""
+        lines = self.text.split("\n")
+        last_row = len(lines) - 1
+        self.move_cursor((last_row, len(lines[last_row])))
+
+    def clear_text(self) -> None:
+        """Clear the text area."""
+        # Increment (not reset) so any pending Changed event from a prior
+        # set_text_from_history is still suppressed, plus one for the
+        # self.text = "" assignment below.
+        self._skip_history_change_events += 1
+        self._reset_paste_burst_state()
+        self.text = ""
+        # Hide the clear/copy buttons in the same frame the draft empties; the
+        # suppressed Changed event would otherwise leave them for an extra frame.
+        self._sync_owner_action_buttons("")
+        self.move_cursor((0, 0))
+
+    def _sync_owner_action_buttons(self, text: str) -> None:
+        """Match the owner's clear/copy buttons to programmatically set text.
+
+        History/clear text swaps suppress the `Changed` event that normally
+        drives button visibility, so the owner is updated directly to keep the
+        buttons in lockstep with the draft (matching the `Changed`-path gate).
+        """
+        owner = self._chat_input_owner
+        if owner is not None:
+            owner._set_action_buttons_visible(visible=bool(text.strip()))
+
+    def discard_text(self) -> bool:
+        """Clear the draft via an undoable edit (restorable with ctrl+z).
+
+        Unlike `clear_text`, the deletion is recorded in the undo history and
+        the resulting `Changed` event is allowed to propagate, so completion
+        and argument-hint state stay in sync.
+
+        Returns:
+            `True` when there was text to clear.
+        """
+        if not self.text:
+            return False
+        self._reset_paste_burst_state()
+        self.clear()
+        return True
+
+
+class _CompletionViewAdapter:
+    """Translate completion-space replacements to text-area coordinates."""
+
+    def __init__(self, chat_input: ChatInput) -> None:
+        """Initialize adapter with its owning `ChatInput`."""
+        self._chat_input = chat_input
+
+    def render_completion_suggestions(
+        self, suggestions: list[tuple[str, str]], selected_index: int
+    ) -> None:
+        """Delegate suggestion rendering to `ChatInput`."""
+        self._chat_input.render_completion_suggestions(suggestions, selected_index)
+
+    def clear_completion_suggestions(self) -> None:
+        """Delegate completion clearing to `ChatInput`."""
+        self._chat_input.clear_completion_suggestions()
+
+    def replace_completion_range(self, start: int, end: int, replacement: str) -> None:
+        """Map completion indices to text-area indices before replacing text."""
+        # The completion controller returns the full command name (e.g.
+        # "/remember") in completion space, but the TextArea only contains
+        # text after the virtual mode prefix (e.g. "/" in command mode).
+        # Strip the prefix to avoid double-insertion.
+        prefix = MODE_PREFIXES.get(self._chat_input.mode, "")
+        if prefix and replacement.startswith(prefix):
+            replacement = replacement[len(prefix) :]
+        self._chat_input.replace_completion_range(
+            self._chat_input._completion_index_to_text_index(start),
+            self._chat_input._completion_index_to_text_index(end),
+            replacement,
+        )
+
+
+class ChatInput(Vertical):
+    """Chat input widget with prompt, multi-line text, autocomplete, and history.
+
+    Features:
+    - Multi-line input with TextArea
+    - Enter to submit, modifier key for newlines (see `config.newline_shortcut`)
+    - Up/Down arrows for command history at input boundaries (start/end of text)
+    - Autocomplete for @ (files) and / (commands)
+    """
+
+    DEFAULT_CSS = """
+    ChatInput {
+        height: auto;
+        layers: base actions;
+    }
+
+    ChatInput #input-box {
+        height: auto;
+        min-height: 3;
+        max-height: 25;
+        padding: 0;
+        background: $background;
+        border: solid $primary;
+    }
+
+    ChatInput.mode-shell #input-box {
+        border: solid $mode-bash;
+    }
+
+    ChatInput.mode-command #input-box {
+        border: solid $mode-command;
+    }
+
+    ChatInput.mode-shell-incognito #input-box {
+        border: solid $mode-incognito;
+        border-title-color: $mode-incognito;
+        border-title-style: bold;
+    }
+
+    /* Action buttons float on their own z-layer over the top border line, so
+       they cost no content row and never overlap the draft text. The row docks
+       to the right edge and sizes to its buttons (`width: auto`), overlaying
+       only the right portion of the border line and leaving the rest clear. */
+    ChatInput #input-actions {
+        layer: actions;
+        dock: right;
+        width: auto;
+        height: 1;
+        margin-right: 1;
+        display: none;
+    }
+
+    ChatInput .input-row {
+        height: auto;
+        width: 100%;
+    }
+
+    ChatInput .input-prompt {
+        width: 3;
+        height: 1;
+        padding: 0 1;
+        color: $primary;
+        text-style: bold;
+    }
+
+    ChatInput.mode-shell .input-prompt {
+        color: $mode-bash;
+    }
+
+    ChatInput.mode-command .input-prompt {
+        color: $mode-command;
+    }
+
+    ChatInput.mode-shell-incognito .input-prompt {
+        color: $mode-incognito;
+    }
+
+    ChatInput ChatTextArea {
+        width: 1fr;
+        height: auto;
+        min-height: 1;
+        max-height: 8;
+        border: none;
+        background: transparent;
+        padding: 0;
+    }
+
+    ChatInput ChatTextArea.cursor-underline .text-area--cursor {
+        background: transparent;
+        color: $text;
+        text-style: underline;
+    }
+
+    ChatInput ChatTextArea:focus {
+        border: none;
+    }
+    """
+    """Border and prompt glyph change color per mode for immediate visual feedback."""
+
+    class Submitted(Message):
+        """Message sent when input is submitted."""
+
+        def __init__(self, value: str, mode: str = "normal") -> None:
+            """Initialize with value and mode."""
+            super().__init__()
+            self.value = value
+            self.mode = mode
+
+    class ModeChanged(Message):
+        """Message sent when input mode changes."""
+
+        def __init__(self, mode: str) -> None:
+            """Initialize with new mode."""
+            super().__init__()
+            self.mode = mode
+
+    class Typing(Message):
+        """Posted when the user presses a printable key or backspace in the input.
+
+        The app uses this to delay approval widgets while the user is actively
+        typing, preventing accidental key presses (e.g. `y`, `n`) from
+        triggering approval decisions.
+        """
+
+    mode: reactive[str] = reactive("normal")
+
+    def __init__(
+        self,
+        cwd: str | Path | None = None,
+        history_file: Path | None = None,
+        image_tracker: MediaTracker | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the chat input widget.
+
+        Args:
+            cwd: Current working directory for file completion
+            history_file: Override path for persisted input history.
+                Resolved by `_default_history_path()` when `None`.
+            image_tracker: Optional tracker for attached images
+            **kwargs: Additional arguments for parent
+        """
+        super().__init__(**kwargs)
+        self._cwd = Path(cwd) if cwd else Path.cwd()
+        self._image_tracker = image_tracker
+        self._input_box: Vertical | None = None
+        self._action_buttons: Horizontal | None = None
+        self._text_area: ChatTextArea | None = None
+        self._popup: CompletionPopup | None = None
+        self._completion_manager: MultiCompletionManager | None = None
+        self._completion_view: _CompletionViewAdapter | None = None
+        self._slash_controller: SlashCommandController | None = None
+
+        # Collapsed paste storage: paste_id → full content.  When a large paste
+        # arrives, the full text is stored here and a compact
+        # `[Pasted text #N +M lines]` placeholder is inserted into the text
+        # area instead.  At submission the placeholder is expanded back.
+        self._pasted_contents: dict[int, PastedContent] = {}
+        self._next_paste_id = 1
+
+        # Whether large pastes are collapsed into `[Pasted text #N +M lines]`
+        # placeholders.
+        # Gated by `display.collapse_pastes` (env / `[ui].collapse_pastes`);
+        # when disabled, pasted text is inserted verbatim.
+        self._collapse_pastes = _load_collapse_pastes()
+
+        # Guard flag: set True before programmatically stripping the mode
+        # prefix character so the resulting text-change event does not
+        # re-evaluate mode.
+        self._stripping_prefix = False
+
+        # When the user submits, we clear the text area which fires a
+        # text-change event. Without this guard the tracker would see the
+        # now-empty text, assume all media were deleted, and discard them
+        # before the app has a chance to send them. Each submit bumps the
+        # counter by one; the next text-change event decrements it and
+        # skips the sync.
+        self._skip_media_sync_events = 0
+
+        # Number of virtual prefix characters currently injected for
+        # completion controller calls (0 for normal, 1 for shell/command).
+        self._completion_prefix_len = 0
+
+        # Guard flag: set while replacing a dropped path payload with an
+        # inline image placeholder so the resulting change event doesn't
+        # immediately recurse into the same replacement path.
+        self._applying_inline_path_replacement = False
+
+        # Text area content from the previous Changed event. Used to skip
+        # blocking filesystem path-detection on single-keystroke edits while
+        # still detecting replacement edits that insert a full path payload.
+        self._prev_text = ""
+
+        # Track current suggestions for click handling
+        self._current_suggestions: list[tuple[str, str]] = []
+        self._current_selected_index = 0
+
+        # Command name (without /) → argument hint for inline ghost text
+        self._argument_hints: dict[str, str] = {}
+
+        # Set up history manager
+        if history_file is None:
+            history_file = _default_history_path()
+        self._history = HistoryManager(history_file)
+
+    def compose(self) -> ComposeResult:  # noqa: PLR6301  # Textual widget method convention
+        """Compose the chat input layout.
+
+        Yields:
+            Widgets for the input row and completion popup.
+        """
+        # The bordered box owns the prompt, text area, and completion popup so
+        # the action buttons (a sibling) can float on its top border line; a
+        # widget can only render on its sibling's border, not its parent's.
+        with Vertical(id="input-box"):
+            with Horizontal(classes="input-row"):
+                yield Static(">", classes="input-prompt", id="prompt")
+                yield ChatTextArea(id="chat-input")
+            yield CompletionPopup(id="completion-popup")
+
+        # Action buttons float on their own z-layer over the top border line so
+        # they cost no content row and never overlap the draft text.
+        with Horizontal(id="input-actions"):
+            yield InputActionButton(
+                "[ X ]",
+                "clear",
+                id="clear-button",
+                classes="input-action input-action-clear",
+            )
+            yield InputActionButton(
+                "[ COPY ]",
+                "copy",
+                id="copy-button",
+                classes="input-action input-action-copy",
+            )
+
+    def on_mount(self) -> None:
+        """Initialize components after mount."""
+        self._input_box = self.query_one("#input-box", Vertical)
+        self._action_buttons = self.query_one("#input-actions", Horizontal)
+        if is_ascii_mode():
+            colors = theme.get_theme_colors(self)
+            self._input_box.styles.border = ("ascii", colors.primary)
+
+        self._text_area = self.query_one("#chat-input", ChatTextArea)
+        self._popup = self.query_one("#completion-popup", CompletionPopup)
+        self._text_area._chat_input_owner = self
+
+        # Both controllers implement the CompletionController protocol but have
+        # different concrete types; the list-item warning is a false positive.
+        self._completion_view = _CompletionViewAdapter(self)
+        self._file_controller = FuzzyFileController(
+            self._completion_view, cwd=self._cwd
+        )
+        self._slash_controller = SlashCommandController(
+            SLASH_COMMANDS, self._completion_view
+        )
+        self._completion_manager = MultiCompletionManager(
+            [
+                self._slash_controller,
+                self._file_controller,
+            ]  # ty: ignore[invalid-argument-type]  # Controller types are compatible at runtime
+        )
+
+        self._rebuild_argument_hints(SLASH_COMMANDS)
+
+        self._warm_file_cache()
+        self.set_interval(
+            _FILE_CACHE_REFRESH_INTERVAL_SECONDS,
+            self._refresh_file_cache,
+        )
+        self._text_area.focus()
+
+    def _warm_file_cache(self, *, force: bool = False, exclusive: bool = False) -> None:
+        """Schedule an `@` file-completion cache warmer.
+
+        No-ops before `on_mount` wires up the file controller (the periodic
+        refresh interval can fire during teardown or a partial mount).
+
+        Args:
+            force: Re-walk even when the cache is already populated. The prior
+                cache stays visible until the new walk completes.
+            exclusive: Cancel any other in-flight warmer in the shared worker
+                group before starting, so a slow walk is superseded by the next
+                tick rather than stacking overlapping walks. Used by the
+                periodic refresh; the on-mount/cwd-switch warmers run
+                non-exclusively so a quick invalidation can warm concurrently.
+        """
+        file_controller = getattr(self, "_file_controller", None)
+        if file_controller is None:
+            return
+        self.run_worker(
+            file_controller.warm_cache(force=force),
+            exclusive=exclusive,
+            group=_FILE_CACHE_WORKER_GROUP,
+            exit_on_error=False,
+        )
+
+    def _refresh_file_cache(self) -> None:
+        """Re-warm the `@` file-completion cache off the event loop."""
+        self._warm_file_cache(force=True, exclusive=True)
+
+    def set_cwd(self, cwd: str | Path) -> None:
+        """Update file completion to use a new cwd.
+
+        Re-roots the file controller and schedules a background cache warm so
+        the project-root walk runs off the event loop.
+        """
+        self._cwd = Path(cwd)
+        file_controller = getattr(self, "_file_controller", None)
+        if file_controller is not None:
+            file_controller.set_cwd(self._cwd)
+            self._warm_file_cache()
+
+    def update_slash_commands(self, commands: list[CommandEntry]) -> None:
+        """Update the slash command controller's command list.
+
+        Called by the app after discovering skills to merge static
+        commands with dynamic `/skill:` entries.
+
+        Args:
+            commands: Full list of `CommandEntry` instances.
+        """
+        if self._slash_controller:
+            self._slash_controller.update_commands(commands)
+            self._rebuild_argument_hints(commands)
+        else:
+            logger.warning(
+                "Cannot update slash commands: controller not initialized "
+                "(widget not yet mounted)"
+            )
+
+    def _rebuild_argument_hints(self, commands: list[CommandEntry]) -> None:
+        """Rebuild the command-name -> argument-hint lookup.
+
+        Args:
+            commands: Current list of `CommandEntry` instances.
+        """
+        self._argument_hints = {
+            entry.name.removeprefix("/"): entry.argument_hint
+            for entry in commands
+            if entry.argument_hint
+        }
+
+    def _update_argument_hint(self) -> None:
+        """Show or clear inline ghost text for slash-command argument hints.
+
+        Sets `ChatTextArea.argument_hint` when the input is a known slash
+        command followed by a trailing space with no args typed yet. Both
+        spacebar and Tab completion produce this state (Tab goes through
+        `replace_completion_range` which appends a trailing space).
+        """
+        if not self._text_area:
+            return
+
+        if self.mode == "command":
+            text = self._text_area.text
+            if text.endswith(" ") and text.count(" ") == 1:
+                hint = self._argument_hints.get(text[:-1], "")
+                if hint:
+                    self._text_area.argument_hint = hint
+                    return
+
+        self._text_area.argument_hint = ""
+
+    def _set_action_buttons_visible(self, *, visible: bool) -> None:
+        """Show or hide the clear/copy action buttons on the input border.
+
+        Only writes `display` when it actually changes. Mutating it on every
+        keystroke would trigger a layout reflow each time, which perturbs the
+        completion popup's deferred (`call_after_refresh`) show/hide ordering.
+        """
+        if self._action_buttons is not None and self._action_buttons.display != visible:
+            self._action_buttons.display = visible
+
+    def on_text_area_changed(self, event: TextArea.Changed) -> None:
+        """Detect input mode and update completions."""
+        text = event.text_area.text
+        # Reveal the clear/copy buttons only when there is a meaningful draft to
+        # act on, so an empty input keeps a clean, uncluttered border.
+        # Whitespace-only input (e.g. stray spaces or newlines) has nothing
+        # worth clearing or copying, so it stays hidden too. Done before the
+        # early returns below so recalled-history text shows them as well.
+        # NOTE: this `strip()` gate is deliberately stricter than the keyboard
+        # paths (esc+esc clear, Ctrl+C copy), which act on the raw value so a
+        # whitespace-only draft is still clearable/copyable without the buttons.
+        self._set_action_buttons_visible(visible=bool(text.strip()))
+        # Drag-drop / bracketed paste arrive as one Changed event with a
+        # multi-character inserted span. Normal typing arrives one character at
+        # a time. Checking the changed span (rather than net length delta)
+        # preserves replacement edits where selected text is replaced by a path
+        # of similar length.
+        should_check_path_payload = self._should_check_path_payload(text)
+        previous_text = self._prev_text
+        self._sync_media_tracker_to_text(
+            text, previous_text=previous_text, cursor_offset=self._get_cursor_offset()
+        )
+        self._prev_text = text
+
+        # History handlers explicitly decide mode and stripped display text.
+        # Skip mode detection here so recalled entries don't inherit stale mode.
+        if self._text_area and self._text_area._skip_history_change_events > 0:
+            self._text_area._skip_history_change_events -= 1
+            if self._completion_manager:
+                self._completion_manager.reset()
+            self.scroll_visible()
+            return
+        if self._text_area and self._text_area._skip_history_change_events < 0:
+            logger.warning(
+                "_skip_history_change_events is negative (%d); resetting to 0",
+                self._text_area._skip_history_change_events,
+            )
+            self._text_area._skip_history_change_events = 0
+
+        if self._applying_inline_path_replacement:
+            self._applying_inline_path_replacement = False
+        elif should_check_path_payload and self._apply_inline_dropped_path_replacement(
+            text
+        ):
+            return
+
+        # Checked after the guards above so we skip the (potentially slow)
+        # filesystem lookup when the text change came from history navigation
+        # or prefix stripping, which never need path detection.
+        is_path_payload = should_check_path_payload and self._is_dropped_path_payload(
+            text
+        )
+
+        # Guard: skip mode re-detection after we programmatically stripped
+        # a prefix character.
+        if self._stripping_prefix:
+            self._stripping_prefix = False
+        elif detected_prefix := detect_mode_prefix(text):
+            prefix, raw_detected = detected_prefix
+            detected, strip_length = self._resolve_prefix_mode(prefix, raw_detected)
+            if prefix == "/" and is_path_payload:
+                # Absolute dropped paths stay normal input, not slash-command mode.
+                if self.mode != "normal":
+                    self.mode = "normal"
+            else:
+                # Detected a mode-trigger prefix (e.g. "!" or "/").
+                # Strip it unconditionally -- even when already in the correct
+                # mode -- because completion controllers may write replacement
+                # text that re-includes the trigger character.  The
+                # _stripping_prefix guard prevents the resulting change event
+                # from looping back here.
+                if self.mode != detected:
+                    self.mode = detected
+                if strip_length:
+                    self._strip_mode_prefix(strip_length)
+                # Fall through to update completion suggestions in the same
+                # refresh cycle as the mode/glyph change rather than waiting
+                # for the next text-change event caused by the prefix strip.
+                # Note: the strip's text-change event will also call
+                # on_text_changed (idempotently) since _stripping_prefix only
+                # skips mode detection, not the completion block below.
+        # Set inline argument hint before the completion manager runs so
+        # the suggestion is ready in the same render pass that hides the popup.
+        self._update_argument_hint()
+
+        # Update completion suggestions using completion-space text/cursor.
+        if self._completion_manager and self._text_area:
+            if is_path_payload:
+                self._completion_manager.reset()
+            else:
+                vtext, vcursor = self._completion_text_and_cursor()
+                self._completion_manager.on_text_changed(vtext, vcursor)
+
+        # Scroll input into view when content changes (handles text wrap)
+        self.scroll_visible()
+
+    def _should_check_path_payload(self, text: str) -> bool:
+        """Return whether a text change may contain a pasted path payload."""
+        old = self._prev_text
+        if text == old:
+            return False
+
+        prefix_len = 0
+        max_prefix_len = min(len(old), len(text))
+        while prefix_len < max_prefix_len and old[prefix_len] == text[prefix_len]:
+            prefix_len += 1
+
+        old_suffix = len(old)
+        text_suffix = len(text)
+        while (
+            old_suffix > prefix_len
+            and text_suffix > prefix_len
+            and old[old_suffix - 1] == text[text_suffix - 1]
+        ):
+            old_suffix -= 1
+            text_suffix -= 1
+
+        inserted_len = text_suffix - prefix_len
+        return inserted_len > 1
+
+    @staticmethod
+    def _parse_dropped_path_payload(
+        text: str, *, allow_leading_path: bool = False
+    ) -> ParsedPastedPathPayload | None:
+        """Parse dropped-path payload text through a single parser entrypoint.
+
+        Returns:
+            Parsed payload details, otherwise `None`.
+        """
+        from deepagents_code.input import parse_pasted_path_payload
+
+        return parse_pasted_path_payload(text, allow_leading_path=allow_leading_path)
+
+    def _parse_dropped_path_payload_with_command_recovery(
+        self, text: str, *, allow_leading_path: bool = False
+    ) -> tuple[str, ParsedPastedPathPayload | None]:
+        """Parse payload and recover stripped leading slash in command mode.
+
+        Args:
+            text: Input text to parse.
+            allow_leading_path: Whether to parse leading path + suffix payloads.
+
+        Returns:
+            Tuple of `(candidate_text, parsed_payload)`.
+        """
+        candidate = text
+        parsed = self._parse_dropped_path_payload(
+            text, allow_leading_path=allow_leading_path
+        )
+        if parsed is not None:
+            return candidate, parsed
+
+        if self.mode != "command":
+            return candidate, None
+
+        prefixed = f"/{text.lstrip('/')}"
+        parsed = self._parse_dropped_path_payload(
+            prefixed, allow_leading_path=allow_leading_path
+        )
+        if parsed is None:
+            return candidate, None
+
+        logger.debug(
+            "Recovering stripped absolute path; resetting mode from "
+            "'command' to 'normal'"
+        )
+        self.mode = "normal"
+        return prefixed, parsed
+
+    def _extract_leading_dropped_path_with_command_recovery(
+        self, text: str
+    ) -> tuple[str, tuple[Path, int] | None]:
+        """Extract a leading dropped-path token with command-mode recovery.
+
+        Args:
+            text: Input text to parse.
+
+        Returns:
+            Tuple of `(candidate_text, leading_match)`, where `leading_match` is
+            `(path, token_end)` when extraction succeeds, otherwise `None`.
+        """
+        from deepagents_code.input import extract_leading_pasted_file_path
+
+        leading_match = extract_leading_pasted_file_path(text)
+        candidate = text
+        if leading_match is not None:
+            return candidate, leading_match
+
+        if self.mode != "command":
+            return candidate, None
+
+        prefixed = f"/{text.lstrip('/')}"
+        leading_match = extract_leading_pasted_file_path(prefixed)
+        if leading_match is None:
+            return candidate, None
+
+        logger.debug(
+            "Recovering stripped absolute leading path; resetting mode "
+            "from 'command' to 'normal'"
+        )
+        self.mode = "normal"
+        return prefixed, leading_match
+
+    @staticmethod
+    def _is_existing_path_payload(text: str) -> bool:
+        """Return whether text is a dropped-path payload for existing files."""
+        if len(text) < 2:  # noqa: PLR2004  # Need at least '/' + one char
+            return False
+        from deepagents_code.input import parse_pasted_path_payload
+
+        return parse_pasted_path_payload(text, allow_leading_path=True) is not None
+
+    def _is_dropped_path_payload(self, text: str) -> bool:
+        """Return whether current text looks like a dropped file-path payload."""
+        if not text:
+            return False
+        if self._is_existing_path_payload(text):
+            return True
+        if self.mode == "command":
+            candidate = f"/{text.lstrip('/')}"
+            return self._is_existing_path_payload(candidate)
+        return False
+
+    def _resolve_prefix_mode(self, prefix: str, detected: str) -> tuple[str, int]:
+        """Resolve target mode and strip length for a detected mode prefix.
+
+        Applies the `!`/`!!` state machine relative to the current mode.
+
+        Returns:
+            Tuple of `(target_mode, strip_length)`.
+        """
+        strip_length = len(prefix)
+        if self.mode == "shell" and detected == "shell":
+            # First `!` was stripped on entry to shell mode, so this `!` is the
+            # second bang of `!!`. Promote to incognito and consume it.
+            detected = "shell_incognito"
+        elif self.mode == "shell_incognito" and detected == "shell":
+            # Already in incognito; an extra `!` is part of the command body.
+            # Skip the strip-and-demote path that would drop back to shell mode.
+            detected = "shell_incognito"
+            strip_length = 0
+        return detected, strip_length
+
+    def handle_mode_prefix_keystroke(self, char: str) -> bool:
+        """Switch input mode for a mode trigger typed at the start of the input.
+
+        Handles the switch before `TextArea` inserts the character so the
+        trigger (`!`, `!!`, `/`) never flashes on screen for a frame before the
+        change handler would strip it.
+
+        Returns:
+            True if the keystroke was consumed as a mode selector without
+            inserting the character, otherwise False.
+        """
+        detected_prefix = detect_mode_prefix(char)
+        if detected_prefix is None:
+            return False
+        prefix, raw_detected = detected_prefix
+        detected, strip_length = self._resolve_prefix_mode(prefix, raw_detected)
+        if not strip_length:
+            # An extra `!` inside an incognito command body is literal text.
+            return False
+        if self.mode != detected:
+            self.mode = detected
+        # No text changed, so run the same hint/completion refresh that
+        # on_text_area_changed performs after stripping a typed prefix.
+        self._update_argument_hint()
+        if self._completion_manager and self._text_area:
+            vtext, vcursor = self._completion_text_and_cursor()
+            self._completion_manager.on_text_changed(vtext, vcursor)
+        self.scroll_visible()
+        return True
+
+    def _strip_mode_prefix(self, length: int = 1) -> None:
+        """Remove the mode trigger from the text area.
+
+        Sets the `_stripping_prefix` guard so the resulting text-change event is
+        not misinterpreted as new input.
+
+        Args:
+            length: Number of leading characters to strip (matches the trigger
+                length detected by `detect_mode_prefix`).
+        """
+        if not self._text_area:
+            return
+        if self._stripping_prefix:
+            logger.warning(
+                "Previous _stripping_prefix guard was never cleared; "
+                "resetting. This may indicate a missed text-change event."
+            )
+        text = self._text_area.text
+        if not text:
+            return
+        row, col = self._text_area.cursor_location
+        self._stripping_prefix = True
+        self._text_area.text = text[length:]
+        if row == 0 and col > 0:
+            col = max(0, col - length)
+        self._text_area.move_cursor((row, col))
+
+    def _completion_text_and_cursor(self) -> tuple[str, int]:
+        """Return controller-facing text/cursor in completion space.
+
+        Also updates `_completion_prefix_len` so that subsequent calls to
+        `_completion_index_to_text_index` use the matching offset.
+        """
+        if not self._text_area:
+            self._completion_prefix_len = 0
+            return "", 0
+
+        text = self._text_area.text
+        cursor = self._get_cursor_offset()
+        prefix = MODE_PREFIXES.get(self.mode, "")
+        self._completion_prefix_len = len(prefix)
+
+        if prefix:
+            return prefix + text, cursor + len(prefix)
+        return text, cursor
+
+    def _completion_index_to_text_index(self, index: int) -> int:
+        """Translate completion-space index into text-area index.
+
+        Args:
+            index: Cursor/index position in completion space.
+
+        Returns:
+            Clamped index in text-area space.
+        """
+        if not self._text_area:
+            return 0
+
+        if 0 <= index <= self._completion_prefix_len:
+            return 0
+
+        mapped = index - self._completion_prefix_len
+        text_len = len(self._text_area.text)
+        if mapped < 0 or mapped > text_len:
+            logger.warning(
+                "Completion index %d mapped to %d, outside [0, %d]; "
+                "clamping (prefix_len=%d, mode=%s)",
+                index,
+                mapped,
+                text_len,
+                self._completion_prefix_len,
+                self.mode,
+            )
+        return max(0, min(mapped, text_len))
+
+    def _handle_stale_slash_enter(self) -> bool:
+        """Refresh stale slash completions during an Enter-key race.
+
+        Returns:
+            `True` when Enter was handled by applying a single visible
+            suggestion or by showing multiple visible suggestions.
+        """
+        if self.mode != "command" or self._text_area is None:
+            return False
+
+        slash_controller = self._slash_controller
+        if slash_controller is None:
+            return False
+
+        if self._text_area._completion_active:
+            return False
+
+        text, cursor = self._completion_text_and_cursor()
+        if not text.startswith("/"):
+            return False
+
+        matches = slash_controller.name_prefix_matches(text, cursor)
+        if not matches:
+            return False
+
+        completion_manager = self._completion_manager
+        if completion_manager is None:
+            logger.warning(
+                "Slash controller is initialized without completion manager; "
+                "stale slash Enter cannot refresh completions."
+            )
+            return False
+
+        completion_manager.on_text_changed(text, cursor)
+        if len(matches) == 1:
+            slash_controller.apply_name_prefix_completion(matches[0], cursor)
+            self._submit_value(self._text_area.text.strip())
+            return True
+        return True
+
+    def _submit_value(self, value: str) -> None:
+        """Prepend mode prefix, save to history, post message, and reset input.
+
+        This is the single path for all submission flows so the prefix-prepend +
+        history + post + clear + mode-reset logic stays in one place.
+
+        Args:
+            value: The stripped text to submit (without mode prefix).
+        """
+        if not value:
+            return
+
+        if self._completion_manager:
+            self._completion_manager.reset()
+
+        # Expand collapsed paste placeholders back to their full content so the
+        # agent receives the original text, not the compact reference.
+        value = expand_paste_refs(value, self._pasted_contents)
+        value = self._replace_submitted_paths_with_images(value)
+
+        mode = self.mode
+        if mode == "normal":
+            detected = detect_mode_prefix(value)
+            if detected is not None:
+                _, mode = detected
+
+        # Prepend mode prefix so the app layer receives the original trigger
+        # form (e.g. "!ls", "/help"). The value may already contain the prefix
+        # when a completion controller wrote it back into the text area before
+        # the strip handler ran.
+        prefix = MODE_PREFIXES.get(mode, "")
+        if prefix and not value.startswith(prefix):
+            value = prefix + value
+
+        # Placeholder spans were captured against the raw draft; the transforms
+        # above (whitespace strip, paste expansion, path substitution, prefix)
+        # shifted offsets. Re-map spans onto the final submitted text so the
+        # adapter strips the correct display token from the model-facing message
+        # instead of a same-looking literal the user typed.
+        if self._text_area is not None and self._image_tracker is not None:
+            self._image_tracker.remap_spans_to_text(
+                value, previous_text=self._text_area.text
+            )
+
+        self._history.add(value)
+        self.post_message(self.Submitted(value, mode))
+
+        if self._text_area:
+            # Preserve submission-time attachments until adapter consumes them.
+            self._skip_media_sync_events += 1
+            self._text_area.clear_text()
+        # Clear only after submit. Ordinary edits are undoable, so removing
+        # backing content earlier can strand a restored placeholder.  The input
+        # and its paste map are emptied together here, so IDs can safely restart
+        # at 1 for the next message.
+        self._pasted_contents.clear()
+        self._next_paste_id = 1
+        self.mode = "normal"
+
+    def _sync_media_tracker_to_text(
+        self,
+        text: str,
+        *,
+        previous_text: str | None = None,
+        cursor_offset: int | None = None,
+    ) -> None:
+        """Keep tracked media aligned with placeholder tokens in input text.
+
+        Args:
+            text: Current text in the input area.
+            previous_text: Previous text in the input area.
+            cursor_offset: Current cursor offset in the input area.
+        """
+        if not self._image_tracker:
+            return
+        if self._skip_media_sync_events:
+            if self._skip_media_sync_events < 0:
+                logger.warning(
+                    "_skip_media_sync_events is negative (%d); resetting to 0",
+                    self._skip_media_sync_events,
+                )
+                self._skip_media_sync_events = 0
+            else:
+                self._skip_media_sync_events -= 1
+            return
+        self._image_tracker.sync_to_text(
+            text, previous_text=previous_text, cursor_offset=cursor_offset
+        )
+
+    def on_chat_text_area_typing(
+        self,
+        event: ChatTextArea.Typing,  # noqa: ARG002  # Textual event handler signature
+    ) -> None:
+        """Relay typing activity to the app as `ChatInput.Typing`."""
+        self.post_message(self.Typing())
+
+    def on_chat_text_area_submitted(self, event: ChatTextArea.Submitted) -> None:
+        """Handle text submission.
+
+        Always posts the Submitted event - the app layer decides whether to
+        process immediately or queue based on agent status.
+        """
+        self._submit_value(event.value)
+
+    def on_chat_text_area_history_previous(
+        self, event: ChatTextArea.HistoryPrevious
+    ) -> None:
+        """Handle history previous request."""
+        entry = self._history.get_previous(event.current_text, query=event.current_text)
+        if entry is not None and self._text_area:
+            mode, display_text = self._history_entry_mode_and_text(entry)
+            self.mode = mode
+            # Cursor at top so pressing up again continues backward through
+            # history without the user having to navigate to the first row.
+            self._text_area.set_text_from_history(display_text, cursor_at_end=False)
+        else:
+            # No matching older entry — surface the boundary so the user
+            # doesn't think their keypress was lost.
+            self.app.bell()
+
+    def on_chat_text_area_history_next(
+        self,
+        event: ChatTextArea.HistoryNext,  # noqa: ARG002  # Textual event handler signature
+    ) -> None:
+        """Handle history next request."""
+        entry = self._history.get_next()
+        if entry is not None and self._text_area:
+            mode, display_text = self._history_entry_mode_and_text(entry)
+            self.mode = mode
+            # Cursor at end so pressing down again continues forward through
+            # history.
+            self._text_area.set_text_from_history(display_text, cursor_at_end=True)
+        else:
+            self.app.bell()
+
+    def on_chat_text_area_pasted_paths(self, event: ChatTextArea.PastedPaths) -> None:
+        """Handle paste payloads that resolve to dropped file paths."""
+        if not self._text_area:
+            return
+
+        self._insert_pasted_paths(event.raw_text, event.paths)
+
+    def on_chat_text_area_pasted_text(self, event: ChatTextArea.PastedText) -> None:
+        """Handle large pastes by collapsing into a compact placeholder.
+
+        Stores the full text in `_pasted_contents` and inserts a
+        `[Pasted text #N +M lines]` placeholder into the text area instead
+        of the raw content, keeping the input box compact.
+
+        Args:
+            event: The `PastedText` message carrying the full pasted text.
+        """
+        if not self._text_area:
+            return
+        self._collapse_and_insert_paste(event.text)
+
+    def handle_external_paste(self, pasted: str) -> bool:
+        """Handle paste text from app-level routing when input is not focused.
+
+        When the text area is mounted, the paste is always consumed: file paths
+        are attached as images, large text is collapsed into a placeholder,
+        and remaining plain text is inserted directly.
+
+        Args:
+            pasted: Raw pasted text payload.
+
+        Returns:
+            `True` when the text area is mounted and the paste was inserted,
+                `False` if the widget is not yet composed.
+        """
+        if not self._text_area:
+            return False
+
+        parsed = self._parse_dropped_path_payload(pasted)
+        if parsed is not None:
+            self._insert_pasted_paths(pasted, parsed.paths)
+        elif self._collapse_pastes and _should_collapse_chat_paste(pasted):
+            self._collapse_and_insert_paste(pasted)
+        else:
+            self._text_area.insert(pasted)
+
+        self._text_area.focus()
+        return True
+
+    def _collapse_and_insert_paste(self, text: str) -> None:
+        """Store full paste content and insert a compact placeholder.
+
+        Pasting content identical to a visible already-collapsed placeholder
+        expands that placeholder back to the full text in place instead of
+        adding a second placeholder — a repeat paste is treated as a request to
+        see the content in full.
+
+        Args:
+            text: The full pasted text to collapse.
+        """
+        if not self._text_area:
+            logger.debug("Dropping collapsed paste: text area not mounted")
+            return
+        visible_ids = {
+            int(match.group(1))
+            for match in PASTE_PLACEHOLDER_PATTERN.finditer(self._text_area.text)
+        }
+        match_id = next(
+            (
+                pid
+                for pid, stored in self._pasted_contents.items()
+                if pid in visible_ids and stored.content == text
+            ),
+            None,
+        )
+        if match_id is not None and self._text_area.replace_placeholder_with_text(
+            match_id, text
+        ):
+            return
+        paste_id = self._next_paste_id
+        self._next_paste_id += 1
+        self._pasted_contents[paste_id] = PastedContent(content=text)
+        placeholder = format_paste_ref(paste_id, count_lines(text))
+        self._text_area.insert(placeholder)
+
+    def _apply_inline_dropped_path_replacement(self, text: str) -> bool:
+        """Replace full dropped-path payload text with image placeholders.
+
+        Some terminals insert drag-and-drop payloads as plain text rather than
+        dispatching a dedicated paste event. When the current text resolves to
+        one or more file paths and at least one path is an image, rewrite the
+        text inline to `[image N]` placeholders.
+
+        Args:
+            text: Current text area content.
+
+        Returns:
+            `True` if text was rewritten inline, otherwise `False`.
+        """
+        if not self._text_area:
+            return False
+
+        parsed = self._parse_dropped_path_payload(text)
+        if parsed is None:
+            return False
+
+        replacement, attached = self._build_path_replacement(
+            text, parsed.paths, add_trailing_space=True
+        )
+        if not attached or replacement == text:
+            return False
+
+        self._applying_inline_path_replacement = True
+        self._text_area.text = replacement
+        self._text_area.move_cursor_to_end()
+        return True
+
+    def _insert_pasted_paths(self, raw_text: str, paths: list[Path]) -> None:
+        """Insert pasted path payload, attaching images when possible.
+
+        Args:
+            raw_text: Original paste payload text.
+            paths: Resolved file paths parsed from the payload.
+        """
+        if not self._text_area:
+            return
+        replacement, attached = self._build_path_replacement(
+            raw_text, paths, add_trailing_space=True
+        )
+        if attached:
+            self._text_area.insert(replacement)
+            return
+        self._text_area.insert(raw_text)
+
+    def _build_path_replacement(
+        self,
+        raw_text: str,
+        paths: list[Path],
+        *,
+        add_trailing_space: bool,
+    ) -> tuple[str, bool]:
+        """Build replacement text for dropped paths and attach any images.
+
+        Args:
+            raw_text: Original paste payload text.
+            paths: Resolved file paths parsed from the payload.
+            add_trailing_space: Whether to append a trailing space after the
+                last token when paths are separated by spaces.
+
+        Returns:
+            Tuple of `(replacement, attached)` where `attached` indicates whether
+            at least one media attachment (image or video) was created.
+        """
+        if not self._image_tracker:
+            return raw_text, False
+
+        from deepagents_code.media_utils import (
+            IMAGE_EXTENSIONS,
+            MAX_MEDIA_BYTES,
+            VIDEO_EXTENSIONS,
+            ImageData,
+            get_media_from_path,
+        )
+
+        parts: list[str] = []
+        attached = False
+        for path in paths:
+            media = get_media_from_path(path)
+            if media is not None:
+                kind = "image" if isinstance(media, ImageData) else "video"
+                existing_text = self._text_area.text if self._text_area else raw_text
+                parts.append(
+                    self._image_tracker.add_media(
+                        media,
+                        kind,
+                        existing_text=existing_text,
+                    )
+                )
+                attached = True
+                continue
+
+            # Check if it looked like media but failed validation
+            suffix = path.suffix.lower()
+            if suffix in IMAGE_EXTENSIONS or suffix in VIDEO_EXTENSIONS:
+                label = "Video" if suffix in VIDEO_EXTENSIONS else "Image"
+                try:
+                    size = path.stat().st_size
+                    if size > MAX_MEDIA_BYTES:
+                        msg = (
+                            f"{label} too large: {path.name} "
+                            f"({size // (1024 * 1024)} MB, max "
+                            f"{MAX_MEDIA_BYTES // (1024 * 1024)} MB)"
+                        )
+                    else:
+                        msg = f"Could not attach {label.lower()}: {path.name}"
+                except OSError as exc:
+                    logger.debug("Failed to stat media file %s: %s", path, exc)
+                    msg = f"Could not attach {label.lower()}: {path.name}"
+                self.app.notify(msg, severity="warning", timeout=5, markup=False)
+
+            # Not a supported media file, keep as path
+            logger.debug("Could not load media from dropped path: %s", path)
+            parts.append(str(path))
+
+        if not attached:
+            return raw_text, False
+
+        separator = "\n" if "\n" in raw_text else " "
+        replacement = separator.join(parts)
+        if separator == " " and add_trailing_space:
+            replacement += " "
+        return replacement, True
+
+    def _replace_submitted_paths_with_images(self, value: str) -> str:
+        """Replace dropped-path payloads in submitted text with image placeholders.
+
+        Handles both full-path payloads and leading-path-with-suffix payloads
+        (for example, `'<path>' what is this?`). When command mode previously
+        stripped a leading slash, this method also retries with the slash
+        restored before giving up.
+
+        Args:
+            value: Stripped submitted text (without mode prefix).
+
+        Returns:
+            Submitted text with image placeholders when attachment succeeded.
+        """
+        candidate, parsed = self._parse_dropped_path_payload_with_command_recovery(
+            value, allow_leading_path=True
+        )
+        if parsed is None:
+            return value
+
+        if parsed.token_end is None:
+            replacement, attached = self._build_path_replacement(
+                candidate, parsed.paths, add_trailing_space=False
+            )
+            if attached:
+                return replacement.strip()
+            # Even when full-payload parsing resolves, still retry explicit
+            # leading-token extraction before giving up.
+            candidate, leading_match = (
+                self._extract_leading_dropped_path_with_command_recovery(value)
+            )
+            if leading_match is None:
+                return value
+            leading_path, token_end = leading_match
+        else:
+            leading_path = parsed.paths[0]
+            token_end = parsed.token_end
+
+        replacement, attached = self._build_path_replacement(
+            str(leading_path), [leading_path], add_trailing_space=False
+        )
+        if attached:
+            suffix = candidate[token_end:].lstrip()
+            if suffix:
+                return f"{replacement.strip()} {suffix}".strip()
+            return replacement.strip()
+        return value
+
+    @staticmethod
+    def _history_entry_mode_and_text(entry: str) -> tuple[str, str]:
+        """Return mode and stripped display text for a history entry.
+
+        Args:
+            entry: Raw entry value read from history storage.
+
+        Returns:
+            Tuple of `(mode, display_text)` where mode-trigger prefixes are
+                removed from `display_text`.
+        """
+        if mode_match := detect_mode_prefix(entry):
+            prefix, mode = mode_match
+            return mode, entry[len(prefix) :]
+        return "normal", entry
+
+    async def on_key(self, event: events.Key) -> None:
+        """Handle key events for completion navigation."""
+        if not self._completion_manager or not self._text_area:
+            return
+
+        # Backspace at the start of a mode prompt exits the current mode. Prefix
+        # characters are mode selectors, not hidden draft text, so exiting the
+        # mode does not restore `/`, `!`, or `!!` into the input.
+        if (
+            event.key == "backspace"
+            and self.mode != "normal"
+            and self._get_cursor_offset() == 0
+            and not self._text_area.text
+        ):
+            # Schedule the popup reset alongside the prompt/style update so both
+            # visual changes land before the next paint.
+            def _deferred_reset() -> None:
+                if self._completion_manager is not None:
+                    self._completion_manager.reset()
+
+            self.call_next(_deferred_reset)
+            self.mode = "normal"
+            event.prevent_default()
+            event.stop()
+            return
+
+        text, cursor = self._completion_text_and_cursor()
+        result = self._completion_manager.on_key(event, text, cursor)
+
+        match result:
+            case CompletionResult.HANDLED:
+                event.prevent_default()
+                event.stop()
+            case CompletionResult.SUBMIT:
+                event.prevent_default()
+                event.stop()
+                self._submit_value(self._text_area.text.strip())
+            case CompletionResult.IGNORED if event.key == "space":
+                # Space was intercepted (prevent_default) so the active
+                # controller could attempt completion. The controller
+                # declined (e.g. file completion), so insert the space that
+                # TextArea would have inserted normally.
+                self._text_area.insert(" ")
+            case CompletionResult.IGNORED if event.key == "enter":
+                # Handle Enter when completion is not active (shell/normal modes)
+                value = self._text_area.text.strip()
+                if value:
+                    event.prevent_default()
+                    event.stop()
+                    self._submit_value(value)
+
+    def _get_cursor_offset(self) -> int:
+        """Get the cursor offset as a single integer.
+
+        Returns:
+            Cursor position as character offset from start of text.
+        """
+        if not self._text_area:
+            return 0
+
+        text = self._text_area.text
+        row, col = self._text_area.cursor_location
+
+        if not text:
+            return 0
+
+        lines = text.split("\n")
+        row = max(0, min(row, len(lines) - 1))
+        col = max(0, col)
+
+        offset = sum(len(lines[i]) + 1 for i in range(row))
+        return offset + min(col, len(lines[row]))
+
+    def watch_mode(self, mode: str) -> None:
+        """Post mode changed message and update prompt indicator.
+
+        The prompt glyph update is scheduled for the next message-loop turn so
+        callers which also schedule popup work can coalesce both visual changes
+        before the next paint.
+        """
+        # Keep inline argument hints in sync for mode-only transitions
+        # (for example, exiting command mode via Escape or backspace).
+        self._update_argument_hint()
+
+        glyph = MODE_DISPLAY_GLYPHS.get(mode)
+        if not glyph and mode != "normal":
+            logger.warning(
+                "No display glyph for mode %r; falling back to '>'",
+                mode,
+            )
+
+        def _apply() -> None:
+            self.remove_class("mode-shell", "mode-command", "mode-shell-incognito")
+            if glyph:
+                class_name = (
+                    "mode-shell-incognito"
+                    if mode == "shell_incognito"
+                    else f"mode-{mode}"
+                )
+                self.add_class(class_name)
+            try:
+                prompt = self.query_one("#prompt", Static)
+            except NoMatches:
+                logger.warning("watch_mode._apply: prompt widget not found")
+                if mode == "shell_incognito":
+                    # Privacy-sensitive: surface a visible warning so the user
+                    # never types an incognito command without confirmation
+                    # that the mode is active.
+                    app = getattr(self, "app", None)
+                    if app is not None:
+                        with contextlib.suppress(Exception):
+                            app.notify(
+                                "Incognito mode UI failed to render; "
+                                "switching back to normal input.",
+                                severity="warning",
+                                markup=False,
+                            )
+                    self.mode = "normal"
+                return
+            prompt.update(glyph or ">")
+            if self._input_box is not None:
+                self._input_box.border_title = (
+                    "incognito" if mode == "shell_incognito" else None
+                )
+
+        self.call_next(_apply)
+        self.post_message(self.ModeChanged(mode))
+
+    def focus_input(self) -> None:
+        """Focus the input field."""
+        if self._text_area:
+            self._text_area.focus()
+
+    @property
+    def value(self) -> str:
+        """Current input value.
+
+        Returns:
+            Current text in the input field.
+        """
+        if self._text_area:
+            return self._text_area.text
+        return ""
+
+    @value.setter
+    def value(self, val: str) -> None:
+        """Set the input value."""
+        if self._text_area:
+            self._text_area.text = val
+
+    def set_value_at_end(self, val: str) -> bool:
+        """Set the input value and place the cursor at the end of the text.
+
+        Returns:
+            `True` when the value was written, `False` when the text area is
+            unavailable and the value could not be set. Callers that surface a
+            "restored"/"moved to input" toast should gate it on this so the
+            toast never claims a write that did not happen.
+        """
+        if not self._text_area:
+            return False
+        self._text_area.text = val
+        self._text_area.move_cursor_to_end()
+        return True
+
+    def discard_text(self) -> bool:
+        """Clear the draft, keeping it restorable via undo (ctrl+z).
+
+        Returns:
+            `True` when there was text to clear.
+        """
+        if self._text_area is None:
+            return False
+        if self._text_area.text:
+            self._skip_media_sync_events += 1
+        return self._text_area.discard_text()
+
+    def on_input_action_button_clicked(self, event: InputActionButton.Clicked) -> None:
+        """Handle clicks on the `[ X ]` / `[ COPY ]` input buttons."""
+        event.stop()
+        if event.action == "clear":
+            self._clear_via_button()
+        elif event.action == "copy":
+            self._copy_via_button()
+        else:
+            assert_never(event.action)
+
+    def _clear_via_button(self) -> None:
+        """Clear the draft from the `[ X ]` button (undoable with ctrl+z).
+
+        Also exits any active slash/shell mode, unlike the Esc-driven clear.
+        """
+        cleared = self.discard_text()
+        self.exit_mode()
+        if cleared:
+            self.app.notify("Input cleared (ctrl+z to undo)", timeout=3, markup=False)
+        if self._text_area is not None:
+            self._text_area.focus()
+
+    def _copy_via_button(self) -> None:
+        """Copy the current draft to the clipboard from the `[ COPY ]` button."""
+        from deepagents_code.clipboard import copy_text_with_feedback
+
+        text = expand_paste_refs(self.value, self._pasted_contents)
+        if text:
+            copy_text_with_feedback(
+                self.app,
+                text,
+                failure_noun="input",
+                success_message="Input copied to clipboard",
+            )
+        # Refocus the input so clicking the button never strands focus on the
+        # (non-focusable) button.
+        if self._text_area is not None:
+            self._text_area.focus()
+
+    @property
+    def input_widget(self) -> ChatTextArea | None:
+        """Underlying `TextArea` widget.
+
+        Returns:
+            The `ChatTextArea` widget or `None` if not mounted.
+        """
+        return self._text_area
+
+    def set_disabled(self, *, disabled: bool) -> None:
+        """Enable or disable the input widget."""
+        if self._text_area:
+            self._text_area.disabled = disabled
+            if disabled:
+                self._text_area.blur()
+                if self._completion_manager:
+                    self._completion_manager.reset()
+
+    def set_cursor_active(self, *, active: bool) -> None:
+        """Toggle input focus state (e.g., unfocus while agent is working).
+
+        Args:
+            active: Whether the input should be focused and accepting input.
+        """
+        if self._text_area:
+            self._text_area.set_app_focus(has_focus=active)
+
+    def set_cursor_style(self, *, style: CursorStyle) -> None:
+        """Set the input cursor's visual style.
+
+        Args:
+            style: Whether to render a block or underlined character cell.
+        """
+        if self._text_area is not None:
+            self._text_area.set_class(style == "underline", "cursor-underline")
+
+    def set_cursor_blink(self, *, blink: bool) -> None:
+        """Toggle the input's cursor blink without changing focus.
+
+        Args:
+            blink: Whether the cursor should blink.
+        """
+        if self._text_area is not None:
+            self._text_area.cursor_blink = blink
+
+    def _notify_app_blur(self) -> None:
+        """Tell the text area the terminal window lost OS focus."""
+        if self._text_area is not None:
+            self._text_area._notify_app_blur()
+
+    def _notify_app_focus(self) -> None:
+        """Tell the text area the terminal window regained OS focus."""
+        if self._text_area is not None:
+            self._text_area._notify_app_focus()
+
+    def exit_mode(self) -> bool:
+        """Exit the current input mode (command/shell) back to normal.
+
+        Returns:
+            True if mode was non-normal and has been reset.
+        """
+        if self.mode == "normal":
+            return False
+        self.mode = "normal"
+        if self._completion_manager:
+            self._completion_manager.reset()
+        self.clear_completion_suggestions()
+        return True
+
+    def dismiss_completion(self) -> bool:
+        """Dismiss completion: clear view and reset controller state.
+
+        Returns:
+            True if completion was active and has been dismissed.
+        """
+        if not self._current_suggestions:
+            return False
+        if self._completion_manager:
+            self._completion_manager.reset()
+        # Always clear local state so the popup is hidden even if the
+        # manager's active controller was already None (no-op reset).
+        self.clear_completion_suggestions()
+        return True
+
+    # =========================================================================
+    # CompletionView protocol implementation
+    # =========================================================================
+
+    def render_completion_suggestions(
+        self, suggestions: list[tuple[str, str]], selected_index: int
+    ) -> None:
+        """Render completion suggestions in the popup."""
+        prev_suggestions = self._current_suggestions
+        self._current_suggestions = suggestions
+        self._current_selected_index = selected_index
+
+        if self._popup:
+            # If only the selection changed (same items), skip full rebuild
+            if suggestions == prev_suggestions:
+                self._popup.update_selection(selected_index)
+            else:
+                self._popup.update_suggestions(suggestions, selected_index)
+        # Tell TextArea that completion is active so it yields navigation keys
+        if self._text_area:
+            self._text_area.set_completion_active(active=bool(suggestions))
+
+    def clear_completion_suggestions(self) -> None:
+        """Clear/hide the completion popup."""
+        self._current_suggestions = []
+        self._current_selected_index = 0
+
+        if self._popup:
+            self._popup.hide()
+        # Tell TextArea that completion is no longer active
+        if self._text_area:
+            self._text_area.set_completion_active(active=False)
+
+    def on_completion_popup_option_clicked(
+        self, event: CompletionPopup.OptionClicked
+    ) -> None:
+        """Handle click on a completion option."""
+        if not self._current_suggestions or not self._text_area:
+            return
+
+        index = event.index
+        if index < 0 or index >= len(self._current_suggestions):
+            return
+
+        # Get the selected completion
+        label, _ = self._current_suggestions[index]
+        text = self._text_area.text
+        cursor = self._get_cursor_offset()
+
+        # Determine replacement range based on completion type.
+        # Slash completions use completion-space coordinates and are translated
+        # through the completion view adapter.
+        if label.startswith("/"):
+            if self._completion_view is None:
+                logger.warning(
+                    "Slash completion clicked but _completion_view is not "
+                    "initialized; this indicates a widget lifecycle issue."
+                )
+                return
+            _, virtual_cursor = self._completion_text_and_cursor()
+            self._completion_view.replace_completion_range(0, virtual_cursor, label)
+        elif label.startswith("@"):
+            # File mention: replace from @ to cursor
+            at_index = text[:cursor].rfind("@")
+            if at_index >= 0:
+                self.replace_completion_range(at_index, cursor, label)
+
+        # Reset completion state
+        if self._completion_manager:
+            self._completion_manager.reset()
+
+        # Re-focus the text input after click
+        self._text_area.focus()
+
+    def replace_completion_range(self, start: int, end: int, replacement: str) -> None:
+        """Replace text in the input field."""
+        if not self._text_area:
+            return
+
+        text = self._text_area.text
+
+        start = max(0, min(start, len(text)))
+        end = max(start, min(end, len(text)))
+
+        prefix = text[:start]
+        suffix = text[end:]
+
+        # Add space after completion unless it's a directory path
+        if replacement.endswith("/"):
+            insertion = replacement
+        else:
+            insertion = replacement + " " if not suffix.startswith(" ") else replacement
+
+        new_text = f"{prefix}{insertion}{suffix}"
+        self._text_area.text = new_text
+
+        # Calculate new cursor position and move cursor
+        new_offset = start + len(insertion)
+        lines = new_text.split("\n")
+        remaining = new_offset
+        for row, line in enumerate(lines):
+            if remaining <= len(line):
+                self._text_area.move_cursor((row, remaining))
+                break
+            remaining -= len(line) + 1
+
+        # Completion selections should render their final inline hint
+        # immediately, without waiting for the subsequent Changed event.
+        self._update_argument_hint()