@xingular/harness 0.1.7 → 2.0.0

package/src/sessions/sessions.ts

@@ -21,11 +21,13 @@ import { FIRST_PARTY_PLUGINS, firstPartyExtensions, type InlineExtension } from
 import * as registry from '../skills/registry'
 import { ASK_USER, askUserTool } from '../tools/askUser'
 import { PLUGIN_PROPOSE, pluginProposeTool } from '../tools/pluginPropose'
-import { SPAWN_SUBAGENT, SUBAGENT_RELATION, spawnSubagentTool, subagentDepth, type SubagentOptions } from '../tools/spawnSubagent'
+import { subagentTools } from '../tools/spawnSubagent'
 import { WIKI_TOOL_NAMES } from '../tools/definitions'
 import { memoryTools } from '../tools/memoryTools'
 import type { ToolProvider, ToolSession, ToolSpec } from '../tools/types'
 import type { RunRecord } from './contracts'
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, subagentDepth, subagentHistory, subagentNesting, type SubagentInput, type SubagentOptions } from './subagents'
+import type { Subagents } from './subagentService'
 import { selectHistory } from './history'
 import { runLineageJoin } from './lineageJoin'
 import type { ToolPolicy } from './policy'
@@ -67,7 +69,7 @@ export interface SessionRunInput {
   capabilities?: CapabilitySet
   /** Hops from the user to this session (0 when the user started it). */
   depth?: number
-  /** Offer `spawn_subagent`: the model may start child runs of this caller, up to this depth. */
+  /** Interactive default: native child tools. Null disables; unattended callers must opt in. */
   subagents?: SubagentOptions | null
   /** Ask the application's tool providers for tools (the default). False runs with the harness's own tools only. */
   providers?: boolean
@@ -80,6 +82,7 @@ export interface SessionBroker {
 }
 
 export interface SessionsOptions {
+  subagents: Subagents
   env: DispatchEnv
   accounts: Accounts
   runs: RunRegistry
@@ -105,6 +108,7 @@ export class Sessions {
 
   constructor(private readonly options: SessionsOptions) {
     this.factory = options.factory ?? piSessionFactory
+
   }
 
   private get env(): HarnessEnv {
@@ -151,33 +155,9 @@ export class Sessions {
     }
   }
 
-  /** `spawn_subagent` for a run: each child is this caller again, one hop deeper, with no more tools than the parent. */
-  private subagentTool(input: SessionRunInput, runId: string, accountId: string, parent: CapabilitySet): ToolSpec {
-    const parentTools = parent.tools.filter((name) => name !== SPAWN_SUBAGENT)
-    return spawnSubagentTool({
-      root: this.env.root,
-      parentRunId: runId,
-      parentSessionId: input.run.sessionId,
-      parentTools,
-      sessionDir: input.sessionDir,
-      start: (child) => this.run({
-        ...input,
-        run: { ...input.run, id: child.runId, sessionId: child.sessionId, parentRunId: runId, relation: SUBAGENT_RELATION, goal: takeChars(child.brief, 4000), resumedFromRunId: null, handoffId: null },
-        accountId,
-        poolId: null,
-        sessionDir: child.sessionDir,
-        resume: null,
-        text: child.brief,
-        images: undefined,
-        requiresImageInput: false,
-        preamble: null,
-        caller: { ...input.caller, runId: undefined, sessionId: child.sessionId },
-        tools: { allow: [...child.tools, SPAWN_SUBAGENT], gated: (input.tools.gated ?? []).filter((name) => child.tools.includes(name)) },
-        // Never wider than the parent's frozen set; the session intersects it with what is available now.
-        capabilities: { ...parent, tools: [...parent.tools.filter((name) => child.tools.includes(name)), SPAWN_SUBAGENT] },
-        depth: (input.depth ?? 0) + 1
-      })
-    })
+  /** Compatibility alias for the shared native service. */
+  spawnSubagent(request: SubagentInput): Promise<{ runId: string; nativeSessionId: string | null }> {
+    return this.options.subagents.spawn(request)
   }
 
   /**
@@ -187,6 +167,7 @@ export class Sessions {
   async run(input: SessionRunInput): Promise<{ runId: string; nativeSessionId: string | null }> {
     const { root } = this.env
     if (!input?.run?.id || !input.run.sessionId || typeof input.text !== 'string') throw invalid('A session turn needs a run id, a session, and text.')
+    input = structuredClone(input)
     const historyFile = selectHistory({ sessionDir: input.sessionDir, resume: input.resume })
     const account = this.options.accounts.resolve(input.accountId, input.poolId)
     const context = this.options.accounts.context(account)
@@ -194,14 +175,14 @@ export class Sessions {
     const caller: CallerContext = { ...input.caller, maintenanceJobIds: input.caller.maintenanceJobIds?.slice(), runId, sessionId: input.caller.sessionId ?? input.run.sessionId }
     const broker = input.connections ? this.options.broker : null
     const depth = input.depth ?? 0
-    const canSpawn = Boolean(input.subagents) && depth < subagentDepth(input.subagents ?? undefined)
+    const canSpawn = input.subagents !== null && (!input.automatic || input.subagents !== undefined) && subagentNesting(root, input.run) < subagentDepth(input.subagents ?? undefined)
     const requestedTools = [...new Set([
-      ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT),
+      ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT && name !== WAIT_SUBAGENTS),
       ASK_USER,
       ...(input.automatic ? [] : [PLUGIN_PROPOSE]),
       ...WIKI_TOOL_NAMES,
       ...(broker?.toolNames ?? []),
-      ...(canSpawn ? [SPAWN_SUBAGENT] : [])
+      ...(canSpawn ? [SPAWN_SUBAGENT, WAIT_SUBAGENTS] : [])
     ])]
     const available = this.options.resolveCapabilities
       ? await this.options.resolveCapabilities(caller, requestedTools, input.cwd)
@@ -278,18 +259,19 @@ export class Sessions {
     const session: ToolSession = { run, caller, allow, depth, cwd: input.cwd, capabilities }
     const { plugins } = this.options
 
-    let pi: PiSessionLike
+    let pi: PiSessionLike | undefined
     try {
       const tools: ToolSpec[] = [
         ...(broker ? broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) : []),
         ...memoryTools(this.options.env, caller, capabilities.contributions),
         askUserTool(run),
         pluginProposeTool(this.options.env, caller),
-        ...(allow.includes(SPAWN_SUBAGENT) ? [this.subagentTool(input, runId, account.id, capabilities)] : [])
+        ...subagentTools(this.options.subagents, runId).filter(tool => allow.includes(tool.name))
       ]
       if (input.providers !== false) for (const provider of this.providers) tools.push(...(await provider(session)))
       const params: TurnParams = {
         runId,
+        restrictTools: input.run.relation === 'subagent',
         cwd: input.cwd,
         sessionDir: input.sessionDir,
         historyFile,
@@ -302,7 +284,7 @@ export class Sessions {
         automatic: input.automatic,
         account: context,
         resources: registry.resources(root, caller.projectId ?? null, caller.agentId ?? null, capabilities.contributions),
-        inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId)],
+        inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId), this.options.subagents.extension(runId)],
         ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
         system,
         update
@@ -310,25 +292,35 @@ export class Sessions {
       pi = await this.factory({
         params,
         allow,
-        gate: this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name)))),
+        gate: (() => {
+          const gate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))))
+          return { ...gate, check: (name: string, args: unknown) => input.run.relation === 'subagent' && !capabilities.tools.includes(name) ? Promise.resolve('This tool is outside the child capability snapshot.') : gate.check(name, args) }
+        })(),
         tools,
         runtime: () => this.options.accounts.runtime(context),
         // An unattended run loads no extension, so it has nobody to relay for.
         ...(input.automatic ? {} : { extensions: { ask: (question) => run.requestAnswer(question), notice: (notice) => run.emit('extension.notice', notice) } })
       })
-      if ((input.requiresImageInput || input.images?.length) && !pi.model?.input.includes('image')) {
+      if (run.finished) {
         pi.dispose()
+        return { runId, nativeSessionId: null }
+      }
+      if ((input.requiresImageInput || input.images?.length) && !pi.model?.input.includes('image')) {
         throw new HarnessError('image_input_unsupported', 'Choose a model that supports images, or remove the image attachments and send again.')
       }
       if (input.resume?.nativeSessionId && pi.sessionId !== input.resume.nativeSessionId) {
-        pi.dispose()
         run.finish('failed', { code: 'native_resume_unavailable', message: 'The saved conversation could not be restored.' })
         throw new HarnessError('native_resume_unavailable', 'The saved conversation could not be restored.')
       }
-      updateRun(root, runId, (record) => void (record.nativeSessionId = pi.sessionId))
+      const opened = pi
+      updateRun(root, runId, (record) => void (record.nativeSessionId = opened.sessionId))
+      this.options.subagents.register(input, account.id, capabilities, Boolean(pi.sessionManager))
+      if (pi.model?.id && pi.model.provider) this.options.subagents.resolvedModel(runId, `${pi.model.provider}/${pi.model.id}`, pi.thinkingLevel)
+      params.settle = () => this.options.subagents.verify(runId, opened.sessionManager ? subagentHistory(opened.sessionManager.getBranch()) : undefined)
       void runTurn(run, pi, params)
       return { runId, nativeSessionId: pi.sessionId }
     } catch (error) {
+      pi?.dispose()
       if (error instanceof HarnessError && error.code === 'native_resume_unavailable') throw error
       const message = error instanceof Error ? error.message : String(error)
       log('session failed to start', message)

package/src/sessions/subagentService.test.ts

@@ -0,0 +1,159 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { memorySecretStore } from '../accounts/secrets'
+import { createHarness, type Harness } from '../harness'
+import type { SessionRunInput } from './sessions'
+import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, subagentHistory } from './subagents'
+import { loadRun, recordSubagent, saveRun } from './runStore'
+
+const open: Harness[] = []
+afterEach(async () => { for (const harness of open.splice(0)) await harness.close() })
+
+function setup() {
+  const finish = new Map<string, (text: string) => void>()
+  const root = mkdtempSync(join(tmpdir(), 'native-subagents-'))
+  const harness = createHarness({ dataRoot: join(root, 'data'), stateDir: join(root, 'state'), secrets: memorySecretStore(), sessionFactory: async ({ params }) => {
+    let emit: (event: any) => void = () => {}
+    let done: () => void = () => {}
+    return { sessionId: 'native-history', subscribe: (listener) => { emit = listener; return () => {} }, sendCustomMessage: async () => {},
+      prompt: () => new Promise<void>((resolve) => { done = resolve; finish.set(params.runId, (text) => {
+        emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text }] } }); resolve()
+      }) }), abort: async () => done(), dispose: () => {} }
+  } })
+  open.push(harness)
+  harness.accounts.create('Main', 'apiKey')
+  const start = (id: string, extra: Partial<SessionRunInput> = {}) => harness.sessions.run({
+    run: { id, sessionId: 'opaque-parent' }, caller: { agentId: 'caller', actor: 'Chat' }, cwd: root,
+    sessionDir: join(root, 'history'), text: 'Parent', tools: { allow: ['read'] }, ...extra
+  })
+  return { harness, finish, start }
+}
+const empty = () => ({ owners: [], receipts: [] })
+
+describe('native subagent ownership and delivery', () => {
+  it('spawns asynchronously, joins selected children, and rejects foreign handles', async () => {
+    const { harness, finish, start } = setup()
+    await start('parent')
+    const a = await harness.subagents.spawn({ parentRunId: 'parent', brief: 'First', tools: ['read'] })
+    const b = await harness.subagents.spawn({ parentRunId: 'parent', brief: 'Second', tools: [] })
+    expect(harness.subagents.results({ parentRunId: 'parent' }).map(result => result.status)).toEqual(['running', 'running'])
+    await expect(harness.subagents.wait({ parentRunId: 'parent', runIds: ['foreign'] })).rejects.toMatchObject({ code: 'invalid_request' })
+    let joined = false
+    const pending = harness.subagents.wait({ parentRunId: 'parent', runIds: [b.runId] }).then(results => { joined = true; return results })
+    finish.get(a.runId)!('First result')
+    await harness.runs.wait(a.runId)
+    expect(joined).toBe(false)
+    const canceled = new AbortController()
+    canceled.abort()
+    await expect(harness.subagents.wait({ parentRunId: 'parent', runIds: [b.runId] }, canceled.signal)).rejects.toMatchObject({ code: 'run_not_active' })
+    finish.get(b.runId)!('Second result')
+    expect(await pending).toMatchObject([{ runId: b.runId, status: 'completed', text: 'Second result' }])
+    expect(loadRun(harness.env.root, a.runId).sessionId).not.toContain(':subagent:')
+  })
+
+  it('delivers already-settled results, retries uncommitted drafts, and trusts only typed receipts', async () => {
+    const { harness, finish, start } = setup()
+    await start('parent')
+    const child = await harness.subagents.spawn({ parentRunId: 'parent', brief: 'Find evidence' })
+    finish.get(child.runId)!('Evidence')
+    await harness.runs.wait(child.runId)
+    const mentioned = subagentHistory([{ content: `I mentioned ${child.runId}` }])
+    const first = await harness.subagents.delivery('parent', mentioned, true)
+    expect(first?.text).toContain('Evidence')
+    expect(await harness.subagents.delivery('parent', empty(), true)).toEqual(first)
+    const committed = subagentHistory([{ type: 'custom_message', details: { [SUBAGENT_RECEIPT]: first!.receipt } }])
+    expect(await harness.subagents.delivery('parent', committed, true)).toBeNull()
+  })
+
+  it('waits before final delivery and releases pending joins when the parent stops', async () => {
+    const { harness, start } = setup()
+    await start('parent')
+    const child = await harness.subagents.spawn({ parentRunId: 'parent', brief: 'Wait' })
+    const pending = harness.subagents.delivery('parent', empty(), true)
+    const interrupted = expect(pending).rejects.toMatchObject({ code: 'run_not_active' })
+    await harness.runs.interrupt('parent')
+    await interrupted
+    expect(loadRun(harness.env.root, child.runId).status).toBe('interrupted')
+    expect(harness.subagents.results({ parentRunId: 'parent' })).toMatchObject([{ runId: child.runId, status: 'interrupted' }])
+  })
+
+  it('recovers a child whose spawn return was lost, only from its owning history and account', async () => {
+    const { harness, finish, start } = setup()
+    await start('original')
+    const child = await harness.subagents.spawn({ parentRunId: 'original', brief: 'Recover' })
+    finish.get(child.runId)!('Retained result')
+    await harness.runs.wait(child.runId)
+    recordSubagent(harness.env.root, 'original', 'reserved-before-crash')
+    await harness.runs.interrupt('original')
+    await start('resumed')
+    expect(await harness.subagents.delivery('resumed', empty(), true)).toBeNull()
+    const branch = subagentHistory([{ type: 'custom', customType: SUBAGENT_OWNER, data: { runId: 'original' } }])
+    const recovered = await harness.subagents.delivery('resumed', branch, true)
+    expect(recovered?.text).toContain('Retained result')
+    expect(recovered?.receipt.delivered).toEqual([child.runId, 'reserved-before-crash'])
+    expect(loadRun(harness.env.root, 'reserved-before-crash')).toMatchObject({ status: 'interrupted', relation: 'subagent', parentRunId: 'original' })
+    await harness.runs.interrupt('resumed')
+    const other = harness.accounts.create('Other', 'apiKey').accounts.find(account => account.label === 'Other')!
+    await start('wrong-account', { accountId: other.id })
+    expect(await harness.subagents.delivery('wrong-account', branch, true)).toBeNull()
+  })
+
+  it('reconstructs disk ownership after reopening without automatically restarting model work', async () => {
+    const { harness, finish, start } = setup()
+    await start('original')
+    const child = await harness.subagents.spawn({ parentRunId: 'original', brief: 'Persisted work' })
+    finish.get(child.runId)!('On-disk result')
+    await harness.runs.wait(child.runId)
+    recordSubagent(harness.env.root, 'original', 'orphan-after-crash')
+    const original = loadRun(harness.env.root, 'original')
+    saveRun(harness.env.root, { ...original, id: 'orphan-after-crash', sessionId: 'orphan-session', parentRunId: 'original', relation: 'subagent', status: 'running' })
+    const dataRoot = harness.env.root
+    const stateDir = harness.stateDir
+    await harness.close()
+    open.splice(open.indexOf(harness), 1)
+    let opened = 0
+    const restarted = createHarness({ dataRoot, stateDir, secrets: memorySecretStore(), sessionFactory: async () => {
+      opened++
+      return { sessionId: 'native-history', subscribe: () => () => {}, prompt: async () => new Promise<void>(() => {}), sendCustomMessage: async () => {}, abort: async () => {}, dispose: () => {} }
+    } })
+    open.push(restarted)
+    expect(opened).toBe(0)
+    expect(loadRun(dataRoot, 'orphan-after-crash').status).toBe('interrupted')
+    await restarted.sessions.run({ run: { id: 'explicit-resume', sessionId: original.sessionId, resumedFromRunId: original.id }, caller: { agentId: 'caller', actor: 'Chat' }, cwd: original.workingDirectory!, sessionDir: join(original.workingDirectory!, 'history'), text: 'Resume', tools: { allow: ['read'] } })
+    const delivery = await restarted.subagents.delivery('explicit-resume', { owners: ['original'], receipts: [] }, true)
+    expect(delivery?.text).toContain('On-disk result')
+    expect(delivery?.receipt.delivered).toEqual([child.runId, 'orphan-after-crash'])
+    expect(opened).toBe(1)
+  })
+
+  it('enables interactive callers at a host depth without extending native nesting or unattended access', async () => {
+    const { harness, start } = setup()
+    await start('host-depth', { depth: 3 })
+    const child = await harness.subagents.spawn({ parentRunId: 'host-depth', brief: 'One native level' })
+    await expect(harness.subagents.spawn({ parentRunId: child.runId, brief: 'Too deep' })).rejects.toMatchObject({ code: 'invalid_request' })
+    await harness.runs.interrupt('host-depth')
+    await start('unattended', { automatic: true })
+    await expect(harness.subagents.spawn({ parentRunId: 'unattended', brief: 'Not enabled' })).rejects.toMatchObject({ code: 'invalid_request' })
+  })
+
+  it('does not acknowledge results omitted from a bounded delivery batch', async () => {
+    const { harness, finish, start } = setup()
+    await start('parent')
+    const children = await Promise.all([1, 2, 3].map(n => harness.subagents.spawn({ parentRunId: 'parent', brief: String(n) })))
+    for (const child of children) finish.get(child.runId)!('x'.repeat(16_000))
+    await harness.subagents.wait({ parentRunId: 'parent' })
+    const receipts: any[] = []
+    const delivered: string[] = []
+    for (let i = 0; i < 3; i++) {
+      const batch = await harness.subagents.delivery('parent', { owners: [], receipts }, true)
+      expect(batch).not.toBeNull()
+      delivered.push(...batch!.receipt.delivered!)
+      receipts.push(batch!.receipt)
+    }
+    expect(delivered).toEqual(children.map(child => child.runId))
+    expect(await harness.subagents.delivery('parent', { owners: [], receipts }, true)).toBeNull()
+  })
+})

package/src/sessions/subagentService.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import { loadRun as loadCapabilities } from '../capabilities/runSnapshot'
+import type { CapabilitySet } from '../capabilities/types'
+import type { HarnessEnv } from '../core/env'
+import { HarnessError, invalid } from '../core/errors'
+import { now } from '../core/fs'
+import { takeChars } from '../core/text'
+import type { InlineExtension } from '../plugins/firstParty'
+import type { RunRegistry } from './registry'
+import type { Effort } from './runner'
+import type { SessionRunInput } from './sessions'
+import { isActiveStatus } from './contracts'
+import { findRun, loadRun, readEvents, recordedSubagents, recordSubagent, saveRun } from './runStore'
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory, type SubagentInput, type SubagentReceipt, type SubagentResult, type SubagentSelection } from './subagents'
+
+type Started = { runId: string; nativeSessionId: string | null }
+interface Parent {
+  input: SessionRunInput
+  accountId: string
+  capabilities: CapabilitySet
+  stopped: AbortController
+  recovered: Set<string>
+  launching: Map<string, Promise<Started>>
+  ready: Promise<void>
+  started: () => void
+}
+export interface SubagentHistory {
+  owners: string[]
+  receipts: SubagentReceipt[]
+}
+
+function until<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    void promise.catch(() => {})
+    return Promise.reject(new HarnessError('run_not_active', 'The parent run stopped.'))
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new HarnessError('run_not_active', 'The parent run stopped.'))
+    signal.addEventListener('abort', abort, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+  })
+}
+
+/** One owner of native child execution and delivery, shared by SDK and terminal adapters. */
+export class Subagents {
+  private readonly parents = new Map<string, Parent>()
+
+  constructor(private readonly env: HarnessEnv, private readonly runs: RunRegistry, private readonly launch: (input: SessionRunInput) => Promise<Started>) {
+    runs.listen((event) => {
+      if (event.type !== 'completed' && event.type !== 'failed' && !(event.type === 'status.changed' && (event.payload as { status?: string }).status === 'interrupted')) return
+      this.parents.get(event.runId)?.stopped.abort()
+      this.parents.delete(event.runId)
+      if (event.type !== 'completed') for (const id of runs.activeRunIds()) {
+        const child = findRun(this.env.root, id)
+        if (child?.relation === SUBAGENT_RELATION && child.parentRunId === event.runId) void runs.interrupt(id).catch(() => {})
+      }
+    })
+  }
+
+  /** Internal adapter contract: context comes from a live run, never from model arguments. */
+  register(input: SessionRunInput, accountId: string, capabilities: CapabilitySet, deferUntilPrompt = false): void {
+    if (!this.runs.active(input.run.id)) throw new HarnessError('run_not_active', 'The parent run is not active.')
+    if (this.parents.has(input.run.id)) return
+    const frozen = loadCapabilities(this.env.root, input.run.id)
+    if (!frozen) throw invalid('A native parent requires a frozen capability snapshot.')
+    const ceiling: CapabilitySet = {
+      version: 1,
+      tools: capabilities.tools.filter(name => frozen.tools.includes(name)),
+      connectors: capabilities.connectors.filter(id => frozen.connectors.includes(id)),
+      contributions: capabilities.contributions.filter(id => frozen.contributions.includes(id))
+    }
+    let started!: () => void
+    const ready = new Promise<void>(resolve => { started = resolve })
+    if (!deferUntilPrompt) started()
+    this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() })
+  }
+
+  resolvedModel(runId: string, model: string, effort?: Effort): void {
+    const parent = this.parents.get(runId)
+    if (parent) {
+      parent.input.model = model
+      parent.input.effort = effort ?? parent.input.effort
+    }
+  }
+
+  private parent(runId: string): Parent {
+    const parent = this.parents.get(runId)
+    if (!parent || !this.runs.active(runId)) throw new HarnessError('run_not_active', 'The parent run is not accepting subagents.')
+    return parent
+  }
+
+  async spawn(request: SubagentInput): Promise<Started> {
+    const parent = this.parent(request.parentRunId)
+    const { input, accountId, capabilities } = parent
+    if (!capabilities.tools.includes(SPAWN_SUBAGENT)) throw invalid('Subagents are not enabled for this run.')
+    const brief = typeof request.brief === 'string' ? request.brief.trim() : ''
+    if (!brief) throw invalid('Give the subagent a brief.')
+    if (request.wait !== undefined && typeof request.wait !== 'boolean') throw invalid('wait must be a boolean.')
+    if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some((name) => typeof name !== 'string'))) throw invalid('Tools must be an array of tool names.')
+    const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? []
+    if (outside.length) throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`)
+    const tools = capabilities.tools.filter((name) => !request.tools || request.tools.includes(name))
+    await until(parent.ready, parent.stopped.signal)
+    const runId = randomUUID()
+    const sessionId = randomUUID()
+    recordSubagent(this.env.root, request.parentRunId, runId)
+    const child: SessionRunInput = {
+      ...input,
+      run: { ...input.run, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), attachmentCount: 0, resumedFromRunId: null, handoffId: null },
+      accountId, poolId: null, sessionDir: join(input.sessionDir, 'subagents', runId), resume: null,
+      text: brief, images: undefined, requiresImageInput: false, preamble: null,
+      caller: { ...input.caller, runId: undefined, sessionId },
+      tools: { allow: tools, gated: (input.tools.gated ?? []).filter((name) => tools.includes(name)) },
+      capabilities: { ...capabilities, tools }, depth: (input.depth ?? 0) + 1
+    }
+    const started = this.launch(child).catch((error) => {
+      if (!findRun(this.env.root, runId)) {
+        const source = loadRun(this.env.root, request.parentRunId)
+        saveRun(this.env.root, { ...source, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: takeChars(brief, 4000), attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.' })
+      }
+      return { runId, nativeSessionId: null }
+    })
+    parent.launching.set(runId, started)
+    void started.finally(() => parent.launching.delete(runId))
+    const result = await until(started, parent.stopped.signal)
+    if (request.wait) await this.wait({ parentRunId: request.parentRunId, runIds: [runId] })
+    return result
+  }
+
+  private selected(selection: SubagentSelection, parent?: Parent): string[] {
+    const owned = new Set([...recordedSubagents(this.env.root, selection.parentRunId), ...(parent?.recovered ?? [])])
+    if (selection.runIds !== undefined && (!Array.isArray(selection.runIds) || selection.runIds.some((id) => typeof id !== 'string'))) throw invalid('runIds must be an array of child run IDs.')
+    const ids = [...new Set(selection.runIds ?? [...owned])]
+    if (ids.some((id) => !owned.has(id))) throw invalid('Select only subagents owned by this parent.')
+    return ids
+  }
+
+  results(selection: SubagentSelection): SubagentResult[] {
+    loadRun(this.env.root, selection.parentRunId)
+    const parent = this.parents.get(selection.parentRunId)
+    return this.selected(selection, parent).map((runId) => {
+      const run = findRun(this.env.root, runId)
+      const reply = run && readEvents(this.env.root, runId).filter((event) => event.type === 'message.completed' && (event.payload as { role?: unknown }).role === 'assistant').at(-1)
+      const payload = reply?.payload as { text?: string } | undefined
+      return { runId, status: run?.status ?? 'queued', text: takeChars(payload?.text ?? '', 16_000), terminalReason: run?.terminalReason ?? null }
+    })
+  }
+
+  async wait(selection: SubagentSelection, signal?: AbortSignal): Promise<SubagentResult[]> {
+    const parent = this.parent(selection.parentRunId)
+    const ids = this.selected(selection, parent)
+    const abort = signal ? AbortSignal.any([signal, parent.stopped.signal]) : parent.stopped.signal
+    await until(Promise.all(ids.map(async (id) => {
+      const starting = parent.launching.get(id)
+      if (starting) await starting
+      const run = findRun(this.env.root, id)
+      if (run && isActiveStatus(run.status)) await this.runs.wait(id, abort)
+    })), abort)
+    return this.results({ ...selection, runIds: ids })
+  }
+
+  /** Reconcile only owners present on the selected native branch, with matching account and caller. */
+  restore(parentRunId: string, history: SubagentHistory): void {
+    const parent = this.parent(parentRunId)
+    const current = loadRun(this.env.root, parentRunId)
+    for (const owner of history.owners) {
+      if (owner === parentRunId) continue
+      const old = findRun(this.env.root, owner)
+      if (!old || old.sessionId !== current.sessionId || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId) continue
+      for (const id of recordedSubagents(this.env.root, owner)) {
+        let child = findRun(this.env.root, id)
+        if (!child) {
+          // The process can die after reserving ownership but before sessions.run saves the child.
+          saveRun(this.env.root, { ...old, id, sessionId: id, parentRunId: owner, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: null, attachmentCount: 0, status: 'interrupted', startedAt: now(), endedAt: now(), terminalReason: 'Subagent startup was interrupted before its session opened.' })
+          child = findRun(this.env.root, id)
+        }
+        if (child?.parentRunId === owner && child.relation === SUBAGENT_RELATION && child.accountId === current.accountId) parent.recovered.add(id)
+      }
+    }
+  }
+
+  async delivery(parentRunId: string, history: SubagentHistory, settle: boolean, signal?: AbortSignal): Promise<{ text: string; receipt: SubagentReceipt } | null> {
+    const parent = this.parent(parentRunId)
+    this.restore(parentRunId, history)
+    if (settle) {
+      // A host may start another child while earlier children are settling.
+      for (;;) {
+        await this.wait({ parentRunId }, signal)
+        if (!parent.launching.size && this.results({ parentRunId }).every((result) => !isActiveStatus(result.status))) break
+      }
+    }
+    const delivered = new Set(history.receipts.flatMap((receipt) => receipt.delivered ?? []))
+    const pending = this.results({ parentRunId }).filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId))
+    const chunks: string[] = []
+    const ids: string[] = []
+    let size = 0
+    for (const result of pending) {
+      const text = `Subagent run ${result.runId} · ${result.status}\n${result.text || result.terminalReason || 'No written reply.'}`
+      if (size + text.length > 32_000 && ids.length) break
+      chunks.push(text)
+      ids.push(result.runId)
+      size += text.length
+    }
+    return ids.length ? { text: chunks.join('\n\n'), receipt: { version: 1, ownerRunId: parentRunId, delivered: ids } } : null
+  }
+
+  /** A broken adapter must fail visibly rather than complete with an undelivered child result. */
+  async verify(parentRunId: string, history?: SubagentHistory): Promise<void> {
+    if (history) this.restore(parentRunId, history)
+    await this.wait({ parentRunId })
+    if (history && await this.delivery(parentRunId, history, false)) throw new HarnessError('subagent_delivery_failed', 'A child result was not persisted in this conversation. Resume this reply to recover it.')
+  }
+
+  extension(runId: string): InlineExtension {
+    return { name: 'native-subagents', factory: (pi: ExtensionAPI) => {
+      pi.on('before_agent_start', (_event, ctx) => {
+        if (!this.parents.has(runId)) return
+        this.restore(runId, subagentHistory(ctx.sessionManager.getBranch()))
+        pi.appendEntry(SUBAGENT_OWNER, { runId })
+        this.parent(runId).started()
+      })
+      const deliver = async (event: any, ctx: any, settle: boolean) => {
+        if (!this.parents.has(runId) || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
+        const history = subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries])
+        const result = await this.delivery(runId, history, settle, ctx.signal)
+        if (!result) return
+        return { entries: [...event.entries, { type: 'custom_message' as const, customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true }
+      }
+      pi.on('turn_end', (event, ctx) => deliver(event, ctx, false))
+      pi.on('agent_before_settle', (event, ctx) => deliver(event, ctx, true))
+    } }
+  }
+}