@xingular/harness 0.1.7 → 2.1.0

package/src/terminal/piExtension.ts

@@ -9,7 +9,8 @@ import { connectionFromEnv, socketCall, terminalCall } from './client'
 import { runAccountsMenu, type SessionAccount } from './accountsMenu'
 import { runPluginsMenu } from './pluginMenu'
 import { runHubMenu } from './hubMenu'
-import { claimTerminalControl } from './control'
+import { claimTerminalControl, controlCall } from './control'
+import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory, type SubagentReceipt } from '../sessions/subagents'
 import { askUserTool } from '../tools/askUser'
 import type { QuestionAnswer } from '../sessions/registry'
 
@@ -27,9 +28,18 @@ function resultSize(result: unknown): number | null {
   return content.reduce((total: number, part: { type?: string; text?: unknown }) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0)
 }
 
+async function withParentCancellation<T>(signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T> {
+  const stop = () => { void controlCall('terminal.interrupt').catch(() => {}) }
+  if (signal?.aborted) stop()
+  signal?.addEventListener('abort', stop, { once: true })
+  try { return await work() } finally { signal?.removeEventListener('abort', stop) }
+}
+
 export default async function (pi: ExtensionAPI) {
   await terminalCall('startup', { phase: 'Pi extension loaded' })
   let context: ExtensionContext | null = null
+  let nativeSubagents = false
+  let subagentParent = false
   let timer: ReturnType<typeof setInterval> | null = null
   let polling = false
   let failure: string | undefined
@@ -105,6 +115,15 @@ export default async function (pi: ExtensionAPI) {
         }
       })
     }
+    const native = await controlCall<{ tools: SocketTool[] }>('terminal.subagents.tools')
+    nativeSubagents = native.tools.length > 0
+    for (const tool of native.tools) pi.registerTool({
+      name: tool.name, label: tool.label, description: tool.description, parameters: Type.Unsafe(tool.parameters),
+      execute: async (_id, input, signal) => {
+        const result = await withParentCancellation(signal, () => controlCall<{ text: string; details?: Record<string, unknown> }>('terminal.subagents.call', { name: tool.name, input }, 2_147_483_647))
+        return { content: [{ type: 'text' as const, text: result.text }], details: result.details ?? {} }
+      }
+    })
   } catch (error) {
     await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => {})
     throw error
@@ -142,8 +161,21 @@ export default async function (pi: ExtensionAPI) {
     reasoningTokens = undefined
     costReported = false
     // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
-    await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    const begun = await terminalCall<{ runId: string }>('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    if (nativeSubagents) {
+      pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId })
+      await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) })
+      subagentParent = true
+    }
   })
+  const deliverChildren = async (event: any, ctx: ExtensionContext, settle: boolean) => {
+    if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
+    const result = await withParentCancellation(ctx.signal, () => controlCall<{ text: string; receipt: SubagentReceipt } | null>('terminal.subagents.delivery', { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2_147_483_647))
+    if (!result) return
+    return { entries: [...event.entries, { type: 'custom_message' as const, customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true }
+  }
+  pi.on('turn_end', (event, ctx) => deliverChildren(event, ctx, false))
+  pi.on('agent_before_settle', (event, ctx) => deliverChildren(event, ctx, true))
   pi.on('message_end', async (event) => {
     if (event.message.role !== 'assistant') return
     if (event.message.stopReason === 'error' || event.message.stopReason === 'aborted') failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`
@@ -193,9 +225,9 @@ export default async function (pi: ExtensionAPI) {
   })
   pi.on('tool_call', async (event) => {
     try {
-      const policy = await terminalCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('policy', { tool: event.toolName, args: event.input })
+      const policy = await controlCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('terminal.policy', { tool: event.toolName, args: event.input })
       if (policy.requiresApproval) {
-        const approval = await terminalCall<{ decision: string }>('approval', { requestId: event.toolCallId, target: event.toolName, action: JSON.stringify(event.input), tool: event.toolName, args: event.input })
+        const approval = await controlCall<{ decision: string }>('terminal.approval', { requestId: event.toolCallId, tool: event.toolName, args: event.input })
         if (approval.decision === 'approved') return
         return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' }
       }
@@ -218,8 +250,12 @@ export default async function (pi: ExtensionAPI) {
     fileTools.delete(event.toolCallId)
     if (!event.isError && path) await terminalCall('file', { path, change: 'modified' })
   })
-  pi.on('agent_settled', async () => {
-    await terminalCall('settled', { error: failure })
+  pi.on('agent_settled', async (event, ctx) => {
+    if (subagentParent && !event.aborted && !failure) {
+      try { await controlCall('terminal.subagents.verify', { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2_147_483_647) } catch (error) { failure = error instanceof Error ? error.message : String(error) }
+    }
+    subagentParent = false
+    await terminalCall('settled', { error: failure, aborted: event.aborted })
   })
   pi.on('user_bash', async () => {
     throw new Error('Use the bash tool so this action can be checked.')

package/src/terminal/socket.test.ts

@@ -33,6 +33,29 @@ describe('session socket path', () => {
 })
 
 describe('session socket', () => {
+  it.skipIf(process.platform === 'win32')('keeps an existing Harness socket reachable when another instance uses the same state folder', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'sock-shared-state-'))
+    const path = socketPath(base)
+    const first = new SessionSocket(path, handlers)
+    const second = new SessionSocket(path, handlers)
+    const canConnect = (socketPath: string): Promise<void> => new Promise((resolve, reject) => {
+      const client = createConnection(socketPath)
+      client.once('connect', () => { client.end(); resolve() })
+      client.once('error', reject)
+    })
+    try {
+      await first.listen()
+      await second.listen()
+      expect(second.path).not.toBe(first.path)
+      await second.close()
+      await expect(canConnect(first.path)).resolves.toBeUndefined()
+    } finally {
+      await first.close()
+      await second.close()
+      rmSync(base, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(process.platform !== 'win32')('listens on a named pipe and answers a request on Windows', async () => {
     const socket = new SessionSocket(socketPath('unused'), handlers)
     await socket.listen()

package/src/terminal/socket.ts

@@ -56,6 +56,11 @@ export function socketPath(stateDir: string): string {
   return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
 }
 
+function alternateSocketPath(path: string): string {
+  const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`)
+  return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${randomBytes(16).toString('hex')}.sock`)
+}
+
 /** A named pipe has no folder, file mode, or owner to check or clean up. */
 const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
 
@@ -88,6 +93,7 @@ function refusedBind(path: string, error: unknown): unknown {
 export class SessionSocket {
   private server: Server | null = null
   private listening: Promise<void> | null = null
+  private socketPathValue: string
   private readonly grants = new Map<string, SocketGrant>()
   /**
    * A second key per token, handed out once. The token is in the session's environment, where a
@@ -97,10 +103,11 @@ export class SessionSocket {
   private readonly controls = new Map<string, string>()
   private readonly clients = new Set<Socket>()
 
-  constructor(
-    readonly path: string,
-    private readonly handlers: SocketHandlers
-  ) {}
+  constructor(path: string, private readonly handlers: SocketHandlers) {
+    this.socketPathValue = path
+  }
+
+  get path(): string { return this.socketPathValue }
 
   issue(grant: SocketGrant): string {
     const token = `${newId()}${newId()}`.replaceAll('-', '')
@@ -141,6 +148,7 @@ export class SessionSocket {
       const call = typeof request.call === 'string' ? request.call : ''
       const params = (request.params && typeof request.params === 'object' ? request.params : {}) as Record<string, unknown>
       if (['wiki.', 'memory.', 'recall.'].some((prefix) => call.startsWith(prefix))) return { result: this.handlers.memory(grant.caller(), call, params) }
+      if (call === 'tools.list' && !grant.broker) return { result: { tools: [] } }
       if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
         if (!grant.broker) throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.')
         return { result: await this.handlers.apps(grant.broker, call, params) }
@@ -193,22 +201,14 @@ export class SessionSocket {
     })
   }
 
-  /** Binds the socket once; later calls wait for the same bind. */
-  listen(): Promise<void> {
-    this.listening ??= new Promise<void>((resolve, reject) => {
-      if (!isPipePath(this.path)) {
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-        rmSync(this.path, { force: true })
-      }
+  private bind(path: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
       const server = createServer((client) => this.serve(client))
-      server.once('error', (error) => {
-        this.listening = null
-        reject(refusedBind(this.path, error))
-      })
-      server.listen(this.path, () => {
-        if (!isPipePath(this.path)) {
+      server.once('error', reject)
+      server.listen(path, () => {
+        if (!isPipePath(path)) {
           try {
-            chmodSync(this.path, 0o600)
+            chmodSync(path, 0o600)
           } catch (error) {
             log('session socket permissions', error instanceof Error ? error.message : String(error))
           }
@@ -217,6 +217,30 @@ export class SessionSocket {
         resolve()
       })
     })
+  }
+
+  /** Binds the usual path, or an instance-specific path if another Harness owns it. */
+  private async bindAvailablePath(): Promise<void> {
+    if (!isPipePath(this.path)) mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+    try {
+      await this.bind(this.path)
+    } catch (error) {
+      if (isPipePath(this.path) || (error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw refusedBind(this.path, error)
+      this.socketPathValue = alternateSocketPath(this.path)
+      try {
+        await this.bind(this.path)
+      } catch (alternateError) {
+        throw refusedBind(this.path, alternateError)
+      }
+    }
+  }
+
+  /** Binds the socket once; later calls wait for the same bind. */
+  listen(): Promise<void> {
+    this.listening ??= this.bindAvailablePath().catch(error => {
+      this.listening = null
+      throw error
+    })
     return this.listening
   }
 

package/src/terminal/standalone.ts

@@ -1,9 +1,11 @@
 // The standalone host prepares an isolated Harness terminal and supervises its frontend.
 import { spawn as nodeSpawn } from 'node:child_process'
 import { createHash, randomUUID } from 'node:crypto'
+import { appendFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 
+import { setLogSink } from '../core/bus'
 import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { TerminalLaunch } from './terminals'
 
@@ -128,6 +130,15 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
   const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: 'Xingular Harness' })
   const newSessionId = dependencies.createSessionId ?? randomUUID
   let current = { sessionId: newSessionId(), accountId: null as string | null, nativeSessionId: null as string | null }
+  // The frontend draws on this terminal, so the host's diagnostics go to a file the person can read instead.
+  const logFile = join(paths.stateDir, 'harness.log')
+  setLogSink((text) => {
+    try {
+      appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`)
+    } catch {
+      // Diagnostics are best effort; a full disk must not stop the terminal.
+    }
+  })
 
   try {
     await harness.ready
@@ -149,5 +160,6 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
   } finally {
     await harness.terminals.dispose(current.sessionId)
     await harness.close()
+    setLogSink(null)
   }
 }

package/src/terminal/terminal.test.ts

@@ -22,6 +22,23 @@ afterEach(async () => {
   for (const harness of open.splice(0)) await harness.close()
 })
 
+function tellOn(connection: SocketConnection, event: string, data: Record<string, unknown> = {}) {
+  return new Promise<any>((resolve, reject) => {
+    const stream = connect(connection.socket)
+    let buffer = ''
+    stream.on('connect', () => stream.write(`${JSON.stringify({ token: connection.token, event, data })}\n`))
+    stream.on('data', (chunk) => {
+      buffer += chunk.toString()
+      if (!buffer.includes('\n')) return
+      const reply = JSON.parse(buffer.slice(0, buffer.indexOf('\n')))
+      stream.end()
+      if (reply.error) reject(new Error(reply.error.message))
+      else resolve(reply.result)
+    })
+    stream.on('error', reject)
+  })
+}
+
 async function setup(policy: ToolPolicy = {}) {
   const root = rootWithProject()
   const harness = createHarness({ dataRoot: root, stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), policy, piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' } })
@@ -39,21 +56,7 @@ async function setup(policy: ToolPolicy = {}) {
   const launch = await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder, model: 'chosen-model', launch: { connections: 'Use mcp_list_tools.' } })
   const connection: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
   /** One telemetry line, as the native extension sends it. */
-  const tell = (event: string, data: Record<string, unknown> = {}) =>
-    new Promise<any>((resolve, reject) => {
-      const stream = connect(connection.socket)
-      let buffer = ''
-      stream.on('connect', () => stream.write(`${JSON.stringify({ token: connection.token, event, data })}\n`))
-      stream.on('data', (chunk) => {
-        buffer += chunk.toString()
-        if (!buffer.includes('\n')) return
-        const reply = JSON.parse(buffer.slice(0, buffer.indexOf('\n')))
-        stream.end()
-        if (reply.error) reject(new Error(reply.error.message))
-        else resolve(reply.result)
-      })
-      stream.on('error', reject)
-    })
+  const tell = (event: string, data: Record<string, unknown> = {}) => tellOn(connection, event, data)
   return { harness, root, account, events, notices, launch, connection, tell, sessionFolder }
 }
 
@@ -237,6 +240,117 @@ describe('a pi terminal session', () => {
     expect(await decision).toEqual({ decision: 'approved' })
   })
 
+  it('protects permission controls and shares saved terminal grants across sessions', async () => {
+    const { connection, harness, account, root } = await setup()
+    await expect(socketCall(connection, 'terminal.permissions.get')).rejects.toMatchObject({ code: 'unauthorized' })
+    await expect(socketCall(connection, 'terminal.policy', { tool: 'bash', args: {} })).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.permissions.get', {}, 1000, key)).toEqual({ full: false, globalTools: [] })
+    await socketCall(connection, 'terminal.permissions.setTool', { tool: 'bash', allowed: true }, 1000, key)
+    await socketCall(connection, 'terminal.permissions.setFull', { enabled: true }, 1000, key)
+
+    const secondLaunch = await harness.terminals.prepare({ sessionId: 'term-2', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-2') })
+    const secondConnection: SocketConnection = { socket: String(secondLaunch.env[SOCKET_ENV]), token: String(secondLaunch.env[TOKEN_ENV]) }
+    const { key: secondKey } = await socketCall<{ key: string }>(secondConnection, 'control.claim')
+    expect(await socketCall(secondConnection, 'terminal.permissions.get', {}, 1000, secondKey)).toEqual({ full: true, globalTools: ['bash'] })
+    await socketCall(secondConnection, 'terminal.permissions.setTool', { tool: 'bash', allowed: false }, 1000, secondKey)
+    expect(await socketCall(connection, 'terminal.permissions.get', {}, 1000, key)).toEqual({ full: true, globalTools: [] })
+    await expect(socketCall(connection, 'terminal.permissions.setFull', { enabled: 'yes' }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+  })
+
+  it('does not let a permission change retroactively resolve an already pending approval', async () => {
+    const { connection, tell } = await setup()
+    await tell('ready')
+    await tell('begin', { text: 'Wait for a decision' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'already-pending', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1)
+      requestId = requests[0]!.requestId
+    })
+
+    await socketCall(connection, 'terminal.permissions.setFull', { enabled: true }, 1000, key)
+    expect(await socketCall(connection, 'terminal.pending', {}, 1000, key)).toMatchObject({ requests: [{ requestId }] })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'denied' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('rechecks native tool policy when a pending approval is resolved', async () => {
+    let denied = false
+    const { connection, tell } = await setup({
+      scope: async () => denied ? { allowed: false, reason: 'The policy now denies this tool.' } : { allowed: true, requiresApproval: true }
+    })
+    await tell('ready')
+    await tell('begin', { text: 'Run a tool' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.policy', { tool: 'bash', args: { command: 'pwd' } }, 1000, key)).toMatchObject({ requiresApproval: true, rememberable: true })
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'call-approval', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const pending = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(pending.requests).toHaveLength(1)
+      requestId = pending.requests[0]!.requestId
+    })
+
+    denied = true
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'approved' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('keeps human-only rules out of tool grants and Full Permission unless the host opts in', async () => {
+    const { connection, tell, events, harness } = await setup({
+      scope: async () => ({ allowed: true, humanOnly: true, allowGlobalApproval: false })
+    })
+    harness.approvals.setAuto('pi', true)
+    await tell('ready')
+    await tell('begin', { text: 'Human decision required' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    expect(await socketCall(connection, 'terminal.policy', { tool: 'bash', args: {} }, 1000, key)).toMatchObject({ requiresApproval: true, rememberable: false, standing: 'none' })
+    const approval = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'human-only', tool: 'bash', args: {} }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      expect(events.some(event => event.type === 'approval.requested')).toBe(true)
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string; rememberable?: boolean }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1)
+      expect(requests[0]?.rememberable).toBe(false)
+      requestId = requests[0]!.requestId
+    })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'denied' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'denied' })
+  })
+
+  it('remembers a tool choice for future Pi terminal sessions sharing the state directory', async () => {
+    const { connection, tell, events, harness, account, root } = await setup()
+    await tell('ready')
+    await tell('begin', { text: 'Allow a tool' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const first = socketCall<{ decision: string }>(connection, 'terminal.approval', { requestId: 'remember-call', tool: 'bash', args: { command: 'pwd' } }, 1000, key)
+    let requestId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string; rememberable?: boolean }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests[0]?.rememberable).toBe(true)
+      requestId = requests[0]!.requestId
+    })
+    await socketCall(connection, 'terminal.approve', { requestId, decision: 'approved', alwaysAllow: true }, 1000, key)
+    expect(await first).toEqual({ decision: 'approved' })
+    expect(harness.approvals.read().globalTools.pi).toEqual(['bash'])
+
+    const launch = await harness.terminals.prepare({ sessionId: 'term-2', accountId: account.id, projectId: 'p1', cwd: root, sessionFolder: join(root, 'sessions', 'p1', 'term-2') })
+    const next: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
+    await tellOn(next, 'startup', { phase: 'ready' })
+    await tellOn(next, 'ready')
+    await tellOn(next, 'begin', { text: 'Reuse the grant' })
+    const { key: nextKey } = await socketCall<{ key: string }>(next, 'control.claim')
+    const before = events.filter(event => event.type === 'approval.requested').length
+    expect(await socketCall(next, 'terminal.approval', { requestId: 'next-call', tool: 'bash', args: { command: 'git status' } }, 1000, nextKey)).toEqual({ decision: 'approved' })
+    const automatic = events.filter(event => event.type === 'approval.requested').slice(before)
+    expect(automatic).toHaveLength(1)
+    expect(automatic[0]?.payload).toMatchObject({ automatic: 'remembered', target: 'bash' })
+    expect(await socketCall(next, 'terminal.pending', {}, 1000, nextKey)).toEqual({ requests: [] })
+  })
+
   it('applies the application policy to native tool calls', async () => {
     const seen: string[] = []
     const { tell } = await setup({
@@ -332,6 +446,27 @@ describe('xagent-wiki command', () => {
 
 
 describe('decisions in the Harness-owned frontend', () => {
+  it('exposes trajectory reads only to the input owner and scopes them to the current native conversation', async () => {
+    const { connection, tell, events } = await setup()
+    await tell('ready', { nativeSessionId: '/history/current.jsonl' })
+    await tell('begin', { text: 'Inspect this run' })
+    await tell('message', { text: 'Recorded response' })
+    await tell('settled', {})
+    const runId = events.find(event => event.type === 'started')!.runId
+
+    await expect(socketCall(connection, 'terminal.trajectory.list')).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const listed = await socketCall<{ runs: Array<{ id: string }> }>(connection, 'terminal.trajectory.list', {}, 1000, key)
+    expect(listed.runs.map(run => run.id)).toContain(runId)
+    await expect(socketCall(connection, 'terminal.trajectory.events', { runId }, 1000, key)).resolves.toMatchObject({
+      run: { id: runId }, events: expect.arrayContaining([expect.objectContaining({ type: 'message.completed' })])
+    })
+
+    await tell('ready', { nativeSessionId: '/history/another.jsonl' })
+    await expect(socketCall(connection, 'terminal.trajectory.events', { runId }, 1000, key)).rejects.toMatchObject({ code: 'not_found' })
+    await expect(socketCall(connection, 'terminal.trajectory.list', {}, 1000, key)).resolves.toEqual({ runs: [] })
+  })
+
   it('requires the private input-owner key for pending decisions and exact draft state', async () => {
     const { connection, harness, tell } = await setup()
     await tell('ready', { nativeSessionId: '/native.jsonl' })

package/src/terminal/terminals.ts

@@ -5,7 +5,16 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync,
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { Type } from 'typebox'
+
+import type { CapabilitySet } from '../capabilities/types'
+import { freezeRun } from '../capabilities/runSnapshot'
+import type { Subagents } from '../sessions/subagentService'
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, type SubagentOptions } from '../sessions/subagents'
+import { subagentTools } from '../tools/spawnSubagent'
+import type { Effort } from '../sessions/runner'
 import type { Accounts } from '../accounts/accounts'
+import type { Approvals } from '../sessions/approvals'
 import { configDir, launchEnv } from '../accounts/env'
 import { readAudit, type Account } from '../accounts/store'
 import type { Bus } from '../core/bus'
@@ -34,6 +43,7 @@ import { SOCKET_ENV, TOKEN_ENV } from './client'
 import { TerminalController, type PolicyReply } from './controller'
 import { resolvePiCommand, terminalCommandFiles } from './launch'
 import { SessionSocket, socketPath } from './socket'
+import { listTerminalTrajectoryRuns, readTerminalTrajectory } from './trajectory'
 
 /** Identity of the exact resource decision that this terminal was prepared with. */
 function resourceIdentity(loading: Loading | null): string {
@@ -63,6 +73,7 @@ export function defaultAssets(): TerminalAssets {
 }
 
 export interface TerminalPrepareInput {
+  subagents?: SubagentOptions | null
   sessionId: string
   /** The account the session is pinned to. Omitted only for a session that has none yet; it then takes the default and keeps it. */
   accountId?: string | null
@@ -100,10 +111,13 @@ interface Live {
 }
 
 export interface TerminalsOptions {
+  subagents?: Subagents
+  resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>
   env: HarnessEnv
   stateDir: string
   accounts: Accounts
   runs: RunRegistry
+  approvals: Approvals
   apps: ConnectedApps
   policy: ToolPolicy
   bus: Bus
@@ -136,7 +150,21 @@ export class Terminals {
 
   constructor(private readonly options: TerminalsOptions) {
     this.assets = options.assets ?? defaultAssets()
-    options.runs.listen(event => this.sessions.get(event.sessionId)?.controller.observe(event))
+    options.runs.listen(event => {
+      this.sessions.get(event.sessionId)?.controller.observe(event)
+      const record = findRun(options.env.root, event.runId)
+      if (record?.relation !== 'subagent') return
+      let parentId = record.parentRunId
+      const seen = new Set<string>()
+      while (parentId && !seen.has(parentId)) {
+        seen.add(parentId)
+        const parent = findRun(options.env.root, parentId)
+        if (!parent) break
+        const owner = this.sessions.get(parent.sessionId)
+        if (owner?.controller.activeRun?.runId === parent.id) { owner.controller.observe(event, true); break }
+        parentId = parent.parentRunId
+      }
+    })
     this.socket = new SessionSocket(socketPath(options.stateDir), {
       memory: (caller, call, params) => dispatch(options.env, caller, call, params),
       apps: (session, call, params) => this.appsCall(session, call, params),
@@ -383,19 +411,80 @@ export class Terminals {
     const { policy } = this.options
     if (policy.scope) {
       const scope = await policy.scope(call)
-      if (!scope.allowed && !scope.requiresApproval) return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' }
+      if (!scope.allowed && (scope.automatic || !scope.requiresApproval)) return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' }
       try {
         await policy.authorize?.(call)
       } catch (error) {
         return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' }
       }
-      return { allowed: scope.allowed, requiresApproval: !!scope.requiresApproval, reason: scope.reason ?? null }
+      const requiresApproval = !!scope.requiresApproval || (scope.allowed && !!scope.humanOnly)
+      return {
+        allowed: scope.allowed,
+        requiresApproval,
+        reason: scope.reason ?? null,
+        rememberable: scope.allowed && !scope.humanOnly,
+        ...(scope.humanOnly ? { standing: scope.allowGlobalApproval ? 'switch' as const : 'none' as const } : {})
+      }
     }
     // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
     const name = tool.toLowerCase()
-    if (READ_ONLY_TOOLS.has(name) || this.options.apps.toolNames.includes(name as never)) return { allowed: true }
+    if (name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.options.apps.toolNames.includes(name as never)) return { allowed: true }
     if (live.input.readOnly) return { allowed: false, reason: 'This session is read-only.' }
-    return { allowed: false, requiresApproval: true, reason: 'This native action requires approval.' }
+    return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.' }
+  }
+
+  private async subagentsCall(live: Live, call: string, params: Record<string, any>): Promise<unknown> {
+    const service = this.options.subagents
+    if (!service || live.input.subagents === null) {
+      if (call === 'terminal.subagents.tools') return { tools: [] }
+      throw invalid('Subagents are disabled for this terminal.')
+    }
+    if (call === 'terminal.subagents.tools') return { tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) }
+    const run = live.controller.activeRun
+    if (!run) throw new HarnessError('run_not_active', 'This terminal has no active parent run.')
+    if (call === 'terminal.subagents.register') {
+      if (!Array.isArray(params.tools) || params.tools.some((name: unknown) => typeof name !== 'string')) throw invalid('Native tool names are required.')
+      const readOnly = live.input.readOnly === true
+      const readTools = new Set([...READ_ONLY_TOOLS, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load'])
+      const tools = params.tools.filter((name: string) => !readOnly || readTools.has(name)) as string[]
+      const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(live.caller, tools, live.input.cwd) : { version: 1 as const, tools, connectors: [], contributions: [] }
+      freezeRun(this.options.env.root, run.runId, live.caller, capabilities)
+      service.register({
+        run: { id: run.runId, sessionId: live.input.sessionId, mode: live.input.run?.mode ?? 'code', projectId: live.input.projectId, worktreeId: live.input.run?.worktreeId },
+        cwd: live.input.cwd, sessionDir: this.historyDir(live.input), text: '', caller: live.caller,
+        model: typeof params.model === 'string' ? params.model : live.input.model,
+        effort: typeof params.effort === 'string' ? params.effort as Effort : null,
+        launch: live.input.launch, tools: { allow: capabilities.tools, gated: capabilities.tools.filter(name => !readTools.has(name)) },
+        connections: live.input.connections === false ? false : { readOnly }, subagents: live.input.subagents,
+        capabilities
+      }, live.account.id, capabilities)
+      service.restore(run.runId, params.history ?? { owners: [], receipts: [] })
+      return { runId: run.runId }
+    }
+    if (call === 'terminal.subagents.verify') { await service.verify(run.runId, params.history); return {} }
+    if (call === 'terminal.subagents.delivery') return service.delivery(run.runId, params.history, params.settle === true)
+    if (call === 'terminal.subagents.call') {
+      const tool = subagentTools(service, run.runId).find(tool => tool.name === params.name)
+      if (!tool) throw invalid('Unknown subagent tool.')
+      const reason = await this.decide(live, run, tool.name, params.input ?? {})
+      if (!reason.allowed) throw new HarnessError('tool_denied', reason.reason ?? 'Subagents are unavailable.')
+      const result = await tool.execute(params.input ?? {})
+      return typeof result === 'string' ? { text: result } : result
+    }
+    throw invalid('Unknown subagent operation.')
+  }
+
+  private trajectoryCall(live: Live, call: string, params: Record<string, unknown>): unknown {
+    if (call === 'terminal.trajectory.list') {
+      return { runs: listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId) }
+    }
+    if (call === 'terminal.trajectory.events') {
+      if (typeof params.runId !== 'string' || !params.runId) throw invalid('A run id is required.')
+      const afterSequence = params.afterSequence
+      if (afterSequence !== undefined && typeof afterSequence !== 'number') throw invalid('The event sequence must be a number.')
+      return readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, params.runId, afterSequence as number | undefined)
+    }
+    throw new HarnessError('unknown_method', `Unknown call ${call}.`)
   }
 
   /**
@@ -403,6 +492,7 @@ export class Terminals {
    * process's end with `dispose`, also when it never starts.
    */
   async prepare(input: TerminalPrepareInput): Promise<TerminalLaunch> {
+    input = structuredClone(input)
     const { env, accounts, apps, bus } = this.options
     const { root } = env
     if (!input?.sessionId || !input.cwd || !input.sessionFolder) throw invalid('A terminal session needs an id, a working folder, and its own folder.')
@@ -438,6 +528,7 @@ export class Terminals {
           nativeSessionId: input.nativeSessionId ?? null,
           begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
           policy: (run, tool, args) => this.decide(live, run, tool, args),
+          allowToolGlobally: target => { this.options.approvals.allowTool('pi', target) },
           native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
           telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
           interrupt: runId => this.options.runs.interrupt(runId),
@@ -451,6 +542,23 @@ export class Terminals {
         caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
         broker,
         terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
+          if (call.startsWith('terminal.subagents.')) return this.subagentsCall(live, call, params)
+          if (call.startsWith('terminal.trajectory.')) return this.trajectoryCall(live, call, params)
+          if (call === 'terminal.permissions.get') {
+            const policy = this.options.approvals.read()
+            return { full: this.options.approvals.isAuto('pi'), globalTools: policy.globalTools.pi ?? [] }
+          }
+          if (call === 'terminal.permissions.setFull') {
+            if (typeof params.enabled !== 'boolean') throw invalid('A boolean permission state is required.')
+            return { full: this.options.approvals.setAuto('pi', params.enabled).auto.pi === true }
+          }
+          if (call === 'terminal.permissions.setTool') {
+            if (typeof params.tool !== 'string' || !params.tool.trim() || typeof params.allowed !== 'boolean') throw invalid('A tool name and boolean permission state are required.')
+            const policy = params.allowed
+              ? this.options.approvals.allowTool('pi', params.tool)
+              : this.options.approvals.revokeTool('pi', params.tool)
+            return { globalTools: policy.globalTools.pi ?? [] }
+          }
           if (call !== 'terminal.resources') return live.controller.control(call, params)
           const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: false, caller: { projectId: input.projectId ?? null } }) ?? null
           if (resourceIdentity(current) !== resourceIdentity(loading)) throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.')