@xingular/harness 0.1.6 → 2.0.0

package/src/sessions/registry.ts

@@ -27,6 +27,7 @@ export interface ApprovalInput {
 export interface QuestionInput {
   requestId?: string
   userOnly?: boolean
+  summary?: string
   question: string
   options: QuestionOption[]
   multiSelect: boolean
@@ -36,6 +37,21 @@ export interface QuestionInput {
 export interface QuestionAnswer {
   selected: string[]
   text?: string
+  /** Optional notes keyed by the selected choice label. */
+  notes?: Record<string, string>
+}
+
+interface QuestionBatchMetadata {
+  batchId: string
+  batchIndex: number
+  batchCount: number
+}
+
+interface PendingQuestion {
+  runId: string
+  input: QuestionInput
+  batch?: QuestionBatchMetadata
+  resolve: (answer: QuestionAnswer) => void
 }
 
 export interface ActiveRun {
@@ -43,10 +59,14 @@ export interface ActiveRun {
   sessionId: string
   emit(type: RunEventType, payload: unknown, native?: unknown): void
   onInterrupt(handler: () => Promise<void> | void): void
+  /** Hands a message to the model after its current step; the session registers how. */
+  onSteer(handler: (text: string) => Promise<void> | void): void
   /** Resolves when the user decides; only the approval with this exact id can be resolved by it. */
   requestApproval(input: ApprovalInput): Promise<ApprovalDecision>
   /** Asks the user a question and resolves with their answer. */
   requestAnswer(input: QuestionInput): Promise<QuestionAnswer>
+  /** Asks one to five related questions and resolves only after the whole batch is answered. */
+  requestAnswers(inputs: QuestionInput[]): Promise<QuestionAnswer[]>
   finish(outcome: 'completed' | 'failed' | 'interrupted', failure?: { code: string; message: string }): void
   readonly finished: boolean
 }
@@ -64,13 +84,14 @@ export interface RegistryOptions {
   redact?: (event: RunEvent) => void
 }
 
-type LiveRun = ActiveRun & { interrupt: () => Promise<void> }
+type LiveRun = ActiveRun & { interrupt: () => Promise<void>; steer: (text: string) => Promise<void> }
 
 export class RunRegistry {
   private readonly runs = new Map<string, LiveRun>()
   private readonly approvals = new Map<string, { runId: string; resolve: (decision: ApprovalDecision) => void }>()
-  private readonly questions = new Map<string, { runId: string; input: QuestionInput; resolve: (answer: QuestionAnswer) => 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[] = []
 
@@ -110,10 +131,34 @@ 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 =>
       [...this.approvals.values()].some((request) => request.runId === runId) ? 'waiting_for_approval' : [...this.questions.values()].some((request) => request.runId === runId) ? 'waiting_for_input' : 'running'
 
+    const requestQuestion = (input: QuestionInput, batch?: QuestionBatchMetadata, statusEvent = true): Promise<QuestionAnswer> => {
+      const { requestId, ...payload } = input
+      const questionId = requestId ?? randomUUID()
+      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, {
+          runId,
+          input,
+          ...(batch ? { batch } : {}),
+          resolve: (answer) => {
+            this.questions.delete(questionId)
+            emit('question.answered', { questionId, ...answer, ...(batch ?? {}) })
+            emit('status.changed', { status: waitingStatus() })
+            resolve(answer)
+          }
+        })
+        emit('question.requested', { questionId, ...payload, ...(batch ?? {}) })
+        if (statusEvent) emit('status.changed', { status: 'waiting_for_input' })
+      })
+    }
+
     const emit = (type: RunEventType, payload: unknown, native?: unknown): void => {
       if (finished) return
       const parsed = runEventSchema.safeParse({ id: randomUUID(), runId, sessionId, sequence, timestamp: new Date().toISOString(), type, payload, ...(native === undefined ? {} : { native }) })
@@ -130,13 +175,20 @@ export class RunRegistry {
       sessionId,
       emit,
       onInterrupt: (handler) => void interruptHandlers.push(handler),
+      onSteer: (handler) => {
+        steerHandler = handler
+      },
+      steer: async (text) => {
+        if (finished || !steerHandler) throw new HarnessError('run_not_active', 'This run is not accepting messages.')
+        await steerHandler(text)
+      },
       requestApproval: async (input) => {
         const { requestId, standing = 'full', timeoutMs, ...payload } = input
         const approvalId = requestId ?? randomUUID()
         // 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.
@@ -160,35 +212,35 @@ export class RunRegistry {
           })
         })
       },
-      requestAnswer: (input) => {
-        const { requestId, ...payload } = input
-        const questionId = requestId ?? randomUUID()
-        if (finished || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] })
-        emit('question.requested', { questionId, ...payload })
+      requestAnswer: (input) => requestQuestion(input),
+      requestAnswers: (inputs) => {
+        if (!Array.isArray(inputs) || inputs.length < 1 || inputs.length > 5) {
+          throw new HarnessError('invalid_request', 'A question batch must contain between one and five questions.')
+        }
+        const requestedIds = inputs.flatMap((input) => input.requestId ? [input.requestId] : [])
+        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 || 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 new Promise<QuestionAnswer>((resolve) => {
-          this.questions.set(questionId, {
-            runId,
-            input,
-            resolve: (answer) => {
-              this.questions.delete(questionId)
-              emit('question.answered', { questionId, ...answer })
-              emit('status.changed', { status: waitingStatus() })
-              resolve(answer)
-            }
-          })
-        })
+        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) {
@@ -199,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()
@@ -206,7 +260,6 @@ export class RunRegistry {
             log(`an interrupt handler failed for run ${runId}`, error instanceof Error ? error.message : String(error))
           }
         }
-        run.finish('interrupted')
       }
     }
 
@@ -232,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
@@ -243,6 +320,13 @@ export class RunRegistry {
     return null
   }
 
+  /** Hands a message to a live run's model after its current step. Throws `run_not_active` when the run cannot take it. */
+  async steer(runId: string, text: string): Promise<void> {
+    const run = this.runs.get(runId)
+    if (!run) throw new HarnessError('run_not_active', 'This run is not active.')
+    await run.steer(text)
+  }
+
   async interrupt(runId: string): Promise<void> {
     const run = this.runs.get(runId)
     if (!run) throw new HarnessError('run_not_active', 'This run is not active.')
@@ -272,10 +356,44 @@ export class RunRegistry {
   answerQuestion(runId: string, questionId: string, answer: QuestionAnswer): void {
     const question = this.questions.get(questionId)
     if (!question || question.runId !== runId) throw new HarnessError('question_not_pending', 'This question is not waiting for an answer.')
-    if ((!question.input.multiSelect && answer.selected.length > 1) || answer.selected.some((label) => !question.input.options.some((option) => option.label === label)) || (answer.text && !question.input.allowText)) {
-      throw new HarnessError('invalid_answer', 'Choose the offered options or an allowed text answer.')
+    if (question.batch) throw new HarnessError('question_batch_required', 'Answer every question in this batch together.')
+    question.resolve(this.validateAnswer(question.input, answer))
+  }
+
+  answerQuestions(runId: string, batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): void {
+    const questions = [...this.questions.entries()].filter(([, pending]) => pending.runId === runId && pending.batch?.batchId === batchId)
+    if (!questions.length || answers.length !== questions.length || new Set(answers.map(({ questionId }) => questionId)).size !== answers.length) {
+      throw new HarnessError('question_not_pending', 'This question batch is not waiting for an answer.')
+    }
+    const pendingById = new Map(questions)
+    const validated = answers.map(({ questionId, answer }) => {
+      const pending = pendingById.get(questionId)
+      if (!pending) throw new HarnessError('question_not_pending', 'Every question in the batch must be answered together.')
+      return { pending, answer: this.validateAnswer(pending.input, answer) }
+    })
+    for (const { pending, answer } of validated) pending.resolve(answer)
+  }
+
+  private validateAnswer(input: QuestionInput, answer: QuestionAnswer): QuestionAnswer {
+    const selected = answer.selected
+    const selectedLabels = new Set(selected)
+    const notes: Record<string, string> = {}
+    for (const [label, note] of Object.entries(answer.notes ?? {})) {
+      const normalized = typeof note === 'string' ? note.trim() : ''
+      if (normalized) notes[label] = normalized
+    }
+    const text = answer.text?.trim()
+    if (
+      (!input.multiSelect && selected.length > 1) ||
+      selectedLabels.size !== selected.length ||
+      selected.some((label) => !input.options.some((option) => option.label === label)) ||
+      (text && !input.allowText) ||
+      Object.keys(notes).some((label) => !selectedLabels.has(label)) ||
+      Object.values(notes).some((note) => note.length > 10_000)
+    ) {
+      throw new HarnessError('invalid_answer', 'Choose the offered options or an allowed text answer, and attach notes only to selected choices.')
     }
-    question.resolve(answer)
+    return { selected, ...(text ? { text } : {}), ...(Object.keys(notes).length ? { notes } : {}) }
   }
 
   activeRunIds(): string[] {

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,13 +80,19 @@ 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
   prompt(text: string, options?: { images?: unknown[] }): Promise<void>
+  /** Queues a message for the model after the current step. Resolves `handled` when Pi takes it without queueing. */
+  steer?(text: string): Promise<'handled' | 'queued'>
+  /** Drops queued messages Pi has not delivered. */
+  clearQueue?(): unknown
   sendCustomMessage?(message: { customType: string; content: string; display: boolean; details: unknown }, options: { triggerTurn: boolean }): Promise<void>
   abort(): Promise<void>
   dispose(): void
@@ -255,11 +264,35 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
     await session.abort()
   })
 
+  // Steers handed to Pi and not yet delivered, oldest first. Pi delivers them in that order, after
+  // the prompt's own user message, which is the first user message it starts.
+  const pendingSteers: string[] = []
+  let accepting = false
+  let promptStarted = false
+  const forgetSteer = (text: string): void => {
+    const index = pendingSteers.lastIndexOf(text)
+    if (index >= 0) pendingSteers.splice(index, 1)
+  }
+  run.onSteer(async (text) => {
+    if (!accepting || !session.steer) throw new HarnessError('run_not_active', 'This reply is not accepting messages.')
+    pendingSteers.push(text)
+    try {
+      if ((await session.steer(text)) === 'handled') forgetSteer(text)
+    } catch (error) {
+      forgetSteer(text)
+      throw error
+    }
+  })
+
   const unsubscribe = session.subscribe((event) => {
     switch (event.type) {
       case 'message_start': {
         const { message } = event as Extract<PiEvent, { type: 'message_start' }>
         if (message.role === 'assistant') currentMessageId = `${run.runId}:m${messageIndex++}`
+        else if (message.role === 'user' && promptStarted) {
+          const text = pendingSteers.shift()
+          if (text !== undefined) run.emit('message.steered', { text })
+        } else if (message.role === 'user') promptStarted = true
         break
       }
       case 'turn_start': {
@@ -424,7 +457,15 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
     }
     const prompt = params.preamble && !extensionCommand ? `${params.preamble}\n\n${params.text}` : params.text
     const images = (params.images ?? []).map((image) => ({ type: 'image', mimeType: image.mediaType, data: image.data }))
-    await session.prompt(prompt, images.length ? { images } : undefined)
+    accepting = true
+    try {
+      await session.prompt(prompt, images.length ? { images } : undefined)
+    } finally {
+      // A message Pi has not delivered by now never will be; the caller sends it again as a new reply.
+      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')
@@ -505,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
@@ -523,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

@@ -326,6 +326,36 @@ describe('session turns on Pi', () => {
     expect(events.at(-1)?.type).toBe('completed')
   })
 
+  it('asks a person for a humanOnly call even when the tool was remembered', async () => {
+    let blockReason: string | null | undefined
+    const policy: ToolPolicy = { scope: async () => ({ allowed: false, requiresApproval: true, humanOnly: true, reason: 'Run this command?' }) }
+    const { events, run, harness } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (blockReason = await check()), gate), policy)
+    harness.approvals.remember('agent-1', 'bash')
+    harness.approvals.setAuto('chat', true)
+    await run('run-human', { text: 'npm install' })
+    await tick()
+    const requested = events.find((event) => event.type === 'approval.requested')!.payload as { approvalId: string }
+    expect(requested).toMatchObject({ target: 'bash', rememberable: false })
+    expect(requested).not.toHaveProperty('automatic')
+    expect(events.some((event) => event.type === 'status.changed' && (event.payload as { status: string }).status === 'waiting_for_approval')).toBe(true)
+    harness.runs.resolveApproval('run-human', requested.approvalId, 'approved')
+    await tick()
+    expect(blockReason).toBeNull()
+  })
+
+  it('lets the Agent chat switch approve humanOnly calls without remembering the tool', async () => {
+    let blockReason: string | null | undefined
+    const policy: ToolPolicy = { scope: async () => ({ allowed: false, requiresApproval: true, humanOnly: true, allowGlobalApproval: true, reason: 'Run this command?' }) }
+    const { events, run, harness } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (blockReason = await check()), gate), policy)
+    harness.approvals.setAuto('chat', true)
+    await run('run-human-auto', { text: 'run command' })
+    await tick()
+    expect(blockReason).toBeNull()
+    expect(events.find((event) => event.type === 'approval.requested')?.payload).toMatchObject({ target: 'bash', rememberable: false, automatic: 'always' })
+    expect(events.find((event) => event.type === 'approval.resolved')?.payload).toMatchObject({ decision: 'approved', automatic: 'always' })
+    expect(events.some((event) => event.type === 'status.changed' && (event.payload as { status: string }).status === 'waiting_for_approval')).toBe(false)
+  })
+
   it('still asks when the application cannot say what is allowed', async () => {
     const { events, run } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (await check()), gate), { approval: async () => { throw new Error('down') } })
     await run('run-ask', { text: 'list files' })
@@ -344,14 +374,32 @@ describe('session turns on Pi', () => {
         if (authorized > 1) throw new Error('Tool unavailable in the app settings.')
       }
     }
-    const { run } = setup(async ({ gate }) => fakeSession(async () => {
+    const { run, harness } = setup(async ({ gate }) => fakeSession(async () => {
       reasons.push(await gate.check('bash', {}), await gate.check('read', {}), await gate.check('read', {}))
     }, gate), policy)
+    harness.approvals.setAuto('chat', true)
     await run('run-scope')
     await tick()
     expect(reasons).toEqual(['Scheduled workers may use scoped file tools only.', null, 'Tool unavailable in the app settings.'])
   })
 
+  it('forwards opaque caller policy context to the application tool policy', async () => {
+    const contexts: unknown[] = []
+    const policy: ToolPolicy = {
+      scope: async ({ caller }) => {
+        contexts.push(caller.policyContext)
+        return { allowed: true }
+      }
+    }
+    const { run } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (await check()), gate), policy)
+    const policyContext = { delegatesTo: ['worker-1'], snapshot: 'run-start' }
+    await run('run-policy-context', {
+      caller: { agentId: 'agent-1', agentName: 'Helper', actor: 'Chat', policyContext }
+    })
+    await tick()
+    expect(contexts).toEqual([policyContext])
+  })
+
   it('aborts the Pi session on interrupt', async () => {
     let session: (PiSessionLike & { aborted: boolean }) | null = null
     const { events, run, harness } = setup(async ({ gate }) => (session = fakeSession(() => new Promise((resolve) => setTimeout(resolve, 50)), gate)))
@@ -375,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')
   })
@@ -438,8 +486,93 @@ describe('history selection', () => {
   })
 })
 
+describe('subagents', () => {
+  it('starts a child run of the same caller with no more tools than its parent, and returns its result', async () => {
+    const seen = new Map<string, { allow: string[]; tools: string[]; depth: string | null }>()
+    let parentResult: unknown = null
+    const { harness, run } = setup(async ({ gate, params, allow, tools }) => {
+      seen.set(params.runId, { allow: [...allow], tools: tools.map((tool) => tool.name), depth: null })
+      return fakeSession(async (emit) => {
+        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'], wait: true })
+          return
+        }
+        emit({ type: 'message_start', message: { role: 'assistant' } })
+        emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Found it in parser.ts' }] } })
+      }, gate)
+    })
+    await run('parent', { subagents: { maxDepth: 1 } })
+    for (let attempt = 0; attempt < 50 && !parentResult; attempt++) await tick()
+    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)!
+    expect(child.allow).toContain('read')
+    expect(child.allow).not.toContain('bash')
+    // At the depth limit the child cannot start subagents of its own.
+    expect(child.allow).not.toContain('spawn_subagent')
+    expect(loadRun(harness.env.root, childId)).toMatchObject({ parentRunId: 'parent', relation: 'subagent', agentId: 'agent-1', status: 'completed' })
+  })
+
+  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'] }, subagents: null })
+    await run('solo', { tools: { allow: ['app_tool'] }, providers: false })
+    await tick()
+    expect(offered[0]).toContain('app_tool')
+    expect(offered[0]).not.toContain('spawn_subagent')
+    expect(offered[1]).not.toContain('app_tool')
+  })
+})
+
 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', () => {
@@ -450,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()
   })
 })