@a-t-h-i/bot-lobby 0.6.32 → 0.6.34

package/src/execution/pi-runner.ts

@@ -1,3 +1,7 @@
+import type { AgentRun } from "../schemas/findings.ts";
+import type { Domain, Role } from "../schemas/agent.ts";
+import { delegationHost } from "./delegation.ts";
+import { fileURLToPath } from "node:url";
 import { spawn, type ChildProcess } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -6,7 +10,7 @@ import { activityWord } from "../pi/activity.ts";
 import { shortDuration } from "../text.ts";
 import { readRelayRequest } from "../ask/relay.ts";
 import type { AskQuestion, AskResult } from "../ask/types.ts";
-import { grantEnv, grantNote, toolsOf, type Grant } from "../excalidraw/sessions.ts";
+import { grantEnv, grantNote, type Grant } from "../excalidraw/sessions.ts";
 
 /** Live control over one running subagent: queue a steering message for its next turn. */
 export interface RunHandle {
@@ -20,6 +24,10 @@ export interface RunHandle {
 export type RelayAsk = (questions: AskQuestion[], signal: AbortSignal) => Promise<AskResult>;
 
 export interface PiRunOptions {
+  agent?: { runId: string; taskId: string; domain: Domain; role: Role; depth?: number };
+  mcpTools?: string[];
+  delegationQuota?: { used: number };
+  onChildRun?: (run: AgentRun) => void;
   cwd: string;
   task: string;
   systemPrompt?: string;
@@ -96,6 +104,7 @@ export type PiStreamEvent =
   | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; error: string }
   | { type: "retry_end"; success: boolean }
   | { type: "compaction" }
+  | { type: "compaction_end"; error?: string }
   | { type: "usage"; input: number; output: number; cost: number; model?: string }
   | { type: "wrap_up" }
   /** Its allotted time is up: it was asked to stop and report where it left off. */
@@ -139,6 +148,7 @@ export type ProcessRunner = (
 ) => Promise<ProcessOutcome>;
 
 export interface PiRunResult {
+  children?: AgentRun[];
   status: "success" | "failed" | "cancelled" | "timeout";
   output: string;
   error?: string;
@@ -186,6 +196,7 @@ export interface ControlEvent {
   /** extension_ui_request: the dialog's title and (editor) prefilled text. */
   title?: string;
   prefill?: string;
+  message?: string;
 }
 
 /** Buffers one JSON-mode stream, keeping only lines parsePiStream consumes. */
@@ -203,6 +214,7 @@ const INTERESTING = [
   '"turn_start"',
   '"auto_retry_',
   '"compaction_start"',
+  '"compaction_end"',
   '"agent_settled"',
   '"agent_end"',
   '"extension_ui_request"',
@@ -241,6 +253,8 @@ function streamEvent(event: RawEvent): PiStreamEvent | undefined {
       return { type: "retry_end", success: event.success === true };
     case "compaction_start":
       return { type: "compaction" };
+    case "compaction_end":
+      return { type: "compaction_end", ...(typeof event.errorMessage === "string" ? { error: event.errorMessage } : {}) };
     case "message_end": {
       const message = event.message;
       if (message?.role !== "assistant") return undefined;
@@ -345,7 +359,7 @@ export function finishedThought(line: string): string | undefined {
 
 /** Build the `pi` argv for one isolated, headless RPC agent run; the task goes over stdin. */
 export function buildPiArgs(options: Omit<PiRunOptions, "task"> & { systemPromptFile?: string }): string[] {
-  const args = ["--mode", "rpc", "--no-session", "--no-prompt-templates", "--no-themes"];
+  const args = ["--mode", "rpc", "--no-session", "--no-prompt-templates", "--no-themes", "--extension", fileURLToPath(new URL("../index.ts", import.meta.url))];
   if (options.model && options.model !== "inherit") args.push("--model", options.model);
   if (options.thinking) args.push("--thinking", options.thinking);
   if (options.tools && options.tools.length > 0) args.push("--tools", options.tools.join(","));
@@ -608,6 +622,11 @@ export function spawnPiProcess(args: string[], options: ProcessRunOptions): Prom
         });
     };
     const onControl = (event: ControlEvent) => {
+      if (event.type === "extension_ui_request" && event.method === "notify") {
+        if (event.message === "Compacting agent context") options.onEvent?.({ type: "compaction" });
+        else if (event.message === "Agent context compacted") options.onEvent?.({ type: "compaction_end" });
+        else if (event.message?.startsWith("Context compaction failed:")) options.onEvent?.({ type: "compaction_end", error: event.message });
+      }
       const relayed = event.type === "extension_ui_request" && event.method === "editor" && options.onAsk ? readRelayRequest(event.title, event.prefill) : undefined;
       if (event.type === "response" && event.command === "prompt" && event.success === false) {
         state.protocolError = event.error ?? "the prompt was rejected";
@@ -744,31 +763,38 @@ function writePromptFile(prompt: string): { file: string; cleanup: () => void }
 
 /** Run one isolated subagent and normalise its outcome. */
 export async function runPiAgent(options: PiRunOptions, run: ProcessRunner = spawnPiProcess): Promise<PiRunResult> {
-  const prompt = options.systemPrompt ? writePromptFile(options.systemPrompt) : undefined;
+  const host = await delegationHost(options, run);
+  let prompt: ReturnType<typeof writePromptFile> | undefined;
   const grant = options.excalidraw;
-  // An agent with an allowlist gets the Excalidraw tools added to it; one without is not restricted, so already has them.
-  const tools = grant && options.tools ? [...new Set([...options.tools, ...toolsOf(grant)])] : options.tools;
   try {
-    const args = buildPiArgs({ ...options, ...(tools ? { tools } : {}), systemPromptFile: prompt?.file });
+    prompt = writePromptFile([options.systemPrompt, host.note].filter(Boolean).join("\n\n"));
+    if (options.signal?.aborted) return { status: "cancelled", output: "", usage: { input: 0, output: 0, cost: 0, turns: 0 } };
+    const args = buildPiArgs({ ...options, tools: host.tools, systemPromptFile: prompt.file });
     const outcome = await run(args, {
       cwd: options.cwd,
       signal: options.signal,
       timeoutMs: options.timeoutMs,
       prompt: `Task: ${options.task}${grant ? `\n\n${grantNote(grant)}` : ""}`,
-      env: grant ? { ...options.env, ...grantEnv(grant) } : options.env,
+      env: grant ? { ...host.env, ...grantEnv(grant) } : host.env,
       stallTimeoutMs: options.stallTimeoutMs,
       toolStallTimeoutMs: options.toolStallTimeoutMs,
       wrapUpAtMs: options.wrapUpAtMs,
       ...(options.time ? { time: options.time } : {}),
       ...(options.onAsk ? { onAsk: options.onAsk } : {}),
-      onStart: options.onStart,
+      onStart: host.onStart,
       onEvent: (event) => {
+        if (event.type === "asking") host.pause?.();
+        if (event.type === "answered") host.extend?.(event.waitedMs);
+        if (event.type === "extended") host.extend?.(event.ms, true);
         if (event.type === "tool_execution_start") options.onActivity?.(activityWord(event.toolName));
         options.onEvent?.(event);
       },
     });
-    return toResult(parsePiStream(outcome.stdout), outcome, options.signal?.aborted === true, options);
+    const result = toResult(parsePiStream(outcome.stdout), outcome, options.signal?.aborted === true, options);
+    await host.close();
+    return host.children.length ? { ...result, children: host.children } : result;
   } finally {
     prompt?.cleanup();
+    await host.close();
   }
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+import { registerAgentPermissions, registerDelegation } from "./pi/delegation.ts";
+import { registerAutoCompaction } from "./pi/auto-compaction.ts";
 import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerCommands } from "./pi/commands.ts";
 import { registerLifecycle } from "./pi/events.ts";
@@ -20,6 +22,9 @@ import { registerWebTools } from "./web/tools.ts";
 import { registerExcalidrawTools } from "./excalidraw/tools.ts";
 
 export default function (pi: ExtensionAPI): void {
+  registerAgentPermissions(pi);
+  registerDelegation(pi);
+  registerAutoCompaction(pi);
   let root = detectProjectRoot(process.cwd(), CONFIG_DIR_NAME);
   pi.on("session_start", (_event, ctx) => { root = detectProjectRoot(ctx.cwd, CONFIG_DIR_NAME); });
   // First, so every session_start handler below finds the classifier bound to this session's keys.

package/src/lobby/planner.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 /**
  * Task planning mode: a planning panel. The user describes an idea (or picks a
  * GitHub issue) and every seat questions them from its own domain — DEV,
@@ -998,14 +999,22 @@ export class PlanningSession {
 
   private async run(label: string, kind: "planner" | "panel", profile: QuickFixProfile, request: { task: string; systemPrompt: string; tools: readonly string[]; excalidraw?: Grant }, signal: AbortSignal, setStep: (step: string) => void, routedFrom?: string): Promise<RunOutcome> {
     const startedAt = Date.now();
+    const runId = randomUUID();
     let outcome: RunOutcome;
     try {
       const attempt = (model: string | undefined, thinking: string) => runPiAgent(
         {
           cwd: this.deps.cwd,
+          agent: { runId, taskId: runId, domain: label === "DESIGN" ? "designer" : label === "QA" ? "qa" : "backend", role: label === "RESEARCH" ? "researcher" : "reviewer" },
           ...request,
           model,
           thinking,
+          mcpTools: profile.mcpTools,
+          onChildRun: (child) => {
+            this.deps.feed?.step(label, `child ${child.runId.slice(0, 8)}: ${child.step ?? child.status}`, child.runId);
+            if (child.status !== "running") this.deps.feed?.end(child.runId, child.status !== "success");
+            this.deps.onChange?.();
+          },
           timeoutMs: profile.timeoutMs,
           signal,
           stallTimeoutMs: this.deps.stallTimeoutMs,

package/src/lobby/pr-review.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 /**
  * Reviewing pull requests from the Git tab. A read-only agent (on QA's model,
  * thinking and time limit) gets the pull request's description, changed files
@@ -264,17 +265,25 @@ export class PullReviews {
 
   private async run(review: PullReview, task: string, signal: AbortSignal): Promise<RunUsage> {
     const profile = this.deps.profile();
+    const runId = randomUUID();
     if (profile.model) review.model = profile.model;
     review.thinking = profile.thinking;
     this.step(review, "reading the diff");
     const attempt = (model: string | undefined, thinking: string) => runPiAgent(
       {
         cwd: this.deps.cwd,
+        agent: { runId, taskId: runId, domain: "qa", role: "reviewer" },
         task,
         systemPrompt: reviewPrompt(profile.instructions),
         tools: REVIEW_TOOLS,
         model,
         thinking,
+        mcpTools: profile.mcpTools,
+        onChildRun: (child) => {
+          this.deps.feed?.step(REVIEW_SOURCE, `child ${child.runId.slice(0, 8)}: ${child.step ?? child.status}`, child.runId);
+          if (child.status !== "running") this.deps.feed?.end(child.runId, child.status !== "success");
+          this.deps.onChange?.();
+        },
         timeoutMs: profile.timeoutMs,
         signal,
         stallTimeoutMs: this.deps.stallTimeoutMs,

package/src/lobby/quickfix.ts

@@ -1,3 +1,4 @@
+import type { AgentRun } from "../schemas/findings.ts";
 /**
  * Quick fixes: a direct prompt from the lobby goes straight to one coding
  * subagent — no scouting, proposal, plan or QA gate — while any bot-lobby task
@@ -38,6 +39,7 @@ export interface QuickFixStep {
 }
 
 export interface QuickFixJob {
+  children?: AgentRun[];
   id: string;
   prompt: string;
   status: QuickFixStatus;
@@ -83,6 +85,7 @@ export interface QuickFixProfile {
   thinking: string;
   timeoutMs: number;
   instructions?: string;
+  mcpTools?: string[];
   /** Where the job goes when its model runs out of usage or is unavailable. */
 }
 
@@ -295,6 +298,7 @@ export class QuickFixQueue {
     this.edits.set(job.id, new EditLog(this.deps.cwd));
     try {
       const [likely, route] = await Promise.all([this.likely(job.prompt, controller.signal), this.route(job.prompt, profile, controller.signal)]);
+      const quota = { used: 0 };
       const attempt = (model: string | undefined, thinking: string) => runPiAgent(
         {
           cwd: this.deps.cwd,
@@ -304,6 +308,18 @@ export class QuickFixQueue {
           ...grantOption("quickfix"),
           model,
           thinking,
+          mcpTools: profile.mcpTools,
+          delegationQuota: quota,
+          agent: { runId: job.id, taskId: job.id, domain: "backend", role: "worker" },
+          onChildRun: (child) => {
+            const edits = this.edits.get(job.id);
+            for (const path of child.edited ?? []) edits?.note("edit", { path });
+            if (edits) job.files = edits.shown();
+            job.children = [...(job.children ?? []).filter((entry) => entry.runId !== child.runId), child];
+            this.deps.feed?.step(QUICK_FIX_SOURCE, `child ${child.runId.slice(0, 8)}: ${child.step ?? child.status}`, child.runId);
+            if (child.status !== "running") this.deps.feed?.end(child.runId, child.status !== "success");
+            this.changed();
+          },
           timeoutMs: profile.timeoutMs,
           signal: controller.signal,
           stallTimeoutMs: this.deps.stallTimeoutMs,

package/src/master/master.ts

@@ -52,7 +52,7 @@ export interface ScoutRequest {
 /** Model, thinking and time limit for one run, from settings. */
 function profileFields(config: BotLobbyConfig, resolver: ProfileResolver | undefined, domain: Domain, role: AgentRequest["role"]) {
   const profile = profileFor(config, resolver, domain, role);
-  return { model: profile.model, thinking: profile.thinking, timeoutMs: profile.timeoutMs };
+  return { model: profile.model, mcpTools: profile.mcpTools, thinking: profile.thinking, timeoutMs: profile.timeoutMs };
 }
 
 function scoutInstruction(request: ScoutRequest, domain: Domain): string {
@@ -141,6 +141,7 @@ export async function runScouts(request: ScoutRequest, run: ProcessRunner = spaw
   ]);
   const extraTools = request.hints?.tools() ?? [];
   const requests: AgentRequest[] = request.domains.map((domain, index) => ({
+    delegationQuota: { used: 0 },
     taskId: request.taskId,
     domain,
     role: "scout",
@@ -286,6 +287,7 @@ export async function runWorker(
   const hintTools = request.hints?.tools() ?? [];
   const extraTools = [...(request.agent?.extraTools ?? []), ...hintTools];
   const base: AgentRequest = {
+    delegationQuota: { used: 0 },
     taskId: request.taskId,
     domain: request.domain,
     role: "worker",

package/src/master/research.ts

@@ -70,6 +70,7 @@ export async function runResearch(request: ResearchRequest, run: ProcessRunner =
       instruction: request.instruction,
       context: researchContext(request),
       model: profile.model,
+      mcpTools: profile.mcpTools,
       thinking: profile.thinking,
       timeoutMs: profile.timeoutMs,
       ...(request.time ? { time: request.time } : {}),

package/src/pi/auto-compaction.ts

@@ -0,0 +1,72 @@
+import { compact, DEFAULT_COMPACTION_SETTINGS, estimateTokens, findCutPoint, type ExtensionAPI, type TurnEndEvent } from "@earendil-works/pi-coding-agent";
+import { contextMarks, freshContextOn } from "./fresh-context.ts";
+import { isSubagentProcess } from "./quiet.ts";
+
+export const CONTEXT_TARGET = 250_000;
+
+export function compactionThreshold(window: number, reserve = DEFAULT_COMPACTION_SETTINGS.reserveTokens): number {
+  return Math.max(1, Math.min(CONTEXT_TARGET, Math.floor(window * 0.8), window - Math.min(reserve, Math.floor(window / 2))));
+}
+
+/** Compact at a settled tool boundary; ctx.compact() would abort the turn we need to continue. */
+export function registerAutoCompaction(pi: ExtensionAPI, summarize: typeof compact = compact): void {
+  let busy = false;
+  let lastLeaf: string | null | undefined;
+  pi.on("session_start", () => { busy = false; lastLeaf = undefined; });
+  pi.on("turn_end", async (event: TurnEndEvent, ctx) => {
+    if (busy || !ctx.model) return;
+    const leaf = ctx.sessionManager.getLeafId();
+    if (leaf === lastLeaf) return;
+    const configured = pi.getSettings().compaction;
+    const override = configured?.modelOverrides?.[`${ctx.model.provider}/${ctx.model.id}`];
+    const reserve = Math.min(override?.reserveTokens ?? configured?.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens, Math.floor(ctx.model.contextWindow / 2));
+    const threshold = compactionThreshold(ctx.model.contextWindow, reserve);
+    const estimate = event.context.contextMessages.reduce((total, message) => total + estimateTokens(message), 0) + Math.ceil(ctx.getSystemPrompt().length / 4);
+    const usage = ctx.getContextUsage();
+    if (Math.max(estimate, usage?.tokens ?? 0) < threshold) return;
+    let entries = ctx.sessionManager.buildContextEntries();
+    if (!isSubagentProcess() && freshContextOn()) {
+      const boundary = contextMarks(ctx.sessionManager.getBranch()).at(-1)?.at;
+      if (boundary !== undefined) entries = entries.filter((entry) => Date.parse(entry.timestamp) >= boundary);
+    }
+    if (entries.length < 2) return;
+    const keepRecentTokens = Math.min(override?.keepRecentTokens ?? configured?.keepRecentTokens ?? DEFAULT_COMPACTION_SETTINGS.keepRecentTokens, Math.floor(threshold / 4));
+    const cut = findCutPoint(entries, 0, entries.length, keepRecentTokens);
+    if (cut.firstKeptEntryIndex <= 0) return;
+    const prefix = entries.slice(0, cut.firstKeptEntryIndex);
+    const messages = prefix.flatMap((entry) => entry.type === "message" ? [entry.message] : []);
+    if (!messages.length) return;
+    const previous = [...entries].reverse().find((entry) => entry.type === "compaction");
+    const firstKeptEntryId = entries[cut.firstKeptEntryIndex]!.id;
+    const fileOps = { read: new Set<string>(), written: new Set<string>(), edited: new Set<string>() };
+    const details = previous?.type === "compaction" ? previous.details as { readFiles?: string[]; modifiedFiles?: string[] } | undefined : undefined;
+    for (const path of details?.readFiles ?? []) fileOps.read.add(path);
+    for (const path of details?.modifiedFiles ?? []) fileOps.edited.add(path);
+    for (const message of messages) {
+      const calls = message.role === "assistant" ? message.content.filter((part) => part.type === "toolCall") : message.role === "toolResult" ? message.nestedCalls?.calls ?? [] : [];
+      for (const call of calls) {
+        const path = call.arguments?.path;
+        if (typeof path !== "string") continue;
+        if (call.name === "read") fileOps.read.add(path);
+        if (call.name === "write") fileOps.written.add(path);
+        if (call.name === "edit") fileOps.edited.add(path);
+      }
+    }
+    lastLeaf = leaf;
+    busy = true;
+    ctx.ui.notify("Compacting agent context", "info");
+    try {
+      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+      if (!auth.ok) throw new Error(auth.error);
+      const headers = auth.headers ? Object.fromEntries(Object.entries(auth.headers).filter((entry): entry is [string, string] => entry[1] !== null)) : undefined;
+      const retry = pi.getSettings().retry;
+      const retryPolicy = { enabled: retry?.enabled ?? true, maxRetries: retry?.maxRetries ?? 3, baseDelayMs: retry?.baseDelayMs ?? 2_000, maxAgentDelayMs: retry?.maxAgentDelayMs };
+      const result = await summarize({ firstKeptEntryId, messagesToSummarize: messages, turnPrefixMessages: [], isSplitTurn: false, tokensBefore: estimate, previousSummary: previous?.type === "compaction" ? previous.summary : undefined, fileOps, settings: { enabled: true, reserveTokens: reserve, keepRecentTokens } }, auth.baseUrl ? { ...ctx.model, baseUrl: auth.baseUrl } : ctx.model, auth.apiKey, headers, "Preserve goals, constraints, decisions, file references, verification evidence, unfinished work and outstanding delegated subtasks. The parent remains responsible for integration and verification.", ctx.signal, undefined, undefined, auth.env, retryPolicy);
+      ctx.signal?.throwIfAborted();
+      ctx.ui.notify("Agent context compacted", "info");
+      return { entries: [...event.entries, { type: "compaction" as const, summary: result.summary, firstKeptEntryId, usage: result.usage, details: result.details }] };
+    } catch (error) {
+      ctx.ui.notify(`Context compaction failed: ${(error as Error).message}`, "warning");
+    } finally { busy = false; }
+  });
+}

package/src/pi/delegation.ts

@@ -0,0 +1,68 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createDeskClient } from "../desk/ipc.ts";
+import { AGENT_ENV, DELEGATION_ENV, DELEGATE_TOOL, MAX_CHILDREN, type AgentPolicy } from "../execution/delegation.ts";
+import { loadConfig } from "../state/project.ts";
+import { isSubagentProcess } from "./quiet.ts";
+
+export function allowedAgentTool(policy: AgentPolicy, name: string, readOnlyHint?: boolean, hidden = false): boolean {
+  if (hidden) return false;
+  if (name.startsWith("mcp__")) return policy.mcpTools.includes(name) && (!policy.readOnly || readOnlyHint === true);
+  if (name === DELEGATE_TOOL && policy.depth > 1) return false;
+  return policy.tools.includes(name);
+}
+
+/** Enforce the same permissions on direct, discovered and codemode-nested calls. */
+export function registerAgentPermissions(pi: ExtensionAPI): void {
+  const raw = process.env[AGENT_ENV];
+  let policy: AgentPolicy | undefined;
+  if (raw) {
+    try { policy = JSON.parse(raw) as AgentPolicy; }
+    catch { throw new Error("Invalid bot-lobby agent policy."); }
+    if (!Array.isArray(policy?.tools) || !Array.isArray(policy?.mcpTools) || typeof policy.readOnly !== "boolean" || ![1, 2].includes(policy.depth)) throw new Error("Invalid bot-lobby agent policy.");
+  }
+  pi.on("tool_call", (event) => {
+    const info = pi.getAllTools().find((tool) => tool.name === event.toolName);
+    if (!info) return { block: true, reason: `Unknown tool ${event.toolName}.` };
+    if (["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"].includes(event.toolName)) {
+      const server = (event.input as { server?: unknown }).server;
+      const grants = policy?.mcpTools ?? loadConfig().master.mcpTools ?? [];
+      if (typeof server === "string" && grants.some((tool) => tool.startsWith(`mcp__${server.replace(/[^A-Za-z0-9_]/g, "_")}__`)) && info?.exposure !== "hidden") return;
+      return { block: true, reason: "Specify an MCP server with an explicit tool grant to read its resources." };
+    }
+    if (policy) {
+      if (allowedAgentTool(policy, event.toolName, info?.annotations?.readOnlyHint, info?.exposure === "hidden")) return;
+      return { block: true, reason: `This agent is not granted ${event.toolName}.` };
+    }
+    if (event.toolName.startsWith("mcp__")) {
+      if ((loadConfig().master.mcpTools ?? []).includes(event.toolName) && info?.exposure !== "hidden") return;
+      return { block: true, reason: `Grant ${event.toolName} to the master in bot-lobby settings first.` };
+    }
+    if (event.parentToolCallId && !pi.getActiveTools().includes(event.toolName)) return { block: true, reason: `${event.toolName} is not active for this agent.` };
+  });
+}
+
+export function registerDelegation(pi: ExtensionAPI): void {
+  if (!isSubagentProcess() || !process.env[DELEGATION_ENV]) return;
+  const target = JSON.parse(process.env[DELEGATION_ENV]!) as { address: string; token: string; timeoutMs: number };
+  const client = createDeskClient(target.address, target.token);
+  pi.on("session_shutdown", () => client.close());
+  pi.registerTool({
+    name: DELEGATE_TOOL,
+    label: "Delegate subtasks",
+    description: "Split substantial, separable work among at most five children total. Supply complete briefs with goals, files, contracts, constraints and done criteria. Wait for their reports, integrate changes and verify the whole task yourself. Children cannot delegate further.",
+    parameters: Type.Object({ briefs: Type.Array(Type.String({ minLength: 1, maxLength: 32_000 }), { minItems: 1, maxItems: MAX_CHILDREN }) }),
+    executionMode: "sequential",
+    async execute(_id, params, signal) {
+      signal?.throwIfAborted();
+      const cancel = () => { void client.request({ op: "cancel_delegate" }); };
+      signal?.addEventListener("abort", cancel, { once: true });
+      try {
+        const answer = await client.request({ op: "delegate", briefs: params.briefs }, target.timeoutMs + 10_000);
+        if (!answer.ok) throw new Error(answer.text);
+        const children = JSON.parse(answer.text) as Array<{ runId: string; status: string; report: string; reportPath?: string; error?: string }>;
+        return { content: [{ type: "text", text: children.map((child) => `Child ${child.runId}: ${child.status}\n${child.report}${child.reportPath ? `\nFull report: ${child.reportPath}` : ""}${child.error ? `\nError: ${child.error}` : ""}`).join("\n\n") }], details: { children } };
+      } finally { signal?.removeEventListener("abort", cancel); }
+    },
+  });
+}

package/src/pi/model-support.ts

@@ -90,7 +90,7 @@ export function createProfileResolver(config: BotLobbyConfig, options: ResolverO
   };
 }
 
-type RunProfile = { model?: string; thinking: string; timeoutMs: number; instructions?: string };
+type RunProfile = { model?: string; thinking: string; timeoutMs: number; instructions?: string; mcpTools?: string[] };
 
 /** Unset models run on the session's; thinking is clamped to the model, with a one-time warning. */
 function resolveRunProfile(profile: RunProfile, label: string, options: ResolverOptions): RunProfile {

package/src/pi/plan-checklist.ts

@@ -315,7 +315,7 @@ export function targetStep(steps: readonly string[], instruction: string | undef
 export function latestWorkerRun(runs: readonly AgentRun[]): AgentRun | undefined {
   let latest: AgentRun | undefined;
   for (const run of runs) {
-    if (run.role !== "worker" || !run.instruction) continue;
+    if (run.role !== "worker" || run.parentRunId || !run.instruction) continue;
     if (!latest || Date.parse(run.startedAt) >= Date.parse(latest.startedAt)) latest = run;
   }
   return latest;
@@ -360,7 +360,7 @@ function replaySteps(steps: readonly string[], runs: readonly AgentRun[]): { com
   const latestRun = latestWorkerRun(runs);
   let latest = -1;
   for (const run of byStart(runs)) {
-    if (run.role !== "worker") continue;
+    if (run.role !== "worker" || run.parentRunId) continue;
     const matched = targetStep(steps, run.instruction, completed);
     if (run === latestRun) latest = matched >= 0 && run.status === "success" ? matched + 1 : matched;
     if (run.status !== "success") continue;
@@ -401,6 +401,7 @@ export interface StepWork {
   ms: number;
   /** A worker is on it right now. */
   active: boolean;
+  activeAgentCount: number;
 }
 
 /** The steps a run works on: every step of a range it names, else the step it targets, else the next one still open. */
@@ -419,19 +420,29 @@ function runSteps(steps: readonly string[], instruction: string | undefined, com
  * completes them, so a later run that names no step goes to the next one.
  */
 export function stepWork(steps: readonly string[], runs: readonly AgentRun[], now = Date.now()): StepWork[] {
-  const work = steps.map(() => ({ ms: 0, active: false }));
+  const work = steps.map(() => ({ ms: 0, active: false, activeAgentCount: 0 }));
+  const assigned = new Map<string, number[]>();
+  const counted = new Set<string>();
   const completed = new Set<number>();
   for (const run of byStart(runs)) {
     if (run.role !== "worker") continue;
-    const covered = runSteps(steps, run.instruction, completed);
+    if (counted.has(run.runId)) continue;
+    counted.add(run.runId);
+    const covered = run.parentRunId
+      ? assigned.get(run.parentRunId) ?? runSteps(steps, run.stepInstruction, completed)
+      : runSteps(steps, run.instruction, completed);
+    assigned.set(run.runId, covered);
     const start = Date.parse(run.startedAt);
     const end = run.finishedAt ? Date.parse(run.finishedAt) : now;
     const ms = Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, end - start) : 0;
     for (const index of covered) {
-      work[index]!.ms += ms;
-      if (run.status === "running") work[index]!.active = true;
+      if (!run.parentRunId) work[index]!.ms += ms;
+      if (run.status === "running") {
+        work[index]!.active = true;
+        work[index]!.activeAgentCount += 1;
+      }
     }
-    if (run.status === "success" && covered.length > 0) markThrough(completed, covered[covered.length - 1]!);
+    if (!run.parentRunId && run.status === "success" && covered.length > 0) markThrough(completed, covered[covered.length - 1]!);
   }
   return work;
 }

package/src/pi/run-summary.ts

@@ -69,6 +69,7 @@ export function runFlags(run: Pick<AgentRun, "status" | "stalled" | "wrappedUp"
  */
 export function describeRun(run: AgentRun, now = Date.now()): string {
   const parts = [`${STATUS_ICONS[run.status]} ${agentName(run)} ${run.role}`, shortDuration(durationOf(run, now))];
+  if (run.parentRunId) parts.push(`child of ${run.parentRunId}`);
   const turns = run.turns ?? run.usage?.turns;
   if (turns) parts.push(`${turns} turn${turns === 1 ? "" : "s"}`);
   if (run.tools) parts.push(`${run.tools} tool${run.tools === 1 ? "" : "s"}`);
@@ -84,6 +85,10 @@ export function describeRun(run: AgentRun, now = Date.now()): string {
 export function runLogEntry(run: AgentRun): RunLogEntry {
   return {
     runId: run.runId,
+    ...(run.parentRunId ? { parentRunId: run.parentRunId } : {}),
+    ...(run.depth ? { depth: run.depth } : {}),
+    ...(run.instruction ? { instruction: run.instruction } : {}),
+    ...(run.stepInstruction ? { stepInstruction: run.stepInstruction } : {}),
     domain: run.domain,
     role: run.role,
     status: run.status,
@@ -106,6 +111,10 @@ export function runLogEntry(run: AgentRun): RunLogEntry {
 export function runFromLog(entry: RunLogEntry, taskId: string): AgentRun {
   return {
     runId: entry.runId,
+    ...(entry.parentRunId ? { parentRunId: entry.parentRunId } : {}),
+    ...(entry.depth ? { depth: entry.depth } : {}),
+    ...(entry.instruction ? { instruction: entry.instruction } : {}),
+    ...(entry.stepInstruction ? { stepInstruction: entry.stepInstruction } : {}),
     taskId,
     domain: entry.domain,
     role: entry.role,

package/src/schemas/configuration.ts

@@ -27,12 +27,15 @@ export interface AgentModelConfig {
   thinking: string;
   /** Free-form instructions layered on top of this agent's built-in prompt. */
   instructions?: string;
+  /** Exact native MCP tool names this profile may call; empty grants none. */
+  mcpTools?: string[];
   /** Time limit per run; falls back to `workflow.agentTimeoutMs`. */
   timeoutMs?: number;
 }
 
 /** Scouts pick a model and a time limit only; their thinking is fixed at `SCOUT_THINKING`. */
 export interface ScoutConfig {
+  mcpTools?: string[];
   model: ModelRef;
   timeoutMs: number;
 }
@@ -320,20 +323,27 @@ function positive(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
 }
 
+export function normalizeMcpTools(value: unknown): string[] {
+  return Array.isArray(value) ? [...new Set(value.filter((tool): tool is string => typeof tool === "string" && /^mcp__[A-Za-z0-9_]+__[A-Za-z0-9_]+$/.test(tool)))] : [];
+}
+
 /** Merge one agent's override over its default; legacy `inherit` or unknown thinking falls back to the default level. */
 function normalizeAgent(base: AgentModelConfig, override: Partial<AgentModelConfig> | undefined): AgentModelConfig {
   const merged = { ...base, ...(override ?? {}) };
   const thinking = isThinkingLevel(merged.thinking) ? merged.thinking : base.thinking;
   const timeoutMs = positive(merged.timeoutMs) ?? base.timeoutMs;
-  return { model: merged.model, thinking, ...(typeof merged.instructions === "string" ? { instructions: merged.instructions } : {}), ...(timeoutMs ? { timeoutMs } : {}) };
+  const mcpTools = normalizeMcpTools(merged.mcpTools);
+  return { model: merged.model, thinking, ...(mcpTools.length ? { mcpTools } : {}), ...(typeof merged.instructions === "string" ? { instructions: merged.instructions } : {}), ...(timeoutMs ? { timeoutMs } : {}) };
 }
 
 /** Scouts keep a model and a time limit; any thinking value in the file is dropped. */
 function normalizeScout(override: Partial<ScoutConfig> | undefined): ScoutConfig {
   const base = DEFAULT_CONFIG.scout;
+  const mcpTools = normalizeMcpTools(override?.mcpTools);
   return {
     model: typeof override?.model === "string" && override.model.trim() ? override.model : base.model,
     timeoutMs: positive(override?.timeoutMs) ?? base.timeoutMs,
+    ...(mcpTools.length ? { mcpTools } : {}),
   };
 }
 
@@ -479,6 +489,8 @@ export interface AgentProfile {
   thinking: string;
   timeoutMs: number;
   instructions?: string;
+  /** Exact native MCP tool names this profile may call; empty grants none. */
+  mcpTools?: string[];
 }
 
 /** The settings entry a domain/role run draws from. */
@@ -503,10 +515,10 @@ export function agentProfile(config: BotLobbyConfig, domain: Domain, role: Role)
   const instructions = config.agents[domain].instructions;
   const fallback = config.workflow.agentTimeoutMs;
   if (kind === "scout") {
-    return { kind, model: modelOf(config.scout.model), thinking: SCOUT_THINKING, timeoutMs: config.scout.timeoutMs || fallback, instructions };
+    return { kind, model: modelOf(config.scout.model), thinking: SCOUT_THINKING, timeoutMs: config.scout.timeoutMs || fallback, instructions, ...(config.scout.mcpTools?.length ? { mcpTools: config.scout.mcpTools } : {}) };
   }
   const entry = kind === "researcher" ? config.researcher : config.agents[kind];
-  return { kind, model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? fallback, instructions };
+  return { kind, model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? fallback, instructions, ...(entry.mcpTools?.length ? { mcpTools: entry.mcpTools } : {}) };
 }
 
 /** The settings entry of a lobby agent (quick fix or planner). */
@@ -515,19 +527,19 @@ export function lobbyAgentConfig(config: BotLobbyConfig, kind: LobbyAgentKind):
 }
 
 /** Profile for a lobby agent run, from settings alone; `model` is undefined while unset. */
-export function lobbyAgentProfile(config: BotLobbyConfig, kind: LobbyAgentKind): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+export function lobbyAgentProfile(config: BotLobbyConfig, kind: LobbyAgentKind): { model?: string; thinking: string; timeoutMs: number; instructions?: string; mcpTools?: string[] } {
   const entry = lobbyAgentConfig(config, kind);
-  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? config.workflow.agentTimeoutMs, instructions: entry.instructions };
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? config.workflow.agentTimeoutMs, instructions: entry.instructions, ...(entry.mcpTools?.length ? { mcpTools: entry.mcpTools } : {}) };
 }
 
 /**
  * A planning panel seat's profile: the domain's (or the researcher's) model,
  * thinking and custom instructions, bounded by the planner's per-turn limit.
  */
-export function panelMemberProfile(config: BotLobbyConfig, member: PanelMember): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+export function panelMemberProfile(config: BotLobbyConfig, member: PanelMember): { model?: string; thinking: string; timeoutMs: number; instructions?: string; mcpTools?: string[] } {
   const entry = member === "researcher" ? config.researcher : config.agents[member];
   const timeoutMs = config.planner.timeoutMs ?? config.workflow.agentTimeoutMs;
-  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs, instructions: entry.instructions };
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs, instructions: entry.instructions, ...(entry.mcpTools?.length ? { mcpTools: entry.mcpTools } : {}) };
 }
 
 /** Resolves the model, thinking and time limit one subagent run uses. */

package/src/schemas/findings.ts

@@ -100,6 +100,10 @@ export interface ResearchResult {
 
 export interface AgentRun {
   runId: string;
+  parentRunId?: string;
+  depth?: number;
+  /** Parent instruction used to assign children to plan steps. */
+  stepInstruction?: string;
   taskId: string;
   domain: Domain;
   role: Role;