@xingular/harness 0.1.7 → 2.0.0

package/src/memory/wiki.ts

@@ -6,6 +6,7 @@ import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { noteChange } from '../core/changes'
+import { logLine } from '../core/bus'
 import { HarnessError, notFound } from '../core/errors'
 import * as frontmatter from '../core/frontmatter'
 import { atomicWrite, now } from '../core/fs'
@@ -216,7 +217,7 @@ export function searchEntries(root: string, query: string, options: SearchOption
   try {
     ranked = wikiIndex.search(root, query, limit * 4, boost)
   } catch (error) {
-    process.stderr.write(`[index] search fell back to files: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[index] search fell back to files: ${error instanceof Error ? error.message : String(error)}`)
     const needle = query.trim().toLowerCase()
     if (!needle) return []
     const rank = (entry: IndexedEntry): number => (entry.namespace === boost ? 0 : 2) + (entry.title.toLowerCase().includes(needle) ? 0 : 1)

package/src/memory/wikiIndex.ts

@@ -3,6 +3,7 @@
 import { existsSync } from 'node:fs'
 import type { DatabaseSync } from 'node:sqlite'
 
+import { logLine } from '../core/bus'
 import { all, dbPath, deleteIndex, ftsQuery, run, transaction, withIndex } from '../core/index'
 import { readAllRuns, syncRuns, upsertRun } from '../sessions/runIndex'
 import { scan } from './wiki'
@@ -55,7 +56,7 @@ export function reindexQuietly(root: string): void {
   try {
     reindexWiki(root)
   } catch (error) {
-    process.stderr.write(`[index] reindex failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[index] reindex failed: ${error instanceof Error ? error.message : String(error)}`)
   }
 }
 
@@ -81,7 +82,7 @@ export function ensure(root: string, after?: () => void): number {
     try {
       syncRuns(root)
     } catch (error) {
-      process.stderr.write(`[index] ${error instanceof Error ? error.message : String(error)}\n`)
+      logLine(`[index] ${error instanceof Error ? error.message : String(error)}`)
     }
   } else {
     pages = rebuild(root)

package/src/plugins/builtin.ts

@@ -2,8 +2,9 @@
 // exists; none of it is loaded through Pi's extension system.
 import { CONNECTION_TOOLS, NATIVE_GROUP } from '../prompt/compile'
 import { ASK_USER } from '../tools/askUser'
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from '../sessions/subagents'
 import { PLUGIN_PROPOSE } from '../tools/pluginPropose'
-import { MEMORY_TOOLS, RECALL_TOOLS, WIKI_TOOLS, type WikiToolDefinition } from '../tools/definitions'
+import { MEMORY_TOOLS, RECALL_TOOLS, TRAJECTORY_TOOLS, WIKI_TOOLS, type WikiToolDefinition } from '../tools/definitions'
 import { FIRST_PARTY_PLUGINS } from './firstParty'
 import type { PluginDescriptor } from './types'
 
@@ -36,6 +37,7 @@ export const INCLUDED_PLUGIN: PluginDescriptor = { id: 'included', title: 'Inclu
 
 export const HARNESS_PLUGINS: readonly PluginDescriptor[] = [
   PI_PLUGIN,
+  { id: 'subagents', title: 'Subagents', description: 'Isolated child runs of the same caller, bounded by parent capabilities and nesting depth.', required: 'Availability is selected by the session host; child runs retain the parent permission boundary.', tools: [{ name: SPAWN_SUBAGENT, description: 'Start a subagent' }, { name: WAIT_SUBAGENTS, description: 'Wait for subagents' }] },
   {
     id: 'memory',
     title: 'Memory',
@@ -59,7 +61,7 @@ export const HARNESS_PLUGINS: readonly PluginDescriptor[] = [
     ],
     toolGroups: ['Knowledge']
   },
-  { id: 'history', title: 'History', description: 'Search over earlier conversations and runs.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools(RECALL_TOOLS) },
+  { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]) },
   {
     id: 'plugin-proposals',
     title: 'Plugin proposals',

package/src/plugins/catalogue.test.ts

@@ -73,7 +73,7 @@ describe('the plugin list', () => {
       ['app-tasks', 'application', ['tool:start_task:on']],
       ['web', 'application', ['tool:web_search:on', 'tool:web_fetch:on']]
     ])
-    expect(plugins.filter((plugin) => plugin.source === 'builtin').map((plugin) => plugin.id)).toEqual(['ask-user', 'budget-guard', 'connected-apps', 'history', 'memory', 'output-trim', 'plugin-proposals', 'wiki'])
+    expect(plugins.filter((plugin) => plugin.source === 'builtin').map((plugin) => plugin.id)).toEqual(['ask-user', 'budget-guard', 'connected-apps', 'history', 'memory', 'output-trim', 'plugin-proposals', 'subagents', 'wiki'])
 
     const kit = plugins.find((plugin) => plugin.id === 'package:review-kit')!
     // It was there when trust was first asked per package, so it was taken over as trusted.

package/src/server/methods.ts

@@ -33,6 +33,7 @@ import { comparison, compile, CONTEXT_PROFILES, load, profiles, render, setProfi
 import { selectHistory } from '../sessions/history'
 import { runsSince } from '../sessions/runIndex'
 import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from '../sessions/runStore'
+import type { SubagentInput, SubagentSelection } from '../sessions/subagents'
 import type { SessionRunInput } from '../sessions/sessions'
 import * as registry from '../skills/registry'
 import type { TerminalPrepareInput } from '../terminal/terminals'
@@ -134,6 +135,7 @@ export function methods(harness: Harness): Record<string, Handler> {
     'connections.setAgentScope': (params: Params) => apps.setAgentScope(params.creator ?? {}, text(params, 'agentId'), Array.isArray(params.ids) ? params.ids : []),
     'connections.removeAgentScope': (params: Params) => apps.removeAgentScope(text(params, 'agentId')),
     'connections.revision': () => apps.connections.revision(),
+    'connections.appClients': () => apps.appClients(),
     'connections.validateScope': (params: Params) => validateScopeIds(apps.connections.list(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') }, Array.isArray(params.ids) ? params.ids : []),
 
     // ---- Wiki: what a person browses and edits ---------------------------------------------------
@@ -336,6 +338,10 @@ export function methods(harness: Harness): Record<string, Handler> {
     },
 
     // ---- Sessions ----------------------------------------------------------------------------------
+    'subagents.spawn': (params: Params) => harness.subagents.spawn(params as SubagentInput),
+    'subagents.wait': (params: Params) => harness.subagents.wait(params as SubagentSelection),
+    'subagents.results': (params: Params) => harness.subagents.results(params as SubagentSelection),
+    'sessions.spawnSubagent': (params: Params) => sessions.spawnSubagent(params as SubagentInput),
     'sessions.run': (params: Params) => sessions.run(params as SessionRunInput),
     'sessions.history': (params: Params) => ({ sessionFile: selectHistory({ sessionDir: text(params, 'sessionDir'), resume: params.resume ?? null }) }),
 

package/src/server/server.test.ts

@@ -59,6 +59,23 @@ function host(hostCalls: Record<string, (params: any) => unknown> = {}) {
 const idle = (): PiSessionLike => ({ sessionId: 'native-1', subscribe: () => () => undefined, prompt: async () => undefined, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined })
 
 describe('the harness served to a host', () => {
+  it('starts native subagents over RPC using the live parent launch', async () => {
+    const { transport, request } = host()
+    const harness = createHarness({
+      dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(),
+      sessionFactory: async ({ params }) => ({ ...idle(), ...(params.runId === 'rpc-parent' ? { prompt: async () => new Promise<void>(() => undefined) } : {}) })
+    })
+    open.push(harness)
+    serve(harness, transport)
+    harness.accounts.create('Main', 'apiKey')
+    await request('sessions.run', { run: { id: 'rpc-parent', sessionId: 'opaque-session' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'sessions'), text: 'Parent', caller: { agentId: 'caller' }, tools: { allow: ['read'] }, subagents: {} })
+    const child = await request('subagents.spawn', { parentRunId: 'rpc-parent', brief: 'Review', tools: ['read'] })
+    expect(await request('subagents.wait', { parentRunId: 'rpc-parent', runIds: [child.runId] })).toMatchObject([{ runId: child.runId, status: 'completed' }])
+    const { loadRun } = await import('../sessions/runStore')
+    expect(loadRun(harness.env.root, child.runId)).toMatchObject({ parentRunId: 'rpc-parent', relation: 'subagent', agentId: 'caller', status: 'completed' })
+    await request('runs.interrupt', { runId: 'rpc-parent' })
+  })
+
   it('answers by method name, reports failures with their code, and forwards events and notices', async () => {
     const { transport, request, events, notices } = host()
     const harness = createHarness({ dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), sessionFactory: async () => idle() })
@@ -67,7 +84,9 @@ describe('the harness served to a host', () => {
 
     const status = await request('harness.status')
     expect(status).toMatchObject({ dataRoot: harness.env.root, productName: 'Xingular Harness', activeRuns: [] })
-    expect(await request<string[]>('harness.methods')).toEqual(expect.arrayContaining(['accounts.list', 'sessions.run', 'wiki.pages', 'terminal.prepare', 'skills.list', 'skills.import', 'connections.list', 'harness.shutdown']))
+    expect(await request<string[]>('harness.methods')).toEqual(expect.arrayContaining(['accounts.list', 'sessions.run', 'sessions.spawnSubagent', 'subagents.spawn', 'subagents.wait', 'subagents.results', 'wiki.pages', 'terminal.prepare', 'skills.list', 'skills.import', 'connections.list', 'harness.shutdown']))
+
+    await expect(request('sessions.spawnSubagent', { parentRunId: 'missing', brief: 'Review' })).rejects.toMatchObject({ code: 'run_not_active' })
 
     const overview = await request('accounts.create', { label: 'Main', authKind: 'apiKey' })
     expect(overview.accounts).toHaveLength(1)

package/src/sessions/approvals.test.ts

@@ -0,0 +1,49 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { Bus } from '../core/bus'
+import { Approvals, grant } from './approvals'
+
+const folders: string[] = []
+afterEach(() => { for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }) })
+
+function state() {
+  const folder = mkdtempSync(join(tmpdir(), 'harness-approvals-'))
+  folders.push(folder)
+  const bus = new Bus()
+  return { folder, approvals: new Approvals(folder, bus) }
+}
+
+describe('standing approval policy', () => {
+  it('loads old files with no global tool grants', () => {
+    const { folder, approvals } = state()
+    writeFileSync(join(folder, 'approvals.json'), JSON.stringify({ auto: { pi: true }, remembered: { old: ['write'] } }))
+
+    expect(approvals.read()).toEqual({ auto: { pi: true }, globalTools: {}, remembered: { old: ['write'] } })
+  })
+
+  it('persists a profile-wide tool grant, while read-only and other profiles stay isolated', () => {
+    const { folder, approvals } = state()
+    approvals.allowTool('pi', 'bash')
+    const policy = approvals.read()
+
+    expect(policy.globalTools).toEqual({ pi: ['bash'] })
+    expect(grant(policy, 'pi', 'terminal-one', 'bash')).toBe('remembered')
+    expect(grant(policy, 'pi', 'terminal-two', 'bash')).toBe('remembered')
+    expect(grant(policy, 'chat', 'terminal-two', 'bash')).toBeNull()
+    expect(grant(policy, 'pi', 'terminal-two', 'bash', { readOnly: true })).toBeNull()
+    expect(JSON.parse(readFileSync(join(folder, 'approvals.json'), 'utf8'))).toMatchObject({ globalTools: { pi: ['bash'] } })
+  })
+
+  it('revokes a global tool grant without changing the full switch or session grants', () => {
+    const { approvals } = state()
+    approvals.setAuto('pi', true)
+    approvals.remember('one-session', 'write')
+    approvals.allowTool('pi', 'bash')
+
+    expect(approvals.revokeTool('pi', 'bash')).toEqual({ auto: { pi: true }, globalTools: {}, remembered: { 'one-session': ['write'] } })
+    expect(approvals.read().globalTools).toEqual({})
+  })
+})

package/src/sessions/approvals.ts

@@ -1,5 +1,5 @@
-// What the user has chosen to stop being asked about: an "always approve" switch per kind of
-// session and, per session, the tools they answered "Always allow" for.
+// What the user has chosen to stop being asked about: an "always approve" switch, tools allowed
+// across a harness state directory, and tools remembered for one session.
 import { chmodSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -14,6 +14,8 @@ export const APPROVAL_KEYS = ['chat', 'pi'] as const
 export interface ApprovalPolicy {
   /** Switch key → every approval is granted without asking. */
   auto: Record<string, boolean>
+  /** Approval key → tools allowed across sessions that share this local state directory. */
+  globalTools: Record<string, string[]>
   /** Session id → approval targets always allowed there. */
   remembered: Record<string, string[]>
 }
@@ -34,13 +36,14 @@ export interface ApprovalFacts {
 /** Why the standing choices grant this request, if they do. */
 export function decide(policy: ApprovalPolicy, key: string, sessionId: string, target: string): AutomaticReason | null {
   if (policy.auto[key]) return 'always'
+  if (policy.globalTools[key]?.includes(target)) return 'remembered'
   return policy.remembered[sessionId]?.includes(target) ? 'remembered' : null
 }
 
 export function grant(policy: ApprovalPolicy, key: string, sessionId: string, target: string, facts: ApprovalFacts = {}): AutomaticReason | null {
   if (facts.unattended) return null
   // "Always approve" must not let a read-only session approve its way out of read-only mode.
-  return decide(facts.readOnly ? { auto: {}, remembered: policy.remembered } : policy, key, sessionId, target)
+  return decide(facts.readOnly ? { auto: {}, globalTools: {}, remembered: policy.remembered } : policy, key, sessionId, target)
 }
 
 /** A conversation's runs share one switch whatever model they use; other runs follow their own. */
@@ -55,7 +58,7 @@ export class Approvals {
 
   read(): ApprovalPolicy {
     const stored = readJson<Partial<ApprovalPolicy>>(this.path) ?? {}
-    return { auto: stored.auto ?? {}, remembered: stored.remembered ?? {} }
+    return { auto: stored.auto ?? {}, globalTools: stored.globalTools ?? {}, remembered: stored.remembered ?? {} }
   }
 
   private change(update: (policy: ApprovalPolicy) => void): ApprovalPolicy {
@@ -90,6 +93,25 @@ export class Approvals {
     return this.change((policy) => void (policy.auto[key] = on))
   }
 
+  /** Always allow `target` for every session in this approval profile and state directory. */
+  allowTool(key: string, target: string): ApprovalPolicy {
+    if (!(APPROVAL_KEYS as readonly string[]).includes(key)) throw invalid('Unknown harness.')
+    if (!target.trim()) throw invalid('A tool is required.')
+    return this.change((policy) => {
+      const targets = (policy.globalTools[key] ??= [])
+      if (!targets.includes(target)) targets.push(target)
+    })
+  }
+
+  revokeTool(key: string, target: string): ApprovalPolicy {
+    if (!(APPROVAL_KEYS as readonly string[]).includes(key)) throw invalid('Unknown harness.')
+    return this.change((policy) => {
+      const targets = policy.globalTools[key]?.filter((item) => item !== target) ?? []
+      if (targets.length) policy.globalTools[key] = targets
+      else delete policy.globalTools[key]
+    })
+  }
+
   /** Always allow `target` in this session. */
   remember(sessionId: string, target: string): ApprovalPolicy {
     if (!target.trim()) throw invalid('A tool is required.')

package/src/sessions/conversation.test.ts

@@ -56,6 +56,62 @@ async function setup() {
 }
 
 describe('a whole reply, with a scripted model', () => {
+  it('joins async native children and persists one result receipt before the final reply', async () => {
+    const { harness, root, model, start, until, settled, of } = await setup()
+    const route = (context: { messages: Array<{ role: string; content: unknown }> }) => {
+      const users = context.messages.filter(message => message.role === 'user').map(message => typeof message.content === 'string' ? message.content : (message.content as Array<{ text?: string }>).map(part => part.text ?? '').join(''))
+      if (users.includes('native-child-brief')) return model.says('CHILD_EVIDENCE')
+      if (JSON.stringify(context.messages).includes('CHILD_EVIDENCE')) return model.says('Final with CHILD_EVIDENCE')
+      if (!context.messages.some(message => message.role === 'toolResult')) return model.calls(['spawn_subagent', { brief: 'native-child-brief' }])
+      return model.says('Draft before joining')
+    }
+    model.script(Array(8).fill(route))
+    const id = await start()
+    await until(() => settled(id))
+    expect(of(id).at(-1)?.type).toBe('completed')
+    expect(of(id).filter(event => event.type === 'message.completed').at(-1)?.payload).toMatchObject({ text: 'Final with CHILD_EVIDENCE' })
+    const { sessionFile } = await import('../prompt/compile')
+    const { readFileSync } = await import('node:fs')
+    const entries = readFileSync(sessionFile(join(root, 'sessions', 'a1'))!, 'utf8').trim().split('\n').map(line => JSON.parse(line))
+    expect(entries.filter(entry => entry.customType === 'xingular-subagent-results')).toHaveLength(1)
+    expect(model.requests()).toBeLessThanOrEqual(4)
+    expect(harness.runs.activeRunIds()).toEqual([])
+  })
+
+  it('uses blocking native results without adding an unsolicited duplicate delivery', async () => {
+    const { root, model, start, until, settled, of } = await setup()
+    model.script([model.calls(['spawn_subagent', { brief: 'Find proof', wait: true }]), model.says('INLINE_CHILD_PROOF'), model.says('Final')])
+    const id = await start()
+    await until(() => settled(id))
+    expect(of(id).at(-1)?.type).toBe('completed')
+    expect(model.lastToolResults().join('')).toContain('INLINE_CHILD_PROOF')
+    const { sessionFile } = await import('../prompt/compile')
+    const { readFileSync } = await import('node:fs')
+    expect(readFileSync(sessionFile(join(root, 'sessions', 'a1'))!, 'utf8')).not.toContain('"customType":"xingular-subagent-results"')
+    expect(model.requests()).toBe(3)
+  })
+
+  it('interrupts a parent waiting on a child question without deadlocking SDK abort', async () => {
+    const { harness, model, start, until, settled } = await setup()
+    const ai = await import('@earendil-works/pi-ai')
+    model.script([
+      model.calls(['spawn_subagent', { brief: 'Ask for a decision', wait: true }]),
+      ai.fauxAssistantMessage([ai.fauxToolCall('ask_user', { questions: [{ summary: 'A decision', question: 'Which approach?' }] })], { stopReason: 'toolUse' })
+    ])
+    let childRunId: string | null = null
+    harness.runs.listen((event, run) => { if (event.type === 'question.requested' && run?.relation === 'subagent') childRunId = event.runId })
+    const id = await start()
+    await until(() => childRunId !== null || settled(id))
+    expect(childRunId).not.toBeNull()
+    await harness.runs.interrupt(id)
+    const { loadRun } = await import('./runStore')
+    expect(loadRun(harness.env.root, id).status).toBe('interrupted')
+    expect(loadRun(harness.env.root, childRunId!).status).toBe('interrupted')
+    const { readEvents } = await import('./runStore')
+    expect(readEvents(harness.env.root, childRunId!).some(event => event.type === 'question.answered')).toBe(true)
+    expect(harness.runs.activeRunIds()).toEqual([])
+  })
+
   it('dispatches a registered command with notes without making a provider request', async () => {
     const { harness, model, start, until, settled, of } = await setup()
     const account = harness.accounts.context(harness.accounts.resolve(null, null))

package/src/sessions/lineageJoin.ts

@@ -16,7 +16,7 @@ function directChildren(root: string, runId: string): RunSummary[] {
   try {
     return runFamily(root, runId).runs
       .map(({ run }) => run)
-      .filter((run) => run.parentRunId === runId)
+      .filter((run) => run.parentRunId === runId && run.relation !== 'subagent')
       .map((run) => ({ id: run.id, status: run.status, goal: run.goal, terminalReason: run.terminalReason }))
   } catch {
     return []

package/src/sessions/registry.ts

@@ -91,6 +91,7 @@ export class RunRegistry {
   private readonly approvals = new Map<string, { runId: string; resolve: (decision: ApprovalDecision) => void }>()
   private readonly questions = new Map<string, PendingQuestion>()
   private readonly nativeCleared = new Map<string, string>()
+  private readonly waiters = new Map<string, Array<() => void>>()
   private readonly stopping = new Set<string>()
   private readonly listeners: RunListener[] = []
 
@@ -130,6 +131,7 @@ export class RunRegistry {
       sequence = 0
     }
     let finished = false
+    let finishing = false
     const interruptHandlers: Array<() => Promise<void> | void> = []
     let steerHandler: ((text: string) => Promise<void> | void) | null = null
     const waitingStatus = (): string =>
@@ -138,7 +140,7 @@ export class RunRegistry {
     const requestQuestion = (input: QuestionInput, batch?: QuestionBatchMetadata, statusEvent = true): Promise<QuestionAnswer> => {
       const { requestId, ...payload } = input
       const questionId = requestId ?? randomUUID()
-      if (finished || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] })
+      if (finished || finishing || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] })
       if (this.questions.has(questionId)) throw new HarnessError('invalid_request', 'This question id is already pending.')
       return new Promise<QuestionAnswer>((resolve) => {
         this.questions.set(questionId, {
@@ -186,7 +188,7 @@ export class RunRegistry {
         // What the user already allowed is known here; if it cannot be read, ask as usual.
         const record = findRun(this.options.root(), runId)
         const automatic = record && this.options.automatic && standing !== 'none' ? await this.options.automatic(record, input.target, input.operation, standing).catch(() => null) : null
-        if (finished) return 'denied'
+        if (finished || finishing) return 'denied'
         if (this.nativeCleared.delete(approvalId)) return 'native'
         if (automatic) {
           // Marked on the request too, so nothing treats it as waiting on someone.
@@ -219,22 +221,26 @@ export class RunRegistry {
         if (new Set(requestedIds).size !== requestedIds.length || requestedIds.some((id) => this.questions.has(id))) {
           throw new HarnessError('invalid_request', 'Question ids in a batch must be unique and not already pending.')
         }
-        if (finished) return Promise.resolve(inputs.map(() => ({ selected: [] })))
+        if (finished || finishing) return Promise.resolve(inputs.map(() => ({ selected: [] })))
         const batchId = randomUUID()
         const answers = inputs.map((input, index) => requestQuestion(input, { batchId, batchIndex: index + 1, batchCount: inputs.length }, false))
         emit('status.changed', { status: 'waiting_for_input' })
         return Promise.all(answers)
       },
       finish: (outcome, failure) => {
-        if (finished) return
+        if (finished || finishing) return
+        finishing = true
+        // Persist cancellation receipts while emit is still open, so every interface clears them.
+        for (const [, approval] of [...this.approvals]) if (approval.runId === runId) approval.resolve('denied')
+        for (const [, question] of [...this.questions]) if (question.runId === runId) question.resolve({ selected: [] })
         if (outcome === 'failed') emit('failed', failure ?? { code: 'failed', message: 'The run failed.' })
         else if (outcome === 'interrupted') emit('status.changed', { status: 'interrupted' })
         else emit('completed', {})
         finished = true
         this.runs.delete(runId)
+        for (const resolve of [...(this.waiters.get(runId) ?? [])]) resolve()
+        this.waiters.delete(runId)
         for (const [id, owner] of this.nativeCleared) if (owner === runId) this.nativeCleared.delete(id)
-        for (const [, approval] of [...this.approvals]) if (approval.runId === runId) approval.resolve('denied')
-        for (const [, question] of [...this.questions]) if (question.runId === runId) question.resolve({ selected: [] })
         try {
           this.options.ended?.(runId, sessionId)
         } catch (error) {
@@ -245,6 +251,8 @@ export class RunRegistry {
         return finished
       },
       interrupt: async () => {
+        // Release approvals/questions before SDK abort waits for their blocked tools.
+        run.finish('interrupted')
         for (const handler of interruptHandlers) {
           try {
             await handler()
@@ -252,7 +260,6 @@ export class RunRegistry {
             log(`an interrupt handler failed for run ${runId}`, error instanceof Error ? error.message : String(error))
           }
         }
-        run.finish('interrupted')
       }
     }
 
@@ -278,6 +285,30 @@ export class RunRegistry {
     return false
   }
 
+  /** Wait for a recorded run to settle without polling storage or retaining an event listener. */
+  wait(runId: string, signal?: AbortSignal): Promise<void> {
+    const record = findRun(this.options.root(), runId)
+    if (!record) throw new HarnessError('not_found', 'Run was not found.')
+    if (!isActiveStatus(record.status)) return Promise.resolve()
+    if (!this.runs.has(runId)) throw new HarnessError('run_not_active', 'This run is not active in this process.')
+    if (signal?.aborted) return Promise.reject(new HarnessError('run_not_active', 'The wait was interrupted.'))
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        signal?.removeEventListener('abort', abort)
+        const pending = this.waiters.get(runId)
+        const index = pending?.indexOf(done) ?? -1
+        if (index >= 0) pending!.splice(index, 1)
+        if (!pending?.length) this.waiters.delete(runId)
+      }
+      const done = () => { cleanup(); resolve() }
+      const abort = () => { cleanup(); reject(new HarnessError('run_not_active', 'The wait was interrupted.')) }
+      const pending = this.waiters.get(runId) ?? []
+      pending.push(done)
+      this.waiters.set(runId, pending)
+      signal?.addEventListener('abort', abort, { once: true })
+    })
+  }
+
   /** The live run with this id, for a tool or broker that reports into it. */
   active(runId: string): ActiveRun | null {
     return this.runs.get(runId) ?? null

package/src/sessions/runStore.ts

@@ -74,6 +74,20 @@ export function findRun(root: string, runId: string): RunRecord | null {
   }
 }
 
+/** A parent's reserved child IDs survive a crash before the spawn tool returns. */
+export function recordSubagent(root: string, parentRunId: string, childRunId: string): void {
+  loadRun(root, parentRunId)
+  const ids = recordedSubagents(root, parentRunId)
+  if (!ids.includes(childRunId)) writeJson(join(runDir(root, parentRunId), 'subagents.json'), [...ids, childRunId])
+}
+
+export function recordedSubagents(root: string, parentRunId: string): string[] {
+  const value = readJson(join(runDir(root, parentRunId), 'subagents.json'))
+  if (value === null) return []
+  if (!Array.isArray(value) || value.some(id => typeof id !== 'string')) throw new Error('Recorded subagent ownership is unreadable.')
+  return value as string[]
+}
+
 /** Changes a run's record. A settled run keeps its outcome whatever the change says. */
 export function updateRun(root: string, runId: string, update: (record: RunRecord) => void): void {
   const record = readRecord(recordPath(root, runId))

package/src/sessions/runner.ts

@@ -23,6 +23,9 @@ export type Effort = (typeof EFFORTS)[number]
 /** What one turn needs once its prompt is compiled and its tools are chosen. */
 export interface TurnParams {
   runId: string
+  /** Child runs may not gain tools registered by extensions outside their snapshot. */
+  restrictTools?: boolean
+  settle?: () => Promise<void>
   cwd: string
   sessionDir: string
   /** The native history to open, or `null` to start a fresh one. */
@@ -77,9 +80,11 @@ export type PiEvent =
 
 export interface PiSessionLike {
   sessionId: string
+  sessionManager?: { getBranch(): unknown[] }
+  thinkingLevel?: Effort
   systemPrompt?: string
   extensionCommands?: readonly string[]
-  model?: { input: string[]; contextWindow?: number }
+  model?: { input: string[]; contextWindow?: number; id?: string; provider?: string }
   getActiveToolNames?(): string[]
   getAllTools?(): Array<{ name: string; description?: string; parameters?: unknown }>
   subscribe(listener: (event: PiEvent) => void): () => void
@@ -460,6 +465,7 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
       accepting = false
       session.clearQueue?.()
     }
+    if (!aborted && !lastError) await params.settle?.()
     if (aborted) run.finish('interrupted')
     else if (lastError) run.finish('failed', { code: 'provider_error', message: lastError })
     else run.finish('completed')
@@ -540,7 +546,7 @@ export const piSessionFactory: SessionFactory = async ({ params, allow, gate, to
   const loaded = registeredBy(resourceLoader)
   // A tool an extension brought is offered to the model, and asks before every call: the person
   // trusted the code to load, and still decides each thing it does through a tool.
-  const extensionTools = [...new Set(loaded.flatMap((extension) => extension.tools))].filter((name) => !allow.includes(name))
+  const extensionTools = [...new Set(loaded.flatMap((extension) => extension.tools))].filter((name) => !allow.includes(name) && !params.restrictTools)
   gate.ask?.([...new Set(loaded.flatMap((extension) => extension.tools))])
 
   let supportsImageInput = false
@@ -558,7 +564,7 @@ export const piSessionFactory: SessionFactory = async ({ params, allow, gate, to
           if (output.image && !supportsImageInput) throw new HarnessError('image_input_unsupported', 'This model cannot inspect images. Choose a model that supports image input.')
           return {
             content: [{ type: 'text', text: output.text }, ...(output.image ? [{ type: 'image', data: output.image.data, mimeType: output.image.mimeType }] : [])] as never,
-            details: output.attachments?.length ? { attachments: output.attachments } : {}
+            details: { ...output.details, ...(output.attachments?.length ? { attachments: output.attachments } : {}) }
           }
         }
       })

package/src/sessions/sessions.test.ts

@@ -423,7 +423,7 @@ describe('session turns on Pi', () => {
     await tick()
     expect(received!.allow.slice(0, 3)).toEqual(['react', 'ask_user', 'plugin_propose'])
     expect(received!.allow).toEqual(expect.arrayContaining(['memory_append', 'history_search', 'wiki_search', 'wiki_read', 'wiki_propose']))
-    expect(received!.tools.map((tool) => tool.name)).toEqual(['memory_append', 'memory_replace', 'memory_rethink', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load', 'memory_facts', 'wiki_propose', 'ask_user', 'plugin_propose', 'react'])
+    expect(received!.tools.map((tool) => tool.name)).toEqual(['memory_append', 'memory_replace', 'memory_rethink', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load', 'memory_facts', 'wiki_propose', 'trajectory_search', 'trajectory_read', 'ask_user', 'plugin_propose', 'spawn_subagent', 'wait_subagents', 'react'])
     expect(await received!.tools[0].execute({ block: 'notes', text: 'Remember this.' })).toContain('Updated the notes block')
     expect(received!.params.system).toContain('# Xingular Harness context')
   })
@@ -496,7 +496,7 @@ describe('subagents', () => {
         if (params.runId === 'parent') {
           const spawn = tools.find((tool) => tool.name === 'spawn_subagent')!
           expect(await spawn.execute({ brief: 'Find the bug', tools: ['bash', 'web'] })).toMatch(/cannot have tools you do not have: web/)
-          parentResult = await spawn.execute({ brief: 'Find the bug', tools: ['read'] })
+          parentResult = await spawn.execute({ brief: 'Find the bug', tools: ['read'], wait: true })
           return
         }
         emit({ type: 'message_start', message: { role: 'assistant' } })
@@ -505,7 +505,7 @@ describe('subagents', () => {
     })
     await run('parent', { subagents: { maxDepth: 1 } })
     for (let attempt = 0; attempt < 50 && !parentResult; attempt++) await tick()
-    expect(parentResult).toMatch(/Subagent run .* · completed\nResult:\nFound it in parser.ts/)
+    expect(parentResult).toMatchObject({ text: expect.stringContaining('Found it in parser.ts'), details: expect.any(Object) })
     expect(seen.get('parent')!.allow).toContain('spawn_subagent')
     const [childId] = [...seen.keys()].filter((id) => id !== 'parent')
     const child = seen.get(childId)!
@@ -516,14 +516,53 @@ describe('subagents', () => {
     expect(loadRun(harness.env.root, childId)).toMatchObject({ parentRunId: 'parent', relation: 'subagent', agentId: 'agent-1', status: 'completed' })
   })
 
-  it('offers no subagent tool unless the caller asks for it, and can run without the application\'s tool providers', async () => {
+  it('exposes native child runs, freezes the launch, respects nesting, and settles waiters on parent stop', async () => {
+    const seen = new Map<string, string[]>()
+    const { harness, run } = setup(async ({ gate, params, allow }) => {
+      seen.set(params.runId, [...allow])
+      return fakeSession(async () => new Promise<void>(() => undefined), gate)
+    })
+    const subagents = { maxDepth: 2 }
+    const starting = run('parent', { subagents })
+    subagents.maxDepth = 3
+    await starting
+    await expect(harness.sessions.spawnSubagent({ parentRunId: 'parent', brief: 'Bad tools', tools: ['outside'] })).rejects.toMatchObject({ code: 'invalid_request' })
+    const child = await harness.sessions.spawnSubagent({ parentRunId: 'parent', brief: 'Search' })
+    const grandchild = await harness.sessions.spawnSubagent({ parentRunId: child.runId, brief: 'Review' })
+    expect(seen.get(child.runId)).toContain('spawn_subagent')
+    expect(seen.get(grandchild.runId)).not.toContain('spawn_subagent')
+    await expect(harness.sessions.spawnSubagent({ parentRunId: grandchild.runId, brief: 'Too deep' })).rejects.toMatchObject({ code: 'invalid_request' })
+    const narrowed = await harness.sessions.spawnSubagent({ parentRunId: 'parent', brief: 'Read only', tools: ['read'] })
+    expect(seen.get(narrowed.runId)).toEqual(['read'])
+    const settled = Promise.all([child, grandchild, narrowed].map(({ runId }) => harness.runs.wait(runId)))
+    await harness.runs.interrupt('parent')
+    await settled
+    for (const { runId } of [child, grandchild, narrowed]) expect(loadRun(harness.env.root, runId).status).toBe('interrupted')
+    await expect(harness.sessions.spawnSubagent({ parentRunId: 'parent', brief: 'Too late' })).rejects.toMatchObject({ code: 'run_not_active' })
+    await harness.runs.wait(child.runId)
+  })
+
+  it('settles a failed child and attributes the tool to the Harness plugin', async () => {
+    const { harness, run } = setup(async ({ gate, params }) => {
+      if (params.runId !== 'parent') throw new Error('No provider')
+      return fakeSession(async () => new Promise<void>(() => undefined), gate)
+    })
+    await run('parent', { subagents: {} })
+    const child = await harness.sessions.spawnSubagent({ parentRunId: 'parent', brief: 'Try' })
+    await harness.runs.wait(child.runId)
+    expect(loadRun(harness.env.root, child.runId)).toMatchObject({ status: 'failed', parentRunId: 'parent', terminalReason: 'No provider' })
+    const { HARNESS_PLUGINS } = await import('../plugins/builtin')
+    expect(HARNESS_PLUGINS.find((plugin) => plugin.id === 'subagents')?.tools).toContainEqual(expect.objectContaining({ name: 'spawn_subagent' }))
+  })
+
+  it('can explicitly disable subagents and run without the application\'s tool providers', async () => {
     const offered: string[][] = []
     const { harness, run } = setup(async ({ gate, tools }) => {
       offered.push(tools.map((tool) => tool.name))
       return fakeSession(async () => undefined, gate)
     })
     harness.sessions.provide(() => [{ name: 'app_tool', label: 'App', description: 'An app tool', parameters: (Type) => Type.Object({}), execute: async () => 'ok' }])
-    await run('plain', { tools: { allow: ['app_tool'] } })
+    await run('plain', { tools: { allow: ['app_tool'] }, subagents: null })
     await run('solo', { tools: { allow: ['app_tool'] }, providers: false })
     await tick()
     expect(offered[0]).toContain('app_tool')
@@ -533,7 +572,7 @@ describe('subagents', () => {
 })
 
 describe('standing approvals', () => {
-  const policy = { auto: { pi: true }, remembered: { 'pane-1': ['shell'] } }
+  const policy = { auto: { pi: true }, globalTools: {}, remembered: { 'pane-1': ['shell'] } }
   const facts = (unattended: boolean, readOnly: boolean): ApprovalFacts => ({ unattended, readOnly })
 
   it('the switch reaches attended sessions but not unattended or read-only ones', () => {
@@ -544,6 +583,6 @@ describe('standing approvals', () => {
     expect(grant(policy, 'pi', 'pane-1', 'shell', facts(true, false))).toBeNull()
     expect(grant(policy, 'chat', 'pane-1', 'edit files', facts(false, false))).toBeNull()
     expect(grant(policy, 'pi', 'pane-2', 'shell', {})).toBe('always')
-    expect(grant({ auto: {}, remembered: policy.remembered }, 'pi', 'pane-2', 'shell', {})).toBeNull()
+    expect(grant({ auto: {}, globalTools: {}, remembered: policy.remembered }, 'pi', 'pane-2', 'shell', {})).toBeNull()
   })
 })