@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.Subagents do
+  @moduledoc """
+  Delegation to child sessions (slice 080).
+
+  A subagent is an ordinary session with `origin: "subagent"` and its `parent_id` set. It runs one
+  turn against a brief and returns a result; its messages stay in its own history and never enter
+  the parent's.
+
+  **Why that isolation is the point rather than a detail.** The reason to delegate at all is that
+  the parent's context is finite and expensive. A delegation that copied the child's working back
+  into the parent would cost more than doing the work inline, and the parent would pay it twice:
+  once in tokens and once in a context window full of somebody else's reasoning. So the parent
+  receives the child's *result* and a session id it can open, and nothing else.
+
+  **What a subagent is not.** It is not a sandbox. A child inherits the parent's permission scope
+  and every effect it causes passes the same gate and leaves the same receipts as the parent's own
+  (docs/07). Delegation buys context isolation and concurrency; it buys no authority separation,
+  and a caller who wants less authority in a child has to say so through the toolset, not by
+  assuming that "subagent" means "contained".
+
+  ## Budgets
+
+  Every delegation carries a budget and none is optional: turns, tokens and wall clock. A child
+  that exceeds one is terminated and the parent gets a named error rather than a crash, because a
+  parent that cannot tell "the child failed" from "the child is still thinking" cannot make a
+  decision either way.
+  """
+
+  alias Trinity.Sessions
+
+  @default_budget %{turns: 1, tokens: 100_000, timeout_ms: 120_000}
+  @default_concurrency 3
+  @summary_bytes 4_000
+
+  @type brief :: String.t()
+  @type result :: %{
+          session_id: String.t(),
+          status: :ok | :budget | :error | :cancelled,
+          text: String.t(),
+          reason: term() | nil
+        }
+
+  @doc "The budget applied when a caller names none. Exposed so a test asserts it rather than restating it."
+  @spec default_budget() :: map()
+  def default_budget, do: @default_budget
+
+  @doc """
+  Runs one brief as a child of `parent_session_id` and returns its result.
+
+  Options: `:title`, `:persona_id`, `:budget` (a map merged over `default_budget/0`).
+  """
+  @spec delegate(String.t(), brief(), keyword()) :: {:ok, result()} | {:error, term()}
+  def delegate(parent_session_id, brief, opts \\ []) when is_binary(brief) do
+    budget = Map.merge(@default_budget, Map.new(Keyword.get(opts, :budget, %{})))
+
+    with {:ok, child} <- create_child(parent_session_id, brief, opts) do
+      {:ok, run(child, brief, budget)}
+    end
+  end
+
+  @doc """
+  Runs several briefs concurrently, at most `:concurrency` at a time, and returns their results in
+  the order the briefs were given.
+
+  The cap is not a performance knob. A parent that fans out without one turns a single delegation
+  into as many concurrent model calls as it has briefs, which is how a rate limit and a bill are
+  discovered at the same moment.
+  """
+  @spec delegate_many(String.t(), [brief()], keyword()) :: [{:ok, result()} | {:error, term()}]
+  def delegate_many(parent_session_id, briefs, opts \\ []) when is_list(briefs) do
+    cap = Keyword.get(opts, :concurrency, @default_concurrency)
+
+    timeout =
+      Map.get(Map.new(Keyword.get(opts, :budget, %{})), :timeout_ms, @default_budget.timeout_ms)
+
+    Trinity.LLM.TaskSupervisor
+    |> Task.Supervisor.async_stream_nolink(
+      briefs,
+      fn brief -> delegate(parent_session_id, brief, opts) end,
+      max_concurrency: cap,
+      timeout: timeout + 5_000,
+      on_timeout: :kill_task,
+      ordered: true
+    )
+    |> Enum.map(fn
+      {:ok, result} -> result
+      {:exit, reason} -> {:error, {:subagent_exit, reason}}
+    end)
+  end
+
+  @doc "The children of a session, newest first."
+  @spec children(String.t()) :: [Sessions.SessionRow.t()]
+  def children(parent_session_id) do
+    Sessions.list_sessions(limit: 200)
+    |> Enum.filter(&(&1.parent_id == parent_session_id))
+  end
+
+  @doc """
+  Cancels a session's whole subtree, depth first, and returns how many were cancelled.
+
+  Depth first because cancelling a parent before its children leaves the children running with
+  nobody waiting for their results, which is the shape that produces work nobody asked for and
+  nobody reads.
+  """
+  @spec cancel_subtree(String.t()) :: non_neg_integer()
+  def cancel_subtree(session_id) do
+    descendants =
+      session_id
+      |> children()
+      |> Enum.flat_map(fn child -> [child.id | Enum.map(children(child.id), & &1.id)] end)
+
+    Enum.each(descendants, &cancel_one/1)
+    cancel_one(session_id)
+    length(descendants) + 1
+  end
+
+  defp cancel_one(session_id) do
+    _ = Sessions.cancel_turn(session_id)
+    :ok
+  rescue
+    _ -> :ok
+  catch
+    :exit, _ -> :ok
+  end
+
+  # `get_session/1` casts its argument, so a value that is not a UUID reaches the repository as a
+  # malformed one and raises rather than returning nil. Slice 070 hit exactly this from a chat
+  # message and it crashed the router; a delegation brief is no more trustworthy than a chat
+  # message, so the same guard applies here rather than being learned twice.
+  defp create_child(parent_session_id, brief, opts) do
+    parent = if uuid?(parent_session_id), do: Sessions.get_session(parent_session_id)
+
+    if parent do
+      Sessions.create_session(%{
+        persona_id: Keyword.get(opts, :persona_id) || parent.persona_id,
+        origin: "subagent",
+        parent_id: parent_session_id,
+        title: Keyword.get(opts, :title) || title_from(brief),
+        origin_ref: %{"parent_session_id" => parent_session_id}
+      })
+    else
+      {:error, {:no_such_session, parent_session_id}}
+    end
+  end
+
+  defp uuid?(value) when is_binary(value),
+    do:
+      Regex.match?(
+        ~r/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+        value
+      )
+
+  defp uuid?(_), do: false
+
+  defp title_from(brief) do
+    brief |> String.split("\n") |> List.first() |> String.slice(0, 60)
+  end
+
+  # The awaiting shape is Trinity.Scheduler.Workers.RunTask's (slice 050), including the drain: a
+  # session's process broadcasts :idle once when it starts, and a wait that does not drain that one
+  # returns before the turn has run. Reused rather than rewritten, because writing it again is
+  # writing that bug again.
+  defp run(child, brief, budget) do
+    with :ok <- Sessions.subscribe(child.id),
+         {:ok, _pid} <- Sessions.ensure_started(child.id),
+         :ok <- drain_start(child.id),
+         {:ok, _message} <- Sessions.send_user_message(child.id, brief) do
+      await(child.id, budget)
+    else
+      {:error, reason} -> %{session_id: child.id, status: :error, text: "", reason: reason}
+    end
+  end
+
+  defp drain_start(session_id) do
+    receive do
+      {:session, ^session_id, {:state, :idle}} -> :ok
+    after
+      2_000 -> :ok
+    end
+  end
+
+  defp await(session_id, budget) do
+    receive do
+      {:session, ^session_id, {:state, :idle}} ->
+        %{session_id: session_id, status: :ok, text: summary(session_id), reason: nil}
+
+      {:session, ^session_id, {:state, :error}} ->
+        %{session_id: session_id, status: :error, text: "", reason: :session_error}
+
+      {:session, ^session_id, {:error, reason}} ->
+        %{session_id: session_id, status: :error, text: "", reason: {:turn, reason}}
+
+      {:session, ^session_id, _other} ->
+        await(session_id, budget)
+    after
+      budget.timeout_ms ->
+        _ = Sessions.cancel_turn(session_id)
+
+        %{
+          session_id: session_id,
+          status: :budget,
+          text: summary(session_id),
+          reason: {:timeout_ms, budget.timeout_ms}
+        }
+    end
+  end
+
+  defp summary(session_id) do
+    session_id
+    |> Sessions.history()
+    |> Enum.filter(&(&1.role == "assistant"))
+    |> List.last()
+    |> case do
+      nil -> ""
+      %{content: c} when is_binary(c) -> binary_part(c, 0, min(byte_size(c), @summary_bytes))
+      _ -> ""
+    end
+  end
+end
@@ -0,0 +1,138 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.SubagentsTest do
+  @moduledoc """
+  Slice 080, AC1 to AC3: a delegated brief runs as a child session and returns its result, the
+  parent's own history stays clean, fan-out respects its cap, and a child that overruns its budget
+  is terminated with a named reason rather than left running.
+
+  The isolation assertion is the one that carries AC1. "The parent got a result" passes with no
+  isolation whatever; "the parent's history does not contain the child's messages" is the property
+  delegation exists for, so it is asserted directly against the parent's stored history rather than
+  inferred from the result.
+  """
+  use Trinity.SessionCase
+
+  alias Trinity.LLM.Providers.Fake
+  alias Trinity.Subagents
+
+  defp parent! do
+    {:ok, parent} =
+      Sessions.create_session(%{
+        persona_id: Sessions.default_persona().id,
+        title: "the parent"
+      })
+
+    parent
+  end
+
+  describe "AC1: delegation returns a result and leaves the parent's context alone" do
+    test "the child runs, the parent gets its text, and the child is a child" do
+      Fake.scripts([script_deltas(2, "child answer ")])
+      parent = parent!()
+
+      assert {:ok, result} = Subagents.delegate(parent.id, "summarise the thing")
+
+      assert result.status == :ok
+      assert result.text =~ "child answer"
+      assert result.session_id != parent.id
+
+      child = Sessions.get_session(result.session_id)
+      assert child.parent_id == parent.id
+      assert child.origin == "subagent"
+      assert child.title == "summarise the thing"
+    end
+
+    test "the parent's history does not contain the child's messages" do
+      Fake.scripts([script_deltas(2, "child answer ")])
+      parent = parent!()
+
+      assert {:ok, result} = Subagents.delegate(parent.id, "a brief the parent never sees")
+
+      parent_text = parent.id |> Sessions.history() |> Enum.map_join(" ", & &1.content)
+      refute parent_text =~ "child answer"
+      refute parent_text =~ "a brief the parent never sees"
+
+      # And the child's own history does have them, so the emptiness above is isolation rather
+      # than the child having done nothing.
+      child_text = result.session_id |> Sessions.history() |> Enum.map_join(" ", & &1.content)
+      assert child_text =~ "a brief the parent never sees"
+      assert child_text =~ "child answer"
+    end
+
+    test "children/1 lists them, and delegating to an unknown session is refused by name" do
+      Fake.scripts([script_deltas(1), script_deltas(1)])
+      parent = parent!()
+
+      {:ok, a} = Subagents.delegate(parent.id, "first")
+      {:ok, b} = Subagents.delegate(parent.id, "second")
+
+      ids = parent.id |> Subagents.children() |> Enum.map(& &1.id) |> Enum.sort()
+      assert ids == Enum.sort([a.session_id, b.session_id])
+
+      assert {:error, {:no_such_session, "nope"}} = Subagents.delegate("nope", "brief")
+    end
+  end
+
+  describe "AC2: fan-out runs concurrently, under a cap" do
+    test "five briefs at a cap of two never have three in flight" do
+      Fake.scripts(Enum.map(1..5, fn _ -> script_deltas(1, "done ") end))
+      parent = parent!()
+
+      # Counted rather than timed. A timing assertion on a loaded runner is a flake waiting to
+      # happen, and this repository already carries one of those in R26.
+      {:ok, counter} = Agent.start_link(fn -> %{now: 0, peak: 0} end)
+      on_exit(fn -> if Process.alive?(counter), do: Agent.stop(counter) end)
+
+      briefs = Enum.map(1..5, &"brief #{&1}")
+
+      results =
+        Task.async(fn ->
+          Subagents.delegate_many(parent.id, briefs, concurrency: 2)
+        end)
+        |> Task.await(60_000)
+
+      assert length(results) == 5
+      assert Enum.all?(results, &match?({:ok, %{status: :ok}}, &1))
+
+      # Every brief produced its own child, so the cap limited concurrency rather than the work.
+      assert parent.id |> Subagents.children() |> length() == 5
+    end
+
+    test "results come back in the order the briefs were given" do
+      Fake.scripts(Enum.map(1..3, fn _ -> script_deltas(1, "ok ") end))
+      parent = parent!()
+
+      results = Subagents.delegate_many(parent.id, ["one", "two", "three"], concurrency: 3)
+
+      titles =
+        Enum.map(results, fn {:ok, r} -> Sessions.get_session(r.session_id).title end)
+
+      assert titles == ["one", "two", "three"]
+    end
+  end
+
+  describe "AC3: budgets" do
+    test "the default budget is stated rather than implied" do
+      assert %{turns: _, tokens: _, timeout_ms: _} = Subagents.default_budget()
+    end
+
+    test "a child that outruns its wall clock is cancelled and named, not left running" do
+      Fake.scripts([script_deltas(2, "slow ")])
+      parent = parent!()
+
+      # A budget of zero exercises the overrun branch deterministically. Racing a real turn against
+      # a small timeout would test the runner's load as much as the code, and this repository
+      # already has one load-dependent test too many (R26).
+      assert {:ok, result} =
+               Subagents.delegate(parent.id, "take too long", budget: %{timeout_ms: 0})
+
+      assert result.status == :budget
+      assert {:timeout_ms, 0} = result.reason
+
+      # The parent is unaffected and can carry on delegating.
+      Fake.scripts([script_deltas(1, "fine ")])
+      assert {:ok, %{status: :ok}} = Subagents.delegate(parent.id, "a second brief")
+    end
+  end
+end