Module delegation 

Which capsule delegated to this one, and how a delegated child says that it finished.

A child launched by crate::child_launch knows its spawner from one injected environment variable, SPAWNER_ENV, and from nothing it inherited: the parent’s launcher composes a SpawnerHandle and applies it in the runtime-owned tail of the child’s environment. A capsule launched any other way has no handle, records no lineage and contacts nothing.

Knowing your parent and reporting to it are separate. Every handle names the session that spawned this one and the delegation that created it, which is what the child writes into its own session_start. Only a handle carrying a CompletionAddress also has somewhere to post an outcome: a parent that waits on the connection it already holds — every delegation made through crate::delegation_plane — supplies none, so its child is attributable without anything being sent anywhere.

The completion names the delegation; the parent’s runtime hands over the answer. Every field of DelegationOutcome is composed by a runtime — ids, a status word, a path, a duration — and the one input that could grow, the crash detail, is capped twice: at the 20 stderr lines child_launch retains, and again at MAX_DETAIL_BYTES. Neither COMPLETION_FILE nor the posted message carries the child’s output. The child leaves its answer in a result file in its own directories, and the parent’s runtime reads it there itself, through the child directories it holds, once the child has exited: [result_block] puts it under a result: line in what the delegating task is told, inside the delegation:<capsule> fence [outcomes_message] applies. An answer over [crate::delegation_plane::MAX_OUTPUT_BYTES] is cut there with the cut marked, and the whole text is kept in the parent’s runtime directory, which every kind of tool reads ([hand_over_answer]). The parent’s commands cannot read the children’s records directories.

Two reporters, one arrival path. The child reports for itself at the end of its own session; the completion watcher behind the parent’s crate::child_launch::LaunchedChild reports for a child that could not. Both write COMPLETION_FILE into the child’s directory and both post the same JSON-RPC SendMessage to the parent’s A2A door. The door hands it to the task that made the delegation, which reads this file and continues its conversation with [outcomes_message]; it never becomes a task of its own. A completion that cannot be delivered is recorded in that file with delivered: false and the refusal’s reason, and a line goes to stderr; it is not retried beyond the launcher’s single retry and it is not silently discarded.

Structs

CompletionAddress

Where a completion is posted.

DelegationOutcome

What a delegation left behind: the notification the parent receives, and the shape of COMPLETION_FILE.

Spawner

The parent a delegated child belongs to, supplied by the parent at launch.

SpawnerHandle

The value injected into the child: a Spawner plus the delegation id the launcher minted.

Enums

DelegationStatus

How a delegated child ended.

Reporter

Which of the two reporters built a completion.

Constants

COMPLETION_FILE

The child’s own record of how it ended, in the child’s records directory.

COMPLETION_SESSION_HEADER

Header naming the session a completion is addressed to.

DELEGATION_ID_HEADER

Header naming the delegation a completion reports on. Read by the parent’s door only for a request classified completion, which hands the delegation’s outcome to the task that made it.

DELEGATION_ID_PREFIX

Prefix on every delegation id. Distinct from tsk_/ctx_/ses_/wrk_, so a reader of trace.jsonl can tell at a glance which id space a value belongs to.

MAX_DETAIL_BYTES

Ceiling on DelegationOutcome::detail, the one field built from something a child wrote.

PARENT_ENDED_DETAIL

The detail a launcher records in COMPLETION_FILE for a child its parent ended on purpose: through the handle a delegate-task call left with its task, or from inside a plan capsule step whose task was cancelled.

SPAWNER_ENV

The variable the parent’s launcher injects into a delegated child, carrying its SpawnerHandle as compact JSON.

Functions

deliver_completion

Post one completion to the parent’s A2A door.

new_delegation_id

A fresh delegation id, matching ^dlg_[0-9a-f]+$.

read_completion

The completion the child recorded, or None when it recorded none.

record_terminated

Record a delegation the parent ended itself, without posting it.

report_completion

Record outcome in the child’s records directory, post it, and record what the posting did.

write_completion

Write outcome to COMPLETION_FILE in the child’s records directory, replacing whatever was there.