@foldrun/core 2.6.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,16 +33,17 @@ 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";
-import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.js";
 import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.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],
@@ -1348,7 +1399,8 @@ grantsOnly = false) {
     // the agent, and the date the platform believes it is.
     {
         ...runtime.env,
-        ...secretEnv,
+        // An unexported client certificate is the proxy's, never a script's.
+        ...withoutHeldCerts(secretEnv),
         ...(identity.runId ? { FOLDRUN_RUN_ID: identity.runId } : {}),
         ...(identity.agent ? { FOLDRUN_AGENT: identity.agent } : {}),
         // And the workspace: a commit or a record made by a shared library
@@ -1618,6 +1670,9 @@ grantsOnly = false) {
         // asked for by name fails inside the container with "cannot find" while
         // the host path, which uses this same merged spec, works fine.
         runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec, dispose: runtime.dispose },
+        // Whole: a bound client certificate goes from here into the egress
+        // grant (runStep), which is where it is presented. Programs get theirs
+        // filtered (withoutHeldCerts) where their environments are built.
         secretEnv: { ...runtime.env, ...secretEnv },
         formatWarning: checkFormatVersion(workspaceFrontmatter(agentDir, tenant).foldrun_version).warning,
         providerEnv,
@@ -1848,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` —
@@ -1868,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;
@@ -2319,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) {
@@ -2330,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.
@@ -2490,17 +2585,55 @@ peerBus) {
             // to refuse; the proxy adds the install's own switch and has the last
             // word (egress-proxy.ts), so false here never loosens anything.
             grant.enforce = networkEnforceWanted(readAgentsMd(accountDir(tenant))?.data?.network_enforce, readAgentsMd(workspaceRootOf(agentDir))?.data?.network_enforce);
+            // Keyless cloud identities the step declared: the proxy may mint tokens
+            // for these audiences only, for this workload (oidc-issuer.ts).
+            // A test run withholds them as it withholds every credential
+            // (test-mode.ts): a token is a credential, however it is delivered.
+            const declaredIdentities = Object.entries(liveSecrets).filter(([, v]) => typeof v === "string" && isIdentityValue(v));
+            const identitiesHeld = testRun
+                ? withholdSecrets(Object.fromEntries(declaredIdentities), {
+                    outward: scriptSpecs.some((sc) => sc.outward),
+                    allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
+                }).withheld
+                : [];
+            const identities = Object.fromEntries(declaredIdentities.filter(([name]) => !identitiesHeld.includes(name)).map(([name, v]) => [name, { audience: identityOf(v).audience }]));
+            if (Object.keys(identities).length)
+                grant.identities = identities;
             const lease = await platform.egress.lease({
                 tenant,
                 runId: runId ?? "adhoc",
                 grant,
                 test: testRun,
+                who: { workspace: workspaceName, agent: step.agent },
                 ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}),
                 // tools: [peers] — the roster the proxy serves, and the inboxes a
                 // 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.
@@ -2565,6 +2698,38 @@ peerBus) {
                     push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
                 }
             }
+            // A keyless identity holds nothing to hand over: the sandbox gets the
+            // path of a token file the driver keeps fresh through the proxy's
+            // /identity door. Without a lease there is no door, and so no token.
+            const identityDeclared = declared.filter((name) => typeof liveSecrets[name] === "string" && isIdentityValue(liveSecrets[name]));
+            for (const name of identityDeclared)
+                delete sandboxSecrets[name];
+            for (const name of identitiesHeld) {
+                push("info", `test: ${name} withheld — no identity token on a test run`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
+            }
+            const identityNames = identityDeclared.filter((name) => !identitiesHeld.includes(name));
+            if (identityNames.length) {
+                if (lease) {
+                    const dir = "/tmp/foldrun-identity";
+                    sandboxSecrets.FOLDRUN_IDENTITIES = identityNames.join(",");
+                    sandboxSecrets.FOLDRUN_IDENTITY_DIR = dir;
+                    for (const name of identityNames)
+                        sandboxSecrets[`${name}_FILE`] = `${dir}/${name.toLowerCase()}.jwt`;
+                    push("info", `identity: ${identityNames.join(", ")} — a short-lived token in $NAME_FILE, renewed by the platform while the step runs`);
+                }
+                else {
+                    push("error", `identity: ${identityNames.join(", ")} needs a sandboxed step on the platform — no token here`);
+                }
+            }
+            // A client certificate is the proxy's to present, to the exact sites it
+            // is bound to; never the sandbox's, unless it was saved with `export`.
+            for (const name of declared) {
+                const v = liveSecrets[name];
+                if (typeof v !== "string" || !isClientCertValue(v) || bound.includes(name) || clientCertOf(v).export)
+                    continue;
+                delete sandboxSecrets[name];
+                push("info", `secrets: ${name} is a client certificate — the egress proxy presents it to the sites it is bound to (\`foldrun secrets sites ${name} <host>\`); unbound, it stays out of the sandbox`);
+            }
             // On a test run the http tools always go through the proxy as
             // placeholders, even when a script made the step materialise: the
             // proxy is where the outward-write policy lives, and a header
@@ -2638,6 +2803,7 @@ peerBus) {
                     consults,
                     ...(peers ? { peers: { self: step.agent, siblings } } : {}),
                     ...(subagents.length ? { subagents } : {}),
+                    ...(delegates.length ? { delegates } : {}),
                     timeoutSec: step.timeout,
                     budgetUsd: stepBudgetUsd,
                     budgetNote: stepBudgetNote,
@@ -2854,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) {
@@ -2901,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
@@ -2966,7 +3136,19 @@ peerBus) {
             for (const name of held.withheld) {
                 push("info", `test: ${name} withheld from scripts — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from scripts` } });
             }
-            const stepSecrets = held.env;
+            // A client certificate not saved with `export` has no proxy here to
+            // present it: it stays out of everything this step runs — tools,
+            // consults, verify commands — not only out of the files.
+            const stepSecrets = Object.fromEntries(Object.entries(held.env).filter(([name, v]) => {
+                if (typeof v === "string" && isIdentityValue(v)) {
+                    push("error", `identity: ${name} needs a sandboxed step on the platform — no token here`);
+                    return false;
+                }
+                if (typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export)
+                    return true;
+                push("info", `secrets: ${name} is a client certificate — no egress proxy here to present it; save it with export to use it as files`);
+                return false;
+            }));
             // The model credential for this machine's Claude Code — the agent's
             // own provider when it names one. The host allowlist drops it, so
             // without this every in-process step ran on the machine's login.
@@ -2982,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);
@@ -3023,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,
                 },
@@ -3146,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)
@@ -3804,7 +4007,15 @@ async function harvestQuietly(tenant, workspace, run) {
 export const drivingRuns = new Set();
 export function driveRun(tenant, workspace, run, modelOverride, tags = [], opts = {}) {
     drivingRuns.add(run.id);
+    // The run's egress leases are renewed while it is driven, by whichever
+    // door drove it — the queue, or a reconcile that picked it back up — so an
+    // identity token is renewed for a live step however it was started.
+    const renew = platform.egress.renew;
+    const beat = renew ? setInterval(() => void renew(run.id).catch(() => undefined), 5 * 60_000) : null;
+    beat?.unref?.();
     return driveRunInner(tenant, workspace, run, modelOverride, tags, opts).finally(() => {
+        if (beat)
+            clearInterval(beat);
         drivingRuns.delete(run.id);
     });
 }
@@ -3943,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;
@@ -4087,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);
@@ -4486,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;
                         }
@@ -4503,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]));
@@ -4629,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;
@@ -4755,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);
                         }
@@ -4864,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;
@@ -4943,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;
@@ -5289,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`);
             }