v0.8.68: define parent-stop semantics for detached background agents

[Hmbown]

Problem

Foreground child agents inherit parent cancellation, while detached background agents intentionally outlive the foreground turn. The user-facing contract for Esc/stop is therefore ambiguous: continue, cancel all, or ask. That ambiguity can make a successful detach look like a cancellation leak, or leave work running contrary to user intent.

Decision required

Define one explicit parent-stop policy for detached background agents:

1. Continue detached work and clearly report that it remains active.
2. Cascade cancellation to every child.
3. Prompt when detached children exist, offering stop-parent-only versus stop-all.

Whichever policy is selected must be reflected consistently in the TUI, stream receipts, child status, and session restoration.

Likely files

• crates/tui/src/tools/subagent/mod.rs
• engine turn/cancellation handle modules
• TUI stop-confirm and child-status presentation
• exec-stream receipt/event modules

Acceptance criteria

• The chosen policy is documented in user-facing help and runtime documentation.
• Esc/stop reports which background agents continued or were canceled.
• Canceled children have a typed canceled outcome, not a generic failure.
• Races between natural completion and cancellation produce one terminal outcome.
• Tests cover foreground children, detached children, multiple parallel children, and repeated stop requests.

Related

• v0.8.69: define CLI/TUI parity for subagent and runtime control surfaces #4022 tracks broader CLI/TUI parity for runtime and subagent control.

[Hmbown]

Resolved in merged v0.8.68 commit ed774931c7aa22d70cf7cdd30898665350a194e5 and verified again in the installed merge build 0.8.68 (9bfa466d64c1).

Chosen policy: continue detached work and explicitly report it. A parent-turn Esc/Ctrl+C/approval-abort cancels the foreground turn only. Any already-open detached workers remain active until explicitly canceled.

Acceptance evidence:

• User-facing contract: docs/SUBAGENTS.md states that parent cancellation stops the parent wait path but does not kill opened detached runs; durable/restart-surviving work is directed to Fleet/Workflow-backed runs.
• TUI receipt: every parent stop path now calls parent_stop_status, which reports detached workers continue (none canceled) and names the live workers.
• Typed outcome: explicit child cancellation records SubAgentStatus::Cancelled / AgentWorkerStatus::Cancelled rather than generic failure.
• Race/idempotence: late_completion_does_not_overwrite_cancelled_outcome proves one terminal winner; repeated cancel records exactly one terminal event.
• Coverage: foreground linked-child cancellation, two parallel detached children surviving parent cancellation, UI worker-name receipts, no-worker receipt behavior, repeated stop, and cancel/completion race all have focused tests. Session reload marks an in-process worker that cannot survive process restart as interrupted/checkpointed rather than falsely running.
• Release verification passed 6,681 TUI tests with 0 failures, including these contracts.

This issue was opened before ed774931c landed; the required behavior is now in main and in the installed build.