Delegated threads let a solo-chat agent spawn real, persistent chat sessions through a loopback HTTP API (per-session bearer token, ephemeral port, `useDelegatedThreads` answering marshalled IPC in the renderer). `mode` is permissions and `isolation` is placement — they are independent, and `build` + `shared` is the legitimate "run the test suite in this checkout" case; never re-couple them. **Depth-1 must stay enforced at three layers, not by withholding credentials alone**: `canSessionDelegate()` (`origin !== 'delegated'`) gates the ChatPane toggle, credential minting in `useSessionDelegation`, and — authoritatively — every route in `useDelegatedThreads.perform()` with a 403, so a leaked token cannot read siblings or merge their branches either. The bearer token **is** the caller's identity, so `containsDelegationToken` must reject any create prompt or thread message carrying a live token (checked against every registered token, not just the caller's); refuse rather than redact, because a 64-hex string is never legitimate task text. **An agent must never be able to archive a chat.** `POST /v1/threads/:id/close` sets `Session.delegationClosedAt`, which frees a concurrency slot and dims the drawer row; it must never call `setArchived`, because archived sessions vanish from every live surface and only the user decides they are finished with a thread. Sending a closed thread a message reopens it, `focus` works on a done thread and refuses an archived one, and `closed` in the API projection means either state because both free a slot. Reporting is push, not poll, and is modelled directly on the crew Supervisor loop: `useDelegationReports` subscribes to the bridge registry's `subscribeTurnEnd` and routes a finished worker's bounded final reply into the parent's running turn as a follow-up, wakes an idle parent with a fresh turn, or buffers it in `delegation-inbox-store.ts` for the parent's next prompt; every failure falls back to buffering so a report is never dropped. **Reports must be coalesced, never delivered one wake per thread** — waking costs a full parent turn at that chat's whole context, so a fan-out finishing together gets one wake carrying every report (`REPORT_COALESCE_MS`), and a `delivering` flag must be claimed synchronously before the first `await` (crew's `busy`) or parallel workers all see an idle parent and fire concurrent prompts at one bridge. Autonomous waking is `settings.wakeParentOnDelegatedReport` (default on) and is bounded by `MAX_AUTONOMOUS_WAKES = 4`, which counts **recursion, not volume**: a wide fan-out from a user-driven turn is free however many threads it contains, while a wake caused by threads spawned during an autonomous turn (`Session.delegatedDuringWake`, stamped at spawn) costs one. Only a real user message refills the budget (an auto-wake bypasses the send path, so it cannot refill its own), follow-ups into a running turn never spend it, and an exhausted budget must say so in the transcript. A finished thread must be re-read on a settle retry (`REPORT_SETTLE_ATTEMPTS` × `REPORT_SETTLE_INTERVAL_MS`, mirroring crew's `reportLaneReply`) before its reply is extracted — `turn_end` fires before the renderer flushes stream buffers, so a synchronous read captures the agent's opening line and none of its result. One logical turn must report exactly once: `useAgentBridge` routes `turn_end`, `error` and `closed` through the same callback, so the guard is a consume-once `reported` set released only by the child's next `turn_start` (crew's `waiting.delete`), **never reply-text comparison** — the settle retry guarantees an early and a late event see different text, so text dedup silently delivers every report twice. `Session.delegationRunId` is the cohort stamped at spawn so a batch can report "1 of 3 done — do not summarize as finished yet"; it is unrecoverable after the fact, so never try to infer it at report time. The idle watchdog (`shouldAbandonThread`, mirroring crew's `shouldAbandonRound`, fed by `subscribeActivity` + `nextToolsInFlight`) reports a thread that is still running with no tool open and no bridge event for 3 minutes — it must **report, never close or archive**, and must keep the tool-in-flight gate or a single long tool call looks identical to a hang. A wake must revive a bridge reclaimed by the 10-minute idle sweep (`ensureBridgeForSession`), and both the preamble and the `woke` report block must tell the agent the user is not present so an auto-started turn never ends in a question. Every report also lands as a visible system row in the parent transcript, is framed as `<system>` (never user text), is clamped to 1,600 chars, caps at 12 buffered per parent, and drains exactly once at wire-text assembly. See `docs/delegated-threads.md`.
0 commit comments