Module spawn_subtask 

SpawnSubtask — an agent dynamically spawns isolated, tool-constrained sub-agents mid-run via a spawn_subtask tool.

Unlike Delegator, which routes to a fixed set of named specialists, spawn_subtask lets the main agent invent an ephemeral sub-agent on the fly and hand it a subset of its own tools:

main agent calls spawn_subtask(task="scrape the page", tools=["fetch"])
  → SpawnSubtaskExecutor intercepts
  → validates {fetch} ⊆ parent tools  (privilege de-escalation)
  → spawns an ephemeral agent limited to {fetch}
  → returns the sub-agent's answer as the tool result

Tool-subset is enforced twice — once provably

1. Schema (provable): the spawn_subtask tool is registered with a JSON Schema whose tools items are an enum of the parent’s tool names. The runtime’s validator (car-validator, via jsonschema) rejects any proposed call that lists a tool outside that set before execution. The subset constraint is therefore a verified precondition, not a convention.
2. Executor (defense in depth): the executor re-checks the subset at call time, so a caller that dispatches the tool without schema validation still cannot escalate.

Parallelism

Multiple spawn_subtask calls a model emits in one proposal run concurrently through the engine’s DAG executor (futures::join_all over independent actions) — no manual batching needed. Each spawn gets its own runtime over the shared infra, so they don’t contend on a single mutable tool.

Structs

SpawnSubtask

Coordinator: runs a main agent with the spawn_subtask tool enabled.

SpawnSubtaskResult

Result of running an agent that can spawn sub-agents.

SubtaskRecord

Record of one spawn_subtask invocation.

Constants

SPAWN_SUBTASK_TOOL

Reserved name of the meta-tool itself. Never granted to a sub-agent, so delegation is structurally bounded to one level.

Functions

spawn_subtask_schema

Build the spawn_subtask tool schema whose tools parameter is constrained to an enum of parent_tools — the verifiable subset precondition.