@xingular/harness 0.1.7 → 2.1.0

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))
+    } }
+  }
+}

package/src/sessions/subagents.ts

@@ -0,0 +1,97 @@
+import { takeChars } from '../core/text'
+import { findRun, loadRun, readEvents } from './runStore'
+
+export const SPAWN_SUBAGENT = 'spawn_subagent'
+export const WAIT_SUBAGENTS = 'wait_subagents'
+export const SUBAGENT_RELATION = 'subagent'
+
+/** How deep subagents may nest when the caller does not say. */
+export const DEFAULT_SUBAGENT_DEPTH = 1
+export const MAX_SUBAGENT_DEPTH = 3
+
+export interface SubagentOptions {
+  /** Maximum consecutive native subagent levels below a caller (1 to 3). */
+  maxDepth?: number
+}
+
+export function subagentDepth(options: SubagentOptions | undefined): number {
+  const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH)
+  return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH))
+}
+
+export interface SubagentInput {
+  parentRunId: string
+  brief: string
+  tools?: string[]
+  wait?: boolean
+}
+
+export interface SubagentSelection {
+  parentRunId: string
+  runIds?: string[]
+}
+
+export interface SubagentResult {
+  runId: string
+  status: string
+  text: string
+  terminalReason: string | null
+}
+
+export interface SubagentReceipt {
+  version: 1
+  ownerRunId: string
+  spawned?: string[]
+  delivered?: string[]
+}
+
+export const SUBAGENT_RECEIPT = 'xingularSubagents'
+export const SUBAGENT_OWNER = 'xingular-subagent-owner'
+export const SUBAGENT_RESULTS = 'xingular-subagent-results'
+
+/** Read explicit native metadata, including entries retained before compaction. */
+export function subagentHistory(entries: readonly unknown[]): { owners: string[]; receipts: SubagentReceipt[] } {
+  const owners: string[] = []
+  const receipts: SubagentReceipt[] = []
+  for (const raw of entries) {
+    if (!raw || typeof raw !== 'object') continue
+    const entry = raw as Record<string, any>
+    if (entry.type === 'custom' && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === 'string') owners.push(entry.data.runId)
+    const message = entry.type === 'message' ? entry.message : entry
+    const receipt = message?.details?.[SUBAGENT_RECEIPT]
+    if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== 'string') continue
+    const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every((id) => typeof id === 'string')
+    if ((receipt.spawned !== undefined && !strings(receipt.spawned)) || (receipt.delivered !== undefined && !strings(receipt.delivered))) continue
+    receipts.push(receipt)
+  }
+  return { owners, receipts }
+}
+
+/** Native nesting is independent of a host's other uses of the generic caller depth. */
+export function subagentNesting(root: string, run: { relation?: string | null; parentRunId?: string | null }): number {
+  let current: typeof run = run
+  let depth = 0
+  const visited = new Set<string>()
+  while (current.relation === SUBAGENT_RELATION) {
+    const parent = current.parentRunId
+    if (!parent || visited.has(parent)) return MAX_SUBAGENT_DEPTH
+    visited.add(parent)
+    depth++
+    const record = findRun(root, parent)
+    if (!record) return MAX_SUBAGENT_DEPTH
+    current = record
+  }
+  return depth
+}
+
+/** The child's final reply, or why it ended without one. */
+export function subagentReport(root: string, runId: string): string {
+  const run = loadRun(root, runId)
+  const reply = readEvents(root, runId).filter((event) => event.type === 'message.completed' && (event.payload as { role?: unknown }).role === 'assistant').at(-1)
+  const text = typeof (reply?.payload as { text?: unknown } | undefined)?.text === 'string' ? takeChars((reply!.payload as { text: string }).text, 16_000) : ''
+  const lines = [`Subagent run ${runId} · ${run.status}`]
+  if (text) lines.push(`Result:\n${text}`)
+  else if (run.status === 'completed') lines.push('It finished without a written reply.')
+  if (run.status !== 'completed' && run.terminalReason) lines.push(`Stopped because: ${run.terminalReason}`)
+  return lines.join('\n')
+}

package/src/terminal/controller.ts

@@ -12,6 +12,8 @@ export interface PolicyReply {
   allowed: boolean
   reason?: string | null
   requiresApproval?: boolean
+  rememberable?: boolean
+  standing?: 'full' | 'switch' | 'none'
 }
 
 export interface ControllerHooks {
@@ -21,6 +23,8 @@ export interface ControllerHooks {
   begin(input: { reservedRunId: string | null; nativeTurnId: string; text: string }): ActiveRun
   /** Whether a native tool call may run. */
   policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>
+  /** Saves a user-selected tool grant in the shared local approval store. */
+  allowToolGlobally(target: string): void
   /** The native conversation identity changed. */
   native(nativeSessionId: string): void
   telemetry(event: string): void
@@ -148,18 +152,23 @@ export class TerminalController {
   }
 
   /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
-  observe(event: RunEvent): void {
-    if (this.disposed || event.runId !== this.activeRun?.runId) return
+  observe(event: RunEvent, descendant = false): void {
+    if (this.disposed || !this.activeRun || (!descendant && event.runId !== this.activeRun.runId)) return
     if (event.type === 'question.requested') {
       const payload = event.payload as Record<string, unknown>
-      this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId })
+      this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId })
+    } else if (descendant && event.type === 'approval.requested') {
+      const payload = event.payload as Record<string, unknown>
+      if (!payload.automatic) this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId })
+    } else if (event.type === 'approval.resolved') {
+      this.pending.delete(String((event.payload as { approvalId: string }).approvalId))
     } else if (event.type === 'question.answered') {
       this.pending.delete(String((event.payload as { questionId: string }).questionId))
     }
   }
 
   /** The socket grants this interface only to the process that owns terminal input. */
-  control(call: string, data: Record<string, any>): unknown {
+  async control(call: string, data: Record<string, any>): Promise<unknown> {
     if (this.disposed) throw new HarnessError('terminal_not_ready', 'This terminal has ended.')
     if (call === 'terminal.draft') {
       this.dirty = data.dirty === true
@@ -168,12 +177,18 @@ export class TerminalController {
     }
     if (call === 'terminal.pending') return { requests: [...this.pending.values()] }
     if (call === 'terminal.interrupt') return this.activeRun && this.hooks.interrupt ? this.hooks.interrupt(this.activeRun.runId) : {}
+    if (call === 'terminal.policy') {
+      const run = this.activeRun
+      if (!run || typeof data.tool !== 'string' || !data.tool) throw new HarnessError('invalid_request', 'An active run and tool name are required.')
+      return this.hooks.policy(run, data.tool, data.args ?? {})
+    }
+    if (call === 'terminal.approval') return this.requestNativeApproval(data)
     if (call === 'terminal.answers' && this.hooks.answerQuestions) {
       const run = this.activeRun
       const batchId = String(data.batchId ?? '')
       const requests = [...this.pending.values()].filter(request => request.batchId === batchId)
       if (!run || !batchId || !requests.length || !Array.isArray(data.answers)) throw new HarnessError('invalid_request', 'This question batch is no longer pending.')
-      this.hooks.answerQuestions(run.runId, batchId, data.answers)
+      this.hooks.answerQuestions(String(requests[0].runId ?? run.runId), batchId, data.answers)
       return {}
     }
     const requestId = String(data.requestId ?? '')
@@ -182,17 +197,65 @@ export class TerminalController {
     if (!request || !run) throw new HarnessError('invalid_request', 'This terminal decision is no longer pending.')
     if (call === 'terminal.approve' && request.type === 'approval' && this.hooks.resolveApproval) {
       if (data.decision !== 'approved' && data.decision !== 'denied') throw new HarnessError('invalid_request', 'Choose approve or deny.')
-      this.hooks.resolveApproval(run.runId, requestId, data.decision)
+      const alwaysAllow = data.alwaysAllow === true
+      if (alwaysAllow && request.rememberable !== true) throw new HarnessError('invalid_request', 'This approval cannot be remembered for other sessions.')
+      let decision: ApprovalDecision = data.decision
+      if (decision === 'approved' && request.direct === true) {
+        const operation = request.operation as { tool?: unknown; args?: unknown } | undefined
+        const tool = typeof operation?.tool === 'string' ? operation.tool : ''
+        const current = await this.hooks.policy(run, tool, operation?.args ?? {})
+        if (!current.allowed && !current.requiresApproval) decision = 'denied'
+        if (alwaysAllow && current.rememberable !== true) {
+          request.rememberable = false
+          throw new HarnessError('invalid_request', 'This tool can no longer be allowed across sessions. Review the approval again.')
+        }
+      }
+      if (decision === 'approved' && alwaysAllow) this.hooks.allowToolGlobally(String(request.target ?? ''))
+      this.hooks.resolveApproval(String(request.runId ?? run.runId), requestId, decision)
       return {}
     }
     if (call === 'terminal.answer' && request.type === 'question' && this.hooks.answerQuestion) {
       if (!data.answer || !Array.isArray(data.answer.selected)) throw new HarnessError('invalid_request', 'A question answer is required.')
-      this.hooks.answerQuestion(run.runId, requestId, data.answer)
+      this.hooks.answerQuestion(String(request.runId ?? run.runId), requestId, data.answer)
       return {}
     }
     throw new HarnessError('unknown_method', `Unknown terminal control ${call}.`)
   }
 
+  private async requestNativeApproval(data: Record<string, any>): Promise<unknown> {
+    const run = this.activeRun
+    const requestId = typeof data.requestId === 'string' ? data.requestId : ''
+    const tool = typeof data.tool === 'string' ? data.tool : ''
+    if (!run || !requestId || !tool) throw new HarnessError('invalid_request', 'An active run, request id, and tool name are required.')
+    const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args as Record<string, unknown> : {}
+    const policy = await this.hooks.policy(run, tool, args)
+    if (!policy.allowed && !policy.requiresApproval) return { decision: 'denied' }
+    if (policy.allowed && !policy.requiresApproval) return { decision: 'approved' }
+    const key = this.requestId(`approval:${requestId}`)
+    const existing = this.seen.get(key)
+    if (existing) return { decision: await existing }
+    const action = JSON.stringify(args)
+    const operation = { tool, args }
+    const response = run.requestApproval({
+      requestId: key,
+      target: tool,
+      action,
+      operation,
+      rememberable: policy.rememberable === true,
+      standing: policy.standing
+    })
+    this.pending.set(key, {
+      type: 'approval', requestId: key, runId: run.runId, target: tool, action,
+      operation, rememberable: policy.rememberable === true, direct: true
+    })
+    this.seen.set(key, response)
+    try {
+      return { decision: await response }
+    } finally {
+      this.pending.delete(key)
+    }
+  }
+
   async accept(event: string, data: Record<string, any>): Promise<unknown> {
     if (this.disposed) throw new Error('This terminal controller was disposed.')
     if (event !== 'poll') this.hooks.telemetry(event)
@@ -220,8 +283,8 @@ export class TerminalController {
       return {}
     }
     if (event === 'begin') {
-      this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
-      return {}
+      const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
+      return { runId: run.runId }
     }
     if (event === 'shutdown') {
       this.ready = false
@@ -229,7 +292,7 @@ export class TerminalController {
       return {}
     }
     if (event === 'settled') {
-      this.finish(data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
+      this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
       return {}
     }
     const run = this.run