Spawning Sub-Agents

dispatch_child and its five companions are how a coordinator session spawns, steers, and observes other sessions as children. They are served identically on /api/mcp/[sessionId] (on-platform) and /api/cli/mcp (off-platform) from one shared module - the tool names, JSON schemas, and result shapes cannot drift between the two doors.

The six tools

Off-platform, all six require the calling API key to carry the spawn:invoke scope, independent of any dispatch:invoke/a2a:invoke scopes the same key might also hold - a key with only spawn:invoke is admitted at the door and sees exactly this tool family in tools/list. On-platform, the tools are always present on your own session's MCP endpoint; there is no separate scope to grant, because your session's own authority is what every call is checked against.

Two credential lanes, one abstraction

dispatch_child and cancel_session need more than identity - they need a spawn credential, the same signed token POST /api/interactive-sessions accepts on its machine-principal path:

• On-platform: your session's own lineage row is the credential source. The platform mints a short-lived credential from it on your behalf for each call - there is nothing for you to manage.
• Off-platform: you present the credential yourself, as the x-interactive-spawn-credential header, on every call.

watch_session, replay_session, get_session_receipt, and steer_child don't need a credential at all - only your attested caller identity (who you are, and where you sit in the spawn tree), resolved the same way regardless of which door you're calling.

Authority ceiling

Every session that can spawn carries an authority_ceiling document. A child's ceiling is always derived from its parent's and can only narrow - deriveChildCeiling never widens an axis, and a request that asks for more than the parent itself holds is refused, never silently narrowed to fit. There is no path to a child with more capability than its parent.

dispatch_child accepts convenience fields - pool, harness, modelProfile, repository - plus a raw requestedCeiling object for anything more specific. Read these carefully: they narrow the ceiling's allow-list, they do not select placement. Passing pool: "my-pool" means "refuse unless the resolved pool is my-pool" - the normal project/org default cascade still does the resolving. If the cascade would resolve a different pool, the spawn is refused (interactive_spawn_ceiling_violation), not silently redirected to your requested one. If you need to actually pin a launch axis rather than just constrain it, see Customization below.

Platform-wide defaults

Absent any org override, every spawn is subject to:

An org may only tighten these via its plan configuration - never widen them past the platform default. dispatch_child's response, and every session's lineage row, carries spawn_depth so you can see how close a branch is to the ceiling before you spawn further from it.

Typed refusal codes

Every refusal from dispatch_child/cancel_session carries one of nine typed codes, each with a declared class that tells you whether retrying makes sense:

Every refusal body carries { code, class, message } plus axis/limit/current where relevant - a coordinator can branch on class alone without maintaining its own copy of which codes are worth retrying.

Customization

dispatch_child has full field parity with the underlying spawn REST contract (POST /api/interactive-sessions): every customization field the REST body accepts, dispatch_child validates against the exact same zod schemas and forwards verbatim into the same launchSpawnedInteractiveSession call, so the two doors can never resolve a given selection differently.

• The ceiling-narrowing convenience fields from Authority ceiling above - pool, harness, modelProfile, repository, requestedCeiling.
• initialPrompt, agentHandle (the durable, addressable name other sessions use to reach this child over a2a_send_message), and timeouts.maxDurationSec.
• executionSelection, capabilities, and workspace - the richer selection/wiring/bootstrap fields, described below.

All three are intent refs only - they carry no new placement or selection authority beyond what the human launch path already has, and every one is still checked against the child's derived ceiling before it takes effect. A malformed executionSelection/capabilities/workspace value throws before the launch call is ever made, matching the REST body's own safeParse 400 posture; an admission-time rejection surfaces as one of the typed refusals below instead of a generic internal error.

Launch-selection refusal codes

A syntactically valid executionSelection/capabilities/workspace can still be refused by the admission gate underneath dispatch_child - a separate code family from the ceiling-violation codes above, all class terminal:

Each mirrors the REST route's own 409 mapping for the identical failure, surfaced here as a structured { code, class, message, ... } refusal instead of collapsing to a generic internal error over JSON-RPC.

Observability

There is no dedicated tenant-wide swarm dashboard yet. What you have today:

• watch_session - one session's live status plus its direct children (lineage-aware, but one level at a time).
• get_session_receipt - a subtree rollup rooted at any session in your lineage: total count, a per-status tally, and max depth.
• Every session's lineage row carries spawn_depth, useful for noticing a branch approaching the depth ceiling before you spawn further from it.

A cost roll-up and a lineage-aware view across an entire tenant's spawn activity (not just what you can see from your own subtree) is planned but not live - if you need that today, reconcile by walking get_session_receipt from your own root sessions.

Related pages

• Coordinator Overview - front-end comparison
• pi sub-agents - what a spawned pi child gets automatically
• A2A Delivery Tiers - what steer_child and the mailbox tools actually guarantee
• Interactive Sessions - the human launch path these same admission checks serve
• API Key Authentication - scoping an off-platform key with spawn:invoke