@xingular/harness 0.1.7 → 2.1.0

package/src/memory/trajectory.ts

@@ -0,0 +1,220 @@
+// Read-only views over the canonical run records and validated event logs.
+import type { HarnessEnv } from '../core/env'
+import { invalid, notFound } from '../core/errors'
+import { listProjects } from '../core/projects'
+import { compareText } from '../core/text'
+import { scrub } from '../accounts/store'
+import { scrubSensitive } from '../mcp/connections'
+import { isActiveStatus, runStatusSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
+import { readAllRuns } from '../sessions/runIndex'
+import { findRun, snapshot } from '../sessions/runStore'
+import type { CallerContext } from './caller'
+
+const SEARCH_DEFAULT = 10
+const SEARCH_MAX = 30
+const READ_DEFAULT = 8
+const READ_MAX = 10
+const EVENT_MAX_CHARS = 18_000
+const PAGE_MAX_CHARS = 48_000
+
+export type Params = Record<string, unknown> | null | undefined
+
+function textParam(params: Params, key: string): string {
+  const value = params?.[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function boundedInteger(params: Params, key: string, fallback: number, minimum: number, maximum: number): number {
+  const value = params?.[key]
+  if (value === undefined) return fallback
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum || value > maximum) {
+    throw invalid(`${key} must be an integer from ${minimum} to ${maximum}.`)
+  }
+  return value
+}
+
+function dateValue(params: Params, key: string): { text: string; timestamp: number } | null {
+  const value = textParam(params, key)
+  if (!value) return null
+  if (!/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value)) throw invalid(`${key} must be a YYYY-MM-DD date or ISO timestamp.`)
+  const timestamp = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}${key === 'until' ? 'T23:59:59.999Z' : 'T00:00:00.000Z'}` : value)
+  if (!Number.isFinite(timestamp)) throw invalid(`${key} must be a valid date or ISO timestamp.`)
+  return { text: value, timestamp }
+}
+
+interface Cursor {
+  startedAt: string
+  id: string
+}
+
+function decodeCursor(value: string): Cursor | null {
+  if (!value) return null
+  try {
+    const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) as Partial<Cursor>
+    if (typeof parsed.startedAt !== 'string' || !parsed.startedAt || typeof parsed.id !== 'string' || !parsed.id) throw new Error('invalid cursor')
+    return { startedAt: parsed.startedAt, id: parsed.id }
+  } catch {
+    throw invalid('The trajectory cursor is invalid. Start a new search without it.')
+  }
+}
+
+function encodeCursor(run: RunRecord): string {
+  return Buffer.from(JSON.stringify({ startedAt: run.startedAt, id: run.id })).toString('base64url')
+}
+
+function hidden(env: HarnessEnv, context: CallerContext, run: RunRecord): boolean {
+  const excluded = context.recallExcludeAgents ?? []
+  if (!excluded.length) return false
+  return excluded.includes(run.agentId ?? '') || excluded.includes(run.sessionId) || excluded.includes(env.directory.sessionAgent(run.sessionId) ?? '')
+}
+
+function afterCursor(run: RunRecord, cursor: Cursor): boolean {
+  return run.startedAt < cursor.startedAt || (run.startedAt === cursor.startedAt && run.id < cursor.id)
+}
+
+function summary(env: HarnessEnv, run: RunRecord, projects: ReturnType<typeof listProjects>) {
+  const project = projects.find((entry) => entry.id === run.projectId)
+  const goal = run.goal?.trim() ?? ''
+  return {
+    id: run.id,
+    agentId: run.agentId,
+    agentName: run.agentId ? env.directory.agentName(run.agentId) : null,
+    project: project ? { id: project.id, name: project.name, slug: project.slug } : null,
+    mode: run.mode,
+    status: run.status,
+    goal: goal.length > 500 ? `${goal.slice(0, 497)}…` : goal || null,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    parentRunId: run.parentRunId,
+    relation: run.relation
+  }
+}
+
+/** `trajectory.search`: structured list/search over the current Harness data root. */
+export function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const agent = textParam(params, 'agent')
+  const projectKey = textParam(params, 'project')
+  const mode = textParam(params, 'mode')
+  const status = textParam(params, 'status')
+  const since = dateValue(params, 'since')
+  const until = dateValue(params, 'until')
+  const limit = boundedInteger(params, 'limit', SEARCH_DEFAULT, 1, SEARCH_MAX)
+  const cursor = decodeCursor(textParam(params, 'cursor'))
+
+  if (status && !runStatusSchema.safeParse(status).success) throw invalid(`Unknown run status ${status}.`)
+  const projects = listProjects(env.root)
+  const project = projectKey ? projects.find((entry) => entry.id === projectKey || entry.slug === projectKey || entry.name.toLowerCase() === projectKey.toLowerCase()) : null
+  if (projectKey && !project) throw invalid(`There is no project called ${projectKey}.`)
+
+  const matching = readAllRuns(env.root)
+    .filter((run) => !hidden(env, context, run))
+    .filter((run) => !agent || run.agentId === agent || (run.agentId !== null && env.directory.agentName(run.agentId)?.toLowerCase() === agent.toLowerCase()))
+    .filter((run) => !projectKey || run.projectId === project?.id)
+    .filter((run) => !mode || run.mode === mode)
+    .filter((run) => !status || run.status === status)
+    .filter((run) => !since || Date.parse(run.startedAt) >= since.timestamp)
+    .filter((run) => !until || Date.parse(run.startedAt) <= until.timestamp)
+    .filter((run) => !cursor || afterCursor(run, cursor))
+    .sort((left, right) => compareText(right.startedAt, left.startedAt) || compareText(right.id, left.id))
+
+  const page = matching.slice(0, limit)
+  const hasMore = matching.length > page.length
+  return JSON.stringify({
+    runs: page.map((run) => summary(env, run, projects)),
+    hasMore,
+    nextCursor: hasMore && page.length ? encodeCursor(page[page.length - 1]) : null
+  })
+}
+
+function boundedValue(value: unknown, path: string, truncated: string[], stringLimit: number, arrayLimit: number, depth = 0): unknown {
+  if (typeof value === 'string') {
+    const fieldLimit = path.endsWith('.systemPrompt') || path.endsWith('.contextUpdate') ? Math.min(12_000, stringLimit) :
+      path.endsWith('.input') || path.endsWith('.output') || path.endsWith('.summary') ? Math.min(10_000, stringLimit) : stringLimit
+    if (value.length <= fieldLimit) return value
+    truncated.push(path)
+    return `${value.slice(0, Math.max(0, fieldLimit - 16))}… [truncated]`
+  }
+  if (Array.isArray(value)) {
+    const kept = value.slice(0, arrayLimit).map((item, index) => boundedValue(item, `${path}[${index}]`, truncated, stringLimit, arrayLimit, depth + 1))
+    if (value.length > arrayLimit) truncated.push(path)
+    return kept
+  }
+  if (!value || typeof value !== 'object' || depth >= 8) return value
+  const entries = Object.entries(value as Record<string, unknown>)
+  const kept = entries.slice(0, 40).map(([key, item]) => [key, boundedValue(item, `${path}.${key}`, truncated, stringLimit, arrayLimit, depth + 1)])
+  if (entries.length > 40) truncated.push(path)
+  return Object.fromEntries(kept)
+}
+
+function publicEvent(event: RunEvent): Record<string, unknown> {
+  let stringLimit = 12_000
+  let arrayLimit = 20
+  while (true) {
+    const truncated: string[] = []
+    const omitted: string[] = []
+    let payload = scrubSensitive(event.payload)
+    if (event.type === 'account.status' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      const account = payload as Record<string, unknown>
+      if (Object.hasOwn(account, 'accountId')) {
+        delete account.accountId
+        omitted.push('payload.accountId')
+      }
+      if (typeof account.message === 'string') account.message = scrub(account.message)
+    }
+    if (event.type === 'usage.updated' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      const request = (payload as Record<string, unknown>).request
+      if (request && typeof request === 'object' && !Array.isArray(request) && Object.hasOwn(request, 'reasoningSummary')) {
+        delete (request as Record<string, unknown>).reasoningSummary
+        omitted.push('payload.request.reasoningSummary')
+      }
+    }
+    const value: Record<string, unknown> = {
+      id: event.id,
+      sequence: event.sequence,
+      timestamp: event.timestamp,
+      type: event.type,
+      payload: boundedValue(payload, 'payload', truncated, stringLimit, arrayLimit)
+    }
+    if (event.coalescedFrom !== undefined) value.coalescedFrom = event.coalescedFrom
+    if (truncated.length) value.truncatedFields = truncated.slice(0, 40)
+    if (omitted.length) value.omittedFields = omitted
+    if (JSON.stringify(value).length <= EVENT_MAX_CHARS || (stringLimit <= 500 && arrayLimit <= 1)) return value
+    stringLimit = Math.max(500, Math.floor(stringLimit / 2))
+    arrayLimit = Math.max(1, Math.floor(arrayLimit / 2))
+  }
+}
+
+/** `trajectory.read`: a bounded page of the events that affected a run. */
+export function readTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const requested = textParam(params, 'run')
+  if (!requested) throw invalid('Give a run id or "current".')
+  const runId = requested === 'current' ? context.runId ?? '' : requested
+  if (!runId) throw invalid('This caller has no current run.')
+  const run = findRun(env.root, runId)
+  if (!run || hidden(env, context, run)) throw notFound('Run')
+
+  const afterSequence = boundedInteger(params, 'afterSequence', -1, -1, Number.MAX_SAFE_INTEGER)
+  const limit = boundedInteger(params, 'limit', READ_DEFAULT, 1, READ_MAX)
+  const captured = snapshot(env.root, run.id)
+  const candidates = captured.events.filter((event) => event.sequence > afterSequence)
+  const events: Record<string, unknown>[] = []
+  let eventChars = 0
+  for (const event of candidates.slice(0, limit)) {
+    const bounded = publicEvent(event)
+    const size = JSON.stringify(bounded).length
+    if (events.length && eventChars + size > PAGE_MAX_CHARS) break
+    events.push(bounded)
+    eventChars += size
+  }
+  const lastSequence = events.length ? Number(events[events.length - 1].sequence) : afterSequence
+  const hasMore = candidates.some((event) => event.sequence > lastSequence)
+  const projects = listProjects(env.root)
+  const result = {
+    run: summary(env, captured.run, projects),
+    active: isActiveStatus(captured.run.status),
+    events,
+    hasMore,
+    nextAfterSequence: lastSequence
+  }
+  return JSON.stringify(result)
+}

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'
@@ -82,6 +83,8 @@ export function methods(harness: Harness): Record<string, Handler> {
     'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
     'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
     'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+    'hub.preview': (params: Params) => harness.hub.preview(text(params, 'id'), text(params, 'version'), typeof params.offset === 'number' ? params.offset : 0),
+    'hub.uninstall': (params: Params) => harness.hub.uninstall(text(params, 'id'), text(params, 'version')),
     'hub.readDocument': (params: Params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version')),
 
     // ---- Accounts --------------------------------------------------------------------------------
@@ -134,6 +137,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 +340,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/planMode.test.ts

@@ -0,0 +1,40 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from '../prompt/compile'
+import { PLAN_INSTRUCTIONS, PLAN_SECTION_ID, planModeTools, planRefusal, planSection } from './planMode'
+
+function history(sectionIds: string[]): string {
+  const file = join(mkdtempSync(join(tmpdir(), 'plan-history-')), 'session.jsonl')
+  const snapshot = sectionIds.map((id) => ({ id, title: id, body: 'x', sources: [], budget: 100, size: 1, cut: false }))
+  writeFileSync(file, [
+    JSON.stringify({ type: 'session', id: 'session' }),
+    JSON.stringify({ type: 'custom_message', id: 'c1', parentId: null, customType: CONTEXT_MESSAGE_TYPE, details: { [CONTEXT_SNAPSHOT_KEY]: snapshot } })
+  ].join('\n'))
+  return file
+}
+
+describe('plan mode', () => {
+  it('keeps read-only inspection, questions and recall, plus provider tools marked read-only', () => {
+    const normal = ['read', 'bash', 'edit', 'write', 'grep', 'ask_user', 'wiki_search', 'memory_append', 'spawn_subagent', 'files_read', 'files_write', 'skill_load']
+    expect(planModeTools(normal, ['files_read'])).toEqual(['read', 'grep', 'ask_user', 'wiki_search', 'files_read', 'skill_load'])
+  })
+
+  it('refuses changes, commands, memory writes and delegation with a reason the model can act on', () => {
+    const readOnly = new Set(['files_read'])
+    for (const tool of ['read', 'grep', 'wiki_read', 'files_read', 'ask_user']) expect(planRefusal(tool, readOnly), tool).toBeNull()
+    for (const tool of ['bash', 'write', 'edit', 'memory_append', 'wiki_propose', 'spawn_subagent', 'mcp_call_tool', 'files_write']) {
+      expect(planRefusal(tool, readOnly), tool).toContain('Plan mode is read-only')
+    }
+  })
+
+  it('adds its instructions while on, withdraws them once after, and is absent otherwise', () => {
+    expect(planSection(true, null)).toMatchObject({ id: PLAN_SECTION_ID, body: PLAN_INSTRUCTIONS, dynamic: true })
+    expect(PLAN_INSTRUCTIONS).toContain('<proposed_plan>')
+    expect(planSection(false, null)).toBeNull()
+    expect(planSection(false, history(['blocks']))).toBeNull()
+    expect(planSection(false, history(['blocks', PLAN_SECTION_ID]))).toMatchObject({ id: PLAN_SECTION_ID, body: null, dynamic: true })
+  })
+})