Function communicate_child 

pub fn communicate_child(
    child: &mut OwnedChild,
    input: Option<&[u8]>,
    limits: OutputLimits,
    successful_exit: SuccessfulExit,
    cancelled: impl FnMut() -> bool,
) -> Result<ExecutionEvidence, ToolError>

Communicate once with a caller-spawned child using its configured IO.

Uses the capture engine to fairly drain available stdout/stderr pipes and write borrowed input without blocking reader/writer threads. The caller configures IO before crate::child::OwnedChild::spawn: absent output pipes are left alone (for example inherited progress output or files). Limits only apply to captured pipes. Do not take the child’s pipes before this call. Some(input), including empty input, requires piped stdin. None closes any available stdin pipe immediately; inherited stdin remains caller-selected. Stdin closes after input is written. An early broken pipe is accepted, like standard communicate semantics; command status and diagnostics remain primary. This does not guarantee the command consumed all input or applied its effects.

The deadline starts on entry, excluding earlier spawn time. cancelled is polled between bounded IO steps and before returning success; it must return promptly. No signal handler, cancellation thread, retry or output decoding is installed. IO failure, cancellation, timeout, overflow and unsuccessful exit close pipes and terminate/reap through the child’s existing owner, retaining original failure and separate cleanup errors.

On success, all owned pipes are closed. With SuccessfulExit::Cleanup, group cleanup and reaping occur as soon as leader exit is observed. With SuccessfulExit::Retain, the successful leader remains reserved and group cleanup remains armed. After admitting output and checking application cancellation/deadlines, the caller must choose ordinary crate::child::OwnedChild::wait cleanup or explicit crate::child::OwnedChild::handoff. Rejected output can use terminate to retain cleanup evidence. Dropping the owner provides best-effort cleanup. This is not process-tree confinement or a descendant-exit barrier.

Errors

Invalid deadlines leave the already spawned child and its pipes untouched; the caller retains cleanup responsibility. An already reaped/transferred owner is rejected instead of reporting reserved success. Other failures return execution evidence after cleanup. Synchronous cleanup can exceed the deadline.