feat(subagents): show the agent a persona roster so delegation is informed

Selection stays user-led — omitting `persona` runs the subagent as the
caller itself (the chat's bound persona). For the specialist case the
agent no longer guesses a name blindly:

- _personae_roster_block injects a compact `name — role` roster of
  available personae into the main turn preamble, gated to when
  spawn_subagent is actually in scope (subagents enabled + the persona's
  tool allowlist permits it). Off for subagent sub-loops (offer_personae
  defaults False), so it never leaks where it can't be used.
- The "Persona not found" error now lists the valid names, so a wrong
  guess self-corrects.

Tests cover the name/role rendering (first role line only), the current-
persona "(you)" tag, the disabled / out-of-scope gates, main-turn-only
injection, and the name-listing error.

Author: mattmezza

core/agent.py

@@ -635,6 +635,7 @@ async def process(
             scope=_persona_scope(persona),
             persona=persona,
             session_key=session_key,
+            offer_personae=True,
         )
         # Append the status of still-running background subagents from this chat,
         # so the agent always knows what is pending (their results are folded into
@@ -760,6 +761,7 @@ async def _turn_preamble(
         scope: str = "",
         persona: Persona | None = None,
         session_key: tuple[str, str, str] | None = None,
+        offer_personae: bool = False,
     ) -> str:
         """Build the per-turn preamble prepended to the current user message.
 
@@ -821,6 +823,14 @@ async def _turn_preamble(
         except Exception:
             log.exception("Failed to load memories for turn preamble")
 
+        # Roster of personae the agent can delegate to via spawn_subagent, so its
+        # choice is informed rather than guessed (#15). Only on the main turn —
+        # selection stays user-led (omit persona = run as yourself / the bound one).
+        if offer_personae:
+            roster = await self._personae_roster_block(persona)
+            if roster:
+                preamble += f"\n\n{roster}"
+
         if self.config.task_reflection.enabled:
             try:
                 reflections = await self.reflections.format_for_prompt()
@@ -840,6 +850,41 @@ async def _turn_preamble(
             )
         return preamble
 
+    async def _personae_roster_block(self, persona: Persona | None) -> str:
+        """Compact `name — role` roster of personae the agent can delegate to (#15).
+
+        Makes specialist delegation an informed choice instead of a guess, while
+        leaving selection user-led: omitting ``persona`` runs the subagent as the
+        caller itself. Returns "" (nothing injected) when subagents are disabled,
+        the active persona can't spawn, or there is no one to delegate to.
+        """
+        if not self.config.subagents.enabled:
+            return ""
+        if persona is not None and not persona.allows_tool("spawn_subagent"):
+            return ""
+        try:
+            personae = await self.personae.list_personae()
+        except Exception:
+            log.exception("Failed to list personae for the subagent roster")
+            return ""
+        current = persona.name if persona else ""
+        lines = []
+        for p in personae:
+            role = p.role.strip().splitlines()[0].strip() if (p.role or "").strip() else ""
+            tag = " (you)" if p.name == current else ""
+            lines.append(f"- {p.name}{tag}" + (f" — {role}" if role else ""))
+        if not lines:
+            return ""
+        body = "\n".join(lines)
+        return (
+            "<personae>\n"
+            "Personae you may run a subagent as via spawn_subagent's 'persona'. "
+            "Omit 'persona' to run as yourself (the default) — name one only when "
+            "the subtask clearly fits that specialist.\n"
+            f"{body}\n"
+            "</personae>"
+        )
+
     async def _skills_block_in_history(self, session_key: tuple[str, str, str], block: str) -> bool:
         """True if the exact ``<available_skills>`` block is already present in the
         replayed session history — so the model still sees it and we needn't
@@ -1938,7 +1983,17 @@ async def run_subagent(
         if persona_name:
             requested = await self._load_persona(persona_name)
             if requested is None:
-                return {"error": f"Persona not found: {persona_name}"}
+                try:
+                    names = [p.name for p in await self.personae.list_personae()]
+                except Exception:
+                    names = []
+                hint = f" Available: {', '.join(names)}." if names else ""
+                return {
+                    "error": (
+                        f"Persona not found: {persona_name}.{hint} "
+                        "Omit 'persona' to run as yourself."
+                    )
+                }
         else:
             requested = parent_state.get("persona_obj")
         child_persona = self._narrow_persona(requested, parent_state) if requested else None

docs/content/docs/subagents.mdx

@@ -93,6 +93,15 @@ and a scoped caller delegating to an open persona keeps its own limits.
 [Permission rules](/docs/permissions) (`NEVER` in particular) still apply inside
 the subagent, so a blocked action stays blocked at any depth.
 
+## Choosing a persona
+
+Selection stays **user-led**: omitting `persona` runs the subagent as the caller
+itself (the chat's bound persona), so a subtask stays in the identity the user
+already chose. To make the *specialist* case an informed choice rather than a
+guess, each turn the agent sees a compact roster of available personae
+(`name — role`) and only names one when the subtask clearly fits it. A wrong
+name is rejected with the list of valid names, so the agent can self-correct.
+
 ## Guardrails
 
 Sensible defaults keep delegation safe and bounded. Edit them in the admin

tests/test_subagents.py

@@ -506,3 +506,61 @@ def spy(provider, level=""):
     assert result["ok"] is True
     assert captured["level"] == "high"
     assert agent.subagents.get(result["run_id"]).effort == "high"
+
+
+# ---------------------------------------------------------------------------
+# Persona roster — let the agent pick a specialist, selection stays user-led
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_personae_roster_lists_name_and_role(agent, monkeypatch) -> None:
+    personae = [
+        Persona(name="coding-helper", role="Writes and reviews code"),
+        Persona(name="writing-editor", role="Edits prose\nsecond line ignored"),
+    ]
+    monkeypatch.setattr(agent.personae, "list_personae", AsyncMock(return_value=personae))
+    block = await agent._personae_roster_block(None)
+    assert "<personae>" in block
+    assert "- coding-helper — Writes and reviews code" in block
+    assert "- writing-editor — Edits prose" in block  # only the first role line
+    assert "second line ignored" not in block
+
+
+@pytest.mark.asyncio
+async def test_personae_roster_marks_current_and_gates(agent, monkeypatch) -> None:
+    personae = [Persona(name="me", role="r1"), Persona(name="other", role="r2")]
+    monkeypatch.setattr(agent.personae, "list_personae", AsyncMock(return_value=personae))
+    block = await agent._personae_roster_block(Persona(name="me", role="r1"))
+    assert "- me (you) — r1" in block
+    # a persona whose tool scope excludes spawn_subagent gets no roster
+    scoped = Persona(name="me", tools=["web_search"])
+    assert await agent._personae_roster_block(scoped) == ""
+    # nor when subagents are disabled
+    agent.config.subagents.enabled = False
+    assert await agent._personae_roster_block(None) == ""
+
+
+@pytest.mark.asyncio
+async def test_personae_roster_only_offered_on_main_turn(agent, monkeypatch) -> None:
+    monkeypatch.setattr(
+        agent.personae,
+        "list_personae",
+        AsyncMock(return_value=[Persona(name="coding-helper", role="code")]),
+    )
+    # subagent preamble (offer_personae defaults False) → no roster leaks in
+    assert "<personae>" not in await agent._turn_preamble(None, query="x")
+    # main turn opts in
+    assert "<personae>" in await agent._turn_preamble(None, query="x", offer_personae=True)
+
+
+@pytest.mark.asyncio
+async def test_run_subagent_unknown_persona_lists_available(agent, monkeypatch) -> None:
+    monkeypatch.setattr(
+        agent.personae,
+        "list_personae",
+        AsyncMock(return_value=[Persona(name="coding-helper"), Persona(name="analyst")]),
+    )
+    result = await agent.run_subagent(task="x", persona_name="nope")
+    assert "not found" in result["error"].lower()
+    assert "coding-helper" in result["error"] and "analyst" in result["error"]