@bibobonking/opensol 3.1.5 → 3.2.0

package/src/core/services/compaction.ts

@@ -1,9 +1,88 @@
 import { Service, type Context } from 'cordis'
-import { compactSession, isCompacting } from '../../agent/compact'
-import { contextUsageRatio, AUTO_COMPACT_THRESHOLD } from '../../lib/context'
-import { findModel } from '../../store/models'
+import type { AssistantMessage, Message, ModelInfo, UserMessage } from '../../types'
+import { createId } from '../../store/chats'
 import { activeModelId, useSettings } from '../../store/settings'
-import { useChats } from '../../store/chats'
+import { findModel } from '../../store/models'
+import { useRuntime } from '../../store/ui'
+import { AUTO_COMPACT_THRESHOLD, contextLimit, estimateSessionTokens } from '../../lib/context'
+import { backoffMs, classifyProviderError } from '../../lib/retry'
+import {
+  chunkParts,
+  clip,
+  collectFiles,
+  fallbackSummary,
+  planCompaction,
+  previousSummary,
+  recentSteps,
+  tokensOf,
+  transcriptParts,
+} from '../../lib/compact-plan'
+
+const SYSTEM = `You are a session compactor for a coding agent. Produce a dense, structured summary that REPLACES the conversation, so the agent can continue as if it had seen everything.
+
+You may receive <previous_summary> (an earlier compaction) and <new_transcript> (what happened after it). Merge them into ONE updated summary: keep what is still true and relevant, drop what was superseded or finished long ago, and never invent facts.
+
+Write these sections (omit a section only if it is truly empty):
+
+## Goal
+What the user wants overall, with their constraints, preferences and style requirements in their own words.
+
+## Done
+Concrete outcomes: what was built or changed (file paths, function names), commands that mattered with their key results, bugs found and how they were fixed, decisions made and why.
+
+## State
+The exact current state of the workspace and what has been verified (tests, builds) versus assumed. Anything broken or half-finished.
+
+## Next
+The ordered next steps. Quote the user's latest request verbatim if it is not finished.
+
+## Facts
+Technical facts the agent would otherwise have to rediscover: versions, commands to run checks, architecture notes, pitfalls, error messages worth remembering.
+
+Rules: keep exact paths, identifiers, commands and error text; do not paste large file contents; do not list every file touched (a tracked file list is appended automatically); no preamble or closing remarks; stay under about 1500 words.`
+
+const TRANSIENT_ATTEMPTS = 2
+const SUMMARY_PREFIX = '[Summary of the earlier conversation — the original messages were compacted to save context]\n\n'
+
+export interface CompactOptions {
+  /** Extra instructions for the summary, e.g. "focus on the auth bug". */
+  focus?: string
+  /** The user asked for it: report problems instead of failing silently. */
+  manual?: boolean
+  /** Called while the agent is mid-turn: the running request is carried over in a handoff message. */
+  midTurn?: boolean
+}
+
+function notice(message: string, tone: 'info' | 'success' | 'error') {
+  window.dispatchEvent(new CustomEvent('maxcode:notice', { detail: { message, tone } }))
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => window.setTimeout(resolve, ms))
+}
+
+function formatK(tokens: number): string {
+  return tokens >= 1000 ? `${Math.round(tokens / 1000)}k` : String(tokens)
+}
+
+const compacting = new Set<string>()
+
+export function isCompacting(sessionId: string): boolean {
+  return compacting.has(sessionId)
+}
+
+/** Provider-reported prompt size of the newest reply beats our character estimate when it is larger. */
+export function usedTokens(messages: Message[]): number {
+  const estimate = estimateSessionTokens(messages) + 2_000
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message.role === 'assistant' && message.usage?.input) {
+      const reported = message.usage.input + (message.usage.output ?? 0) + estimateSessionTokens(messages.slice(index + 1))
+      return Math.max(estimate, reported)
+    }
+  }
+  return estimate
+}
 
 export class CompactionService extends Service {
   static provide = 'compaction'
@@ -17,29 +96,217 @@ export class CompactionService extends Service {
     return isCompacting(sessionId)
   }
 
-  async compact(sessionId: string): Promise<boolean> {
-    return await compactSession(sessionId)
+  /**
+   * Compacts when the context is nearly full. `midTurn` is for a running turn: it checks again after
+   * tool rounds, because one long turn can fill the window without a new user message.
+   */
+  async checkAutoCompact(sessionId: string, { midTurn = false }: { midTurn?: boolean } = {}): Promise<boolean> {
+    const session = this.ctx.sessions.current(sessionId)
+    if (!session || session.messages.length < 4 || isCompacting(sessionId)) return false
+    const settings = useSettings.getState()
+    const model = findModel(settings.provider, activeModelId(settings))
+    const ratio = usedTokens(session.messages) / contextLimit(model)
+    if (ratio < AUTO_COMPACT_THRESHOLD) return false
+    notice(`Context at ${Math.min(Math.round(ratio * 100), 100)}% — compacting before the next request…`, 'info')
+    return await this.compact(sessionId, { midTurn })
   }
 
-  async checkAutoCompact(sessionId: string): Promise<boolean> {
-    const session = useChats.getState().sessions.find((item) => item.id === sessionId)
-    if (!session || session.messages.length < 4 || this.isCompacting(sessionId)) return false
+  /** Returns true when the transcript was rewritten. Never throws. */
+  async compact(sessionId: string, options: CompactOptions = {}): Promise<boolean> {
+    if (compacting.has(sessionId)) return false
+    compacting.add(sessionId)
+    useRuntime.getState().setCompacting(sessionId, true)
+    try {
+      return await this.run(sessionId, options)
+    } catch (error) {
+      notice(`Compaction failed: ${error instanceof Error ? error.message : 'unknown error'}. Context was left unchanged.`, 'error')
+      return false
+    } finally {
+      compacting.delete(sessionId)
+      useRuntime.getState().setCompacting(sessionId, false)
+    }
+  }
+
+  private async run(sessionId: string, options: CompactOptions): Promise<boolean> {
+    const session = this.ctx.sessions.current(sessionId)
+    if (!session) return false
+    const messages = session.messages
+    const settings = useSettings.getState()
+    const modelId = activeModelId(settings)
+    if (!modelId) return false
+    const model = findModel(settings.provider, modelId)
+    const limit = contextLimit(model)
+    const before = usedTokens(messages)
+
+    // Where to cut: older turns are summarised, the newest ones stay verbatim.
+    const keepTokens = Math.min(Math.floor(limit * 0.3), 60_000)
+    let plan = options.midTurn ? null : planCompaction(messages, keepTokens)
+    const last = messages[messages.length - 1]
+    if (!plan) {
+      if (messages.length < 4) {
+        if (options.manual) notice('Nothing to compact yet.', 'info')
+        return false
+      }
+      // One long turn: summarise everything before the newest user message, or (mid-turn) everything.
+      if (last.role === 'user' && !options.midTurn) {
+        plan = { cut: messages.length - 1, head: messages.slice(0, -1), tail: [last], midTurn: false }
+      } else {
+        plan = { cut: messages.length, head: messages.slice(), tail: [], midTurn: true }
+      }
+    }
+    if (plan.head.length < 3) {
+      if (options.manual) notice('Nothing to compact yet.', 'info')
+      return false
+    }
+
+    const previous = previousSummary(plan.head)
+    const fresh = plan.head.slice(previous?.skip ?? 0)
+    const files = collectFiles(fresh, previous?.files ?? [])
+
+    let summary: string
+    let fallback = false
+    try {
+      summary = await this.summarise(model, previous?.text ?? '', fresh, options.focus)
+    } catch (error) {
+      const ratio = before / limit
+      if (!options.manual && ratio < 0.95) {
+        notice(`Auto-compact failed: ${error instanceof Error ? error.message : 'unknown error'}. Continuing with full context.`, 'error')
+        return false
+      }
+      if (options.manual) {
+        notice(`Compaction failed: ${error instanceof Error ? error.message : 'unknown error'}.`, 'error')
+        return false
+      }
+      summary = fallbackSummary(fresh, previous?.text ?? '', files)
+      fallback = true
+    }
+    if (!summary.trim()) return false
+
+    const now = Date.now()
+    const trigger = options.midTurn ? 'mid-turn' : options.manual ? 'manual' : 'auto'
+    const first = messages.find((message): message is UserMessage => message.role === 'user')
+    const next: Message[] = []
+    if (first) {
+      const names = (first.attachments ?? []).map((item) => item.name)
+      next.push({
+        ...first,
+        content: `${clip(first.content, 8_000)}${names.length ? `\n[Attachments: ${names.join(', ')}]` : ''}`,
+        attachments: undefined,
+      })
+    }
+    const summaryMessage: AssistantMessage = {
+      id: createId('msg'),
+      role: 'assistant',
+      content: `${SUMMARY_PREFIX}${summary.trim()}${files.length ? `\n\n## Files changed (tracked)\n${files.map((file) => `- ${file}`).join('\n')}` : ''}`,
+      reasoning: '',
+      toolCalls: [],
+      round: 0,
+      model: modelId,
+      provider: settings.provider,
+      createdAt: now,
+      durationMs: 0,
+      compaction: {
+        files,
+        turns: plan.head.filter((message) => message.role === 'user').length,
+        toolCalls: plan.head.filter((message) => message.role === 'tool').length,
+        at: now,
+        trigger,
+        fallback: fallback || undefined,
+      },
+    }
+    next.push(summaryMessage)
+
+    if (plan.tail.length > 0) {
+      next.push(...plan.tail)
+    } else if (options.midTurn) {
+      const lastUser = [...messages].reverse().find((message): message is UserMessage => message.role === 'user')
+      const steps = recentSteps(messages)
+      next.push({
+        id: createId('msg'),
+        role: 'user',
+        content: [
+          '[Context compacted while you were working. The summary above is the record so far.]',
+          lastUser ? `The request you are working on:\n${clip(lastUser.content.trim(), 6_000)}` : '',
+          steps ? `Most recent steps (verbatim):\n${steps}` : '',
+          'Continue from exactly here. Do not redo completed work.',
+        ]
+          .filter(Boolean)
+          .join('\n\n'),
+        attachments: lastUser?.attachments,
+        createdAt: now,
+      })
+    }
+
+    const after = tokensOf(next) + 2_000
+    if (after >= before) {
+      if (options.manual) notice('Compaction would not free any space, so nothing changed.', 'info')
+      return false
+    }
+
+    // Rewrite only if the transcript did not change while we were summarising.
+    const latest = this.ctx.sessions.current(sessionId)
+    if (!latest || latest.messages.length !== messages.length || latest.messages[latest.messages.length - 1]?.id !== last.id) {
+      if (options.manual) notice('The conversation changed while compacting, so nothing was changed. Try again.', 'info')
+      return false
+    }
+    this.ctx.sessions.updateSession(sessionId, { messages: next })
+    const kept = plan.tail.filter((message) => message.role === 'user').length
+    notice(
+      `Context compacted: ${formatK(before)} → ${formatK(after)} tokens${kept > 1 ? ` · kept the last ${kept} turns` : ''}${fallback ? ' · summary built without the model' : ''}.`,
+      fallback ? 'info' : 'success',
+    )
+    return true
+  }
+
+  /** Rolling summary: each chunk of transcript updates the running summary, so huge sessions still fit. */
+  private async summarise(model: ModelInfo | null, previous: string, messages: Message[], focus?: string): Promise<string> {
+    const maxChars = Math.min(Math.floor(contextLimit(model) * 0.45 * 3), 120_000)
+    const chunks = chunkParts(transcriptParts(messages), Math.max(maxChars, 12_000))
+    let summary = previous
+    for (let index = 0; index < chunks.length; index += 1) {
+      const last = index === chunks.length - 1
+      const request = [
+        summary ? `<previous_summary>\n${summary}\n</previous_summary>` : '',
+        `<new_transcript part="${index + 1}/${chunks.length}">\n${chunks[index]}\n</new_transcript>`,
+        focus?.trim() && last ? `<focus>\n${focus.trim()}\n</focus>\nGive extra weight to the focus above.` : '',
+        'Write the updated summary now.',
+      ]
+        .filter(Boolean)
+        .join('\n\n')
+      summary = await this.complete(model, request)
+    }
+    return summary
+  }
 
+  private async complete(model: ModelInfo | null, prompt: string): Promise<string> {
     const settings = useSettings.getState()
-    const modelInfo = findModel(settings.provider, activeModelId(settings))
-    const ratio = contextUsageRatio(session.messages, modelInfo)
-
-    if (ratio >= AUTO_COMPACT_THRESHOLD) {
-      window.dispatchEvent(
-        new CustomEvent('maxcode:notice', {
-          detail: {
-            message: `Context at ${Math.round(ratio * 100)}% — compacting session before next request…`,
-            tone: 'info',
+    const controller = new AbortController()
+    for (let attempt = 1; ; attempt += 1) {
+      let text = ''
+      try {
+        const result = await this.ctx.llm.stream({
+          settings,
+          model,
+          history: [{ id: createId('msg'), role: 'user', content: prompt, createdAt: Date.now() }],
+          system: SYSTEM,
+          mode: 'plan',
+          tools: [],
+          signal: controller.signal,
+          handlers: {
+            onText: (delta) => {
+              text += delta
+            },
+            onReasoning: () => undefined,
+            onToolCalls: () => undefined,
+            onUsage: () => undefined,
           },
-        }),
-      )
-      return await this.compact(sessionId)
+        })
+        return (result.content || text).trim()
+      } catch (error) {
+        const message = error instanceof Error ? error.message : ''
+        if (attempt >= TRANSIENT_ATTEMPTS || !classifyProviderError(message).retry) throw error
+        await sleep(backoffMs(attempt, message))
+      }
     }
-    return false
   }
 }

package/src/core/services/llm.ts

@@ -5,7 +5,7 @@ import { streamGemini } from '../../agent/adapters/gemini'
 import { streamOpenAI } from '../../agent/adapters/openai'
 import { streamOpenAIResponses } from '../../agent/adapters/openai-responses'
 import { apiKindFor } from '../../store/models'
-import type { ModelRequest } from '../types'
+import type { ModelRequest, ToolSchema } from '../types'
 
 export class LlmService extends Service {
   static provide = 'llm'
@@ -14,7 +14,11 @@ export class LlmService extends Service {
     super(ctx, 'llm')
   }
 
-  async stream(request: ModelRequest): Promise<AdapterResult> {
+  async stream(input: ModelRequest): Promise<AdapterResult> {
+    const request: ModelRequest & { tools: ToolSchema[] } = {
+      ...input,
+      tools: input.tools ?? this.ctx.tools.schemas(input.settings, input.mode),
+    }
     return await this.ctx.events.waterfall('agent/request', request, async () => {
       const kind = apiKindFor(request.settings.provider, request.settings.model, request.model)
       switch (kind) {

package/src/core/services/subagents.ts

@@ -1,5 +1,61 @@
 import { Service, type Context } from 'cordis'
-import { runSubagent } from '../../agent/subagent'
+import type { AssistantMessage, Message, ToolCall, ToolMessage, UserMessage } from '../../types'
+import { createId } from '../../store/chats'
+import { activeModelId, useSettings } from '../../store/settings'
+import { findModel } from '../../store/models'
+import { contextLimit } from '../../lib/context'
+import { clip, tokensOf } from '../../lib/compact-plan'
+import { MAX_RETRIES, backoffMs, classifyProviderError } from '../../lib/retry'
+import { toolSummary } from '../../lib/tool-meta'
+import { SUBAGENT_TYPES, type SubagentType } from '../../lib/subagent-types'
+
+const TOOL_OUTPUT_LIMIT = 12_000
+const RECENT_RESULTS_KEPT = 8
+
+export interface SubagentRequest {
+  task: string
+  context?: string
+  type?: SubagentType
+  signal: AbortSignal
+  sessionId?: string
+  /** Receives a short live log of what the subagent is doing. */
+  onProgress?: (text: string) => void
+}
+
+export interface SubagentReport {
+  output: string
+  rounds: number
+  toolCalls: number
+  /** Stopped at the round cap and asked to report with what it had. */
+  capped: boolean
+}
+
+function abortError() {
+  return new DOMException('Aborted', 'AbortError')
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = () => {
+      window.clearTimeout(timer)
+      signal.removeEventListener('abort', finish)
+      resolve()
+    }
+    const timer = window.setTimeout(finish, ms)
+    signal.addEventListener('abort', finish, { once: true })
+  })
+}
+
+/** Replaces old tool outputs with a stub so a long investigation never overflows the window. */
+function pruneHistory(history: Message[], budgetTokens: number): void {
+  if (tokensOf(history) <= budgetTokens) return
+  const tools = history.filter((message): message is ToolMessage => message.role === 'tool')
+  for (const message of tools.slice(0, Math.max(0, tools.length - RECENT_RESULTS_KEPT))) {
+    if (message.result && message.result.length > 200) {
+      message.result = `[earlier output of ${message.call.name} pruned: ${message.result.length} characters]`
+    }
+  }
+}
 
 export class SubagentService extends Service {
   static provide = 'subagents'
@@ -9,7 +65,139 @@ export class SubagentService extends Service {
     super(ctx, 'subagents')
   }
 
-  async run(task: string, context: string, signal: AbortSignal, sessionId?: string): Promise<string> {
-    return await runSubagent(task, context, signal, sessionId)
+  async run(request: SubagentRequest): Promise<SubagentReport> {
+    const { signal, onProgress } = request
+    const task = request.task.trim()
+    if (!task) return { output: 'The subagent was not given a task.', rounds: 0, toolCalls: 0, capped: false }
+    if (signal.aborted) throw abortError()
+
+    const type = request.type ?? 'explore'
+    const spec = SUBAGENT_TYPES[type]
+    const settings = useSettings.getState()
+    const model = findModel(settings.provider, activeModelId(settings))
+    const system = this.ctx.systemPrompt.buildSubagentPrompt(settings, request.sessionId, type)
+    const allowed = new Set<string>(spec.tools)
+    const tools = this.ctx.tools.schemas(settings, 'plan', { subagent: true }).filter((tool) => allowed.has(tool.name))
+    const budget = Math.floor(contextLimit(model) * 0.6)
+
+    const history: Message[] = [
+      {
+        id: createId('sub'),
+        role: 'user',
+        content: [
+          `Task (${spec.label.toLowerCase()}): ${task}`,
+          request.context?.trim() ? `\nContext from the main agent:\n${request.context.trim()}` : '',
+          '\nInvestigate now, then write the report.',
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        createdAt: Date.now(),
+      } satisfies UserMessage,
+    ]
+
+    const log: string[] = []
+    const progress = (line: string) => {
+      log.push(line)
+      onProgress?.(`${spec.label} subagent\n${log.slice(-14).join('\n')}`)
+    }
+    progress('starting…')
+
+    let totalCalls = 0
+    let capped = false
+    for (let round = 0; ; round += 1) {
+      if (signal.aborted) throw abortError()
+      // On the last round, withdraw the tools so the model has to write its report.
+      const finalRound = round >= spec.maxRounds
+      if (finalRound) {
+        capped = true
+        history.push({
+          id: createId('sub'),
+          role: 'user',
+          content: 'You have used your investigation budget. Write the final report now from what you found, and say what is still unverified.',
+          createdAt: Date.now(),
+        })
+      }
+      pruneHistory(history, budget)
+      const result = await this.stream(system, history, finalRound ? [] : tools, signal, model)
+      const assistant: AssistantMessage = {
+        id: createId('sub'),
+        role: 'assistant',
+        content: result.content,
+        reasoning: result.reasoning,
+        thinkingBlocks: result.thinkingBlocks,
+        toolCalls: result.toolCalls,
+        round,
+        createdAt: Date.now(),
+      }
+      history.push(assistant)
+
+      if (result.toolCalls.length === 0 || finalRound) {
+        const report = assistant.content.trim()
+        return {
+          output: report || 'The subagent returned no report.',
+          rounds: round + 1,
+          toolCalls: totalCalls,
+          capped,
+        }
+      }
+
+      // Read-only calls are independent, so they run together.
+      const executed = await Promise.all(
+        result.toolCalls.map(async (call: ToolCall): Promise<ToolMessage> => {
+          totalCalls += 1
+          progress(`${call.name} ${clip(toolSummary(call.name, call.args), 90)}`)
+          if (!allowed.has(call.name)) {
+            return this.toolMessage(call, round, 'error', `Tool "${call.name}" is not available to this subagent.`)
+          }
+          try {
+            const output = await this.ctx.tools.execute(call.name, call.args, settings, 'plan', signal)
+            return this.toolMessage(call, round, output.isError ? 'error' : 'done', clip(output.output, TOOL_OUTPUT_LIMIT))
+          } catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') throw error
+            return this.toolMessage(call, round, 'error', error instanceof Error ? error.message : 'The tool failed.')
+          }
+        }),
+      )
+      history.push(...executed)
+    }
+  }
+
+  private toolMessage(call: ToolCall, round: number, status: 'done' | 'error', result: string): ToolMessage {
+    return { id: createId('sub'), role: 'tool', call, status, result, round, createdAt: Date.now() }
+  }
+
+  /** One model call with the same transient-error retry as the main loop. */
+  private async stream(
+    system: string,
+    history: Message[],
+    tools: ReturnType<Context['tools']['schemas']>,
+    signal: AbortSignal,
+    model: ReturnType<typeof findModel>,
+  ) {
+    const settings = useSettings.getState()
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        return await this.ctx.llm.stream({
+          settings,
+          model,
+          history,
+          system,
+          mode: 'plan',
+          tools,
+          signal,
+          handlers: {
+            onText: () => undefined,
+            onReasoning: () => undefined,
+            onToolCalls: () => undefined,
+            onUsage: () => undefined,
+          },
+        })
+      } catch (error) {
+        if (signal.aborted) throw abortError()
+        const message = error instanceof Error ? error.message : ''
+        if (attempt > MAX_RETRIES || !classifyProviderError(message).retry) throw error
+        await sleep(backoffMs(attempt, message), signal)
+      }
+    }
   }
 }

package/src/core/services/system-prompt.ts

@@ -4,7 +4,30 @@ import { activeModelId } from '../../store/settings'
 import { useWorkspace } from '../../store/workspace'
 import { skillCatalogPrompt } from '../../store/skills'
 import { resolveBasePrompt } from '../../lib/system-prompt'
+import { useSettings } from '../../store/settings'
 import type { PromptSection } from '../types'
+import { SUBAGENT_TYPES, type SubagentType } from '../../lib/subagent-types'
+
+function environmentContext(): string {
+  const daemon = useSettings.getState().daemon
+  const os = daemon?.os ?? ''
+  const shell = daemon?.shell ?? ''
+  if (!os && !shell) return ''
+  const guide =
+    os === 'win32'
+      ? [
+          '- Commands run in PowerShell, not bash. Use PowerShell syntax: `Get-ChildItem`, `Get-Content`, `Select-String`, `$env:NAME`, `;` (not `&&` on Windows PowerShell 5).',
+          '- Do not assume `ls -la`, `grep`, `sed`, `cat <<EOF` or `export` exist. Paths may use `\\` or `/`; quote paths that contain spaces.',
+        ]
+      : os === 'darwin'
+        ? [
+            '- Commands run in a login shell on macOS (BSD userland). `sed -i` needs an argument (`sed -i \'\'`), `date`, `xargs` and `grep` differ from GNU; prefer portable flags or the dedicated file tools.',
+          ]
+        : os === 'linux'
+          ? ['- Commands run in bash with GNU userland.']
+          : []
+  return ['## Environment', `- OS: ${os || 'unknown'}${daemon?.arch ? ` (${daemon.arch})` : ''}`, `- Shell: ${shell || 'unknown'}`, ...guide].join('\n')
+}
 
 function workspaceContext(): string {
   const state = useWorkspace.getState()
@@ -88,6 +111,10 @@ export class SystemPromptService extends Service {
       })
     }
 
+    // 3c. Operating system and shell
+    const environment = environmentContext()
+    if (environment) sections.push({ name: 'environment', priority: 38, content: environment })
+
     // 4. Mode
     sections.push({
       name: 'mode',
@@ -156,16 +183,17 @@ export class SystemPromptService extends Service {
     })
   }
 
-  buildSubagentPrompt(settings: AppSettings, sessionId?: string): string {
+  buildSubagentPrompt(settings: AppSettings, sessionId?: string, type: SubagentType = 'explore'): string {
+    const spec = SUBAGENT_TYPES[type]
     return [
       this.assemble(settings, 'plan', sessionId),
       [
-        '## Subagent',
-        'You are a focused read-only investigator. Work only on the assigned task.',
-        '- Inspect the real workspace with read-only file, grep, shell and web tools.',
-        '- Do not edit files, change git state or run commands that mutate the machine. The daemon enforces this.',
-        '- Be concise: return findings, exact file paths and line references, and any uncertainty.',
-        '- Do not repeat the task back. Do not invent evidence. If something cannot be verified, say so.',
+        `## Subagent (${spec.label})`,
+        'You are a focused, read-only investigator working for the main agent. You cannot ask the user questions and cannot start other subagents.',
+        '- Work only on the assigned task. Do not edit files, change git state or run commands that mutate the machine; the daemon enforces this.',
+        ...spec.guidance.map((line) => `- ${line}`),
+        '- Be efficient: you have a limited number of rounds. Batch independent tool calls in one round.',
+        '- Finish with a concise report: the answer first, then evidence (paths, lines, URLs), then open questions. Do not repeat the task. Do not invent evidence; say what could not be verified.',
       ].join('\n'),
     ].join('\n\n')
   }

package/src/core/services/tools.ts

@@ -78,8 +78,9 @@ export class ToolService extends Service {
     signal: AbortSignal,
     callId?: string,
     turnId?: string,
+    extra: Pick<ToolExecutionContext, 'sessionId' | 'onProgress'> = {},
   ): Promise<ToolResult> {
-    const exec: ToolExecutionContext = { name, args, settings, mode, signal, callId, turnId }
+    const exec: ToolExecutionContext = { name, args, settings, mode, signal, callId, turnId, ...extra }
 
     // 1. tools/pre-execute waterfall (approval, permission gate, mode checks)
     const preDecision: ToolPreExecuteResult = await this.ctx.events.waterfall(

package/src/core/types.ts

@@ -46,6 +46,9 @@ export interface ToolExecutionContext {
   callId?: string
   /** The user message that started this turn; file edits are checkpointed under it. */
   turnId?: string
+  sessionId?: string
+  /** Lets a long tool (a subagent) show live progress in its tool card. */
+  onProgress?: (text: string) => void
 }
 
 export type ToolPreExecuteDecision = 'allow' | 'ask' | 'deny'
@@ -89,6 +92,8 @@ export interface ModelRequest {
   system: string
   mode: AgentMode
   signal: AbortSignal
+  /** Tools to offer. Defaults to the tools allowed for `mode`; pass [] for a plain completion. */
+  tools?: ToolSchema[]
   handlers: {
     onText: (delta: string) => void
     onReasoning: (delta: string) => void