@foldrun/core 2.6.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,
@@ -90,7 +94,7 @@ import {
 import { canReadBack } from "./tool-output.ts";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.ts";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf, type Catalog, type TokenPrice } from "./catalog.ts";
-import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.ts";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.ts";
 import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
@@ -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],
@@ -1485,7 +1546,8 @@ export function agentContext(
     // 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
@@ -1766,6 +1828,9 @@ export function agentContext(
     // 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,
@@ -2022,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
@@ -2042,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;
@@ -2515,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) {
@@ -2525,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
@@ -2686,17 +2786,57 @@ async function runStep(
         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.
@@ -2763,6 +2903,34 @@ async function runStep(
           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
@@ -2844,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,
@@ -3066,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) {
@@ -3110,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
@@ -3174,7 +3346,20 @@ async function runStep(
       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.
@@ -3194,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);
@@ -3235,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,
         },
@@ -3353,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 });
@@ -4038,7 +4243,14 @@ export function driveRun(
   opts: { parkOnApproval?: boolean; effortOverride?: string | null } = {},
 ): Promise<void> {
   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);
   });
 }
@@ -4187,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);
@@ -4324,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);
@@ -4735,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;
             }
@@ -4753,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();
@@ -4761,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]));
@@ -4904,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.
@@ -5027,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);
             }
@@ -5134,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;
@@ -5213,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;
             }
@@ -5607,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`);