@foldrun/core 2.7.0 → 2.8.0

package/src/runner.ts

@@ -7,6 +7,7 @@ import { latestRevisionId } from "./history.ts";
 import { recordCallIo, redactionsFor } from "./capture.ts";
 import { AUTH_REFUSAL } from "./issues.ts";
 import { hookNames } from "./hooks.ts";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -36,7 +37,10 @@ const isolatedRun = () => {
   return mode === "container" || (!!mode && mode in platform.isolation);
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.ts";
-import { DELEGATE_TOOL, gatherSubagents, subagentPrompt, subagentTools, type SubagentSpec } from "./subagents.ts";
+import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools, type DelegateSpec, type SubagentSpec } from "./subagents.ts";
+import { DELEGATE_SERVER, buildDelegateTools, delegatePromptLine, delegateToolNames, localDelegateChannel } from "./delegate-tools.ts";
+import type { DelegationResult } from "./operator.ts";
+import type { StepDelegation } from "./store.ts";
 import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool, buildPeerTools, inboxReader, localPeerBus, peersPromptLine, type PeerInfo } from "./operator.ts";
 import { sendPlainNotification } from "./notify.ts";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.ts";
@@ -71,7 +75,7 @@ import {
   checkFormatVersion,
   readRun,
   writeRun,
-  isRescueRecord,
+  isSplicedRecord,
   runSummary,
   verdictOf,
   type FlowStep,
@@ -618,6 +622,9 @@ export function buildSubagentSpecs(o: {
     try {
       const tags = o.tags ?? [];
       const own = agentContext(sub.dir, o.tenant, tags, { runId: o.runId, agent: sub.name }, o.flowTimezone, true);
+      // sandbox: own — delegated to as a step of its own, not inside this
+      // one (buildDelegateSpecs).
+      if (ownSandbox(own.front)) continue;
       const description = typeof own.front.description === "string" ? own.front.description.trim() : "";
       if (!description) {
         o.push("error", `subagents: "${sub.name}" has no description — the model picks a sub-agent by it; not delegated to`);
@@ -649,6 +656,60 @@ export function buildSubagentSpecs(o: {
   return out;
 }
 
+/**
+ * The `sandbox: own` sub-agents a step may hand jobs to: a name and a
+ * description each, all the parent's sandbox needs. What they may hold is
+ * read from their own file when a job arrives — never cut to the parent's,
+ * and never seen by it. `canRun` is false where nothing can start their
+ * sandbox (a sub-agent's own step: depth one; a step outside a run).
+ */
+export function buildDelegateSpecs(o: {
+  names: unknown;
+  self: string;
+  workspaceRoot: string;
+  canRun: boolean;
+  push: (type: "info" | "error", text: string) => void;
+  /** Told, per offered sub-agent, whether a tool it holds acts outside the
+   *  workspace — a delegating step whose job may have sent something must
+   *  not be re-run as if it had only read (launchStep's retry policy). */
+  outward?: (name: string, outward: boolean) => void;
+  tenant?: string;
+  tags?: string[];
+}): DelegateSpec[] {
+  const out: DelegateSpec[] = [];
+  for (const sub of gatherSubagents(o.workspaceRoot, o.names).found) {
+    if (sub.name === o.self) continue; // buildSubagentSpecs says so
+    let front: Record<string, unknown>;
+    try {
+      front = matter(fs.readFileSync(path.join(sub.dir, "agent.md"), "utf8")).data as Record<string, unknown>;
+    } catch {
+      continue; // buildSubagentSpecs says so
+    }
+    if (!ownSandbox(front)) continue;
+    const description = typeof front.description === "string" ? front.description.trim() : "";
+    if (!description) {
+      o.push("error", `subagents: "${sub.name}" has no description — the model picks a sub-agent by it; not delegated to`);
+      continue;
+    }
+    if (!o.canRun) {
+      o.push("info", `subagents: "${sub.name}" runs in its own sandbox, which nothing here can start (a sub-agent cannot delegate again, and a step outside a run has no room for it) — not offered`);
+      continue;
+    }
+    if (o.outward) {
+      let acts = true; // unreadable is treated as able to act: the safe side
+      const tags = o.tags ?? [];
+      try {
+        acts = agentContext(sub.dir, o.tenant ?? "default", tags, { agent: sub.name }, null, true).outward;
+      } catch {
+        /* as above */
+      }
+      o.outward(sub.name, acts);
+    }
+    out.push({ name: sub.name, description });
+  }
+  return out;
+}
+
 export function sharedInstructions(agentDir: string, tenant: string): string | null {
   const sections = [
     ["Everyone in this account", readAgentsMd(accountDir(tenant))?.body],
@@ -2026,6 +2087,10 @@ async function runStep(
   /** The in-process colleagues' bus for this group (localPeerBus), when
    *  the step runs in this process rather than a pod. */
   peerBus?: ReturnType<typeof localPeerBus>,
+  /** Runs one job for a `sandbox: own` sub-agent as a step of its own and
+   *  answers with its reply (the drive loop's delegateFor). Absent for a
+   *  step that is itself a sub-agent's: depth one. */
+  delegateJob?: (agent: string, job: string, cancelled: () => boolean) => Promise<DelegationResult>,
 ) {
   // Secret values are injected into scripts as environment variables and
   // substituted into API headers, so a model that reads one back — from a
@@ -2046,6 +2111,9 @@ async function runStep(
   let fileDir: string | null = null;
   let installDir: string | null = null;
   let disposeRuntime: (() => void) | undefined;
+  /** The delegate door served for this step (sandbox: own sub-agents), held
+   *  here so the finally can close it however the step ends. */
+  let serving: { close(): Promise<void> } | null = null;
   // Can this step's tools act outside the workspace? Set once its context is
   // read; the verdict at the end of this function reads it.
   let canActOutward = false;
@@ -2519,8 +2587,13 @@ async function runStep(
     // Colleagues this agent may DELEGATE to: each with its own context and
     // its own tools — resolved exactly as its own step's would be, then cut
     // to what THIS step holds (subagents.ts). Built host-side, like consults.
+    // A sandbox: own job is a sub-agent already: depth one, so neither kind
+    // of delegation is offered to it.
+    if (step.subagentOf && refNames(front.subagents).length) {
+      push("info", `subagents: not offered — ${step.agent} is running a job for ${step.subagentOf}, and a sub-agent does not delegate again`);
+    }
     const subagents = buildSubagentSpecs({
-      names: front.subagents, self: step.agent, workspaceRoot, tenant, tags, runId, flowTimezone,
+      names: step.subagentOf ? [] : front.subagents, self: step.agent, workspaceRoot, tenant, tags, runId, flowTimezone,
       parentAllowed: [...allowed, ...consultNames.map((n) => `mcp__${n}`)], push,
     });
     if (subagents.length) {
@@ -2529,6 +2602,29 @@ async function runStep(
       allowed.push(DELEGATE_TOOL);
       for (const s of subagents) push("info", `subagent: ${s.name} — ${s.tools.length ? s.tools.join(", ") : "no tools"}`);
     }
+    // sandbox: own sub-agents: a delegate_<name> tool each. Their jobs run as
+    // steps of their own (delegate-tools.ts); dropped again below where no
+    // door to the worker exists.
+    let delegates = buildDelegateSpecs({
+      names: step.subagentOf ? [] : front.subagents, self: step.agent, workspaceRoot, canRun: !!delegateJob && stepIndex !== undefined && stepIndex >= 0, push,
+      tenant,
+      tags,
+      outward: (_name, acts) => void (canActOutward ||= acts),
+    });
+    const offerDelegates = (specs: DelegateSpec[]) => {
+      for (const n of delegateToolNames(delegates)) if (allowed.includes(n)) allowed.splice(allowed.indexOf(n), 1);
+      if (consultNames.includes(DELEGATE_SERVER)) consultNames.splice(consultNames.indexOf(DELEGATE_SERVER), 1);
+      delegates = specs;
+      if (!specs.length) return;
+      allowed.push(...delegateToolNames(specs));
+      consultNames.push(DELEGATE_SERVER);
+    };
+    offerDelegates(delegates);
+    const delegateLine = delegates.length ? `\n\n${delegatePromptLine(delegates)}` : "";
+    if (delegates.length) {
+      prompt += delegateLine;
+      for (const d of delegates) push("info", `subagent: ${d.name} — own sandbox, its own tools, secrets and network`);
+    }
 
     // The last provider refusal this step saw, for the fallback decision —
     // watched on both paths, because a refusal reads the same from a pod
@@ -2716,7 +2812,31 @@ async function runStep(
         // colleague's message may be addressed to. Only when granted: a
         // step without the tools has no reason to know its siblings.
         ...(peers && stepIndex !== undefined && stepIndex >= 0 ? { agent: step.agent, peers: siblings } : {}),
+        // sandbox: own sub-agents: the only names the delegate door takes.
+        ...(delegates.length ? { delegates: delegates.map((d) => d.name) } : {}),
       });
+      // Serve those jobs while this step runs: each one becomes a step of
+      // its own (delegateJob), and the door answers the long-poll with its
+      // reply. No proxy, or a platform without the door: not offered — the
+      // tools would only fail.
+      if (delegates.length) {
+        // Also: the executor must be able to stop ONE job — record its
+        // sandbox (the resumable ones checkpoint it) and destroy it — or a job
+        // whose parent stopped waiting would run on, sending and writing.
+        const canStopAJob = !!platform.killSandbox && platform.sandboxResumable(isolation!);
+        if (lease && platform.egress.delegations && delegateJob && stepIndex !== undefined && canStopAJob) {
+          serving = platform.egress.delegations(
+            // Re-attaching to a sandbox that outlived its driver: what it
+            // queued before the restart is still its own, not a dead attempt's.
+            { tenant, runId: runId ?? "adhoc", step: stepIndex, resuming: !!step.sandbox && step.sandbox.kind === isolation },
+            (j) => delegateJob(j.agent, j.job, j.cancelled ?? (() => false)),
+          );
+        } else {
+          push("error", `subagents: ${delegates.map((d) => d.name).join(", ")} run in their own sandbox, and this install ${canStopAJob ? "has no door to start one from inside a step" : "cannot stop one job's sandbox on its own"} — not offered`);
+          offerDelegates([]);
+          prompt = prompt.replace(delegateLine, "");
+        }
+      }
       // The forward door: every program in the sandbox sends through the
       // proxy, which holds the site list and fills bound secrets. A proxy
       // without the door (an older platform) leaves programs going direct.
@@ -2892,6 +3012,7 @@ async function runStep(
           consults,
           ...(peers ? { peers: { self: step.agent, siblings } } : {}),
           ...(subagents.length ? { subagents } : {}),
+          ...(delegates.length ? { delegates } : {}),
           timeoutSec: step.timeout,
           budgetUsd: stepBudgetUsd,
           budgetNote: stepBudgetNote,
@@ -3114,6 +3235,7 @@ async function runStep(
       // to decide; a second go could send or charge twice.
       step.image = outcome.image ?? null;
       step.browserPod = outcome.browserPod ? { ...outcome.browserPod } : null;
+      if (step.subagentOf && outcome.applied?.length) step.wrote = [...new Set([...(step.wrote ?? []), ...outcome.applied])];
       if (outcome.status === "failed" && outcome.browserPod?.lost) {
         const decision = podLossDecision(outcome.browserPod);
         if (decision.rerun) {
@@ -3158,6 +3280,8 @@ async function runStep(
           if (typeof line === "string") pushWatching("info", line);
           else pushWatching("info", line.text, { effect: line.effect });
         }
+        await serving?.close();
+        serving = null;
         await lease.release();
       }
       // Nothing a test run left in storage/public/ reached storage/, so
@@ -3255,6 +3379,16 @@ async function runStep(
       const peerChannel = peerBus && stepIndex !== undefined && stepIndex >= 0 ? peerBus.channelFor({ agent: step.agent, step: stepIndex }, siblings) : null;
       const peerTools = peers ? buildPeerTools({ channel: peerChannel, self: step.agent, siblings, emit: push }) : null;
       const localInbox = peerChannel ? inboxReader(peerChannel, push) : undefined;
+      // sandbox: own sub-agents, here: no proxy between the step and this
+      // process, so the job is handed to the drive loop directly.
+      const delegateTools = delegates.length && delegateJob
+        ? buildDelegateTools({ specs: delegates, channel: localDelegateChannel(delegateJob), emit: push, timeoutSec: step.timeout })
+        : null;
+      // Said, not hidden: on this machine no step has a sandbox, so a job is
+      // its own context, tools and secrets — but the same files and network.
+      if (delegateTools?.server) {
+        push("info", `subagents: ${delegates.map((d) => d.name).join(", ")} run here in this process — their own tools and secrets, but no sandbox: the same files and network as this step (on the platform each job gets a sandbox of its own)`);
+      }
       // @file secrets become 0600 paths here (host run), cleaned up in the
       // finally — once, however many attempts follow.
       const mat = materializeFileSecrets(agentDir, stepSecrets);
@@ -3296,6 +3430,7 @@ async function runStep(
           ...(deskTools.server ? { foldrun_desks: deskTools.server } : {}),
           ...(askTools ? { foldrun_ask: askTools.server } : {}),
           ...(peerTools ? { foldrun_peers: peerTools.server } : {}),
+          ...(delegateTools?.server ? { foldrun_delegate: delegateTools.server } : {}),
           ...(installTools ? { foldrun_install: installTools.server } : {}),
           ...mcpServers,
         },
@@ -3414,6 +3549,15 @@ async function runStep(
     step.status = "failed";
     push("error", err instanceof Error ? err.message : String(err));
   } finally {
+    // The delegate door's service, when the step ended by throwing before
+    // its lease was released: its jobs are settled, not left hanging.
+    if (serving) {
+      try {
+        await serving.close();
+      } catch {
+        // best-effort — the door's records expire on their own
+      }
+    }
     try {
       cleanupFileSecrets(fileDir);
       if (installDir) fs.rmSync(installDir, { recursive: true, force: true });
@@ -4255,6 +4399,29 @@ function driveRunInner(
       // last driver got, runStep passes that as `resume`, and the step
       // carries on from where it was — a deploy no longer costs the run.
       let orphaned = false;
+      // A sandbox: own job whose driver went away is over: the reply it was
+      // making went to a process that no longer exists, and the step that
+      // asked is told it failed (the platform settles the door's side), so
+      // its model can hand the job over again. Never resumed or relaunched.
+      for (const step of run.steps) {
+        if (!step.subagentOf || (step.status !== "running" && step.status !== "pending")) continue;
+        // Its sandbox may still be executing — outward work included — while
+        // the parent hands the job over again: destroy it before letting go
+        // of the only reference to it.
+        if (step.sandbox?.ref) {
+          try {
+            platform.killSandbox?.(step.sandbox);
+          } catch {
+            // a sandbox we cannot reach must not stop the run from resuming
+          }
+        }
+        step.status = "failed";
+        step.sandbox = null;
+        step.events.push({ t: new Date().toISOString(), type: "error", text: "interrupted — the worker driving this job restarted; the step that asked for it was told it failed" });
+        const parent = run.steps.find((s) => s.delegations?.some((d) => d.id === step.delegation));
+        const entry = parent?.delegations?.find((d) => d.id === step.delegation);
+        if (entry && entry.status === "running") entry.status = "failed";
+      }
       for (const step of run.steps) {
         if (step.status !== "running") continue;
         const resumable = !!step.sandbox && platform.sandboxResumable(step.sandbox.kind);
@@ -4392,7 +4559,7 @@ function driveRunInner(
       // three handoffs below read the flow's steps only: counting the rescue
       // too handed the next group the same output twice, or a stale one
       // from an evaluator loop's earlier cycle.
-      const flowStepsOf = (group: StepRecord[]) => group.filter((s) => !isRescueRecord(s));
+      const flowStepsOf = (group: StepRecord[]) => group.filter((s) => !isSplicedRecord(s));
       const dataOf = (all: StepRecord[]): unknown => {
         const group = flowStepsOf(all);
         const carrying = group.filter((s) => s.status === "completed" && s.data !== undefined);
@@ -4803,7 +4970,7 @@ function driveRunInner(
           save();
           if (freshGroup.every((s) => s.status !== "pending")) {
             // everything in this group was rejected
-            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s))) {
+            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isSplicedRecord(s))) {
               run.status = "failed";
               break;
             }
@@ -4821,7 +4988,7 @@ function driveRunInner(
         // of the flow: one left pending by a drive that died is picked up by
         // rescueStep below, never launched alongside the group (21 Oct 2026:
         // a resumed run launched 77 leftover fixers at once).
-        const launching = freshGroup.filter((s) => s.status === "pending" && !isRescueRecord(s));
+        const launching = freshGroup.filter((s) => s.status === "pending" && !isSplicedRecord(s));
         // tools: [peers] — what each step of the group is told about the
         // others, and the bus they share when they run in this process.
         const peerBus = localPeerBus();
@@ -4829,6 +4996,117 @@ function driveRunInner(
           launching
             .filter((s) => s !== step)
             .map((s) => ({ agent: s.agent, step: run.steps.indexOf(s), instruction: (s.instruction ?? "").split("\n")[0].trim().slice(0, 200) }));
+        // sandbox: own sub-agents (delegate-tools.ts): one job, run as a step
+        // of its own — its own sandbox, tools, secrets and network, from its
+        // own file — and answered with its reply. The record is APPENDED to
+        // run.steps, in the parent's group: every running step's lease and
+        // inbox are addressed by index, so nothing may shift under them.
+        // Marked subagentOf, it is never launched, handed on or reset as a
+        // step of the flow (isSplicedRecord). It gets no delegateJob of its
+        // own: depth one.
+        const delegateFor = (parent: StepRecord) => async (agent: string, job: string, cancelled: () => boolean): Promise<DelegationResult> => {
+          const dir = path.join(pDir, "agents", agent);
+          if (!fs.existsSync(path.join(dir, "agent.md"))) return { status: "failed", result: `${agent} is not an agent in this workspace` };
+          // A stable id on both records: an index into run.steps moves when a
+          // rescue or a fan-out is spliced in before the child.
+          const id = `d_${crypto.randomBytes(5).toString("hex")}`;
+          const child: StepRecord = {
+            agent,
+            subagentOf: parent.agent,
+            delegation: id,
+            instruction: job,
+            group: parent.group,
+            optional: true,
+            timeout: parent.timeout,
+            attempts: 1,
+            status: "running",
+            events: [],
+            result: null,
+            costUsd: null,
+          };
+          run.steps.push(child);
+          const at = run.steps.length - 1;
+          const entry: StepDelegation = { id, agent, status: "running" };
+          (parent.delegations ??= []).push(entry);
+          const started = Date.now();
+          // The same budget rules as a step of the flow: nothing left means
+          // not started (a zero ceiling would read as no cap at all), and
+          // what it may spend is reserved while it runs, so two jobs at once
+          // do not each get the agent's whole remaining budget.
+          // The flow's budget: what is left after what has been spent AND
+          // what every step and job running now holds — the parent's own
+          // ceiling included. ceilingFor's equal share would hand the job a
+          // second copy of an allowance its parent already holds.
+          const held = [...reserved.values()].reduce((a, b) => a + b, 0);
+          const flowLeft = run.budgetUsd && run.budgetUsd > 0 ? Math.max(0, run.budgetUsd - platform.runSpend(run) - held) : null;
+          const ceiling = stepCeilingFor(
+            flowLeft,
+            agentBudgets.get(agent),
+            run.steps
+              .filter((s) => s.agent === agent)
+              .reduce((sum, s) => sum + (s.costUsd ?? 0) + (s !== child && s.status === "running" ? (reserved.get(s) ?? 0) : 0), 0),
+            agent,
+            1,
+          );
+          if (ceiling.ceilingUsd === 0) {
+            child.status = "failed";
+            child.events.push({ t: new Date().toISOString(), type: "error", text: `over budget — nothing left to spend before this job (${ceiling.note}); it was not started` });
+            entry.status = "failed";
+            entry.ms = 0;
+            save();
+            return { status: "failed", result: `${agent} was not started: over budget (${ceiling.note})`, wrote: [] };
+          }
+          if (ceiling.ceilingUsd !== null) reserved.set(child, ceiling.ceilingUsd);
+          save();
+          // A running sandbox does not hear a stop flag: when the parent stops
+          // waiting (its tool timed out, or its step ended), destroy the job's
+          // sandbox, so nothing it does outlives the step that asked for it.
+          const parentGone = () => run.stopRequested === true || cancelled() || (parent.status !== "running" && parent.status !== "pending");
+          let killedIt = false;
+          const watch = setInterval(() => {
+            if (killedIt || !parentGone() || !child.sandbox?.ref) return;
+            killedIt = true;
+            child.events.push({ t: new Date().toISOString(), type: "error", text: "stopped — the step that asked for this job stopped waiting for it" });
+            try {
+              platform.killSandbox?.(child.sandbox);
+            } catch {
+              // its own deadline ends it
+            }
+          }, 2_000);
+          watch.unref?.();
+          try {
+            await runStep(
+              dir, tenant, child, null, save, modelOverride, tags, effortOverride, run.id, undefined,
+              ceiling.ceilingUsd, ceiling.note, run.test === true,
+              () => {
+                save();
+                // The parent's step ending or cancelling ends the job too —
+                // here while it waits for room; the watch above once it runs.
+                return parentGone();
+              },
+              flowTimezone, at,
+            );
+          } catch (err) {
+            child.status = "failed";
+            child.events.push({ t: new Date().toISOString(), type: "error", text: err instanceof Error ? err.message : String(err) });
+          } finally {
+            clearInterval(watch);
+            reserved.delete(child);
+          }
+          // runStep mutates child.status; widen past TS's "running" narrowing.
+          const ended: string = child.status;
+          const status = ended === "completed" ? "completed" : ended === "skipped" ? "skipped" : "failed";
+          entry.status = status;
+          entry.costUsd = child.costUsd ?? null;
+          entry.ms = Date.now() - started;
+          save();
+          const errors = child.events.filter((e) => e.type === "error").map((e) => e.text).join("\n");
+          return {
+            status,
+            result: child.result ?? (errors || "(no reply)"),
+            wrote: child.wrote ?? [],
+          };
+        };
         // An agent's own `budget:` — the most it may spend in one run — is
         // read at launch, so a cap raised mid-run applies to the next step.
         const agentBudgets = new Map(listAgents(tenant, workspace).map((a) => [a.name, a.budget]));
@@ -4972,6 +5250,7 @@ function driveRunInner(
                   run.steps.indexOf(step),
                   siblingsOf(step),
                   peerBus,
+                  delegateFor(step),
                 ).finally(() => reserved.delete(step));
                 // runStep mutates step.status; read it through a widened local
                 // so TS doesn't keep the "running" narrowing from above.
@@ -5095,8 +5374,9 @@ function driveRunInner(
           // answered an earlier failure — an evaluator loop's previous cycle
           // — not this one.
           const leftovers: StepRecord[] = [];
-          for (let j = run.steps.indexOf(step) + 1; j < run.steps.length && isRescueRecord(run.steps[j]); j++) {
+          for (let j = run.steps.indexOf(step) + 1; j < run.steps.length && isSplicedRecord(run.steps[j]); j++) {
             const r = run.steps[j];
+            if (r.subagentOf) continue;
             if (r.agent === step.onFail && (r.rescueOf === undefined || r.rescueOf === step.agent) && (r.status === "pending" || r.status === "running")) {
               leftovers.push(r);
             }
@@ -5202,7 +5482,7 @@ function driveRunInner(
         // A rescue record's own failure is already on the step it took over
         // ("also failed"); counted here it would fail a group whose step a
         // later rescue completed.
-        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s));
+        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isSplicedRecord(s));
         if (requiredFailed) {
           run.status = "failed";
           break;
@@ -5281,7 +5561,7 @@ function driveRunInner(
               // A rescue answered its own failure and stays as it ended: reset
               // to pending it read as an interrupted rescue, and the next
               // cycle's failure was handed the old one's instructions.
-              if (isRescueRecord(s)) continue;
+              if (isSplicedRecord(s)) continue;
               s.status = "pending";
               s.result = null;
             }
@@ -5675,6 +5955,8 @@ export async function waitForRun(
  */
 export function runResult(run: RunRecord): string | null {
   for (let i = run.steps.length - 1; i >= 0; i--) {
+    // A sandbox: own job's reply went to the step that asked (runSummary).
+    if (run.steps[i].subagentOf) continue;
     const r = run.steps[i].result;
     if (r && r.trim()) return r;
   }

package/src/scan.ts

@@ -133,7 +133,7 @@ export const SCAN_RULES: readonly ScanRule[] = [
     help:
       "An agent with all three can be told — by any page it reads — to send what it holds anywhere it can reach. " +
       "Take one leg away: take it off the open network (`network: { level: trusted, allow: [the sites it needs] }` — a bare list only adds sites, " +
-      "and an agent that reads the web stays open), split the reading and the sending into two agents, " +
+      "and an agent that reads the web stays open), split the reading and the sending into two agents (a step each, or a reader sub-agent with \`sandbox: own\`), " +
       "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
     owasp: ["ASI01", "ASI02", "ASI03"],
   },
@@ -147,6 +147,17 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "and if that rule ever changed, they would be a privilege escalation. Grant them to the parent or remove them.",
     owasp: ["ASI03"],
   },
+  {
+    id: "security/subagent-own-sandbox",
+    category: "security",
+    level: "info",
+    title: "A sub-agent works in its own sandbox, with tools its parent does not have",
+    help:
+      "`sandbox: own` on a sub-agent runs each job it is handed in a sandbox of its own, with its own tools, secrets and network — " +
+      "not cut to the parent's. That is the point (a reader with the web and no secrets, under a writer with secrets and no web), " +
+      "so this only says what it holds. Only its reply reaches the parent.",
+    owasp: ["ASI03"],
+  },
   {
     id: "supply-chain/pipe-to-shell",
     category: "supply-chain",
@@ -725,6 +736,13 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
       const sub = byName.get(s);
       if (!sub || s === a.name) continue;
       const extra = refNames(sub.data.tools).filter((t) => !tools.includes(t));
+      if (sub.data.sandbox === "own") {
+        if (extra.length) {
+          push("security/subagent-own-sandbox", a.file, keyLine(a.lines, "subagents"), `subagent ${s} own ${extra.join(",")}`,
+            `subagents: [${s}] — ${s} runs in its own sandbox with ${extra.join(", ")}, which ${a.name} does not have; only its reply comes back`);
+        }
+        continue;
+      }
       if (extra.length && tools.length) {
         push("security/subagent-wider", a.file, keyLine(a.lines, "subagents"), `subagent ${s} ${extra.join(",")}`,
           `subagents: [${s}] — ${s} declares ${extra.join(", ")}, which ${a.name} does not have; inside the delegation they are dropped`);

package/src/starter.ts

@@ -494,6 +494,7 @@ apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
 agents: [writer]            # colleagues this one may consult (an answer, no tools)
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
+sandbox: own                # delegated to: run each job in its own sandbox (own tools, secrets, network)
 secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
 limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
 network: [api.example.com]  # sites its sandbox may reach, added to the trusted list; open | trusted | none

package/src/store.ts

@@ -981,6 +981,8 @@ export interface AgentInfo {
   /** Colleagues this agent may DELEGATE to (`subagents:`) — each runs with
    *  its own context and its own tools, no wider than this agent's. */
   subagents: string[];
+  /** `sandbox: own` — delegated to, it runs each job in its own sandbox. */
+  sandbox?: "own";
   /** The `skills:` allowlist, or null when the field is absent — which is
    *  not the same thing: absent inherits every skill in scope, an empty
    *  list withholds all of them. */
@@ -1633,6 +1635,7 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         retiredTools: retiredToolNames(data),
         consults: refNames(data.agents),
         subagents: refNames(data.subagents),
+        ...(data.sandbox === "own" ? { sandbox: "own" as const } : {}),
         skills: data.skills === undefined ? null : refNames(data.skills),
         secrets: Array.isArray(data.secrets) ? data.secrets.map(String) : [],
         budget: runBudget(data.budget),
@@ -3294,6 +3297,17 @@ export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" |
 export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
 import { sumTokens, type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
 
+/** One job a step handed to an isolated sub-agent. `id` is the job's own
+ *  record's `delegation` — not an index, which moves when records are
+ *  spliced in before it. */
+export interface StepDelegation {
+  id: string;
+  agent: string;
+  status: "running" | "completed" | "failed" | "skipped";
+  costUsd?: number | null;
+  ms?: number | null;
+}
+
 /** The marker rescueStep puts in a rescue's instruction; how a rescue record
  *  written before `rescueOf` existed is still recognised. */
 export const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
@@ -3303,6 +3317,14 @@ export function isRescueRecord(step: { rescueOf?: string; instruction?: string |
   return !!step.rescueOf || (step.instruction ?? "").includes(RESCUE_MARKER);
 }
 
+/** Is this record put in by the runner rather than by the flow — an on-fail
+ *  rescue, or an isolated sub-agent's run (`subagentOf`)? Neither is launched
+ *  with a group, handed on as a group's output, reset by a loop, or copied by
+ *  a re-run as work. */
+export function isSplicedRecord(step: { rescueOf?: string; subagentOf?: string; instruction?: string | null }): boolean {
+  return !!step.subagentOf || isRescueRecord(step);
+}
+
 export interface StepRecord {
   agent: string;
   instruction: string;
@@ -3463,6 +3485,19 @@ export interface StepRecord {
    *  steps). Records written before this field are recognised by their
    *  instruction's `<rescue>` block instead — see isRescueRecord. */
   rescueOf?: string;
+  /** Set on an isolated sub-agent's run (`sandbox: own`, delegate-tools.ts):
+   *  the agent of the step that delegated to it. It ran in its own sandbox
+   *  inside that step; only its reply went back. Like a rescue it is not a
+   *  step of the flow — see isSplicedRecord. */
+  subagentOf?: string;
+  /** On an isolated sub-agent's run: its job's id, as the delegating step's
+   *  `delegations[].id` names it. */
+  delegation?: string;
+  /** On a step that delegated to isolated sub-agents: each job, in order. */
+  delegations?: StepDelegation[];
+  /** On an isolated sub-agent's run: the workspace paths its sandbox's
+   *  changes were applied to — what its delegating step is told it wrote. */
+  wrote?: string[];
   /**
    * Sandbox seconds this step rented, and how many of them were cold start.
    * Set only on the isolated path — an in-process step rents nothing, so
@@ -4254,6 +4289,9 @@ export function runVerdict(run: Pick<RunRecord, "verdict" | "summary">): Verdict
 
 export function runSummary(run: RunRecord): string | null {
   for (let i = run.steps.length - 1; i >= 0; i--) {
+    // A sandbox: own job is appended after every step of the flow; its reply
+    // went to the step that asked, which speaks for the run.
+    if (run.steps[i].subagentOf) continue;
     const line = stepHeadline(run.steps[i]);
     if (line) return line;
   }

package/src/subagents.ts

@@ -42,6 +42,25 @@ export interface SubagentSpec {
   model: string;
 }
 
+/** An isolated sub-agent (`sandbox: own` on its own agent.md): what the
+ *  parent's sandbox needs to offer it as a tool. Everything else — its tools,
+ *  secrets, network, size — is resolved on the worker when the job arrives,
+ *  from its own file, and never enters the parent's sandbox. */
+export interface DelegateSpec {
+  name: string;
+  description: string;
+}
+
+/** Does this agent run in its own sandbox when delegated to? */
+export function ownSandbox(front: { sandbox?: unknown }): boolean {
+  return front.sandbox === "own";
+}
+
+/** The tool the parent calls to hand an isolated sub-agent a job. */
+export function delegateToolName(agent: string): string {
+  return `delegate_${agent.replaceAll("-", "_")}`;
+}
+
 /** The SDK's delegation tool, under both names it has had. Never granted to a
  *  sub-agent: that is what makes the depth one. */
 export const DELEGATE_TOOLS = ["Agent", "Task"] as const;