Module invocation 

The unified sub-agent invocation model.

Replaces the older CallMode (InProcess/Fork/Offload/Transfer) enum which conflated three independent decisions — what context the child sees, how the parent waits, and which orchestrator runs the loop — into a single string mode. Each axis is now its own type.

See distri/docs/invocation-model.md (TODO) for the full design notes. Quick summary:

• ContextScope — Independent / Inherited / Shared.
• Join — Single / All / Detached.
• Executor — Local / Remote{runner}. The agent loop is always server-side; the question is whether THIS orchestrator runs it or another orchestrator does.

Invocation carries Vec<Target> (1..N) so a single sub-agent call is just targets.len() == 1. Validation rejects combinations that don’t make sense (e.g. Join::Single with 2 targets).

Structs

AgentResult

One agent’s final result, returned to the parent’s tool-call response.

Invocation

One agent dispatch — synchronous or asynchronous, single or fan-out, local or remote. The orchestrator validates this at the entry point and then stamps the resolved fields onto the child task row(s).

RunnerConfig

How to start a remote runner. The kind field is dispatched against the orchestrator’s RunnerInitializer registry; config is the initializer’s private payload (image name, k8s namespace, sandbox flags, …). The orchestrator does not interpret config.

Target

One leaf of a (possibly fan-out) invocation.

TaskSnapshot

Snapshot returned by the supervisor tools (get_task, list_my_tasks).

Enums

AgentRef

How to identify the agent for a target.

ContextScope

What the child task sees when it starts its first LLM turn.

Executor

Which orchestrator runs the agent loop.

ExecutorHint

What the caller HINTS for axis 3. Final decision is the orchestrator’s: it intersects (agent.allowed_runtimes, caller.runtime_mode, available_runners).

InvocationResult

Result returned to the parent’s tool call. Shape mirrors Join.

InvocationValidationError

Errors returned by Invocation::validate.

Join

How the parent waits for the dispatched task(s).

ToolPolicy

How the child inherits external tools from the parent session.