@xingular/harness 0.1.7 → 2.1.0

package/src/sessions/planMode.ts

@@ -0,0 +1,57 @@
+// Plan mode: a run that may only look, ask and recall, and ends with a proposed plan. The tool list
+// the model sees is unchanged, so switching the mode does not change the cached prompt prefix; the
+// gate refuses everything else, and the instruction arrives as a context update.
+import { deliveredSnapshot, type HostSection } from '../prompt/compile'
+import { ASK_USER } from '../tools/askUser'
+
+/**
+ * Read-only inspection, questions and recall. Everything else is refused in plan mode: file
+ * changes, commands, memory writes, delegation and connected apps, since none of them can be
+ * judged read-only from their names. A provider marks its own read-only tools with `readOnly`.
+ */
+export const PLAN_READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
+  'read', 'grep', 'find', 'ls', ASK_USER, 'ask_user_question',
+  'history_search', 'history_read', 'trajectory_search', 'trajectory_read',
+  'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load', 'mcp_list_tools'
+])
+
+export const PLAN_SECTION_ID = 'plan'
+/** Between the application's role and the memory blocks. */
+export const PLAN_SECTION_ORDER = 25
+export const PLAN_OPEN_TAG = '<proposed_plan>'
+export const PLAN_CLOSE_TAG = '</proposed_plan>'
+
+export const PLAN_INSTRUCTIONS = `Plan mode is on for this request. Investigate and design; do not carry out the work.
+- Read, search and recall freely. When a decision belongs to the user, ask with ${ASK_USER} instead of guessing.
+- Do not change files, run commands, write memory, delegate, or call connected apps. Such calls are refused while plan mode is on.
+- When the plan is ready, end the reply with exactly one block in this form, after any other text:
+${PLAN_OPEN_TAG}
+# <Plan title>
+<Markdown: the context, the steps with the files they change, and how to verify the result>
+${PLAN_CLOSE_TAG}
+- If you need the user's input before a plan is possible, ask instead of proposing one.`
+
+/** The tools a plan-mode run may call: the read-only set and the provider tools marked read-only. */
+export function planModeTools(normal: readonly string[], readOnly: Iterable<string> = []): string[] {
+  const allowed = new Set([...PLAN_READ_ONLY_TOOLS, ...readOnly])
+  return normal.filter((name) => allowed.has(name))
+}
+
+/** Why a plan-mode run may not call this tool, or null when it may. */
+export function planRefusal(tool: string, readOnly: ReadonlySet<string>): string | null {
+  if (PLAN_READ_ONLY_TOOLS.has(tool) || readOnly.has(tool)) return null
+  return `Plan mode is read-only: ${tool} is not available until the user leaves plan mode. Continue investigating, or finish with a ${PLAN_OPEN_TAG} block.`
+}
+
+/**
+ * The plan section for this request. While plan mode is on it carries the instructions; on the
+ * first request after it, the empty slot withdraws the earlier instructions from the conversation.
+ * Otherwise there is no section, so a conversation that never planned is delivered exactly as before.
+ */
+export function planSection(plan: boolean, historyFile: string | null): HostSection | null {
+  if (plan) return { id: PLAN_SECTION_ID, title: 'Plan mode', body: PLAN_INSTRUCTIONS, budget: 2000, order: PLAN_SECTION_ORDER, dynamic: true }
+  const delivered = historyFile ? deliveredSnapshot(historyFile) : null
+  return delivered?.some((entry) => entry.id === PLAN_SECTION_ID)
+    ? { id: PLAN_SECTION_ID, title: 'Plan mode', body: null, budget: 2000, order: PLAN_SECTION_ORDER, dynamic: true }
+    : null
+}

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

@@ -400,6 +400,29 @@ describe('session turns on Pi', () => {
     expect(contexts).toEqual([policyContext])
   })
 
+  it('refuses non-read-only calls in plan mode and delivers its instructions without changing the system prompt', async () => {
+    const seen: { system: string; update: string | null; reasons: (string | null)[] }[] = []
+    const { run, harness } = setup(async ({ gate, params }) => fakeSession(async () => {
+      const reasons = [await gate.check('bash', {}), await gate.check('write', {}), await gate.check('memory_append', {}), await gate.check('lookup', {}), await gate.check('change', {})]
+      seen.push({ system: params.system, update: params.update?.content ?? null, reasons })
+    }, gate))
+    harness.approvals.setAuto('chat', true)
+    harness.sessions.provide(() => [
+      { name: 'lookup', label: 'Lookup', description: 'Reads', readOnly: true, parameters: (Type) => Type.Object({}), execute: async () => 'ok' },
+      { name: 'change', label: 'Change', description: 'Writes', parameters: (Type) => Type.Object({}), execute: async () => 'ok' }
+    ])
+    await run('plan-run', { plan: true, tools: { allow: ['read', 'bash', 'write', 'lookup', 'change'] } })
+    await tick()
+    await run('normal-run', { tools: { allow: ['read', 'bash', 'write', 'lookup', 'change'] } })
+    await tick()
+    const [planned, normal] = seen
+    expect(planned.reasons.map((reason) => reason?.startsWith('Plan mode is read-only') ?? null)).toEqual([true, true, true, null, true])
+    expect(normal.reasons).toEqual([null, null, null, null, null])
+    expect(planned.system).toBe(normal.system)
+    expect(planned.update).toContain('<proposed_plan>')
+    expect(normal.update ?? '').not.toContain('Plan mode is on')
+  })
+
   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)))
@@ -423,7 +446,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 +519,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 +528,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 +539,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 +595,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 +606,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()
   })
 })

package/src/sessions/sessions.ts

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