@foldrun/core 2.7.0 → 2.8.0

package/dist/src/runner.js

@@ -6,6 +6,7 @@ import { latestRevisionId } from "./history.js";
 import { recordCallIo, redactionsFor } from "./capture.js";
 import { AUTH_REFUSAL } from "./issues.js";
 import { hookNames } from "./hooks.js";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -32,12 +33,13 @@ const isolatedRun = () => {
     return mode === "container" || (!!mode && mode in platform.isolation);
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.js";
-import { DELEGATE_TOOL, gatherSubagents, subagentPrompt, subagentTools } from "./subagents.js";
+import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools } from "./subagents.js";
+import { DELEGATE_SERVER, buildDelegateTools, delegatePromptLine, delegateToolNames, localDelegateChannel } from "./delegate-tools.js";
 import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool, buildPeerTools, inboxReader, localPeerBus, peersPromptLine } from "./operator.js";
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
-import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isRescueRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isSplicedRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { canReadBack } from "./tool-output.js";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
@@ -525,6 +527,10 @@ 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`);
@@ -556,6 +562,51 @@ 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) {
+    const out = [];
+    for (const sub of gatherSubagents(o.workspaceRoot, o.names).found) {
+        if (sub.name === o.self)
+            continue; // buildSubagentSpecs says so
+        let front;
+        try {
+            front = matter(fs.readFileSync(path.join(sub.dir, "agent.md"), "utf8")).data;
+        }
+        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, tenant) {
     const sections = [
         ["Everyone in this account", readAgentsMd(accountDir(tenant))?.body],
@@ -1852,7 +1903,11 @@ stepIndex,
 siblings = [], 
 /** The in-process colleagues' bus for this group (localPeerBus), when
  *  the step runs in this process rather than a pod. */
-peerBus) {
+peerBus, 
+/** 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) {
     // Secret values are injected into scripts as environment variables and
     // substituted into API headers, so a model that reads one back — from a
     // script that prints it, an API error that echoes it, or its own `env` —
@@ -1872,6 +1927,9 @@ peerBus) {
     let fileDir = null;
     let installDir = null;
     let disposeRuntime;
+    /** 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 = 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;
@@ -2323,8 +2381,13 @@ peerBus) {
         // 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) {
@@ -2334,6 +2397,34 @@ peerBus) {
             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) => {
+            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
         // and from this process.
@@ -2519,7 +2610,30 @@ peerBus) {
                 // 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.
@@ -2689,6 +2803,7 @@ peerBus) {
                     consults,
                     ...(peers ? { peers: { self: step.agent, siblings } } : {}),
                     ...(subagents.length ? { subagents } : {}),
+                    ...(delegates.length ? { delegates } : {}),
                     timeoutSec: step.timeout,
                     budgetUsd: stepBudgetUsd,
                     budgetNote: stepBudgetNote,
@@ -2905,6 +3020,8 @@ peerBus) {
             // 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) {
@@ -2952,6 +3069,8 @@ peerBus) {
                     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
@@ -3045,6 +3164,16 @@ peerBus) {
             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);
@@ -3086,6 +3215,7 @@ peerBus) {
                     ...(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,
                 },
@@ -3209,6 +3339,16 @@ peerBus) {
         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)
@@ -4014,6 +4154,32 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
             // 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;
@@ -4158,7 +4324,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
             // 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) => group.filter((s) => !isRescueRecord(s));
+            const flowStepsOf = (group) => group.filter((s) => !isSplicedRecord(s));
             const dataOf = (all) => {
                 const group = flowStepsOf(all);
                 const carrying = group.filter((s) => s.status === "completed" && s.data !== undefined);
@@ -4557,7 +4723,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     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;
                         }
@@ -4574,13 +4740,119 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // 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();
                 const siblingsOf = (step) => 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) => async (agent, job, cancelled) => {
+                    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 = {
+                        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 = { 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 = 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]));
@@ -4700,7 +4972,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         () => {
                             save();
                             return run.stopRequested === true;
-                        }, flowTimezone, run.steps.indexOf(step), siblingsOf(step), peerBus).finally(() => reserved.delete(step));
+                        }, flowTimezone, 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.
                         const outcome = step.status;
@@ -4826,8 +5098,10 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     // answered an earlier failure — an evaluator loop's previous cycle
                     // — not this one.
                     const leftovers = [];
-                    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);
                         }
@@ -4935,7 +5209,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // 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;
@@ -5014,7 +5288,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             // 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))
+                            if (isSplicedRecord(s))
                                 continue;
                             s.status = "pending";
                             s.result = null;
@@ -5360,6 +5634,9 @@ export async function waitForRun(tenant, workspace, runId, timeoutMs = 5 * 60_00
  */
 export function runResult(run) {
     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/dist/src/scan.js

@@ -77,7 +77,7 @@ export const SCAN_RULES = [
         title: "Reads untrusted content, holds private data and can send it out",
         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"],
     },
@@ -90,6 +90,16 @@ export const SCAN_RULES = [
             "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",
@@ -650,6 +660,12 @@ function scanAgents(agents, outward, toolDefs, push, networks) {
             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/dist/src/starter.js

@@ -478,6 +478,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/dist/src/store.d.ts

@@ -311,6 +311,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. */
@@ -1068,6 +1070,16 @@ export interface StepAttempt {
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
 export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
 import { 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 declare const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
@@ -1076,6 +1088,15 @@ export declare function isRescueRecord(step: {
     rescueOf?: string;
     instruction?: string | null;
 }): boolean;
+/** 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 declare function isSplicedRecord(step: {
+    rescueOf?: string;
+    subagentOf?: string;
+    instruction?: string | null;
+}): boolean;
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1242,6 +1263,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

package/dist/src/store.js

@@ -1163,6 +1163,7 @@ export function listAgents(tenant, workspace) {
             retiredTools: retiredToolNames(data),
             consults: refNames(data.agents),
             subagents: refNames(data.subagents),
+            ...(data.sandbox === "own" ? { sandbox: "own" } : {}),
             skills: data.skills === undefined ? null : refNames(data.skills),
             secrets: Array.isArray(data.secrets) ? data.secrets.map(String) : [],
             budget: runBudget(data.budget),
@@ -2662,6 +2663,13 @@ export const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
 export function isRescueRecord(step) {
     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) {
+    return !!step.subagentOf || isRescueRecord(step);
+}
 // ---------------------------------------------------------------- captured calls
 //
 // What each tool call took and gave (FOL-54 step 4), beside the run under
@@ -3218,6 +3226,10 @@ export function runVerdict(run) {
 }
 export function runSummary(run) {
     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/dist/src/subagents.d.ts

@@ -10,6 +10,20 @@ export interface SubagentSpec {
      *  the step's own) or "inherit". */
     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 declare function ownSandbox(front: {
+    sandbox?: unknown;
+}): boolean;
+/** The tool the parent calls to hand an isolated sub-agent a job. */
+export declare function delegateToolName(agent: string): string;
 /** 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 declare const DELEGATE_TOOLS: readonly ["Agent", "Task"];