typeclaw 0.28.2 → 0.30.0

package/src/agent/plugin-tools.ts

@@ -40,14 +40,16 @@ import {
   ensureSessionTmpDir,
   mapVirtualTmpPath,
   resolveHiddenPaths,
+  resolveProcSelfExe,
   resolveProtectedZones,
   resolveWritableZones,
   subtractMasked,
 } from '@/sandbox'
 
-import { createLoopGuard, type LoopGuard } from './loop-guard'
+import { createLoopGuard, type LoopGuard, type LoopGuardDecision } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
+import { SUBAGENT_OUTPUT_TOOL_NAME, type SubagentOutputToolDetails } from './tools/subagent-output'
 import { webFetchTool } from './tools/webfetch'
 import { webSearchTool } from './tools/websearch'
 
@@ -241,10 +243,10 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(`blocked: ${blockResult.reason}`)
       }
 
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, opts.toolName, before.args)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, opts.toolName, before.args)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        return errorResult(loopDecision.message)
+        return errorResult(loopGate.message)
       }
 
       const toolCtx: ToolContext = {
@@ -262,9 +264,12 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(message)
       }
 
-      if (loopDecision.kind === 'warn') {
-        result = appendLoopWarning(result, loopDecision.message)
+      const resolved = loopGate.resolve(result)
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        return errorResult(resolved.deferredBlock)
       }
+      result = resolved.result
 
       await opts.hooks.runToolAfter({
         tool: opts.toolName,
@@ -301,10 +306,10 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -321,15 +326,12 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate, ctx)
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
-      }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -337,7 +339,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
         result: hookResult,
       })
       return {
-        content: hookResult.content,
+        content: hookResult.content as ContentPart[],
         details: hookResult.details as TDetails,
       }
     },
@@ -364,10 +366,10 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -384,15 +386,12 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
-      }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -400,7 +399,7 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
         result: hookResult,
       })
       return {
-        content: hookResult.content,
+        content: hookResult.content as ContentPart[],
         details: hookResult.details as TDetails,
       }
     },
@@ -442,10 +441,10 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       // loop-detection state, or pi's execute.
       const bashEnvOverlay = readBashEnvOverlay(mutableArgs)
       delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -465,22 +464,30 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
         await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId, bashEnvOverlay)
       }
 
-      if (TMP_REDIRECT_TOOLS.has(tool.name) && opts.permissions !== undefined) {
-        await applyTmpPathRedirect(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId)
-      }
+      const tmpRedirect =
+        TMP_REDIRECT_TOOLS.has(tool.name) && opts.permissions !== undefined
+          ? await applyTmpPathRedirect(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId)
+          : undefined
 
-      const result = await bashEnvStore.run(bashEnvOverlay, () =>
-        tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate),
-      )
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
+      let rawResult: ToolResult
+      try {
+        rawResult = await bashEnvStore.run(bashEnvOverlay, () =>
+          tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate),
+        )
+      } catch (error) {
+        // A throwing tool (pi's bash rejects on non-zero exit) must still run
+        // tool.after so cleanup hooks fire — e.g. the github approve guard's
+        // release, whose absence stranded a PR as "already approved" (PR #672).
+        await runToolAfterSafely(opts, tool.name, toolCallId, toErrorResult(error))
+        throw error
       }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const result = tmpRedirect !== undefined ? restoreTmpPathInResult(rawResult, tmpRedirect) : rawResult
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -495,6 +502,26 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
   })
 }
 
+function toErrorResult(error: unknown): ToolResult {
+  const message = error instanceof Error ? error.message : String(error)
+  return { content: [{ type: 'text', text: message }], details: { error: message } }
+}
+
+// The original tool error must always propagate, so a failure inside the
+// after-hook itself is swallowed rather than masking the real cause.
+async function runToolAfterSafely(
+  opts: WrapSystemToolOptions,
+  tool: string,
+  callId: string,
+  result: ToolResult,
+): Promise<void> {
+  try {
+    await opts.hooks.runToolAfter({ tool, sessionId: opts.sessionId, callId, result })
+  } catch {
+    // intentionally ignored: never mask the originating tool error
+  }
+}
+
 export function defaultBuiltinPiAgentTools(): AgentTool<any, any>[] {
   return [piReadTool, piBashTool, piEditTool, piWriteTool, piGrepTool, piFindTool, piLsTool]
 }
@@ -565,6 +592,7 @@ async function applyBashSandbox(
     protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
+    procSelfExe: resolveProcSelfExe(),
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
   })
   mutableArgs.command = commandString
@@ -584,24 +612,47 @@ const TMP_REDIRECT_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'find', 'ls
 // different files. Rewriting the file tool's on-disk path to the same session
 // backing dir makes every layer resolve /tmp/foo to one file. Unsandboxed roles
 // (empty masks) are left untouched: their bash already shares the real /tmp.
+type TmpRedirect = { original: string; backing: string }
+
 async function applyTmpPathRedirect(
   mutableArgs: Record<string, unknown>,
   permissions: PermissionService,
   origin: SessionOrigin | undefined,
   agentDir: string,
   sessionId: string,
-): Promise<void> {
+): Promise<TmpRedirect | undefined> {
   const rawPath = mutableArgs.path
-  if (typeof rawPath !== 'string') return
+  if (typeof rawPath !== 'string') return undefined
 
   const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
-  if (dirs.length === 0 && files.length === 0) return
+  if (dirs.length === 0 && files.length === 0) return undefined
 
   const backing = mapVirtualTmpPath(agentDir, sessionId, rawPath)
-  if (backing === undefined) return
+  if (backing === undefined || backing === rawPath) return undefined
 
   await ensureSessionTmpDir(sessionId)
   mutableArgs.path = backing
+  return { original: rawPath, backing }
+}
+
+// The redirect swaps the model-facing /tmp path for its session backing dir
+// before execution; the file tool then echoes that backing path in its receipt
+// text and details. Reverse it on the way out so the model only ever sees the
+// path it asked for — a leaked backing path is unreachable inside the bwrap
+// bash sandbox, so reusing it in `gh api --input` fails (the PR #672 strand).
+function restoreTmpPathInResult(result: ToolResult, redirect: TmpRedirect): ToolResult {
+  const content = (result.content as ContentPart[]).map((part) =>
+    part.type === 'text' ? { ...part, text: part.text.split(redirect.backing).join(redirect.original) } : part,
+  )
+  const details =
+    isRecord(result.details) && result.details.path === redirect.backing
+      ? { ...result.details, path: redirect.original }
+      : result.details
+  return { content, details }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
 }
 
 function appendLoopWarning(result: ToolResult, message: string): ToolResult {
@@ -609,6 +660,72 @@ function appendLoopWarning(result: ToolResult, message: string): ToolResult {
   return { content, details: result.details }
 }
 
+// `subagent_output` is a read-only poll whose loop/no-loop classification only
+// becomes knowable AFTER execution: a result of `status: 'running'` is a
+// still-pending wait (legitimate), while a repeated terminal result is a real
+// loop. The loop guard's `check` is result-blind and pre-execution, so for this
+// one tool we DEFER enforcing a block until the status is known — otherwise the
+// exact poll that would reveal 'running' gets blocked before it can run (the
+// boundary-call hazard for round-robin fan-out polling). Every other tool
+// enforces its block immediately, as before.
+// A block is deferred only for a `subagent_output` poll the guard still marks
+// `deferable` — i.e. whose signature has not yet proven terminal. Once a poll of
+// that signature returns completed/failed, `deferable` is false and the block is
+// enforced pre-execute, so a finished task is not re-polled forever.
+function shouldDeferLoopBlock(toolName: string, decision: LoopGuardDecision): boolean {
+  return toolName === SUBAGENT_OUTPUT_TOOL_NAME && decision.kind === 'block' && decision.deferable
+}
+
+function subagentPollStatus(toolName: string, result: ToolResult): 'running' | 'terminal' | undefined {
+  if (toolName !== SUBAGENT_OUTPUT_TOOL_NAME) return undefined
+  const details = result.details as SubagentOutputToolDetails | undefined
+  if (details?.ok !== true) return undefined
+  return details.status === 'running' ? 'running' : 'terminal'
+}
+
+type LoopGuardGate = {
+  // True when the guard wants to block AND the block is enforced now (every tool
+  // except a deferable `subagent_output` poll). The caller aborts + errors.
+  blockNow: boolean
+  message: string
+  // Resolves the guard against the tool's result. Returns the result to surface
+  // (possibly warn-annotated), or `{ deferredBlock: message }` when a deferred
+  // `subagent_output` block must now be enforced because the poll did not return
+  // a still-running status.
+  resolve: (result: ToolResult) => { result: ToolResult } | { deferredBlock: string }
+}
+
+// Single chokepoint for the loop-guard pre-check + post-execute resolution so
+// all four tool wrappers share identical deferred-block / pending-retract
+// semantics. `check` runs here (recording the observation); the returned
+// `resolve` is called after execute with the tool's result, feeding the poll's
+// running/terminal status back to the guard so future blocks stop deferring.
+function gateLoopGuard(sessionId: string, toolName: string, args: unknown): LoopGuardGate {
+  const decision = sharedLoopGuard.check(sessionId, toolName, args)
+  const defer = shouldDeferLoopBlock(toolName, decision)
+  return {
+    blockNow: decision.kind === 'block' && !defer,
+    message: decision.kind === 'ok' ? '' : decision.message,
+    resolve(result) {
+      const pollStatus = subagentPollStatus(toolName, result)
+      if (pollStatus !== undefined) {
+        sharedLoopGuard.noteResult(decision.receipt, pollStatus)
+      }
+      if (pollStatus === 'running') {
+        sharedLoopGuard.retract(decision.receipt)
+        return { result }
+      }
+      if (defer && decision.kind === 'block') {
+        return { deferredBlock: decision.message }
+      }
+      if (decision.kind === 'warn') {
+        return { result: appendLoopWarning(result, decision.message) }
+      }
+      return { result }
+    },
+  }
+}
+
 // Clears one tool's loop-guard residue for a session on the process-wide shared
 // guard. The completion-reminder bridges (channel router + TUI server) call this
 // for `subagent_output` when a backgrounded subagent finishes, so the next fetch

package/src/agent/session-origin.ts

@@ -630,9 +630,9 @@ function renderParticipants(
 // mention syntax) and Telegram (uses `@username`, where `authorId` is a
 // numeric id and NOT the username). See issue #188.
 //
-// Symptom in the wild before PR #183 + this fix: 돌쇠 addressing Winky as
-// "Winky님" (plain text) on Discord, which never trips Winky's `isBotMention`
-// check, so Winky observes silently and the conversation stalls. The
+// Symptom in the wild before PR #183 + this fix: Kiki addressing Momo as
+// "Momo님" (plain text) on Discord, which never trips Momo's `isBotMention`
+// check, so Momo observes silently and the conversation stalls. The
 // angle-id branch here is exactly the fix for that case; the at-username
 // and alias branches keep the platform contract honest for KakaoTalk and
 // Telegram instead of self-contradicting the per-adapter mention guidance

package/src/agent/subagent-drain.ts

@@ -0,0 +1,150 @@
+import type { Stream, Unsubscribe } from '@/stream'
+
+import type { LiveSubagentRegistry } from './live-subagents'
+import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from './subagent-completion-reminder'
+
+// Presence of this capability is the single signal that background spawning is
+// permitted from a subagent (see the spawn_subagent guard); absence keeps the
+// subagent a one-shot leaf. It carries everything the drain needs: the shared
+// Stream to listen on, the subagent's own sessionId to filter completions by,
+// and the registry that is the source of truth for child state.
+export type SubagentBackgroundDrain = {
+  stream: Stream
+  sessionId: string
+  liveRegistry: LiveSubagentRegistry
+}
+
+export type DrainPrompt = (text: string) => Promise<void>
+
+export type RunSubagentDrainOptions = {
+  drain: SubagentBackgroundDrain
+  prompt: DrainPrompt
+  // Cooperative cancellation: when this returns true the loop stops re-prompting
+  // and returns, letting the caller's timeout/abort path dispose the session.
+  cancelled?: () => boolean
+}
+
+// Re-prompts a subagent with its children's completion reminders until a fixed
+// point, called after the subagent's initial prompt resolves. The registry is
+// the source of truth; stream broadcasts are only wakeups, so a duplicated or
+// missed broadcast cannot corrupt termination (every iteration re-derives state
+// from the registry). Each child's reminder is delivered at most once (tracked
+// by taskId). Terminates only when no children are running AND none are
+// completed-but-undelivered; a child spawned during a reminder turn reappears as
+// `running` in the next snapshot and keeps the loop alive, so no separate
+// "spawned nothing" flag is needed. The watch MUST have been started before the
+// initial prompt (see `beginSubagentDrainWatch`) to close the lost-wakeup race.
+export async function runSubagentDrain(watch: SubagentDrainWatch, options: RunSubagentDrainOptions): Promise<void> {
+  const { drain, prompt, cancelled } = options
+  const delivered = new Set<string>()
+  try {
+    while (cancelled === undefined || !cancelled()) {
+      const pending = collectPendingReminders(drain, delivered)
+      if (pending.length === 0) {
+        if (!hasRunningChildren(drain)) return
+        // Children still running but none newly completed: wait for the next
+        // wakeup, then re-derive from the registry.
+        const woke = await watch.waitForWakeup()
+        if (!woke) return
+        continue
+      }
+      for (const reminder of pending) {
+        if (cancelled !== undefined && cancelled()) return
+        delivered.add(reminder.taskId)
+        await prompt(reminder.text)
+      }
+    }
+  } finally {
+    watch.stop()
+  }
+}
+
+type PendingReminder = { taskId: string; text: string }
+
+function collectPendingReminders(drain: SubagentBackgroundDrain, delivered: Set<string>): PendingReminder[] {
+  const children = drain.liveRegistry.list({ parentSessionId: drain.sessionId })
+  const pending: PendingReminder[] = []
+  for (const child of children) {
+    // Synchronous spawns return their result inline via the tool call; only
+    // background spawns deliver out-of-band and need a drain reminder.
+    if (child.background !== true) continue
+    if (child.status === 'running') continue
+    if (delivered.has(child.taskId)) continue
+    const completion = child.completion
+    const text = renderSubagentCompletionReminder({
+      subagent: child.subagentName,
+      taskId: child.taskId,
+      ok: child.status === 'completed',
+      durationMs: completion?.durationMs ?? 0,
+      ...(completion?.error !== undefined ? { error: completion.error } : {}),
+    })
+    pending.push({ taskId: child.taskId, text })
+  }
+  return pending
+}
+
+function hasRunningChildren(drain: SubagentBackgroundDrain): boolean {
+  // Only background children gate termination. A sync child still marked running
+  // in the registry settles via its inline tool call, never via a broadcast
+  // wakeup, so waiting on it would hang the drain forever.
+  return drain.liveRegistry
+    .list({ parentSessionId: drain.sessionId })
+    .some((c) => c.background === true && c.status === 'running')
+}
+
+export type SubagentDrainWatch = {
+  // Resolves true on a child-completion wakeup, false once stopped. A wakeup
+  // that arrives before anyone waits is latched (pendingWake), so a completion
+  // during the subagent's prompt is not lost.
+  waitForWakeup: () => Promise<boolean>
+  stop: () => void
+}
+
+export function beginSubagentDrainWatch(drain: SubagentBackgroundDrain): SubagentDrainWatch {
+  let stopped = false
+  let pendingWake = false
+  let resolveWaiter: ((woke: boolean) => void) | null = null
+
+  const wake = (): void => {
+    if (resolveWaiter !== null) {
+      const r = resolveWaiter
+      resolveWaiter = null
+      r(true)
+      return
+    }
+    pendingWake = true
+  }
+
+  const unsubscribe: Unsubscribe = drain.stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+    const parsed = parseSubagentCompletedPayload(msg.payload)
+    if (parsed === null) return
+    if (parsed.parentSessionId !== drain.sessionId) return
+    wake()
+  })
+
+  return {
+    waitForWakeup: () =>
+      new Promise<boolean>((resolve) => {
+        if (stopped) {
+          resolve(false)
+          return
+        }
+        if (pendingWake) {
+          pendingWake = false
+          resolve(true)
+          return
+        }
+        resolveWaiter = resolve
+      }),
+    stop: () => {
+      if (stopped) return
+      stopped = true
+      unsubscribe()
+      if (resolveWaiter !== null) {
+        const r = resolveWaiter
+        resolveWaiter = null
+        r(false)
+      }
+    },
+  }
+}

package/src/agent/subagents.ts

@@ -7,6 +7,12 @@ import type { Stream, Unsubscribe } from '@/stream'
 import { type AgentSession, createSession } from './index'
 import { subscribeProviderErrors } from './provider-error'
 import type { SessionOrigin } from './session-origin'
+import {
+  beginSubagentDrainWatch,
+  runSubagentDrain,
+  type SubagentBackgroundDrain,
+  type SubagentDrainWatch,
+} from './subagent-drain'
 import { renderTurnTimeAnchor } from './system-prompt'
 import type { ToolResultBudget } from './tool-result-budget'
 
@@ -48,6 +54,13 @@ export type SubagentShared<P = unknown> = {
   handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
   toolResultBudget?: ToolResultBudget
   visibility?: 'public' | 'internal'
+  // One-line purpose blurb for the main agent's "## Subagent orchestration"
+  // roster, rendered from the registry by `renderPublicSubagentRoster` instead
+  // of hand-maintained in the prompt (the drift that once left `researcher` and
+  // `planner` unlisted). Required for `visibility: 'public'`; ignored otherwise.
+  // On `SubagentShared` so the plugin→internal shim carries it via rest-spread
+  // (see `pluginSubagentShim`), like `visibility`.
+  rosterDescription?: string
   requiresSpecificPermission?: boolean
   // Opt-in: when true, this subagent's session is wired with the orchestration
   // tools (spawn_subagent/subagent_output/subagent_cancel) so it can delegate
@@ -55,6 +68,12 @@ export type SubagentShared<P = unknown> = {
   // registry scoping. Default (unset/false) keeps the subagent a leaf — the
   // historical contract for explorer/scout/memory-logger/etc.
   canSpawnSubagents?: boolean
+  // Opt-in: allow this subagent to spawn background children AND drain their
+  // completions back into its own session (requires canSpawnSubagents). Default
+  // (unset/false) keeps background spawns denied from this subagent — it must
+  // use synchronous spawns. Only meaningful when the runtime wires the drain
+  // capability (createSessionForSubagent provides stream+sessionId+liveRegistry).
+  canBackgroundSpawnSubagents?: boolean
   // Wall-clock ceiling on a single spawn, enforced at the orchestration
   // layer (both `dispatchSpawnSubagent` and the stream-driven
   // `SubagentConsumer`). When exceeded, the orchestrator's `await` settles
@@ -109,6 +128,7 @@ export type CreateSessionForSubagentResult = {
   agentDir?: string
   origin?: SessionOrigin
   getTranscriptPath?: () => string | undefined
+  backgroundDrain?: SubagentBackgroundDrain
 }
 export type CreateSessionForSubagentOptions = {
   name?: string
@@ -145,6 +165,7 @@ type NormalizedSubagentSession = {
   agentDir: string | undefined
   origin: SessionOrigin | undefined
   getTranscriptPath: (() => string | undefined) | undefined
+  backgroundDrain: SubagentBackgroundDrain | undefined
 }
 
 function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagentResult): NormalizedSubagentSession {
@@ -157,6 +178,7 @@ function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagen
       agentDir: result.agentDir,
       origin: result.origin,
       getTranscriptPath: result.getTranscriptPath,
+      backgroundDrain: result.backgroundDrain,
     }
   }
   return {
@@ -167,6 +189,7 @@ function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagen
     agentDir: undefined,
     origin: undefined,
     getTranscriptPath: undefined,
+    backgroundDrain: undefined,
   }
 }
 
@@ -207,14 +230,16 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
   }
 
   const runSession: RunSession = async (override) => {
-    const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath } = normalizeSubagentSession(
-      await createSessionForSubagent(subagent, sessionOptions),
-    )
+    const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath, backgroundDrain } =
+      normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
+    let aborted = false
+    let drainWatch: SubagentDrainWatch | undefined
     if (options.onSessionCreated !== undefined) {
       options.onSessionCreated({
         session,
         sessionId,
         abort: async () => {
+          aborted = true
           await session.abort()
         },
       })
@@ -232,6 +257,9 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       if (hooks && turnEvent !== undefined) {
         await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn })
       }
+      if (backgroundDrain !== undefined) {
+        drainWatch = beginSubagentDrainWatch(backgroundDrain)
+      }
       try {
         await session.prompt(`${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`)
       } finally {
@@ -239,6 +267,15 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
           await hooks.runSessionTurnEnd(turnEvent)
         }
       }
+      if (drainWatch !== undefined && backgroundDrain !== undefined) {
+        await runSubagentDrain(drainWatch, {
+          drain: backgroundDrain,
+          prompt: async (text) => {
+            await session.prompt(`${renderTurnTimeAnchor()}\n\n${text}`)
+          },
+          cancelled: () => aborted,
+        })
+      }
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionIdle({
           sessionId,
@@ -252,6 +289,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionEnd({ sessionId, ...(origin !== undefined ? { origin } : {}) })
       }
+      drainWatch?.stop()
       session.dispose()
       await dispose()
     }