feat: add sol engage subcommand for agent delegation with --wait support

sol.py

···
     "cortex": "think.cortex",
     "muse": "think.muse_cli",
     "call": "think.call",
+    "engage": "think.engage",
     "help": "think.help_cli",
     "chat": "think.chat_cli",
     "heartbeat": "think.heartbeat",
···
         "cortex",
         "muse",
         "call",
+        "engage",
     ],
     "Convey (web UI)": [
         "convey",

tests/test_cogitate_coder.py

···
 
         assert result.exit_code == 0
         assert "1710864123456" in result.output
-        mock_cortex.assert_called_once_with(prompt="Fix the bug", name="coder")
+        mock_cortex.assert_called_once_with(
+            prompt="Fix the bug", name="coder", config=None
+        )
 
     def test_handoff_empty_stdin(self):
         """Empty stdin produces error and exit code 1."""

tests/test_engage.py

···
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+"""Tests for the engage CLI command."""
+
+import importlib
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def _engage_app():
+    mod = importlib.reload(importlib.import_module("think.engage"))
+    return mod.engage_app
+
+
+def _invoke_engage(*args, input_text=""):
+    return runner.invoke(_engage_app(), [*args], input=input_text)
+
+
+def _call_app():
+    call_mod = importlib.reload(importlib.import_module("think.call"))
+    return call_mod.call_app
+
+
+class TestEngage:
+    def test_fire_and_forget(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ) as mock_cr:
+            result = _invoke_engage("coder", input_text="fix the bug\n")
+
+        assert result.exit_code == 0
+        assert "agent-123" in result.output
+        mock_cr.assert_called_once_with(
+            prompt="fix the bug", name="coder", config=None
+        )
+
+    def test_empty_stdin(self):
+        result = _invoke_engage("coder", input_text="")
+
+        assert result.exit_code == 1
+        assert (
+            "no prompt" in result.output.lower()
+            or "no prompt" in (result.stderr or "").lower()
+        )
+
+    def test_cortex_failure(self):
+        with patch("think.cortex_client.cortex_request", return_value=None):
+            result = _invoke_engage("coder", input_text="fix the bug\n")
+
+        assert result.exit_code == 1
+
+    def test_wait_success(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ), patch(
+            "think.cortex_client.wait_for_agents",
+            return_value=({"agent-123": "finish"}, []),
+        ), patch(
+            "think.cortex_client.read_agent_events",
+            return_value=[{"event": "finish", "result": "All fixed!"}],
+        ):
+            result = _invoke_engage("coder", "--wait", input_text="fix the bug\n")
+
+        assert result.exit_code == 0
+        assert "All fixed!" in result.output
+
+    def test_wait_error(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ), patch(
+            "think.cortex_client.wait_for_agents",
+            return_value=({"agent-123": "error"}, []),
+        ):
+            result = _invoke_engage("coder", "--wait", input_text="fix the bug\n")
+
+        assert result.exit_code == 1
+
+    def test_wait_timeout(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ), patch(
+            "think.cortex_client.wait_for_agents",
+            return_value=({}, ["agent-123"]),
+        ):
+            result = _invoke_engage("coder", "--wait", input_text="fix the bug\n")
+
+        assert result.exit_code == 1
+        combined_output = result.output
+        if result.stderr:
+            combined_output += result.stderr
+        assert "timed out" in combined_output.lower()
+
+    def test_facet_and_day(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ) as mock_cr:
+            result = _invoke_engage(
+                "coder",
+                "--facet",
+                "work",
+                "--day",
+                "20260404",
+                input_text="do stuff\n",
+            )
+
+        assert result.exit_code == 0
+        mock_cr.assert_called_once_with(
+            prompt="do stuff",
+            name="coder",
+            config={"facet": "work", "day": "20260404"},
+        )
+
+    def test_facet_only(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ) as mock_cr:
+            result = _invoke_engage(
+                "coder", "--facet", "work", input_text="do stuff\n"
+            )
+
+        assert result.exit_code == 0
+        mock_cr.assert_called_once_with(
+            prompt="do stuff", name="coder", config={"facet": "work"}
+        )
+
+    def test_day_only(self):
+        with patch(
+            "think.cortex_client.cortex_request", return_value="agent-123"
+        ) as mock_cr:
+            result = _invoke_engage(
+                "coder", "--day", "20260404", input_text="do stuff\n"
+            )
+
+        assert result.exit_code == 0
+        mock_cr.assert_called_once_with(
+            prompt="do stuff", name="coder", config={"day": "20260404"}
+        )
+
+
+class TestHandoffDeprecated:
+    def test_handoff_still_works(self):
+        with patch("think.cortex_client.cortex_request", return_value="agent-123"):
+            result = runner.invoke(_call_app(), ["handoff", "coder"], input="fix the bug\n")
+
+        assert result.exit_code == 0
+        assert "agent-123" in result.output
+
+    def test_handoff_hidden(self):
+        result = runner.invoke(_call_app(), ["--help"])
+
+        assert "handoff" not in result.output

tests/test_handoff.py

···
         result = _invoke_handoff("coder", input_text="fix the bug\n")
     assert result.exit_code == 0
     assert "agent-123" in result.output
-    mock_cr.assert_called_once_with(prompt="fix the bug", name="coder")
+    mock_cr.assert_called_once_with(prompt="fix the bug", name="coder", config=None)
 
 
 def _assert_handoff_empty_stdin():

think/call.py

···
     typer.echo(f"Navigate: {' '.join(parts)}")
 
 
-@call_app.command("handoff")
+@call_app.command("handoff", hidden=True)
 def handoff(
     agent: str = typer.Argument(help="Agent name to hand off to (e.g. coder)."),
 ) -> None:
-    """Spawn a cogitate agent with a request from stdin (fire-and-forget).
-
-    Reads a prompt from stdin, sends it to cortex as an agent request,
-    prints the agent_id to stdout, and exits immediately.
-
-    Example::
-
-        echo 'Fix the matching bug' | sol call handoff coder
-    """
+    """Spawn a cogitate agent with a request from stdin (fire-and-forget)."""
     prompt = sys.stdin.read()
     if not prompt.strip():
         typer.echo("Error: no prompt provided on stdin.", err=True)
         raise typer.Exit(1)
 
-    from think.cortex_client import cortex_request
-
-    agent_id = cortex_request(prompt=prompt.strip(), name=agent)
-    if agent_id is None:
-        typer.echo("Error: failed to send cortex request.", err=True)
-        raise typer.Exit(1)
+    from think.engage import _engage
 
-    typer.echo(agent_id)
+    _engage(agent, prompt.strip())
 
 
 def main() -> None:

think/engage.py

···
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+"""CLI for delegating work to cogitate agents.
+
+Provides ``sol engage <name>`` as the primary agent delegation command,
+replacing ``sol call handoff`` with richer options.
+"""
+
+import sys
+
+import typer
+
+engage_app = typer.Typer(name="engage")
+
+
+def _engage(
+    name: str,
+    prompt: str,
+    *,
+    wait: bool = False,
+    facet: str | None = None,
+    day: str | None = None,
+) -> None:
+    config_data = {}
+    if facet is not None:
+        config_data["facet"] = facet
+    if day is not None:
+        config_data["day"] = day
+    config = config_data or None
+
+    from think.cortex_client import cortex_request
+
+    agent_id = cortex_request(prompt=prompt, name=name, config=config)
+    if agent_id is None:
+        typer.echo("Error: failed to send cortex request.", err=True)
+        raise typer.Exit(1)
+
+    if not wait:
+        typer.echo(agent_id)
+        return
+
+    from think.cortex_client import read_agent_events, wait_for_agents
+
+    completed, timed_out = wait_for_agents([agent_id])
+    if agent_id in timed_out:
+        typer.echo("Error: agent timed out.", err=True)
+        raise typer.Exit(1)
+
+    end_state = completed.get(agent_id, "error")
+    if end_state != "finish":
+        typer.echo(f"Error: agent ended with state: {end_state}", err=True)
+        raise typer.Exit(1)
+
+    events = read_agent_events(agent_id)
+    result = ""
+    for event in reversed(events):
+        if event.get("event") == "finish":
+            result = event.get("result", "")
+            break
+
+    typer.echo(result)
+
+
+@engage_app.command()
+def engage(
+    name: str = typer.Argument(help="Agent name to delegate to (e.g. coder)."),
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        help="Block until the agent completes and print its result.",
+    ),
+    facet: str | None = typer.Option(
+        None, "--facet", help="Facet context for the agent."
+    ),
+    day: str | None = typer.Option(
+        None, "--day", help="Day context for the agent (e.g. 20260404)."
+    ),
+) -> None:
+    """Delegate work to a cogitate agent.
+
+    Reads a prompt from stdin, sends it to cortex as an agent request.
+    By default, prints the agent_id and exits immediately (fire-and-forget).
+
+    Example::
+
+        echo 'Fix the matching bug' | sol engage coder
+        echo 'Fix the matching bug' | sol engage coder --wait
+    """
+    prompt = sys.stdin.read()
+    if not prompt.strip():
+        typer.echo("Error: no prompt provided on stdin.", err=True)
+        raise typer.Exit(1)
+
+    _engage(name, prompt.strip(), wait=wait, facet=facet, day=day)
+
+
+def main() -> None:
+    """Entry point for ``sol engage``."""
+    engage_app()