✨ feat: collaboration substrate for RubyLLM multi-agent runs

[pftg]

What this is

RubyLLM::Team coordinates several RubyLLM agents through one auditable run: named
artifact handoffs, a shared call budget, safe fan-out, and a trace showing the exact prompt
every agent received.

It is a small library, not a framework — 658 lines, one runtime dependency, and your workflow
stays ordinary Ruby.

Why you would install it

You do not need it for one agent, or two in a straight line. You start needing it when several
agents share work and you have to answer "which version did the editor actually review?" and
"why did this run cost 40 calls?"

Hand-rolled	Provided
A result hash plus rules for which version is current	Named artifact versions, as: / from: handoffs
A counter so one runaway loop cannot bill you forever	One atomic budget, bounded by default
Thread.new per agent and a join that swallows a failure	Fan-out that settles every sibling before raising
rescue => e in six shapes	One CollaborationError, typed BudgetExceededError
A logger you grep afterwards	A trace with the verbatim prompt per call

Review guide

Four commits, smallest surface first:

1. 93c3b67 library + packaging — the whole public API. Start at lib/ruby_llm/team.rb.
2. 76d4190 specs — what a reader cannot verify by inspection: budget reservation across
   threads, artifact ordering under out-of-order completion, crash handling on both
   schedulers, re-entrancy, handoff forgery.
3. fa65680 examples — read examples/code_review/ first (110 lines, exercises the whole
   library). examples/blog/ is production-scale and deliberately the largest.
4. 32ed0ea docs — docs/DECISIONS.md is the fastest way to judge scope: it carries the
   measurement behind every refusal, and a known-weaknesses section.

Correctness worth a second look

Each of these was reproduced before it was fixed, not inferred:

• Artifact versions are reserved at submission under the session lock, so artifact(name)
  is deterministic when parallel work completes out of order.
• Re-entrancy protection was absent on the path every example uses — a class-registered
  coworker delegating into itself recursed 51 levels deep. Now a property of the role,
  tracked fiber-locally so concurrent same-role work stays legal.
• Handoffs were forgeable: results were relayed under a fixed literal header, so a coworker
  (or a fetched web page speaking through one) could fabricate a handoff from a coworker that
  never ran. Each result now carries a per-session random fence.
• max_calls is bounded by default. Every framework that loops on paid calls ships a cap;
  this one claimed spend-bounding as its headline while shipping unbounded.

Deliberately not here

No graph DSL, YAML workflows, or role/backstory metaphors. No memory, RAG, MCP, or search. No
dashboards or persistence — ruby_llm-agents owns that Rails layer and Team composes inside
it. Quality loops stay in application Ruby: refine/repair were built, measured, and removed
because upstream teaches the same loop in fewer lines and only one domain ever needed them.

Verification

• 98 examples, 0 failures; RuboCop clean; Ruby 3.1–4.0 in CI
• Three VCR cassettes replay in CI with no API key
• gem build produces exactly 7 files (lib, README, CHANGELOG, LICENSE)
• All five examples run; the live ones were exercised against real providers during development

Known weaknesses

Recorded in docs/DECISIONS.md rather than left for a reviewer to find: a budget bounds
delegation hops rather than provider spend (ruby_llm has no internal tool-call cap);
exhaustion raises on the Ruby path but returns a hash on the tool path; mutual recursion across
threads defeats the re-entrancy guard; run-total token usage sums across models; and the blog
example is larger than the code it saves.

The API is pre-1.0 and moved late — artifact ordering, error types, trace serialization, and
the read-side accessors all changed shortly before this branch settled.