@moxxy/plugin-subagents 0.26.0

package/src/dispatch-agent.test.ts

@@ -0,0 +1,344 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool, type SubagentResult, type SubagentSpawner, type ToolContext } from '@moxxy/sdk';
+import { FakeProvider, createFakeSession, textReply, toolUseReply } from '@moxxy/testing';
+import { defaultModePlugin } from '@moxxy/mode-default';
+import { collectTurn } from '@moxxy/core';
+import { buildDispatchAgentTool } from './dispatch-agent.js';
+
+const dispatchAgentTool = buildDispatchAgentTool({ getAgent: () => undefined });
+
+type DispatchResults = { results: ReadonlyArray<Record<string, unknown>> };
+
+/** Minimal ToolContext carrying only the spawner the handler reads. */
+function ctxWith(spawner: SubagentSpawner): ToolContext {
+  return { subagents: spawner } as unknown as ToolContext;
+}
+
+describe('subagents — basic spawning', () => {
+  it('spawns a child that runs a tool and returns its text', async () => {
+    // The parent immediately dispatches one child agent.
+    const provider = new FakeProvider({
+      script: [
+        // Parent's only message — kick off the child.
+        toolUseReply(
+          'dispatch_agent',
+          {
+            agents: [
+              {
+                prompt: 'Read /etc/config and report its version',
+                label: 'reader',
+              },
+            ],
+          },
+          'p1',
+        ),
+        // Child's iteration 1: call Read.
+        toolUseReply('Read', { file_path: '/etc/config' }, 'c1'),
+        // Child's iteration 2: summarize.
+        textReply('Version is 1.2.3'),
+        // Parent's iteration 2: end turn with summary.
+        textReply('reader reported: Version is 1.2.3'),
+      ],
+    });
+    const session = createFakeSession({ provider });
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.modes.setActive('default');
+    session.tools.register(
+      defineTool({
+        name: 'Read',
+        description: 'read file',
+        inputSchema: z.object({ file_path: z.string() }),
+        handler: () => 'version=1.2.3',
+      }),
+    );
+    // Register the dispatch_agent tool so the parent can invoke it.
+    session.tools.register(dispatchAgentTool);
+
+    const events = await collectTurn(session, 'use a sub-agent to fetch the version');
+
+    // Parent log should carry subagent_started + subagent_completed envelopes.
+    const started = events.find(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_started',
+    );
+    expect(started).toBeDefined();
+    if (started?.type === 'plugin_event') {
+      const payload = started.payload as { label: string; mode: string };
+      expect(payload.label).toBe('reader');
+      expect(payload.mode).toBe('default');
+    }
+
+    const completed = events.find(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_completed',
+    );
+    expect(completed).toBeDefined();
+    if (completed?.type === 'plugin_event') {
+      const payload = completed.payload as { label: string; text: string };
+      expect(payload.label).toBe('reader');
+      expect(payload.text).toContain('1.2.3');
+    }
+  });
+
+  it('streams child tool calls to the parent in real time', async () => {
+    const provider = new FakeProvider({
+      script: [
+        toolUseReply(
+          'dispatch_agent',
+          { agents: [{ prompt: 'Read a file', label: 'a' }] },
+          'p1',
+        ),
+        // Child iteration: tool call + text wrap.
+        toolUseReply('Read', { file_path: '/x' }, 'c1'),
+        textReply('done'),
+        // Parent wrap-up.
+        textReply('child finished'),
+      ],
+    });
+    const session = createFakeSession({ provider });
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.modes.setActive('default');
+    session.tools.register(
+      defineTool({
+        name: 'Read',
+        description: 'read',
+        inputSchema: z.object({ file_path: z.string() }),
+        handler: () => 'contents',
+      }),
+    );
+    session.tools.register(dispatchAgentTool);
+
+    const events = await collectTurn(session, 'fan out');
+
+    // We expect at least one subagent_tool_call event mirroring the child's Read invocation.
+    const childToolCall = events.find(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_tool_call',
+    );
+    expect(childToolCall).toBeDefined();
+    if (childToolCall?.type === 'plugin_event') {
+      const payload = childToolCall.payload as { name: string; label: string };
+      expect(payload.name).toBe('Read');
+      expect(payload.label).toBe('a');
+    }
+
+    // And a tool_result mirror.
+    const childToolResult = events.find(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_tool_result',
+    );
+    expect(childToolResult).toBeDefined();
+  });
+
+  it('spawnAll runs multiple children and returns results in input order', async () => {
+    // 3 children, each replies once. Parent kicks them off in one dispatch_agent call.
+    const provider = new FakeProvider({
+      script: [
+        toolUseReply(
+          'dispatch_agent',
+          {
+            agents: [
+              { prompt: 'task 1', label: 'one' },
+              { prompt: 'task 2', label: 'two' },
+              { prompt: 'task 3', label: 'three' },
+            ],
+          },
+          'p1',
+        ),
+        // The FakeProvider replies to requests in script order; with 3 parallel
+        // children all making their first request roughly together, the order is
+        // deterministic-enough for this test: each child gets a textReply ending its turn.
+        textReply('done 1'),
+        textReply('done 2'),
+        textReply('done 3'),
+        textReply('all done'),
+      ],
+    });
+    const session = createFakeSession({ provider });
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.modes.setActive('default');
+    session.tools.register(dispatchAgentTool);
+
+    const events = await collectTurn(session, 'spawn three');
+
+    const completed = events.filter(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_completed',
+    );
+    expect(completed).toHaveLength(3);
+    const labels = completed
+      .map((e) => (e.type === 'plugin_event' ? (e.payload as { label: string }).label : ''))
+      .sort();
+    expect(labels).toEqual(['one', 'three', 'two']);
+  });
+});
+
+describe('subagents — model override validation', () => {
+  it('falls back to the parent model (with a warning) on a hallucinated model id', async () => {
+    const provider = new FakeProvider({
+      script: [
+        toolUseReply(
+          'dispatch_agent',
+          // Training-era id the calling LLM tends to invent.
+          { agents: [{ prompt: 'task', label: 'kid', model: 'claude-3-5-sonnet' }] },
+          'p1',
+        ),
+        textReply('child done'),
+        textReply('parent done'),
+      ],
+    });
+    const session = createFakeSession({ provider });
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.modes.setActive('default');
+    session.tools.register(dispatchAgentTool);
+
+    const events = await collectTurn(session, 'spawn with a bogus model');
+
+    const warning = events.find(
+      (e) => e.type === 'plugin_event' && e.subtype === 'subagent_warning',
+    );
+    expect(warning).toBeDefined();
+    if (warning?.type === 'plugin_event') {
+      expect((warning.payload as { message: string }).message).toBe(
+        'unknown model "claude-3-5-sonnet" — falling back to parent model "fake-model"',
+      );
+    }
+    // Request order: parent iteration 1, child, parent wrap-up. The child's
+    // provider request must carry the parent's model, not the invented one.
+    expect(provider.received[1]?.model).toBe('fake-model');
+  });
+
+  it('honors a model override the provider actually lists', async () => {
+    const models = [
+      { id: 'fake-model', contextWindow: 200_000 },
+      { id: 'cheap-model', contextWindow: 200_000 },
+    ];
+    const provider = new FakeProvider({
+      models,
+      script: [
+        toolUseReply(
+          'dispatch_agent',
+          { agents: [{ prompt: 'task', label: 'kid', model: 'cheap-model' }] },
+          'p1',
+        ),
+        textReply('child done'),
+        textReply('parent done'),
+      ],
+    });
+    const session = createFakeSession({ provider });
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.modes.setActive('default');
+    session.tools.register(dispatchAgentTool);
+
+    const events = await collectTurn(session, 'spawn cheap');
+
+    expect(
+      events.find((e) => e.type === 'plugin_event' && e.subtype === 'subagent_warning'),
+    ).toBeUndefined();
+    expect(provider.received[1]?.model).toBe('cheap-model');
+  });
+});
+
+describe('subagents — fan-out failure containment', () => {
+  it('degrades a spawnAll rejection to per-child error results instead of crashing the tool', async () => {
+    // The core spawner uses Promise.all; a single child's setup throw rejects
+    // the whole batch and discards siblings. The tool must not propagate that
+    // raw rejection to the loop — it should hand back one error per spec.
+    const spawner: SubagentSpawner = {
+      spawn: async (): Promise<SubagentResult> => {
+        throw new Error('should not be called');
+      },
+      spawnAll: async () => {
+        throw new Error('provider lookup failed');
+      },
+    };
+
+    const out = (await dispatchAgentTool.handler(
+      {
+        agents: [
+          { prompt: 'task one', label: 'one' },
+          { prompt: 'task two', label: 'two' },
+        ],
+      },
+      ctxWith(spawner),
+    )) as DispatchResults;
+
+    expect(out.results).toHaveLength(2);
+    expect(out.results.map((r) => r.label)).toEqual(['one', 'two']);
+    for (const r of out.results) {
+      expect(r.error).toBe('provider lookup failed');
+      expect(r.stopReason).toBe('error');
+      expect(r.text).toBe('');
+    }
+  });
+
+  it('still returns successful results in input order on the happy path', async () => {
+    const spawner: SubagentSpawner = {
+      spawn: async (): Promise<SubagentResult> => {
+        throw new Error('unused');
+      },
+      spawnAll: async (specs) =>
+        specs.map(
+          (s, i): SubagentResult => ({
+            label: s.label ?? `k${i}`,
+            childSessionId: `sess-${i}` as SubagentResult['childSessionId'],
+            text: `done ${i}`,
+            stopReason: 'end_turn',
+          }),
+        ),
+    };
+
+    const out = (await dispatchAgentTool.handler(
+      { agents: [{ prompt: 'a', label: 'x' }, { prompt: 'b', label: 'y' }] },
+      ctxWith(spawner),
+    )) as DispatchResults;
+
+    expect(out.results.map((r) => r.label)).toEqual(['x', 'y']);
+    expect(out.results.every((r) => r.error === undefined)).toBe(true);
+  });
+});
+
+describe('subagents — input bounds', () => {
+  const tool = buildDispatchAgentTool({ getAgent: () => undefined });
+
+  it('rejects an over-long prompt at the schema boundary (before any child is spawned)', () => {
+    // The bound is enforced by the loop's input validation; assert the cap
+    // exists so a regression that drops it is caught here.
+    const schema = tool.inputSchema;
+    const huge = 'x'.repeat(20_001);
+    expect(schema.safeParse({ agents: [{ prompt: huge }] }).success).toBe(false);
+    // A bounded prompt still parses.
+    expect(schema.safeParse({ agents: [{ prompt: 'short' }] }).success).toBe(true);
+  });
+
+  it('rejects an over-long systemPrompt at the schema boundary', () => {
+    const sys = 'y'.repeat(8_001);
+    expect(
+      tool.inputSchema.safeParse({ agents: [{ prompt: 'ok', systemPrompt: sys }] }).success,
+    ).toBe(false);
+  });
+
+  it('rejects more than 8 agents in one batch', () => {
+    const agents = Array.from({ length: 9 }, (_, i) => ({ prompt: `t${i}` }));
+    const parsed = tool.inputSchema.safeParse({ agents });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects a batch whose aggregate payload exceeds the budget even when each spec is within its field caps', () => {
+    // 8 prompts each just under the 20K per-field cap parse field-by-field, but
+    // ~144K chars dispatched as 8 concurrent completions is the worst-case spike
+    // the aggregate budget exists to refuse — before any session is spawned.
+    const big = 'x'.repeat(18_000);
+    const agents = Array.from({ length: 8 }, () => ({ prompt: big }));
+    const parsed = tool.inputSchema.safeParse({ agents });
+    expect(parsed.success).toBe(false);
+    if (!parsed.success) {
+      expect(parsed.error.issues.some((i) => /aggregate limit/.test(i.message))).toBe(true);
+    }
+  });
+
+  it('accepts a realistically-sized multi-agent batch under the aggregate budget', () => {
+    // Five agents with substantial-but-reasonable prompts must still parse.
+    const agents = Array.from({ length: 5 }, (_, i) => ({
+      prompt: `research subtopic ${i}: ` + 'detail '.repeat(200),
+      systemPrompt: 'be concise '.repeat(50),
+    }));
+    expect(tool.inputSchema.safeParse({ agents }).success).toBe(true);
+  });
+});

package/src/dispatch-agent.ts

@@ -0,0 +1,255 @@
+import {
+  defineTool,
+  MoxxyError,
+  z,
+  type AgentDef,
+  type SubagentResult,
+  type SubagentSpec,
+} from '@moxxy/sdk';
+
+/** Upper bound on a single child prompt. Children seed their session with this
+ *  verbatim and send it to the provider; an unbounded string at this trust
+ *  boundary lets a runaway/injected model fan out N multi-megabyte completions. */
+const MAX_PROMPT_CHARS = 20_000;
+/** Upper bound on a per-child system-prompt override. */
+const MAX_SYSTEM_PROMPT_CHARS = 8_000;
+/**
+ * Aggregate text budget across the WHOLE batch (sum of every spec's prompt +
+ * systemPrompt). The per-field caps bound one child, but 8 specs each at the
+ * field ceiling still total ~224K chars, dispatched as 8 *concurrent*
+ * completions — a sudden cost/context/memory spike reachable from untrusted
+ * model output. This caps the simultaneous fan-out payload below that
+ * worst case while staying generously above any real multi-agent call.
+ */
+const MAX_BATCH_TEXT_CHARS = 60_000;
+/** This tool's own name — never re-granted to children by default so a model
+ *  can't drive an unbounded recursive fan-out (8^N sessions). */
+const DISPATCH_AGENT_TOOL_NAME = 'dispatch_agent';
+
+const agentSpecSchema = z.object({
+  prompt: z
+    .string()
+    .min(1)
+    .max(MAX_PROMPT_CHARS)
+    .describe('The task the sub-agent should perform. Phrase as a focused, self-contained request.'),
+  agentType: z
+    .string()
+    .optional()
+    .describe(
+      'Named agent kind to spawn (e.g. "researcher", "code-reviewer"). Looked ' +
+        'up in the agent registry contributed by installed plugins. Omit, or ' +
+        'pass "default", for a generic tool-use agent. Unknown types fall back ' +
+        'to default — the request never fails over a missing kind. List of ' +
+        'currently-registered kinds is visible via the /agents command.',
+    ),
+  label: z
+    .string()
+    .max(60)
+    .optional()
+    .describe('Short label shown in progress events (e.g. "research-deps", "lint-fix-A").'),
+  systemPrompt: z
+    .string()
+    .max(MAX_SYSTEM_PROMPT_CHARS)
+    .optional()
+    .describe(
+      'Override the kind\'s system prompt. Use to set persona, constraints, ' +
+        'or hand off upstream artifacts the child needs as context.',
+    ),
+  model: z
+    .string()
+    .optional()
+    .describe(
+      'Model id override; defaults to the kind\'s model, then the parent\'s. ' +
+        'Omit unless the user explicitly requested a specific model — do NOT ' +
+        'invent model ids. Unknown ids fall back to the parent\'s model with a warning.',
+    ),
+  mode: z
+    .string()
+    .optional()
+    .describe(
+      'Loop strategy override. Valid values: "default", "goal", ' +
+        '"research". OMIT for the kind\'s default — do NOT invent names.',
+    ),
+  allowedTools: z
+    .array(z.string())
+    .optional()
+    .describe('Restrict the child to these tool names. Overrides the kind\'s allowlist if set.'),
+});
+
+// NOTE: `maxIterations` is intentionally absent from the model-facing
+// schema. Models tend to hallucinate small numbers (4, 5, 10) when
+// given a free integer field, which causes legitimate research tasks
+// to fail with `loop exceeded maxIterations (4)`. The cap belongs on
+// the AgentDef (per-kind, set by the plugin author) or the spawner
+// default (50), not on the per-call payload.
+
+export type AgentSpecInput = z.infer<typeof agentSpecSchema>;
+
+export interface DispatchAgentDeps {
+  /** Live lookup against the session's agent registry. Closure-bound at
+   *  plugin construction so handler reads see fresh state. */
+  readonly getAgent: (name: string) => AgentDef | undefined;
+  /**
+   * Live snapshot of the parent's tool names. When wired, a child that
+   * neither the caller nor its kind restricts is defaulted to the parent's
+   * tools MINUS `dispatch_agent`, so a model can't drive an unbounded
+   * recursive fan-out (8^N concurrent sessions / fork-bomb). Omit (the
+   * default) to preserve full unrestricted inheritance — useful for
+   * standalone tests/scripts that don't wire a session.
+   */
+  readonly getToolNames?: () => ReadonlyArray<string>;
+}
+
+/** Built-in "default" kind — surfaced when the model omits agentType or
+ *  passes an unknown one. Never registered in the AgentRegistry so
+ *  plugins can override it cleanly via `replace()` if they want. */
+export const DEFAULT_AGENT: AgentDef = {
+  name: 'default',
+  description:
+    'Generic tool-use loop. Inherits the parent\'s full tool registry; no system prompt override.',
+};
+
+export function buildDispatchAgentTool(deps: DispatchAgentDeps) {
+  return defineTool({
+    name: 'dispatch_agent',
+    description:
+      'Spawn one or more focused sub-agents in parallel. Use when a task fans out ' +
+      'into independent subtasks (multi-source research, per-file refactor, ' +
+      'multi-perspective review). Each child runs in isolation and returns its ' +
+      'final message; children stream their progress so you see what each one is ' +
+      'doing in real time. Pass `agentType` to pick a specialized kind from the ' +
+      'agent registry (see /agents); omit for the default generic agent. Unknown ' +
+      'kinds fall back to the default instead of erroring.',
+    inputSchema: z.object({
+      agents: z
+        .array(agentSpecSchema)
+        .min(1)
+        .max(8)
+        .superRefine((specs, ctx) => {
+          // Bound the *aggregate* concurrent fan-out payload, not just each
+          // child. Reject the whole batch before any session is spawned.
+          let total = 0;
+          for (const s of specs) total += s.prompt.length + (s.systemPrompt?.length ?? 0);
+          if (total > MAX_BATCH_TEXT_CHARS) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message:
+                `dispatch_agent batch payload too large: ${total} chars across ${specs.length} ` +
+                `agent(s) exceeds the ${MAX_BATCH_TEXT_CHARS}-char aggregate limit. Spawn fewer ` +
+                `agents per call or shorten the prompts/systemPrompts.`,
+            });
+          }
+        })
+        .describe('Specs for the agents to spawn. Run in parallel; results returned in order.'),
+    }),
+    handler: async (input, ctx) => {
+      if (!ctx.subagents) {
+        throw new MoxxyError({
+          code: 'INTERNAL',
+          message:
+            'dispatch_agent: no subagent spawner available — this tool must be invoked from a run-turn loop.',
+          hint: 'Invoke dispatch_agent from within a run-turn loop so the subagent spawner is wired into the tool context.',
+        });
+      }
+      const agents = input.agents as AgentSpecInput[];
+      const specs: SubagentSpec[] = agents.map((s, i) =>
+        resolveSpec(s, deps, { index: i, total: agents.length }),
+      );
+      // The core spawner runs children with Promise.all, which rejects on the
+      // FIRST child's setup throw (model/log/provider lookup before the
+      // per-child try) and discards every sibling's result. Degrade to
+      // per-child errors here so one child's failure doesn't abort the batch
+      // and orphan the rest — the model still gets the specs that succeeded.
+      let results: ReadonlyArray<SubagentResult>;
+      try {
+        results = await ctx.subagents.spawnAll(specs);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          results: specs.map((s) => ({
+            label: s.label ?? s.agentType ?? 'default',
+            childSessionId: '',
+            text: '',
+            stopReason: 'error',
+            error: message,
+          })),
+        };
+      }
+      return {
+        results: results.map((r) => ({
+          label: r.label,
+          childSessionId: String(r.childSessionId),
+          text: r.text,
+          stopReason: r.stopReason,
+          ...(r.error ? { error: r.error.message } : {}),
+        })),
+      };
+    },
+  });
+}
+
+/** Position of this spec within a multi-agent batch — used to disambiguate
+ *  fallback labels and (informationally) reason about fan-out width. */
+export interface ResolveSpecPosition {
+  readonly index: number;
+  readonly total: number;
+}
+
+/**
+ * Merge a model-supplied spec with the registered agent kind. Caller
+ * fields win over kind defaults; omitted caller fields fall back to
+ * the kind, which falls back to the built-in DEFAULT.
+ */
+export function resolveSpec(
+  input: AgentSpecInput,
+  deps: DispatchAgentDeps,
+  position?: ResolveSpecPosition,
+): SubagentSpec {
+  const requested = input.agentType ?? 'default';
+  const def = deps.getAgent(requested) ?? DEFAULT_AGENT;
+  const systemPrompt = input.systemPrompt ?? def.systemPrompt;
+  const model = input.model ?? def.model;
+  const mode = input.mode ?? def.mode;
+  // maxIterations only comes from the AgentDef now (the input schema
+  // doesn't expose it — see comment in agentSpecSchema above).
+  const allowedTools = resolveAllowedTools(input, def, deps);
+  // When the caller omits `label`, multiple agents of the same kind would all
+  // collapse to the kind's name (e.g. five "default" labels), making the live
+  // progress display and the returned results indistinguishable. Suffix a
+  // 1-based index in that multi-agent case; keep explicit/single labels clean.
+  const fallbackLabel =
+    position && position.total > 1 ? `${def.name}-${position.index + 1}` : def.name;
+  const merged: SubagentSpec = {
+    prompt: input.prompt,
+    label: input.label ?? fallbackLabel,
+    // The requested kind, surfaced in subagent_* payloads for group rendering.
+    agentType: requested,
+    ...(systemPrompt !== undefined && { systemPrompt }),
+    ...(model !== undefined && { model }),
+    ...(mode !== undefined && { mode }),
+    ...(def.maxIterations !== undefined && { maxIterations: def.maxIterations }),
+    ...(allowedTools !== undefined && { allowedTools }),
+  };
+  return merged;
+}
+
+/**
+ * Decide the child's tool allowlist. Caller `allowedTools` wins, then the
+ * kind's, then — when a parent tool snapshot is wired (`deps.getToolNames`)
+ * and neither restricts — the parent's tools MINUS `dispatch_agent`. That
+ * last default is the recursion cut: without it, an unrestricted child
+ * inherits `dispatch_agent` and each level can spawn another full batch,
+ * giving 8^depth concurrent sessions reachable from untrusted model output.
+ * A kind that genuinely needs to recurse can re-grant `dispatch_agent`
+ * explicitly via its `allowedTools`.
+ */
+function resolveAllowedTools(
+  input: AgentSpecInput,
+  def: AgentDef,
+  deps: DispatchAgentDeps,
+): ReadonlyArray<string> | undefined {
+  const explicit = input.allowedTools ?? def.allowedTools;
+  if (explicit !== undefined) return explicit;
+  if (!deps.getToolNames) return undefined; // not wired → preserve full inheritance
+  return deps.getToolNames().filter((n) => n !== DISPATCH_AGENT_TOOL_NAME);
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+import {
+  definePlugin,
+  type AgentDef,
+  type LifecycleHooks,
+  type NamedRegistry,
+  type Plugin,
+} from '@moxxy/sdk';
+import { buildDispatchAgentTool, type DispatchAgentDeps } from './dispatch-agent.js';
+
+export { buildDispatchAgentTool, type DispatchAgentDeps } from './dispatch-agent.js';
+
+export interface BuildSubagentsPluginOpts {
+  /**
+   * How the tool resolves an `agentType` name → AgentDef at handler
+   * time. Pass a closure that reads from your session's agent registry:
+   * `(name) => session.agents.get(name)`.
+   *
+   * Defaults to "no agents registered" (always falls back to the
+   * built-in default kind). Useful for standalone tests / scripts that
+   * don't want to wire a session.
+   */
+  readonly getAgent?: (name: string) => AgentDef | undefined;
+  /**
+   * Live snapshot of the parent's tool names, e.g.
+   * `() => session.tools.list().map((t) => t.name)`. When provided, a child
+   * that neither the caller nor its kind restricts is defaulted to the
+   * parent's tools MINUS `dispatch_agent` — cutting unbounded recursive
+   * fan-out (8^N sessions). Omit to keep full unrestricted inheritance.
+   */
+  readonly getToolNames?: () => ReadonlyArray<string>;
+}
+
+/**
+ * `@moxxy/plugin-subagents` — adds the dispatch_agent tool + the
+ * auto-detection skill ("dispatch-agents") that triggers on fan-out
+ * patterns. Without this plugin the model can't spawn subagents — the
+ * normal single-loop flow runs as usual.
+ *
+ * Other plugins can ship `AgentDef` kinds via their own
+ * `PluginSpec.agents`. This plugin's tool resolves them at runtime, so
+ * a freshly-installed agent kind becomes available the next time the
+ * model calls dispatch_agent — no restart needed.
+ */
+export function buildSubagentsPlugin(
+  opts: BuildSubagentsPluginOpts = {},
+  hooks?: LifecycleHooks,
+): Plugin {
+  const deps: DispatchAgentDeps = {
+    getAgent: opts.getAgent ?? (() => undefined),
+    ...(opts.getToolNames ? { getToolNames: opts.getToolNames } : {}),
+  };
+  return definePlugin({
+    name: '@moxxy/plugin-subagents',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    tools: [buildDispatchAgentTool(deps)],
+  });
+}
+
+/**
+ * Discovery-loadable default export: resolves the `agents` + `tools` registries
+ * from the inter-plugin service registry in `onInit` (the host publishes them),
+ * so `dispatch_agent` looks up agent kinds + the live parent-tool snapshot from
+ * the session without a host-injected closure. Both reads are lazy (at tool-call
+ * time, after all registration), and degrade to the standalone defaults if the
+ * host hasn't published them.
+ */
+export const subagentsPlugin: Plugin = (() => {
+  let agents: NamedRegistry<AgentDef> | null = null;
+  let tools: NamedRegistry<{ readonly name: string }> | null = null;
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      agents = ctx.services.get<NamedRegistry<AgentDef>>('agents') ?? null;
+      tools = ctx.services.get<NamedRegistry<{ readonly name: string }>>('tools') ?? null;
+    },
+  };
+  return buildSubagentsPlugin(
+    {
+      getAgent: (name) => agents?.get(name),
+      getToolNames: () => (tools ? tools.list().map((t) => t.name) : []),
+    },
+    hooks,
+  );
+})();
+
+export default subagentsPlugin;