@bastani/atomic 0.9.14 → 0.9.15-alpha.1

package/dist/builtin/subagents/src/runs/foreground/subagent-executor.ts

@@ -24,8 +24,6 @@ import {
 	DEFAULT_ARTIFACT_CONFIG,
 	getCurrentSubagentDepth,
 	isWorkflowStageOrchestrationContext,
-	resolveChildMaxSubagentDepth,
-	resolveWorkflowStageMaxSubagentDepth,
 	type SingleResult,
 	SUBAGENT_ACTIONS,
 	type SubagentToolResult,
@@ -39,7 +37,7 @@ import {
 import { inheritedIntercomGroup } from "../shared/intercom-group.js";
 import { currentModelFullId } from "../shared/model-fallback.js";
 import { resolveControlConfig } from "../shared/subagent-control.js";
-import { checkDepthForExecution, prepareExecutionContext } from "./subagent-executor-context.js";
+import { prepareExecutionContext, refuseSubagentChildDelegation } from "./subagent-executor-context.js";
 import { toExecutionErrorResult, withForkContext } from "./subagent-executor-input.js";
 import { runParallelPath } from "./subagent-executor-parallel.js";
 import { resolveRequestedCwd } from "./subagent-executor-resume.js";
@@ -132,12 +130,6 @@ async function resumeRetainedForegroundChild(
 			artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 			artifactConfig,
 			maxOutput: params.maxOutput,
-			maxSubagentDepth:
-				child.maxSubagentDepth ??
-				resolveChildMaxSubagentDepth(
-					resolveWorkflowStageMaxSubagentDepth(ctx, deps.config.maxSubagentDepth),
-					agentConfig.maxSubagentDepth,
-				),
 			parentDepth: getCurrentSubagentDepth(ctx),
 			workflowStageSubagentGuard: isWorkflowStageOrchestrationContext(ctx),
 			workflowSessionMetadata: workflowSessionMetadataFromContext(ctx),
@@ -234,6 +226,12 @@ async function handleManagementRequest(input: {
 			details: { mode: "management" as const, results: [] },
 		};
 	}
+	// Delegation is one level deep: a session admitted as a subagent child may
+	// never start or continue another agent, whatever else it is authorized for.
+	if (!READ_ONLY_MANAGEMENT_ACTIONS.has(action)) {
+		const childRefusal = refuseSubagentChildDelegation(ctx, "management");
+		if (childRefusal) return childRefusal;
+	}
 	if (action === "doctor") {
 		let currentSessionFile: string | null = null;
 		let currentSessionId = deps.state.currentSessionId;
@@ -388,32 +386,23 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 			};
 		}
 
-		const depthError = checkDepthForExecution(ctx, deps);
-		if (depthError) return depthError;
+		const childRefusal = refuseSubagentChildDelegation(ctx, inferExecutionMode(params));
+		if (childRefusal) return childRefusal;
 
 		const built = prepareExecutionContext({ params: paramsWithResolvedCwd, ctx, signal, onUpdate, deps });
 		if (built.error) return built.error;
 		const prepared = built.prepared!;
-		let nestedForegroundStarted = false;
 		try {
-			if (prepared.foregroundControl) {
-				prepared.writeNestedForegroundEvent("subagent.nested.started");
-				nestedForegroundStarted = true;
-			}
 			if (prepared.hasTasks && prepared.effectiveParams.tasks) {
 				const result = await runParallelPath(prepared.execData, deps);
-				prepared.writeNestedForegroundEvent("subagent.nested.completed", result);
 				return withForkContext(result, prepared.effectiveParams.context);
 			}
 			if (prepared.hasSingle) {
 				const result = await runSinglePath(prepared.execData, deps);
-				prepared.writeNestedForegroundEvent("subagent.nested.completed", result);
 				return withForkContext(result, prepared.effectiveParams.context);
 			}
 		} catch (error) {
-			const errorResult = toExecutionErrorResult(prepared.effectiveParams, error);
-			if (nestedForegroundStarted) prepared.writeNestedForegroundEvent("subagent.nested.completed", errorResult);
-			return errorResult;
+			return toExecutionErrorResult(prepared.effectiveParams, error);
 		} finally {
 			if (prepared.foregroundControl) {
 				clearPendingForegroundControlNotices(deps.state, prepared.runId);

package/dist/builtin/subagents/src/runs/inprocess/attempt-handles.ts

@@ -0,0 +1,104 @@
+/**
+ * In-process attempt handles for a top-level session's direct children.
+ *
+ * Delegation is one level deep, so this registry only ever holds a parent's own
+ * children. A live child is addressed by its run id or canonical task path, and
+ * interrupt/resume reach it through the handle registered when its attempt
+ * started — never through a request file, a capability token, or a poller.
+ */
+
+export interface InProcessAttemptResumeOutcome {
+	readonly status: "ok" | "error" | "interrupted" | "continued";
+	readonly path: string;
+	readonly sessionFile?: string;
+	readonly envelope?: string;
+}
+
+export interface InProcessAttemptHandle {
+	readonly runId: string;
+	readonly path: string;
+	readonly status: () => string;
+	readonly interrupt: () => Promise<void>;
+	readonly resume: (message: string) => Promise<InProcessAttemptResumeOutcome>;
+}
+
+export interface InProcessAttemptControlResult {
+	readonly ok: boolean;
+	readonly message: string;
+	readonly outcome?: InProcessAttemptResumeOutcome;
+}
+
+const attemptHandles = new Map<string, Map<string, InProcessAttemptHandle>>();
+
+function attemptKey(id: string): string {
+	return id.trim();
+}
+
+export function registerInProcessAttempt(handle: InProcessAttemptHandle): () => void {
+	const key = attemptKey(handle.runId);
+	let handles = attemptHandles.get(key);
+	if (!handles) {
+		handles = new Map();
+		attemptHandles.set(key, handles);
+	}
+	handles.set(handle.path, handle);
+	const pathKey = attemptKey(handle.path);
+	if (pathKey !== key) {
+		let byPath = attemptHandles.get(pathKey);
+		if (!byPath) {
+			byPath = new Map();
+			attemptHandles.set(pathKey, byPath);
+		}
+		byPath.set(handle.path, handle);
+	}
+	return () => {
+		for (const lookupKey of [key, pathKey]) {
+			const current = attemptHandles.get(lookupKey);
+			if (!current || current.get(handle.path) !== handle) continue;
+			current.delete(handle.path);
+			if (current.size === 0) attemptHandles.delete(lookupKey);
+		}
+	};
+}
+
+function handlesFor(id: string): InProcessAttemptHandle[] {
+	return [...(attemptHandles.get(attemptKey(id))?.values() ?? [])];
+}
+
+export async function interruptInProcessAttempt(targetId: string): Promise<InProcessAttemptControlResult | undefined> {
+	const handles = handlesFor(targetId);
+	if (handles.length === 0) return undefined;
+	const active = handles.filter((handle) => handle.status() === "running" || handle.status() === "continued");
+	if (active.length === 0) {
+		return { ok: false, message: `Run ${targetId} has no active child attempt to interrupt.` };
+	}
+	await Promise.all(active.map((handle) => handle.interrupt()));
+	return { ok: true, message: `Interrupt requested for run ${targetId}.` };
+}
+
+export async function resumeInProcessAttempt(
+	targetId: string,
+	message: string,
+): Promise<InProcessAttemptControlResult | undefined> {
+	const handles = handlesFor(targetId);
+	if (handles.length === 0) return undefined;
+	const handle =
+		handles.find((candidate) => candidate.status() === "interrupted" || candidate.status() === "error") ?? handles[0];
+	if (!handle) return undefined;
+	if (handle.status() === "running" || handle.status() === "continued") {
+		return { ok: false, message: `Run ${targetId} is still running; resume is not required.` };
+	}
+	const outcome = await handle.resume(message);
+	return {
+		ok: outcome.status === "ok" || outcome.status === "continued",
+		message:
+			outcome.status === "ok"
+				? `Reloaded run ${targetId} through the in-process control plane.`
+				: `Run ${targetId} resume ended with status '${outcome.status}'.`,
+		outcome,
+	};
+}
+
+export function clearInProcessAttemptHandles(): void {
+	attemptHandles.clear();
+}

package/dist/builtin/subagents/src/runs/inprocess/index.ts

@@ -1,20 +1,14 @@
+export type {
+	InProcessAttemptControlResult,
+	InProcessAttemptHandle,
+	InProcessAttemptResumeOutcome,
+} from "./attempt-handles.js";
 export {
-	appendInProcessControlRequest,
-	appendInProcessControlResult,
-	appendInProcessNestedEvent,
-	clearInProcessNestedRouting,
-	hasInProcessNestedRoute,
-	interruptInProcessNestedAttempt,
-	readInProcessControlRequests,
-	readInProcessControlResults,
-	readInProcessNestedEvents,
-	registerInProcessNestedAttempt,
-	registerInProcessNestedRoute,
-	removeInProcessControlRequest,
-	resumeInProcessNestedAttempt,
-	subscribeInProcessControlRequests,
-	unregisterInProcessNestedRoute,
-} from "./nested-routing.js";
+	clearInProcessAttemptHandles,
+	interruptInProcessAttempt,
+	registerInProcessAttempt,
+	resumeInProcessAttempt,
+} from "./attempt-handles.js";
 export type {
 	AdmissionRefusal,
 	AdmittedResult,
@@ -25,11 +19,6 @@ export type {
 	ChildSpec,
 	ChildStatus,
 	ContinuationReason,
-	InProcessControlRequest,
-	InProcessControlResult,
-	InProcessNestedAttemptHandle,
-	InProcessNestedResumeOutcome,
-	InProcessNestedRouteKey,
 	ModelCandidate,
 	ParentContext,
 	ResultEnvelope,

package/dist/builtin/subagents/src/runs/inprocess/prompt-behavior.ts

@@ -11,9 +11,8 @@ export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
 	"You are a child subagent with explicit fanout responsibility for this assigned task.",
 	"The parent session owns final orchestration, completion decisions, and follow-up implementation launches.",
-	"You may use the `subagent` tool only for the fanout work explicitly requested in this task.",
-	"Do not broaden yourself into general parent orchestration. Do not launch follow-up workers unless the task explicitly asks for that.",
-	"The maxSubagentDepth cap still applies and may block further fanout.",
+	"Delegation is one level deep: the `subagent` tool refuses every launch, resume, and interrupt from inside a subagent.",
+	"Do the assigned fanout work yourself and report what you found; do not plan around delegating it.",
 	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
 ].join("\n");
 

package/dist/builtin/subagents/src/runs/inprocess/runner.ts

@@ -23,7 +23,7 @@ import {
 	type TerminationCause as NativeTerminationCause,
 	SubagentControl,
 } from "@bastani/atomic-natives";
-import type { Api, Model } from "@earendil-works/pi-ai/compat";
+import type { Api, Model } from "@bastani/pi-ai/compat";
 import type { AgentConfig } from "../../agents/agent-types.js";
 import {
 	buildSkillInjection,
@@ -43,11 +43,10 @@ import {
 	type ArtifactPaths,
 	DEFAULT_MAX_OUTPUT,
 	type MaxOutputConfig,
-	normalizeMaxSubagentDepth,
 	truncateOutput,
 } from "../../shared/types.js";
+import { type InProcessAttemptResumeOutcome, registerInProcessAttempt } from "./attempt-handles.js";
 import { type ChildModePolicy, resolveChildModePolicy } from "./child-policy.js";
-import { type InProcessNestedResumeOutcome, registerInProcessNestedAttempt } from "./nested-routing.js";
 import { createInProcessChildPromptBehavior, createInProcessChildSystemPromptTransform } from "./prompt-behavior.js";
 
 export type ChildStatus = NativeAgentStatus;
@@ -99,12 +98,6 @@ export interface ChildSpec {
 	/** Typed identity/capability resolved by the parent before admission. */
 	readonly intercom?: SubagentIntercomIdentity;
 	readonly sessionFile?: string;
-	/**
-	 * Effective delegation limit for this child, already narrowed by the parent's
-	 * limit and the child agent's own `maxSubagentDepth`. Retained on the spec so
-	 * a cold reload reissues the same limit.
-	 */
-	readonly maxSubagentDepth?: number;
 	readonly testSession?: boolean | TestSessionOptions;
 	readonly artifactJsonlPath?: string;
 	/**
@@ -316,16 +309,6 @@ function workflowMetadataFromContext(
 	};
 }
 
-/**
- * Effective delegation limit for an admitted child. A caller that already
- * narrowed the parent's limit against the agent definition puts the result on
- * the spec; a caller admitting a child directly still gets the agent's own
- * declared limit rather than an unbounded policy.
- */
-export function effectiveChildMaxSubagentDepth(spec: ChildSpec): number | undefined {
-	return spec.maxSubagentDepth ?? normalizeMaxSubagentDepth(spec.agent.maxSubagentDepth);
-}
-
 /**
  * In-process children must load the same bundled extensions as the host.
  * Workflow extensions are disabled inside workflow-owned sessions because their
@@ -618,8 +601,9 @@ function writeEvent(pathValue: string | undefined, event: AgentSessionEvent): vo
 
 /**
  * A child identity whose constructor is private. Depth and path validation happen
- * at the Rust admission door, so callers cannot manufacture an admitted depth-6
- * child or bypass canonical identity allocation.
+ * at the Rust admission door, so callers cannot manufacture an admitted child
+ * below the single permitted delegation level or bypass canonical identity
+ * allocation.
  */
 interface AdmittedChildInput {
 	readonly identity: ChildIdentity;
@@ -655,7 +639,7 @@ export class AdmittedChild {
 	}
 
 	static create(input: AdmittedChildInput): AdmittedChild {
-		if (input.identity.depth > 5) throw new Error("child depth exceeds maximum 5");
+		if (input.identity.depth > 1) throw new Error("child depth exceeds maximum 1");
 		validatePath(input.identity.path);
 		return new AdmittedChild(input);
 	}
@@ -747,9 +731,6 @@ export class SubagentControlRuntime {
 					intercomGroup: parent.intercomGroup,
 					intercom: spec.intercom,
 					depth: identity.depth,
-					...(effectiveChildMaxSubagentDepth(spec) === undefined
-						? {}
-						: { maxSubagentDepth: effectiveChildMaxSubagentDepth(spec) }),
 				},
 				sessionDir,
 				sessionFile: spec.sessionFile,
@@ -1228,16 +1209,17 @@ export class SubagentControlRuntime {
 		};
 	}
 
-	registerNestedAttempt(runId: string, running: RunningAttempt, candidate: ModelCandidate): void {
-		registerInProcessNestedAttempt({
+	/** Expose a direct child's live attempt so `interrupt`/`resume` can reach it by run id or path. */
+	registerAttempt(runId: string, running: RunningAttempt, candidate: ModelCandidate): void {
+		registerInProcessAttempt({
 			runId,
 			path: running.child.identity.path,
 			status: () => running.status,
 			interrupt: () => this.terminateChildAttempt(running, "interrupt"),
-			resume: async (message): Promise<InProcessNestedResumeOutcome> => {
+			resume: async (message): Promise<InProcessAttemptResumeOutcome> => {
 				const admission = this.reloadColdChild(running.child.identity.path, message);
 				if (!admission.admitted) {
-					throw new Error(admission.refusal?.reason ?? "nested child cold reload was refused");
+					throw new Error(admission.refusal?.reason ?? "child cold reload was refused");
 				}
 				const neverAbort = new AbortController().signal;
 				const resumed = this.startAttempt(admission.admitted, candidate, {
@@ -1344,9 +1326,6 @@ export class SubagentControlRuntime {
 			thinkingLevel: spec.thinkingLevel ?? (spec.agent.thinking as ChildPolicy["thinkingLevel"]),
 			intercomGroup: spec.parent?.intercomGroup,
 			depth,
-			...(effectiveChildMaxSubagentDepth(spec) === undefined
-				? {}
-				: { maxSubagentDepth: effectiveChildMaxSubagentDepth(spec) }),
 		};
 	}
 

package/dist/builtin/subagents/src/runs/inprocess/runtime-support/temp-cleanup.ts

@@ -0,0 +1,69 @@
+/**
+ * Startup housekeeping for the subagent runtime temp root.
+ *
+ * The multi-level route/event pipeline that once wrote into this directory is
+ * gone, so nothing creates entries here any more. The scanner stays because
+ * users' machines still hold directories written by earlier versions, and
+ * nothing else would ever reap them.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TEMP_ROOT_DIR } from "../../../shared/types.js";
+
+/**
+ * Historical directory name. It must keep matching what earlier versions wrote,
+ * or their leftovers become unreachable garbage.
+ */
+export const SUBAGENT_RUNTIME_TEMP_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
+
+/** Whether any entry in the tree rooted at filePath has an mtime at or after cutoff, stopping at the first hit. */
+export function hasEntryNewerThan(filePath: string, cutoff: number): boolean {
+	const stat = fs.statSync(filePath);
+	if (stat.mtimeMs >= cutoff) return true;
+	if (!stat.isDirectory()) return false;
+	return directoryHasEntryNewerThan(filePath, cutoff);
+}
+
+function directoryHasEntryNewerThan(dirPath: string, cutoff: number): boolean {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(dirPath);
+	} catch {
+		return false;
+	}
+	for (const entry of entries) {
+		const childPath = path.join(dirPath, entry);
+		try {
+			const stat = fs.statSync(childPath);
+			if (stat.mtimeMs >= cutoff) return true;
+			if (stat.isDirectory() && directoryHasEntryNewerThan(childPath, cutoff)) return true;
+		} catch {
+			// Runtime cleanup is best-effort housekeeping.
+		}
+	}
+	return false;
+}
+
+function cleanupOldSubdirectories(root: string, maxAgeDays: number): void {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+	const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+	for (const entry of entries) {
+		const entryPath = path.join(root, entry);
+		try {
+			if (!hasEntryNewerThan(entryPath, cutoff)) fs.rmSync(entryPath, { recursive: true, force: true });
+		} catch {
+			// Keep startup resilient if a child process removes or rewrites an entry while scanning.
+		}
+	}
+}
+
+export function cleanupOldSubagentRuntimeDirs(maxAgeDays: number): void {
+	cleanupOldSubdirectories(SUBAGENT_RUNTIME_TEMP_DIR, maxAgeDays);
+}

package/dist/builtin/subagents/src/shared/model-resolution.ts

@@ -15,7 +15,7 @@
  * string means.
  */
 
-import type { Api, Model } from "@earendil-works/pi-ai/compat";
+import type { Api, Model } from "@bastani/pi-ai/compat";
 import { splitKnownThinkingSuffix, THINKING_LEVELS, type ThinkingLevel } from "./model-info.js";
 
 /** Registry surface needed to resolve a candidate; satisfied by `ctx.modelRegistry`. */

package/dist/builtin/subagents/src/shared/types-config.ts

@@ -5,7 +5,6 @@
 import type { AgentSessionEvent, SessionWorkflowMetadata } from "@bastani/atomic";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { CandidateModelResolver } from "./model-resolution.js";
-import type { NestedRouteInfo } from "./types-nested.js";
 import type {
 	ArtifactConfig,
 	ControlConfig,
@@ -88,12 +87,10 @@ export interface RunSyncOptions {
 	share?: boolean;
 	outputPath?: string;
 	outputMode?: OutputMode;
-	maxSubagentDepth?: number;
 	/** Current session depth passed to the in-process admission door. */
 	parentDepth?: number;
 	workflowStageSubagentGuard?: boolean;
 	workflowSessionMetadata?: SessionWorkflowMetadata;
-	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
 	/** Registry models available for heuristic bare-model resolution */
@@ -160,7 +157,6 @@ interface TopLevelParallelConfig {
 
 export interface ExtensionConfig {
 	defaultSessionDir?: string;
-	maxSubagentDepth?: number;
 	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
 	worktreeSetupHook?: string;

package/dist/builtin/subagents/src/shared/types-depth.ts

@@ -1,42 +1,15 @@
 /**
- * Recursion-depth guard helpers for nested subagent execution.
+ * Delegation boundary helpers.
+ *
+ * Delegation is exactly one level deep and is not configurable: a top-level
+ * session (main chat or a workflow stage) may call the `subagent` tool, and the
+ * children it admits may not.
  */
 
 import type { ExtensionContext, SessionWorkflowMetadata } from "@bastani/atomic";
-import { DEFAULT_SUBAGENT_MAX_DEPTH, MAX_SUBAGENT_NESTING_DEPTH } from "./types-runtime.js";
 
 // Depth is admission state carried in the typed child policy, not process environment.
 
-// ============================================================================
-export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
-	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
-	if (!Number.isInteger(parsed) || parsed < 0) return undefined;
-	return Math.min(parsed, MAX_SUBAGENT_NESTING_DEPTH);
-}
-
-/**
- * The effective limit is the stricter of the local configuration and any limit
- * inherited through the child policy, both clamped by the global ceiling.
- */
-export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number, inheritedMaxDepth?: number): number {
-	const local = normalizeMaxSubagentDepth(configMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
-	const inherited = normalizeMaxSubagentDepth(inheritedMaxDepth);
-	return inherited === undefined ? local : Math.min(local, inherited);
-}
-
-/** Read the delegation limit a parent admission issued to this child session. */
-export function getInheritedMaxSubagentDepth(
-	ctx: Partial<Pick<ExtensionContext, "subagentPolicy">>,
-): number | undefined {
-	return ctx.subagentPolicy?.maxSubagentDepth;
-}
-
-export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDepth?: number): number {
-	const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
-	const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
-	return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
-}
-
 export function isWorkflowStageOrchestrationContext(ctx: Pick<ExtensionContext, "orchestrationContext">): boolean {
 	return ctx.orchestrationContext?.kind === "workflow-stage";
 }
@@ -53,82 +26,21 @@ export function workflowSessionMetadataFromContext(
 	};
 }
 
-export function resolveWorkflowStageMaxSubagentDepth(
-	ctx: Pick<ExtensionContext, "orchestrationContext"> & Partial<Pick<ExtensionContext, "subagentPolicy">>,
-	configMaxDepth?: number,
-): number {
-	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth, getInheritedMaxSubagentDepth(ctx));
-	return isWorkflowStageOrchestrationContext(ctx)
-		? // Workflow stages receive an explicit host constraint, clamped by the
-			// inherited/global nesting ceiling. A 0-depth workflow constraint still
-			// preserves one child-subagent hop so configured stages can delegate once.
-			Math.min(maxDepth, Math.max(1, ctx.orchestrationContext?.constraints.maxSubagentDepth ?? 1))
-		: maxDepth;
-}
-
-export interface SubagentDepthPolicy {
-	maxSubagentDepth: number;
-	workflowStageSubagentGuard: boolean;
-}
-
-export function resolveSubagentDepthPolicy(
-	ctx: Pick<ExtensionContext, "orchestrationContext"> & Partial<Pick<ExtensionContext, "subagentPolicy">>,
-	configMaxDepth?: number,
-): SubagentDepthPolicy {
-	return {
-		maxSubagentDepth: resolveWorkflowStageMaxSubagentDepth(ctx, configMaxDepth),
-		workflowStageSubagentGuard: isWorkflowStageOrchestrationContext(ctx),
-	};
-}
-
-function workflowStageSubagentDepthMessage(
-	depth: number,
-	maxDepth: number,
-	action: "call" | "resume" = "call",
-): string {
-	return `Nested subagent ${action} blocked (depth=${depth}, max=${maxDepth}). Sub-agents inside workflow stages are running at the maximum nesting depth.`;
-}
-
-export function subagentDepthBlockedMessage(
-	depth: number,
-	maxDepth: number,
-	options?: { action?: "call" | "resume"; workflowStageGuard?: boolean },
-): string {
-	const action = options?.action ?? "call";
-	if (options?.workflowStageGuard) {
-		return workflowStageSubagentDepthMessage(depth, maxDepth, action);
-	}
-	if (action === "resume") {
-		return `Nested subagent resume blocked (depth=${depth}, max=${maxDepth}). Complete the follow-up directly instead.`;
-	}
-	return (
-		`Nested subagent call blocked (depth=${depth}, max=${maxDepth}). ` +
-		"You are running at the maximum subagent nesting depth. " +
-		"Complete your current task directly without delegating to further subagents."
-	);
-}
-
-export interface SubagentDepthCheck {
-	blocked: boolean;
-	depth: number;
-	maxDepth: number;
-}
-
 /** Read the admitted depth carried by an in-process child session. */
 export function getCurrentSubagentDepth(ctx: Pick<ExtensionContext, "subagentPolicy">): number {
 	const depth = ctx.subagentPolicy?.depth;
 	return typeof depth === "number" && Number.isInteger(depth) && depth >= 0 ? depth : 0;
 }
 
-export function checkSubagentDepth(
-	ctx: Pick<ExtensionContext, "subagentPolicy">,
-	configMaxDepth?: number,
-): SubagentDepthCheck {
-	const depth = getCurrentSubagentDepth(ctx);
-	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth, getInheritedMaxSubagentDepth(ctx));
-	return { blocked: Number.isFinite(depth) && depth >= maxDepth, depth, maxDepth };
+/**
+ * True when this session was itself admitted as a subagent child. Such a session
+ * may never delegate further, regardless of any other capability it carries.
+ */
+export function isSubagentChildSession(ctx: Pick<ExtensionContext, "subagentPolicy">): boolean {
+	return getCurrentSubagentDepth(ctx) >= 1;
 }
 
-// ============================================================================
-// Utility Functions
-// ============================================================================
+export const SUBAGENT_CHILD_DELEGATION_BLOCKED_MESSAGE =
+	"Subagent delegation is not available inside a subagent. " +
+	"Only a top-level session (main chat or a workflow stage) can call the subagent tool. " +
+	"Complete your assigned task directly.";

package/dist/builtin/subagents/src/shared/types-foreground-state.ts

@@ -0,0 +1,56 @@
+/**
+ * Foreground run and extension state public types.
+ *
+ * Delegation is one level deep, so a parent tracks only its own direct children.
+ * The multi-level run address, route, and recursive summary types this file once
+ * carried are gone with the pipeline that produced them.
+ */
+
+import type { ExtensionContext } from "@bastani/atomic";
+import type { ActivityState, SingleResult, SubagentResultStatus, SubagentRunMode } from "./types-results.js";
+
+export interface ForegroundResumeChild {
+	agent: string;
+	index: number;
+	sessionFile?: string;
+	status: SubagentResultStatus;
+	result?: SingleResult;
+}
+
+export interface ForegroundResumeRun {
+	runId: string;
+	mode: SubagentRunMode;
+	cwd: string;
+	updatedAt: number;
+	children: ForegroundResumeChild[];
+}
+
+export interface SubagentState {
+	baseCwd: string;
+	currentSessionId: string | null;
+	subagentInProgress?: boolean;
+	foregroundRuns?: Map<string, ForegroundResumeRun>;
+	foregroundControls: Map<
+		string,
+		{
+			runId: string;
+			mode: SubagentRunMode;
+			startedAt: number;
+			updatedAt: number;
+			currentAgent?: string;
+			currentIndex?: number;
+			currentActivityState?: ActivityState;
+			lastActivityAt?: number;
+			currentTool?: string;
+			currentToolStartedAt?: number;
+			currentPath?: string;
+			turnCount?: number;
+			tokens?: number;
+			toolCount?: number;
+			interrupt?: () => boolean;
+		}
+	>;
+	lastForegroundControlId: string | null;
+	pendingForegroundControlNotices?: Map<string, ReturnType<typeof setTimeout>>;
+	lastUiContext: ExtensionContext | null;
+}