feat(cli/tui): -q now seeds a live interactive session; prompts submit literally

On a real TTY, `hermes chat -q "…"` (and `--tui -q`) now starts a normal
interactive session with the prompt submitted literally as the first turn —
no slash-command routing, no '!' shell dispatch, no $(...) interpolation,
no file-drop rewriting — matching how other coding agents handle seeded
launches (Omarchy prompted agent terminals, omacom/omarchy#8705).

Legacy answer-and-exit is preserved everywhere automation depends on it:
- new `hermes chat --oneshot` flag (distinct dest from top-level -z)
- -Q/--quiet machine-readable contract
- any non-TTY stdio (kanban workers, cron, pipes, A2A)
- top-level `hermes -z` unchanged

CLI: seeded prompt rides a _SeededQueryMessage sentinel through
process_loop, which skips the slash/!/file-drop dispatchers for that one
message. TUI: STARTUP_QUERY submits via a new literal path (submitLiteral)
that bypasses dispatchSubmission and the input.detect_drop rewrite.

Author: teknium1

cli.py

@@ -4998,14 +4998,66 @@ def __str__(self) -> str:
         return self.text
 
 
+class _SeededQueryMessage:
+    """Sentinel wrapper for a ``-q/--query`` prompt seeded into an
+    interactive session.
+
+    When ``hermes chat -q "…"`` runs on a real TTY, the query is submitted as
+    the first turn of a normal interactive session instead of the legacy
+    answer-and-exit single-query mode. The prompt is arbitrary user text (an
+    OS launcher, a desktop integration, a script) — it must be treated
+    LITERALLY: no slash-command routing, no ``!`` shell dispatch, no
+    file-drop detection. This sentinel marks the seeded first message so
+    ``process_loop`` skips those dispatchers for it (and only it).
+    """
+
+    __slots__ = ("text", "images")
+
+    def __init__(self, text: str, images=None):
+        self.text = text or ""
+        self.images = list(images or [])
+
+    def __str__(self) -> str:
+        return self.text
+
+
+def _should_seed_interactive(query, image, quiet: bool, oneshot: bool) -> bool:
+    """Whether a ``-q/--image`` invocation should seed an interactive session.
+
+    New default (Aug 2026): on a real TTY, ``chat -q`` submits the prompt as
+    the first turn of a normal interactive session (parity with other coding
+    agents' seeded launches — e.g. Omarchy's prompted agent terminals).
+
+    The legacy answer-and-exit behavior is preserved for every automation
+    surface:
+      - ``--oneshot`` on the chat subcommand (explicit legacy opt-in)
+      - ``-Q/--quiet`` (machine-readable single-query contract)
+      - any non-TTY stdin/stdout (kanban workers, cron, pipes, A2A)
+    ``-z/--oneshot`` at the top level never reaches this path at all.
+    """
+    if not (query or image):
+        return False
+    if oneshot or quiet:
+        return False
+    try:
+        return bool(sys.stdin.isatty() and sys.stdout.isatty())
+    except Exception:
+        return False
+
+
 class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
     """
     Interactive CLI for the Hermes Agent.
 
     Provides a REPL interface with rich formatting, command history,
     and tool execution capabilities.
     """
-    
+
+    # Seeded -q handoff from main() → run() (see _should_seed_interactive):
+    # run() re-creates _pending_input, so the seeded first message rides in
+    # on this attribute and is enqueued after the fresh queue exists.
+    _seeded_first_message: Optional["_SeededQueryMessage"] = None
+
     def __init__(
         self,
         model: str = None,
@@ -17741,6 +17793,13 @@ def _prewarm_agent_runtime() -> None:
         self._agent_running = False
         self._pending_input = queue.Queue()     # For normal input (commands + new queries)
         self._interrupt_queue = queue.Queue()   # For messages typed while agent is running
+        # Seeded -q handoff: main() can't put directly into _pending_input
+        # (this reinit would discard it), so the seeded first message rides
+        # in on an attribute and is enqueued into the fresh queue here.
+        _seed_msg = getattr(self, "_seeded_first_message", None)
+        if _seed_msg is not None:
+            self._seeded_first_message = None
+            self._pending_input.put(_seed_msg)
         # See constructor note. Mirrored here for the run() path that skips
         # the earlier __init__ branch.
         self._last_turn_interrupted = False
@@ -20376,6 +20435,19 @@ def process_loop():
                     if is_voice_input:
                         user_input = user_input.text
 
+                    # Seeded -q prompts arrive wrapped in _SeededQueryMessage:
+                    # arbitrary launcher/script text that must be submitted
+                    # LITERALLY — skip slash routing, ! shell dispatch, and
+                    # file-drop detection for this one message.
+                    is_seeded_query = isinstance(user_input, _SeededQueryMessage)
+                    if is_seeded_query:
+                        seeded = user_input
+                        user_input = (
+                            (seeded.text, seeded.images)
+                            if seeded.images
+                            else seeded.text
+                        )
+
                     if not user_input:
                         continue
 
@@ -20403,8 +20475,13 @@ def process_loop():
                         continue
 
                     # Check for commands — but detect dragged/pasted file paths first.
-                    # See _detect_file_drop() for details.
-                    _file_drop = _detect_file_drop(user_input) if isinstance(user_input, str) else None
+                    # See _detect_file_drop() for details. Seeded -q prompts are
+                    # literal text: no file-drop detection, no !/slash dispatch.
+                    _file_drop = (
+                        _detect_file_drop(user_input)
+                        if isinstance(user_input, str) and not is_seeded_query
+                        else None
+                    )
                     if _file_drop:
                         _drop_path = _file_drop["path"]
                         _remainder = _file_drop["remainder"]
@@ -20436,12 +20513,18 @@ def process_loop():
                     # turn is spent. See handle_bang_shell().
                     if (
                         not _file_drop
+                        and not is_seeded_query
                         and isinstance(user_input, str)
                         and self.handle_bang_shell(user_input)
                     ):
                         continue
 
-                    if not _file_drop and isinstance(user_input, str) and _looks_like_slash_command(user_input):
+                    if (
+                        not _file_drop
+                        and not is_seeded_query
+                        and isinstance(user_input, str)
+                        and _looks_like_slash_command(user_input)
+                    ):
                         _cprint(f"\n⚙️  {user_input}")
                         try:
                             if not self.process_command(user_input):
@@ -21045,6 +21128,7 @@ def _block(reason: str) -> None:
 def main(
     query: str = None,
     q: str = None,
+    oneshot: bool = False,
     image: str = None,
     toolsets: str = None,
     skills: str | list[str] | tuple[str, ...] = None,
@@ -21073,8 +21157,12 @@ def main(
     Hermes Agent CLI - Interactive AI Assistant
 
     Args:
-        query: Single query to execute (then exit). Alias: -q
+        query: Query to run. On a real TTY this seeds an interactive session
+            (submitted literally as the first turn); with --oneshot/-Q or a
+            non-TTY it answers and exits. Alias: -q
         q: Shorthand for --query
+        oneshot: With -q: force the legacy answer-and-exit single-query mode
+            even on a TTY.
         image: Optional local image path to attach to a single query
         toolsets: Comma-separated list of toolsets to enable (e.g., "web,terminal")
         skills: Comma-separated or repeated list of skills to preload for the session
@@ -21404,6 +21492,21 @@ def _signal_handler_q(signum, frame):
 
     # Handle single query mode
     if query or image:
+        # NEW DEFAULT (Aug 2026): on a real TTY, a -q/--image invocation
+        # seeds a normal interactive session with the prompt as the first
+        # turn, submitted LITERALLY (no slash/! dispatch). Legacy
+        # answer-and-exit behavior is kept for --oneshot, -Q, and every
+        # non-TTY invocation (kanban/cron/pipes) — see
+        # _should_seed_interactive().
+        if _should_seed_interactive(query, image, quiet, oneshot):
+            seeded_query, seeded_images = _collect_query_images(query, image)
+            logger.info(
+                "Seeding interactive session with -q prompt (%d chars, %d images)",
+                len(seeded_query or ""), len(seeded_images),
+            )
+            cli._seeded_first_message = _SeededQueryMessage(seeded_query, seeded_images)
+            cli.run()
+            return
         # One-shot mode: no between-turns MCP late-binding refresh, so the
         # agent must wait the full MCP cold-start bound before its first
         # (and only) tool snapshot. See #51316.

hermes_cli/_parser.py

@@ -351,7 +351,12 @@ def build_top_level_parser():
     )
     _query_group = chat_parser.add_mutually_exclusive_group()
     _query_group.add_argument(
-        "-q", "--query", help="Single query (non-interactive mode)"
+        "-q", "--query",
+        help=(
+            "Query to run. On a real TTY the prompt seeds an interactive "
+            "session (submitted literally as the first turn); combined with "
+            "--oneshot or -Q, or on a non-TTY, it answers and exits."
+        ),
     )
     _query_group.add_argument(
         "--query-file",
@@ -363,6 +368,21 @@ def build_top_level_parser():
             "verbatim. Mutually exclusive with -q."
         ),
     )
+    chat_parser.add_argument(
+        "--oneshot",
+        dest="oneshot_exit",
+        action="store_true",
+        # Distinct dest: the top-level `-z/--oneshot PROMPT` is value-taking
+        # and its dispatch sites do `if args.oneshot: _run_and_exit_oneshot(
+        # args.oneshot)` — a shared boolean dest would be passed as the
+        # prompt. `oneshot_exit` keeps the surfaces independent.
+        default=False,
+        help=(
+            "With -q/--query-file: answer the query and exit (legacy "
+            "single-query behavior) instead of seeding an interactive "
+            "session. Implied on non-TTY stdio and by -Q/--quiet."
+        ),
+    )
     chat_parser.add_argument(
         "--image", help="Optional local image path to attach to a single query"
     )

hermes_cli/main.py

@@ -3437,6 +3437,7 @@ def _skills_sync_bg() -> None:
         "verbose": getattr(args, "verbose", None),
         "quiet": getattr(args, "quiet", False),
         "query": args.query,
+        "oneshot": bool(getattr(args, "oneshot_exit", False)),
         "image": getattr(args, "image", None),
         "resume": getattr(args, "resume", None),
         "worktree": getattr(args, "worktree", False),

tests/hermes_cli/test_seeded_interactive_query.py

@@ -0,0 +1,124 @@
+"""Seeded interactive ``-q`` behavior (Aug 2026).
+
+On a real TTY, ``hermes chat -q "…"`` seeds a normal interactive session with
+the prompt submitted literally as the first turn. Legacy answer-and-exit is
+preserved for ``--oneshot``, ``-Q/--quiet``, and every non-TTY invocation
+(kanban workers, cron, pipes, A2A). The seeded prompt bypasses slash-command
+routing, ``!`` shell dispatch, and file-drop detection.
+
+Context: Omarchy prompted-agent launches (basecamp/omarchy#8705) needed a
+"start interactive, seeded with this prompt" mode with literal prompt
+handling, like other coding agents.
+"""
+
+import sys
+import types
+
+import pytest
+
+
+@pytest.fixture()
+def cli_mod():
+    import cli
+
+    return cli
+
+
+class TestShouldSeedInteractive:
+    def _tty(self, monkeypatch, cli_mod, stdin=True, stdout=True):
+        monkeypatch.setattr(
+            cli_mod.sys, "stdin", types.SimpleNamespace(isatty=lambda: stdin)
+        )
+        monkeypatch.setattr(
+            cli_mod.sys, "stdout", types.SimpleNamespace(isatty=lambda: stdout)
+        )
+
+    def test_tty_query_seeds_interactive(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod)
+        assert cli_mod._should_seed_interactive("hi", None, quiet=False, oneshot=False)
+
+    def test_image_only_also_seeds(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod)
+        assert cli_mod._should_seed_interactive(
+            None, "/tmp/x.png", quiet=False, oneshot=False
+        )
+
+    def test_oneshot_flag_forces_legacy(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod)
+        assert not cli_mod._should_seed_interactive(
+            "hi", None, quiet=False, oneshot=True
+        )
+
+    def test_quiet_forces_legacy(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod)
+        assert not cli_mod._should_seed_interactive(
+            "hi", None, quiet=True, oneshot=False
+        )
+
+    def test_non_tty_stdin_forces_legacy(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod, stdin=False)
+        assert not cli_mod._should_seed_interactive(
+            "hi", None, quiet=False, oneshot=False
+        )
+
+    def test_non_tty_stdout_forces_legacy(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod, stdout=False)
+        assert not cli_mod._should_seed_interactive(
+            "hi", None, quiet=False, oneshot=False
+        )
+
+    def test_no_query_no_image_never_seeds(self, monkeypatch, cli_mod):
+        self._tty(monkeypatch, cli_mod)
+        assert not cli_mod._should_seed_interactive(
+            None, None, quiet=False, oneshot=False
+        )
+
+    def test_isatty_failure_forces_legacy(self, monkeypatch, cli_mod):
+        def _boom():
+            raise OSError("no tty")
+
+        monkeypatch.setattr(
+            cli_mod.sys, "stdin", types.SimpleNamespace(isatty=_boom)
+        )
+        assert not cli_mod._should_seed_interactive(
+            "hi", None, quiet=False, oneshot=False
+        )
+
+
+class TestSeededQueryMessage:
+    def test_str_returns_text(self, cli_mod):
+        msg = cli_mod._SeededQueryMessage("!echo pwned")
+        assert str(msg) == "!echo pwned"
+        assert msg.images == []
+
+    def test_images_are_copied(self, cli_mod):
+        imgs = ["/tmp/a.png"]
+        msg = cli_mod._SeededQueryMessage("hi", imgs)
+        assert msg.images == imgs
+        assert msg.images is not imgs
+
+
+class TestChatParserOneshotFlag:
+    """The chat subcommand's --oneshot must not collide with top-level -z."""
+
+    def _parse(self, argv):
+        from hermes_cli._parser import build_top_level_parser
+
+        parser, _subparsers, _chat = build_top_level_parser()
+        return parser.parse_args(argv)
+
+    def test_chat_oneshot_sets_distinct_dest(self):
+        args = self._parse(["chat", "-q", "hello", "--oneshot"])
+        assert args.oneshot_exit is True
+        # Top-level -z prompt dest untouched — dispatch sites check
+        # `args.oneshot` truthiness and would treat True as a prompt.
+        assert getattr(args, "oneshot", None) in (None, False)
+
+    def test_chat_without_oneshot_defaults_false(self):
+        args = self._parse(["chat", "-q", "hello"])
+        assert args.oneshot_exit is False
+
+    def test_top_level_oneshot_prompt_unaffected(self):
+        args = self._parse(["-z", "what is up"])
+        assert args.oneshot == "what is up"
+        assert getattr(args, "oneshot_exit", False) is False

ui-tui/src/__tests__/submissionCore.test.ts

@@ -110,6 +110,45 @@ describe('submissionCore.submitPrompt — synchronous busy (queue-race fix)', ()
   })
 })
 
+describe('submissionCore.submitPrompt — literal submissions (startup -q queries)', () => {
+  beforeEach(() => {
+    resetUiState()
+    patchUiState({ sid: 'sess-1' })
+  })
+
+  it('skipDetectDrop submits directly without the detect_drop round-trip', async () => {
+    const { calls, gw } = makeDeferredGateway()
+
+    submitPrompt('!echo not-a-shell-escape', makeDeps(gw), true, undefined, { skipDetectDrop: true })
+
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(calls).not.toContain('input.detect_drop')
+    expect(calls).toContain('prompt.submit')
+  })
+
+  it('literal text reaches prompt.submit verbatim', async () => {
+    const submitted: string[] = []
+    const gw = {
+      request: vi.fn((method: string, params?: { text?: string }) => {
+        if (method === 'prompt.submit' && params?.text) {
+          submitted.push(params.text)
+        }
+
+        return Promise.resolve({ status: 'streaming' })
+      })
+    } as unknown as GatewayClient
+
+    submitPrompt('/model $(rm -rf ~)', makeDeps(gw), true, undefined, { skipDetectDrop: true })
+
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(submitted).toEqual(['/model $(rm -rf ~)'])
+  })
+})
+
 describe('submissionCore.markSubmitting', () => {
   beforeEach(() => resetUiState())