@modelprofile.com/flexharness 3.4.0 → 3.6.0

package/ts/classes.flexharness.ts

@@ -44,15 +44,18 @@ import type {
   IFlexProjectionSnapshot,
   IFlexResolvedModel,
   IFlexResolvedScope,
+  IFlexResourceToolProviderDescriptor,
   IFlexRunFinishedEvent,
   IFlexScheduledPromptAdmission,
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
   IFlexSessionTombstone,
+  IFlexSubagentDefinition,
   IFlexTerminalProjection,
   IFlexToolHandle,
   IFlexToolMessagePart,
+  IFlexToolProviderContext,
   IFlexUncertainToolExecution,
   IFlexUpdateSessionOptions,
   IFlexUsage,
@@ -199,6 +202,8 @@ interface IActiveRun {
   callbacksClosed: boolean;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
+  subagentCallCount: number;
+  subagentSessionIds: Set<string>;
   pendingPermissionIds: Set<string>;
   phase: TRunPhase;
   reservedUserMessage?: IFlexMessage;
@@ -281,6 +286,18 @@ interface IExecutableToolRecord extends Record<string, unknown> {
   execute?: (input: unknown, options: unknown) => unknown;
 }
 
+interface IFlexSubagentTaskInput {
+  description: string;
+  prompt: string;
+  subagentType: string;
+  taskId?: string;
+}
+
+interface IFlexSubagentAcquisition {
+  stored: IStoredSessionState;
+  created: boolean;
+}
+
 type TEventDetails = Record<string, unknown> & {
   type: TFlexHarnessEvent['type'];
 };
@@ -309,6 +326,23 @@ const maxProjectedErrorMessageBytes = 2048;
 const maxProjectedErrorCodeBytes = 128;
 const maxScheduleDebounceMs = 24 * 60 * 60 * 1000;
 const maxBackgroundExecutions = 100;
+const maxSubagentDefinitions = 32;
+const maxSubagentNameBytes = 128;
+const maxSubagentDescriptionBytes = 2048;
+const maxSubagentModelHintBytes = 512;
+const maxSubagentSystemBytes = 64 * 1024;
+const maxSubagentTaskDescriptionBytes = 256;
+const maxSubagentPromptBytes = 64 * 1024;
+const maxSubagentTaskIdBytes = 512;
+const maxSubagentResultTextBytes = 64 * 1024;
+const defaultMaxSubagentDepth = 1;
+const maximumMaxSubagentDepth = 8;
+const defaultMaxSubagentCallsPerRun = 32;
+const maximumMaxSubagentCallsPerRun = 128;
+const maxResourceToolProviders = 128;
+const maxResourceIdBytes = 512;
+const maxResourceToolNameBytes = 512;
+const resourceToolStemLength = 16;
 const repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
 const externalErrorFallback: IFlexErrorInfo = Object.freeze({
@@ -408,6 +442,136 @@ function validateIdentifier(value: string, name: string): void {
   }
 }
 
+function sha256Hex(value: string): string {
+  return plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+function createFlexResourceIdentityDigest(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  validateUtf8String(resourceId, 'resourceId', maxResourceIdBytes, true);
+  if (!Number.isSafeInteger(attachmentRevision) || attachmentRevision < 0) {
+    throw new FlexHarnessValidationError('attachmentRevision must be a non-negative safe integer.');
+  }
+  return sha256Hex(JSON.stringify([resourceId, attachmentRevision]));
+}
+
+export function createFlexResourceToolNamespace(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  const digest = createFlexResourceIdentityDigest(resourceId, attachmentRevision);
+  return `resource_${digest.slice(0, 16)}`;
+}
+
+export function createFlexResourceToolName(namespace: string, toolName: string): string {
+  if (!/^resource_[a-f0-9]{16}$/u.test(namespace)) {
+    throw new FlexHarnessValidationError('Resource tool namespace is invalid.');
+  }
+  validateUtf8String(toolName, 'resource tool name', maxResourceToolNameBytes, true);
+  const stem = toolName
+    .replace(/[^A-Za-z0-9_-]/gu, '_')
+    .slice(0, resourceToolStemLength) || 'tool';
+  return `${namespace}__${stem}__${sha256Hex(toolName).slice(0, 12)}`;
+}
+
+function validateUtf8String(
+  value: unknown,
+  name: string,
+  maxBytes: number,
+  nonEmpty = false,
+): asserts value is string {
+  if (
+    typeof value !== 'string'
+    || (nonEmpty && !value.trim())
+    || Buffer.byteLength(value, 'utf8') > maxBytes
+  ) {
+    throw new FlexHarnessValidationError(
+      `${name} must be ${nonEmpty ? 'a non-empty ' : 'a '}string of at most ${maxBytes} UTF-8 bytes.`,
+    );
+  }
+}
+
+function normalizeSubagents(
+  definitions: IFlexSubagentDefinition[] | undefined,
+): ReadonlyMap<string, Readonly<IFlexSubagentDefinition>> {
+  if (definitions === undefined) return new Map();
+  if (!Array.isArray(definitions) || definitions.length > maxSubagentDefinitions) {
+    throw new FlexHarnessValidationError(
+      `subagents must be an array with at most ${maxSubagentDefinitions} definitions.`,
+    );
+  }
+  const normalized = new Map<string, Readonly<IFlexSubagentDefinition>>();
+  for (let index = 0; index < definitions.length; index++) {
+    const definition = definitions[index];
+    if (
+      !definition
+      || typeof definition !== 'object'
+      || Array.isArray(definition)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(definition))
+    ) {
+      throw new FlexHarnessValidationError(`subagents[${index}] must be a plain object.`);
+    }
+    const unsupported = Object.keys(definition).find(
+      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps'].includes(key),
+    );
+    if (unsupported) {
+      throw new FlexHarnessValidationError(`subagents[${index}] does not support "${unsupported}".`);
+    }
+    validateUtf8String(definition.name, `subagents[${index}].name`, maxSubagentNameBytes, true);
+    validateUtf8String(
+      definition.description,
+      `subagents[${index}].description`,
+      maxSubagentDescriptionBytes,
+    );
+    if (definition.modelHint !== undefined) {
+      validateUtf8String(
+        definition.modelHint,
+        `subagents[${index}].modelHint`,
+        maxSubagentModelHintBytes,
+      );
+    }
+    if (definition.system !== undefined) {
+      validateUtf8String(
+        definition.system,
+        `subagents[${index}].system`,
+        maxSubagentSystemBytes,
+      );
+    }
+    if (
+      definition.maxSteps !== undefined
+      && (!Number.isSafeInteger(definition.maxSteps) || definition.maxSteps < 1)
+    ) {
+      throw new FlexHarnessValidationError(`subagents[${index}].maxSteps must be a positive integer.`);
+    }
+    if (normalized.has(definition.name)) {
+      throw new FlexHarnessValidationError(`Duplicate subagent definition "${definition.name}".`);
+    }
+    normalized.set(definition.name, Object.freeze({
+      name: definition.name,
+      description: definition.description,
+      ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
+      ...(definition.system === undefined ? {} : { system: definition.system }),
+      ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
+    }));
+  }
+  return Object.freeze(normalized);
+}
+
+function resolveBoundedPositiveInteger(
+  value: number | undefined,
+  name: string,
+  defaultValue: number,
+  maximum: number,
+): number {
+  const resolved = value ?? defaultValue;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+    throw new FlexHarnessValidationError(`${name} must be an integer from 1 through ${maximum}.`);
+  }
+  return resolved;
+}
+
 function requireTransferIdentifier(value: string, field: string): void {
   if (Buffer.byteLength(value, 'utf8') > maxTransferIdentifierBytes) {
     throw new FlexHarnessValidationError(`${field} exceeds the transfer limit.`);
@@ -735,6 +899,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
   private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
   private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
+  private readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
   private readonly stores: IFlexHarnessStores;
   private readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
@@ -742,6 +907,9 @@ export class FlexHarness<TScope = unknown> {
   private readonly callbackLimits: Required<IFlexCallbackLimits>;
   private readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
+  private readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  private readonly maxSubagentDepth: number;
+  private readonly maxSubagentCallsPerRun: number;
   private readonly stateLoads = new Map<string, Promise<IStorageState>>();
   private readonly scopeAdmissions = new Map<string, IScopeAdmissionState>();
   private readonly scopeRetirements = new Map<string, Promise<void>>();
@@ -779,6 +947,7 @@ export class FlexHarness<TScope = unknown> {
     this.scopeResolver = options.scopeResolver;
     this.modelResolver = options.modelResolver;
     this.toolProvider = options.toolProvider;
+    this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
     this.stores = options.stores ?? new InMemoryFlexHarnessStores();
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
@@ -786,6 +955,19 @@ export class FlexHarness<TScope = unknown> {
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
     this.promptQueueLimits = resolvePromptQueueLimits(options.promptQueueLimits);
     this.externalErrorProjector = options.externalErrorProjector;
+    this.subagents = normalizeSubagents(options.subagents);
+    this.maxSubagentDepth = resolveBoundedPositiveInteger(
+      options.maxSubagentDepth,
+      'maxSubagentDepth',
+      defaultMaxSubagentDepth,
+      maximumMaxSubagentDepth,
+    );
+    this.maxSubagentCallsPerRun = resolveBoundedPositiveInteger(
+      options.maxSubagentCallsPerRun,
+      'maxSubagentCallsPerRun',
+      defaultMaxSubagentCallsPerRun,
+      maximumMaxSubagentCallsPerRun,
+    );
   }
 
   public async listSessions(scopeId: string): Promise<IFlexSession[]> {
@@ -851,6 +1033,7 @@ export class FlexHarness<TScope = unknown> {
           updatedAt: timestamp,
           status: 'idle',
           activity: { status: 'idle' },
+          depth: 0,
         };
         resolved.state.sessions.set(
           sessionId,
@@ -864,6 +1047,7 @@ export class FlexHarness<TScope = unknown> {
         metadata,
         scopeId,
         resolved.scope.scope,
+        placeholder.compactorLifecycleController,
       );
       const loaded = await initialization;
       if (resolved.state.sessions.get(sessionId) !== placeholder) {
@@ -890,6 +1074,8 @@ export class FlexHarness<TScope = unknown> {
       const tombstone: IFlexSessionTombstone = {
         sessionId,
         deletedAt: new Date().toISOString(),
+        rootSessionId: sessionId,
+        depth: 0,
       };
       let tombstoneCommitted = false;
       let domainCleanupCompleted = false;
@@ -899,11 +1085,12 @@ export class FlexHarness<TScope = unknown> {
           resolved.state.tombstones.set(sessionId, tombstone);
         }, true);
         tombstoneCommitted = true;
+        completeInitialization();
         await this.finishTombstoneCleanup(
           resolved.state,
           sessionId,
           scopeId,
-          resolved.scope.scope,
+          { scopeId, scope: resolved.scope.scope },
         );
         domainCleanupCompleted = true;
       } catch (cleanupError) {
@@ -981,15 +1168,17 @@ export class FlexHarness<TScope = unknown> {
   public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
     const { scope, state } = await this.resolveState(scopeId);
     validateIdentifier(sessionId, 'sessionId');
-    const existingDeletion = state.sessionDeletions.get(sessionId);
+    await state.scopeQueue;
+    const deletionKey = state.tombstones.get(sessionId)?.rootSessionId ?? sessionId;
+    const existingDeletion = state.sessionDeletions.get(deletionKey);
     if (existingDeletion) return existingDeletion;
     let deletion!: Promise<void>;
     deletion = this.deleteSessionInternal(state, scopeId, scope.scope, sessionId).finally(() => {
-      if (state.sessionDeletions.get(sessionId) === deletion) {
-        state.sessionDeletions.delete(sessionId);
+      if (state.sessionDeletions.get(deletionKey) === deletion) {
+        state.sessionDeletions.delete(deletionKey);
       }
     });
-    state.sessionDeletions.set(sessionId, deletion);
+    state.sessionDeletions.set(deletionKey, deletion);
     return deletion;
   }
 
@@ -1001,35 +1190,91 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<void> {
     const existingTombstone = state.tombstones.get(sessionId);
     if (existingTombstone) {
+      const rootSessionId = existingTombstone.rootSessionId ?? existingTombstone.sessionId;
+      const descendantRoots = this.descendantTombstoneRoots(state, sessionId)
+        .filter((candidate) => candidate !== rootSessionId);
       try {
-        await this.finishTombstoneCleanup(state, sessionId, scopeId, scope);
+        const orphanErrors = await this.closeOrphanedResources(state.storageKey);
+        if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+        for (const descendantRoot of descendantRoots) {
+          await this.finishTombstoneCleanup(
+            state,
+            descendantRoot,
+            scopeId,
+            { scopeId, scope },
+          );
+        }
+        await this.finishTombstoneCleanup(state, rootSessionId, scopeId, { scopeId, scope });
       } catch (error) {
         throw this.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-delete');
       }
       return;
     }
     const stored = this.requireSession(state, sessionId);
-    const deletedSession = publicSnapshot(stored.session);
+    let deletedSessions: IFlexSession[] = [];
+    let descendantRoots: string[] = [];
     await this.mutateScope(state, () => {
       if (state.sessions.get(sessionId) !== stored) {
         throw new FlexHarnessNotFoundError('Session', sessionId);
       }
-      state.sessions.delete(sessionId);
-      state.retainedSessionCleanups.set(sessionId, {
-        stored,
-        domainsCompleted: false,
-      });
-      state.tombstones.set(sessionId, {
-        sessionId,
-        deletedAt: new Date().toISOString(),
-      });
+      const subtree = this.collectSessionSubtree(state, sessionId);
+      descendantRoots = this.descendantTombstoneRoots(state, sessionId);
+      const rootDepth = stored.session.depth ?? 0;
+      const deletedAt = new Date().toISOString();
+      deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
+      for (const entry of subtree) {
+        const entrySessionId = entry.session.sessionId;
+        state.sessions.delete(entrySessionId);
+        state.retainedSessionCleanups.set(entrySessionId, {
+          stored: entry,
+          domainsCompleted: false,
+        });
+        state.tombstones.set(entrySessionId, {
+          sessionId: entrySessionId,
+          deletedAt,
+          rootSessionId: sessionId,
+          depth: (entry.session.depth ?? rootDepth) - rootDepth,
+          ...(entry.session.parentSessionId === undefined
+            ? {}
+            : { parentSessionId: entry.session.parentSessionId }),
+        });
+      }
     });
+    const reason = this.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
+    const childFirstDeletedSessions = [...deletedSessions].sort((left, right) =>
+      (right.depth ?? 0) - (left.depth ?? 0)
+      || left.sessionId.localeCompare(right.sessionId));
+    for (const deleted of childFirstDeletedSessions) {
+      const active = state.activeRuns.get(deleted.sessionId);
+      if (active) {
+        this.cancelRun(
+          active,
+          reason,
+          this.createCompactorContext(scopeId, scope, state.storageKey, deleted.sessionId),
+        );
+      }
+    }
     try {
-      await this.finishTombstoneCleanup(state, sessionId, scopeId, scope);
+      const orphanErrors = await this.closeOrphanedResources(state.storageKey);
+      if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+      for (const descendantRoot of descendantRoots) {
+        await this.finishTombstoneCleanup(
+          state,
+          descendantRoot,
+          scopeId,
+          { scopeId, scope },
+        );
+      }
+      await this.finishTombstoneCleanup(state, sessionId, scopeId, { scopeId, scope });
     } catch (error) {
       throw this.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-delete');
     }
-    this.emitEvent(scopeId, sessionId, { type: 'session.deleted', session: deletedSession });
+    for (const deleted of childFirstDeletedSessions) {
+      this.emitEvent(scopeId, deleted.sessionId, {
+        type: 'session.deleted',
+        session: publicSnapshot(deleted),
+      });
+    }
   }
 
   public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
@@ -1516,6 +1761,8 @@ export class FlexHarness<TScope = unknown> {
     options: IFlexPromptOptions,
     scheduleKey?: string,
     debounceMs?: number,
+    subagentAdmission = false,
+    admissionSignal?: AbortSignal,
   ): Promise<{ admission: IFlexPromptQueueAdmission; started: Promise<IFlexPromptAdmission> }> {
     this.assertOpen();
     const normalizedPrompt = normalizeFlexPrompt(prompt);
@@ -1536,20 +1783,35 @@ export class FlexHarness<TScope = unknown> {
       resolveSettled: () => resolveSettled(),
     };
     this.pendingPromptAdmissionOwners.add(pendingOwner);
+    const admissionSignals = [
+      pendingOwner.controller.signal,
+      ...(admissionSignal === undefined ? [] : [admissionSignal]),
+    ];
     let abortAdmission!: () => void;
     const abortPromise = new Promise<never>((_resolve, reject) => {
-      abortAdmission = () => reject(
-        pendingOwner.controller.signal.reason ?? new FlexHarnessAbortError(),
-      );
-      pendingOwner.controller.signal.addEventListener('abort', abortAdmission, { once: true });
-      if (pendingOwner.controller.signal.aborted) abortAdmission();
+      abortAdmission = () => {
+        const aborted = admissionSignals.find((signal) => signal.aborted);
+        reject(aborted?.reason ?? new FlexHarnessAbortError());
+      };
+      for (const signal of admissionSignals) {
+        signal.addEventListener('abort', abortAdmission, { once: true });
+      }
+      if (admissionSignals.some((signal) => signal.aborted)) abortAdmission();
     });
     try {
       const resolved = await Promise.race([this.resolveState(scopeId), abortPromise]);
       const state = resolved.state;
       await Promise.race([state.scopeQueue, abortPromise]);
+      if (admissionSignal?.aborted) {
+        throw admissionSignal.reason ?? new FlexHarnessAbortError();
+      }
       this.assertStateAcceptingWork(state);
       const stored = this.requireSession(state, sessionId);
+      if (stored.session.agent !== undefined && !subagentAdmission) {
+        throw new FlexHarnessValidationError(
+          'Subagent sessions can only be prompted through the foreground task tool.',
+        );
+      }
       if (stored.outstandingPromptsById.size >= this.promptQueueLimits.maxOutstandingPromptsPerSession) {
         throw new FlexHarnessQueueFullError(
           `Session "${sessionId}" has reached its outstanding prompt limit.`,
@@ -1615,7 +1877,9 @@ export class FlexHarness<TScope = unknown> {
         started,
       };
     } finally {
-      pendingOwner.controller.signal.removeEventListener('abort', abortAdmission);
+      for (const signal of admissionSignals) {
+        signal.removeEventListener('abort', abortAdmission);
+      }
       this.pendingPromptAdmissionOwners.delete(pendingOwner);
       releasePendingAdmission();
       pendingOwner.resolveSettled();
@@ -1714,6 +1978,8 @@ export class FlexHarness<TScope = unknown> {
       callbacksClosed: false,
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
+      subagentCallCount: 0,
+      subagentSessionIds: new Set(),
       pendingPermissionIds: new Set(),
       phase: 'admitting',
       completion: queued.completion,
@@ -2109,28 +2375,38 @@ export class FlexHarness<TScope = unknown> {
       queued.status = 'running';
       this.emitPromptQueueEvent(queued, 'prompt.running');
     }
+    const resolverRelationship = {
+      ...(run.stored.session.parentSessionId === undefined
+        ? {}
+        : { parentSessionId: run.stored.session.parentSessionId }),
+      ...(run.stored.session.agent === undefined ? {} : { agent: run.stored.session.agent }),
+    };
     const modelOutcome = Promise.resolve()
-      .then(() => this.modelResolver.resolveModel({
+      .then(() => this.modelResolver.resolveModel(Object.freeze({
         scopeId: run.scopeId,
         scope: run.scope as TScope,
         sessionId: run.sessionId,
         runId: run.runId,
         ...(options.modelHint ? { modelHint: options.modelHint } : {}),
+        ...resolverRelationship,
         signal,
-      }))
+      })))
       .then(
         (value): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: true, value }),
         (error): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: false, error }),
       );
+    const toolProviderContext: Readonly<IFlexToolProviderContext<TScope>> = Object.freeze({
+      scopeId: run.scopeId,
+      scope: run.scope as TScope,
+      sessionId: run.sessionId,
+      runId: run.runId,
+      ...resolverRelationship,
+      signal,
+      requestPermission: (request: IFlexPermissionRequestInput) =>
+        this.requestPermission(run.state, run, request),
+    });
     const toolOutcome = Promise.resolve()
-      .then(() => this.toolProvider?.provideTools({
-        scopeId: run.scopeId,
-        scope: run.scope as TScope,
-        sessionId: run.sessionId,
-        runId: run.runId,
-        signal,
-        requestPermission: (request) => this.requestPermission(run.state, run, request),
-      }))
+      .then(() => this.provideRunToolHandle(run, toolProviderContext))
       .then(
         (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
         (error): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
@@ -2197,9 +2473,21 @@ export class FlexHarness<TScope = unknown> {
       run.modelResolution = model!;
       let tools: TFlexAgentToolSet | undefined;
       try {
-        tools = toolHandle
+        const providedTools = toolHandle?.tools;
+        if (
+          this.subagents.size > 0
+          && providedTools
+          && Object.prototype.hasOwnProperty.call(providedTools, 'task')
+        ) {
+          throw new FlexHarnessValidationError('The application tool provider cannot define reserved tool "task".');
+        }
+        const combinedTools: Record<string, unknown> = { ...(providedTools ?? {}) };
+        if (this.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
+          combinedTools.task = this.createSubagentTool(run);
+        }
+        tools = Object.keys(combinedTools).length > 0
           ? wrapToolSet(
-              toolHandle.tools,
+              combinedTools as TFlexAgentToolSet,
               this.toolOutputLimits,
               (toolError) => this.projectExternalError(run, toolError, 'toolExecution'),
             )
@@ -2247,6 +2535,426 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private createSubagentTool(run: IActiveRun): unknown {
+    const available = [...this.subagents.values()]
+      .map((definition) => `- ${definition.name}: ${definition.description}`)
+      .join('\n');
+    return plugins.tool({
+      description: `Run one configured FlexHarness subagent in the foreground and return its final text.\nAvailable subagents:\n${available}`,
+      inputSchema: plugins.z.object({
+        description: plugins.z.string(),
+        prompt: plugins.z.string(),
+        subagentType: plugins.z.string(),
+        taskId: plugins.z.string().optional(),
+      }).strict(),
+      execute: (input: IFlexSubagentTaskInput, options?: { toolCallId?: string }) =>
+        this.executeSubagentTask(run, input, options?.toolCallId),
+    });
+  }
+
+  private async executeSubagentTask(
+    run: IActiveRun,
+    input: IFlexSubagentTaskInput,
+    toolCallId: string | undefined,
+  ): Promise<{ taskId: string; status: 'completed'; text: string; model: IFlexModelIdentity }> {
+    run.subagentCallCount++;
+    if (run.subagentCallCount > this.maxSubagentCallsPerRun) {
+      throw new FlexHarnessValidationError(
+        `Run "${run.runId}" exceeds maxSubagentCallsPerRun (${this.maxSubagentCallsPerRun}).`,
+      );
+    }
+    validateUtf8String(
+      input.description,
+      'task description',
+      maxSubagentTaskDescriptionBytes,
+      true,
+    );
+    validateUtf8String(input.prompt, 'task prompt', maxSubagentPromptBytes, true);
+    validateUtf8String(input.subagentType, 'subagentType', maxSubagentNameBytes, true);
+    if (input.taskId !== undefined) {
+      validateUtf8String(input.taskId, 'taskId', maxSubagentTaskIdBytes, true);
+    }
+    validateUtf8String(toolCallId, 'task toolCallId', maxTransferIdentifierBytes, true);
+    const definition = this.subagents.get(input.subagentType);
+    if (!definition || (run.stored.session.depth ?? 0) >= this.maxSubagentDepth) {
+      throw new FlexHarnessValidationError(`Subagent "${input.subagentType}" is not available.`);
+    }
+    const reservedSessionId = input.taskId ?? this.createSubagentSessionId(
+      run.state.storageKey,
+      run.sessionId,
+      run.runId,
+      toolCallId,
+    );
+    if (run.subagentSessionIds.has(reservedSessionId)) {
+      throw new FlexHarnessValidationError(
+        `Subagent task "${reservedSessionId}" has already been acquired by this parent run.`,
+      );
+    }
+    run.subagentSessionIds.add(reservedSessionId);
+    let child: IStoredSessionState | undefined;
+    let childCreated = false;
+    let queued: Awaited<ReturnType<typeof this.enqueuePromptInternal>> | undefined;
+    let admission: IFlexPromptAdmission | undefined;
+    const abortChild = () => {
+      const reason = run.controller.signal.reason instanceof FlexHarnessAbortError
+        ? run.controller.signal.reason
+        : this.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+      const ownedChild = child ?? run.state.sessions.get(reservedSessionId);
+      if (
+        ownedChild
+        && ownedChild.session.parentSessionId === run.sessionId
+        && ownedChild.session.agent === definition.name
+        && run.state.initializingSessions.has(reservedSessionId)
+      ) this.abortCompactorLifecycle(ownedChild, reason);
+      const childQueue = queued === undefined
+        ? undefined
+        : ownedChild?.outstandingPromptsById.get(queued.admission.queueId);
+      if (childQueue) this.cancelQueuedPrompt(childQueue, reason);
+      else if (admission) {
+        this.abortExactRun(run.state, reservedSessionId, admission.runId, reason);
+      }
+    };
+    run.controller.signal.addEventListener('abort', abortChild, { once: true });
+    if (run.controller.signal.aborted) abortChild();
+    try {
+      await this.requestPermission(run.state, run, {
+        kind: 'subagent.start',
+        description: `Start foreground subagent "${definition.name}": ${input.description}`,
+        toolCallId,
+        metadata: {
+          agent: definition.name,
+          description: input.description,
+          ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        },
+      });
+      const acquired = await this.acquireSubagentSession(
+        run,
+        definition,
+        toolCallId,
+        input.taskId,
+        reservedSessionId,
+      );
+      child = acquired.stored;
+      childCreated = acquired.created;
+      if (run.controller.signal.aborted) throw run.controller.signal.reason;
+      this.updateSubagentToolPart(run, toolCallId, child.session.sessionId);
+      const childOptions: IFlexPromptOptions = {
+        ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
+        ...(definition.system === undefined ? {} : { system: definition.system }),
+        ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
+      };
+      queued = await this.enqueuePromptInternal(
+        run.scopeId,
+        child.session.sessionId,
+        input.prompt,
+        childOptions,
+        undefined,
+        undefined,
+        true,
+        run.controller.signal,
+      );
+      admission = await queued.started;
+      const result = await queued.admission.completion;
+      this.updateSubagentToolPart(run, toolCallId, child.session.sessionId, result.model);
+      return {
+        taskId: child.session.sessionId,
+        status: 'completed',
+        text: truncateUtf8(result.assistantMessage.parts
+          .filter((part) => part.type === 'text')
+          .map((part) => part.text)
+          .join(''), maxSubagentResultTextBytes),
+        model: publicSnapshot(result.model),
+      };
+    } catch (error) {
+      if (
+        childCreated
+        && child
+        && queued === undefined
+        && run.state.sessions.get(child.session.sessionId) === child
+        && !run.state.tombstones.has(child.session.sessionId)
+      ) {
+        try {
+          await this.deleteSessionInternal(
+            run.state,
+            run.scopeId,
+            run.scope as TScope,
+            child.session.sessionId,
+          );
+        } catch (cleanupError) {
+          throw combineErrors([error, cleanupError]);
+        }
+      }
+      const childModel = child?.messages
+        .filter((message) => message.runId === admission?.runId && message.role === 'assistant')
+        .at(-1)?.model
+        ?? child?.stagedTerminals.find((terminal) => terminal.runId === admission?.runId)?.model;
+      const parentPart = run.callbackParts.find((part) =>
+        part.type === 'tool' && part.toolCallId === toolCallId);
+      if (
+        child
+        && childModel !== undefined
+        && parentPart?.type === 'tool'
+        && parentPart.model === undefined
+      ) {
+        this.updateSubagentToolPart(run, toolCallId, child.session.sessionId, childModel);
+      }
+      throw error;
+    } finally {
+      run.controller.signal.removeEventListener('abort', abortChild);
+    }
+  }
+
+  private async acquireSubagentSession(
+    run: IActiveRun,
+    definition: Readonly<IFlexSubagentDefinition>,
+    toolCallId: string,
+    taskId?: string,
+    reservedSessionId?: string,
+  ): Promise<IFlexSubagentAcquisition> {
+    const state = run.state;
+    const sessionId = reservedSessionId ?? taskId ?? this.createSubagentSessionId(
+      state.storageKey,
+      run.sessionId,
+      run.runId,
+      toolCallId,
+    );
+    let metadata: IFlexSession | undefined;
+    let placeholder: IStoredSessionState | undefined;
+    let initializationCompletion: Promise<void> | undefined;
+    let resolveInitialization: (() => void) | undefined;
+    let initializationCompleted = false;
+    const completeInitialization = () => {
+      if (initializationCompleted || initializationCompletion === undefined) return;
+      initializationCompleted = true;
+      state.initializingSessions.delete(sessionId);
+      if (state.sessionInitializations.get(sessionId) === initializationCompletion) {
+        state.sessionInitializations.delete(sessionId);
+      }
+      resolveInitialization?.();
+    };
+    try {
+      await this.mutateScope(state, () => {
+        if (state.sessions.get(run.sessionId) !== run.stored || state.tombstones.has(run.sessionId)) {
+          throw new FlexHarnessAbortError('The parent session no longer owns this subagent request.');
+        }
+        if (state.activeRuns.get(run.sessionId) !== run || run.callbacksClosed) {
+          throw new FlexHarnessAbortError('The parent run no longer owns this subagent request.');
+        }
+        if (run.stored.session.agent !== undefined && !this.subagents.has(run.stored.session.agent)) {
+          throw new FlexHarnessValidationError(`Parent subagent "${run.stored.session.agent}" is disabled.`);
+        }
+        if ((run.stored.session.depth ?? 0) >= this.maxSubagentDepth) {
+          throw new FlexHarnessValidationError('The maximum subagent depth has been reached.');
+        }
+        let ancestor: IFlexSession | undefined = run.stored.session;
+        const visited = new Set<string>();
+        while (ancestor) {
+          if (visited.has(ancestor.sessionId) || state.tombstones.has(ancestor.sessionId)) {
+            throw new FlexHarnessValidationError('The subagent ancestor chain is invalid or deleted.');
+          }
+          visited.add(ancestor.sessionId);
+          ancestor = ancestor.parentSessionId
+            ? state.sessions.get(ancestor.parentSessionId)?.session
+            : undefined;
+        }
+        const existing = state.sessions.get(sessionId);
+        if (existing) {
+          if (
+            existing.session.parentSessionId !== run.sessionId
+            || existing.session.agent !== definition.name
+          ) {
+            throw new FlexHarnessValidationError(`Task session "${sessionId}" is not owned by this parent and agent.`);
+          }
+          if (
+            taskId === undefined
+            && (existing.session.parentRunId !== run.runId
+              || existing.session.parentToolCallId !== toolCallId)
+          ) {
+            throw new FlexHarnessValidationError(
+              `Subagent task "${sessionId}" does not match its deterministic invocation origin.`,
+            );
+          }
+          if (state.initializingSessions.has(sessionId)) {
+            throw new FlexHarnessSessionBusyError(sessionId, 'is still being initialized');
+          }
+          if (taskId === undefined && existing.messages.length > 0) {
+            throw new FlexHarnessValidationError(
+              `Subagent task "${sessionId}" has an uncertain prior execution and cannot be replayed automatically.`,
+            );
+          }
+          if (state.activeRuns.has(sessionId) || existing.session.status !== 'idle') {
+            throw new FlexHarnessSessionBusyError(sessionId, 'cannot be resumed while it is not idle');
+          }
+          if (taskId !== undefined && existing.session.parentRunId === run.runId) {
+            throw new FlexHarnessValidationError('taskId can only resume a child from a later parent run.');
+          }
+          placeholder = existing;
+          return;
+        }
+        if (taskId !== undefined || state.tombstones.has(sessionId)) {
+          throw new FlexHarnessNotFoundError('Subagent task', sessionId);
+        }
+        const timestamp = new Date().toISOString();
+        metadata = {
+          scopeId: run.scopeId,
+          sessionId,
+          title: `Subagent: ${definition.name}`,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+          status: 'idle',
+          activity: { status: 'idle' },
+          parentSessionId: run.sessionId,
+          parentRunId: run.runId,
+          parentToolCallId: toolCallId,
+          agent: definition.name,
+          depth: (run.stored.session.depth ?? 0) + 1,
+        };
+        placeholder = this.createUninitializedStoredSession(metadata, state.storageKey);
+        state.sessions.set(sessionId, placeholder);
+        state.initializingSessions.add(sessionId);
+        initializationCompletion = new Promise<void>((resolve) => {
+          resolveInitialization = resolve;
+        });
+        state.sessionInitializations.set(sessionId, initializationCompletion);
+      });
+      if (!metadata) return { stored: placeholder!, created: false };
+      const loaded = await this.loadSessionRuntime(
+        state,
+        metadata,
+        run.scopeId,
+        run.scope as TScope,
+        placeholder!.compactorLifecycleController,
+      );
+      const parentLostOwnership = run.controller.signal.aborted
+        || state.sessions.get(run.sessionId) !== run.stored
+        || state.activeRuns.get(run.sessionId) !== run
+        || run.callbacksClosed;
+      if (
+        parentLostOwnership
+        || state.sessions.get(sessionId) !== placeholder
+        || state.tombstones.has(sessionId)
+      ) {
+        const aborted = run.controller.signal.aborted
+          ? run.controller.signal.reason
+          : new FlexHarnessAbortError('The subagent session lost parent ownership during initialization.');
+        try {
+          await this.closeStoredSession(loaded);
+        } catch (error) {
+          this.orphanedStoredSessions.add(loaded);
+          throw combineErrors([aborted, error]);
+        }
+        throw aborted;
+      }
+      state.sessions.set(sessionId, loaded);
+      this.emitEvent(run.scopeId, sessionId, {
+        type: 'session.created',
+        session: publicSnapshot(metadata),
+      });
+      return { stored: loaded, created: true };
+    } catch (error) {
+      if (metadata === undefined) throw error;
+      if (
+        state.tombstones.has(sessionId)
+        && placeholder?.compactorLifecycleController.signal.aborted
+      ) {
+        throw placeholder.compactorLifecycleController.signal.reason;
+      }
+      const projected = this.projectExternalError(run, error, 'agentSession');
+      if (
+        placeholder === undefined
+        || (state.sessions.get(sessionId) !== placeholder && !state.tombstones.has(sessionId))
+      ) throw projected;
+      if (state.tombstones.has(sessionId)) throw projected;
+      try {
+        await this.mutateScope(state, () => {
+          if (state.sessions.get(sessionId) !== placeholder) return;
+          state.sessions.delete(sessionId);
+          state.tombstones.set(sessionId, {
+            sessionId,
+            deletedAt: new Date().toISOString(),
+            rootSessionId: sessionId,
+            depth: 0,
+            parentSessionId: run.sessionId,
+          });
+        }, true);
+        completeInitialization();
+        await this.finishTombstoneCleanup(
+          state,
+          sessionId,
+          run.scopeId,
+          { scopeId: run.scopeId, scope: run.scope as TScope },
+        );
+      } catch (cleanupError) {
+        const combined = combineErrors([
+          projected,
+          this.projectExternalError(run, cleanupError, 'persistence'),
+        ]);
+        this.deferNamespaceDrain(
+          state,
+          combined,
+          { scopeId: run.scopeId, scope: run.scope as TScope },
+        );
+        throw combined;
+      }
+      throw projected;
+    } finally {
+      completeInitialization();
+    }
+  }
+
+  private createSubagentSessionId(
+    storageKey: string,
+    parentSessionId: string,
+    parentRunId: string,
+    parentToolCallId: string,
+  ): string {
+    return `subagent_${plugins.crypto.createHash('sha256').update(JSON.stringify([
+      'flexharness-subagent-v1',
+      storageKey,
+      parentSessionId,
+      parentRunId,
+      parentToolCallId,
+    ])).digest('hex')}`;
+  }
+
+  private updateSubagentToolPart(
+    run: IActiveRun,
+    toolCallId: string,
+    childSessionId: string,
+    model?: IFlexModelIdentity,
+  ): void {
+    const partId = run.toolPartIds.get(toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') {
+      throw new FlexHarnessValidationError(`Running task part "${toolCallId}" is unavailable.`);
+    }
+    const bytes = Buffer.byteLength(childSessionId, 'utf8')
+      + (model === undefined ? 0 : jsonBytes(model));
+    if (!this.reserveCallbackCapacity(run, 1, bytes, 0)) {
+      throw run.callbackError ?? new FlexHarnessCallbackOverflowError('Task metadata exceeded callback limits.');
+    }
+    part.childSessionId = childSessionId;
+    if (model !== undefined) part.model = cloneSerializable(model);
+    this.emitPartEvent(run, 'part.updated', part);
+  }
+
+  private abortExactRun(
+    state: IStorageState,
+    sessionId: string,
+    runId: string,
+    reason: unknown,
+  ): boolean {
+    const active = state.activeRuns.get(sessionId);
+    if (!active || active.runId !== runId || active.phase === 'finalizing' || active.phase === 'promoting') {
+      return false;
+    }
+    const cancellation = reason instanceof FlexHarnessAbortError
+      ? reason
+      : this.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+    this.cancelRun(active, cancellation);
+    return true;
+  }
+
   private createReservation(
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
@@ -3020,6 +3728,161 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private async provideRunToolHandle(
+    run: IActiveRun,
+    context: Readonly<IFlexToolProviderContext<TScope>>,
+  ): Promise<IFlexToolHandle | undefined> {
+    if (!this.resourceToolProviderResolver) return this.toolProvider?.provideTools(context);
+
+    const resolverContext = Object.freeze({
+      scopeId: context.scopeId,
+      scope: context.scope,
+      sessionId: context.sessionId,
+      runId: context.runId,
+      ...(context.parentSessionId === undefined ? {} : { parentSessionId: context.parentSessionId }),
+      ...(context.agent === undefined ? {} : { agent: context.agent }),
+      signal: context.signal,
+    });
+    const resolved = await this.resourceToolProviderResolver.resolveResourceToolProviders(resolverContext);
+    const descriptors = this.normalizeResourceToolProviderDescriptors(resolved);
+    const owned: Array<{ handle: IFlexToolHandle; closed: boolean }> = [];
+    const tools: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    const closeOwned = async (): Promise<void> => {
+      const errors: unknown[] = [];
+      for (const entry of [...owned].reverse()) {
+        if (entry.closed || !entry.handle.close) continue;
+        try {
+          await entry.handle.close();
+          entry.closed = true;
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length > 0) throw combineErrors(errors);
+    };
+    try {
+      context.signal.throwIfAborted();
+      const applicationHandle = this.normalizeToolHandle(
+        run,
+        await this.toolProvider?.provideTools(context),
+      );
+      if (applicationHandle) {
+        owned.push({ handle: applicationHandle, closed: false });
+        for (const [toolName, tool] of Object.entries(applicationHandle.tools)) {
+          tools[toolName] = tool;
+        }
+      }
+      for (const descriptor of descriptors) {
+        context.signal.throwIfAborted();
+        const namespace = createFlexResourceToolNamespace(
+          descriptor.resourceId,
+          descriptor.attachmentRevision,
+        );
+        const resourceIdentity = createFlexResourceIdentityDigest(
+          descriptor.resourceId,
+          descriptor.attachmentRevision,
+        );
+        const resourceContext = Object.freeze({
+          ...context,
+          requestPermission: (request: IFlexPermissionRequestInput) => context.requestPermission({
+            ...request,
+            kind: `resource.${resourceIdentity}.${request.kind}`,
+            ...(request.rememberKey === undefined
+              ? {}
+              : { rememberKey: `resource:${resourceIdentity}:${request.rememberKey}` }),
+            metadata: {
+              resourceId: descriptor.resourceId,
+              attachmentRevision: descriptor.attachmentRevision,
+              resourceIdentity,
+              toolNamespace: namespace,
+              ...(request.metadata === undefined ? {} : { providerMetadata: request.metadata }),
+            },
+          }),
+        });
+        const handle = this.normalizeToolHandle(
+          run,
+          await descriptor.provider.provideTools(resourceContext),
+        );
+        if (!handle) continue;
+        owned.push({ handle, closed: false });
+        for (const [toolName, tool] of Object.entries(handle.tools)) {
+          const exposedName = createFlexResourceToolName(namespace, toolName);
+          if (Object.prototype.hasOwnProperty.call(tools, exposedName)) {
+            throw new FlexHarnessValidationError(`Duplicate exposed tool "${exposedName}".`);
+          }
+          tools[exposedName] = tool;
+        }
+      }
+      if (owned.length === 0 && Object.keys(tools).length === 0) return undefined;
+      return {
+        tools: tools as TFlexAgentToolSet,
+        ...(owned.some((entry) => entry.handle.close) ? { close: closeOwned } : {}),
+      };
+    } catch (error) {
+      if (owned.some((entry) => entry.handle.close && !entry.closed)) {
+        try {
+          await this.closePartialToolHandle({ tools: {}, close: closeOwned }, run);
+        } catch (cleanupError) {
+          throw combineErrors([error, cleanupError]);
+        }
+      }
+      throw error;
+    }
+  }
+
+  private normalizeResourceToolProviderDescriptors(
+    descriptors: readonly IFlexResourceToolProviderDescriptor<TScope>[],
+  ): IFlexResourceToolProviderDescriptor<TScope>[] {
+    if (!Array.isArray(descriptors) || descriptors.length > maxResourceToolProviders) {
+      throw new FlexHarnessValidationError(
+        `Resource tool providers must be an array with at most ${maxResourceToolProviders} descriptors.`,
+      );
+    }
+    const resourceIds = new Set<string>();
+    const namespaces = new Set<string>();
+    return descriptors.map((descriptor, index) => {
+      if (
+        !descriptor
+        || typeof descriptor !== 'object'
+        || Array.isArray(descriptor)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(descriptor))
+      ) {
+        throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} is invalid.`);
+      }
+      const unsupported = Object.keys(descriptor).find(
+        (key) => !['resourceId', 'attachmentRevision', 'provider'].includes(key),
+      );
+      if (unsupported) {
+        throw new FlexHarnessValidationError(
+          `Resource tool provider descriptor ${index} does not support "${unsupported}".`,
+        );
+      }
+      const resourceId = descriptor.resourceId;
+      const attachmentRevision = descriptor.attachmentRevision;
+      const provider = descriptor.provider;
+      const provideTools = provider?.provideTools;
+      const namespace = createFlexResourceToolNamespace(resourceId, attachmentRevision);
+      if (resourceIds.has(resourceId)) {
+        throw new FlexHarnessValidationError(`Duplicate resourceId "${resourceId}".`);
+      }
+      if (namespaces.has(namespace)) {
+        throw new FlexHarnessValidationError(`Duplicate resource tool namespace "${namespace}".`);
+      }
+      if (!provider || typeof provideTools !== 'function') {
+        throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} has no tool provider.`);
+      }
+      resourceIds.add(resourceId);
+      namespaces.add(namespace);
+      return {
+        resourceId,
+        attachmentRevision,
+        provider: {
+          provideTools: (context) => provideTools.call(provider, context),
+        },
+      };
+    });
+  }
+
   private async closePartialToolHandle(handle: IFlexToolHandle, run: IActiveRun): Promise<void> {
     try {
       await handle.close?.();
@@ -3224,10 +4087,37 @@ export class FlexHarness<TScope = unknown> {
         scopeChanged = (await this.repairLoadedSession(state.storageKey, stored)) || scopeChanged;
         if (stored.projectionRevision < 0) throw new Error('Invalid projection revision.');
       }
-      for (const tombstone of [...state.tombstones.values()]) {
+      for (const stored of state.sessions.values()) {
+        let ancestorId = stored.session.parentSessionId;
+        const visited = new Set<string>([stored.session.sessionId]);
+        while (ancestorId) {
+          if (visited.has(ancestorId)) {
+            throw new FlexHarnessValidationError(
+              `Live session "${stored.session.sessionId}" has a cyclic ancestor chain.`,
+            );
+          }
+          visited.add(ancestorId);
+          if (state.tombstones.has(ancestorId)) {
+            throw new FlexHarnessValidationError(
+              `Live session "${stored.session.sessionId}" descends from tombstoned ancestor "${ancestorId}".`,
+            );
+          }
+          ancestorId = state.sessions.get(ancestorId)?.session.parentSessionId;
+        }
+      }
+      const tombstoneRoots = this.orderTombstoneRootsChildFirst(
+        state,
+        [...new Set([...state.tombstones.values()].map((tombstone) =>
+          tombstone.rootSessionId ?? tombstone.sessionId))],
+      );
+      for (const rootSessionId of tombstoneRoots) {
+        if (this.descendantTombstoneRoots(state, rootSessionId).length > 0) continue;
         try {
-          await this.cleanupSessionDomains(storageKey, tombstone.sessionId);
-          state.tombstones.delete(tombstone.sessionId);
+          const group = this.tombstoneGroup(state, rootSessionId);
+          for (const tombstone of group) {
+            await this.cleanupSessionDomains(storageKey, tombstone.sessionId);
+          }
+          for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
           scopeChanged = true;
         } catch {
           // A retained tombstone is retried by the next load or explicit delete call.
@@ -3260,6 +4150,7 @@ export class FlexHarness<TScope = unknown> {
   private createUninitializedStoredSession(
     session: IFlexSession,
     storageKey: string,
+    compactorLifecycleController = new AbortController(),
   ): IStoredSessionState {
     const unavailable = new Proxy({} as plugins.IAgentSession, {
       get() {
@@ -3283,7 +4174,7 @@ export class FlexHarness<TScope = unknown> {
       agentEventStoreReleased: true,
       executionContextCloseCompleted: true,
       jobStoreReleased: true,
-      compactorLifecycleController: new AbortController(),
+      compactorLifecycleController,
       promptQueue: [],
       outstandingPromptsById: new Map(),
       terminalPromptQueueEntries: new Map(),
@@ -3296,6 +4187,7 @@ export class FlexHarness<TScope = unknown> {
     metadata: IFlexSession,
     scopeId: string,
     scope: TScope,
+    compactorLifecycleController = new AbortController(),
   ): Promise<IStoredSessionState> {
     const sessionId = metadata.sessionId;
     const compactorContext = this.createCompactorContext(
@@ -3380,7 +4272,7 @@ export class FlexHarness<TScope = unknown> {
         executionContextCloseCompleted: executionContextHandle?.close === undefined,
         jobStoreReleased: this.stores.jobs.releaseSession === undefined,
         jobs: executionContextHandle?.context.jobs,
-        compactorLifecycleController: new AbortController(),
+        compactorLifecycleController,
         promptQueue: [],
         outstandingPromptsById: new Map(),
         terminalPromptQueueEntries: new Map(),
@@ -3927,50 +4819,136 @@ export class FlexHarness<TScope = unknown> {
     if (errors.length > 0) throw combineErrors(errors);
   }
 
+  private collectSessionSubtree(
+    state: IStorageState,
+    rootSessionId: string,
+  ): IStoredSessionState[] {
+    const subtree: IStoredSessionState[] = [];
+    const pending = [rootSessionId];
+    const seen = new Set<string>();
+    while (pending.length > 0) {
+      const sessionId = pending.pop()!;
+      if (seen.has(sessionId)) {
+        throw new FlexHarnessValidationError('Session relationships contain a cycle.');
+      }
+      seen.add(sessionId);
+      const stored = state.sessions.get(sessionId);
+      if (!stored) continue;
+      subtree.push(stored);
+      const children = [...state.sessions.values()]
+        .filter((candidate) => candidate.session.parentSessionId === sessionId)
+        .map((candidate) => candidate.session.sessionId)
+        .sort()
+        .reverse();
+      pending.push(...children);
+    }
+    return subtree;
+  }
+
+  private tombstoneGroup(
+    state: IStorageState,
+    rootSessionId: string,
+  ): IFlexSessionTombstone[] {
+    return [...state.tombstones.values()]
+      .filter((tombstone) =>
+        (tombstone.rootSessionId ?? tombstone.sessionId) === rootSessionId)
+      .sort((left, right) =>
+        (right.depth ?? 0) - (left.depth ?? 0)
+        || left.sessionId.localeCompare(right.sessionId));
+  }
+
+  private descendantTombstoneRoots(
+    state: IStorageState,
+    ancestorSessionId: string,
+  ): string[] {
+    return [...new Set([...state.tombstones.values()]
+      .map((tombstone) => tombstone.rootSessionId ?? tombstone.sessionId)
+      .filter((rootSessionId) =>
+        rootSessionId !== ancestorSessionId
+        && this.isSessionAncestor(state, ancestorSessionId, rootSessionId)))]
+      .sort((left, right) =>
+        this.sessionAncestryDepth(state, right) - this.sessionAncestryDepth(state, left)
+        || left.localeCompare(right));
+  }
+
+  private orderTombstoneRootsChildFirst(
+    state: IStorageState,
+    rootSessionIds: readonly string[],
+  ): string[] {
+    return [...rootSessionIds].sort((left, right) =>
+      this.sessionAncestryDepth(state, right) - this.sessionAncestryDepth(state, left)
+      || left.localeCompare(right));
+  }
+
   private finishTombstoneCleanup(
     state: IStorageState,
-    sessionId: string,
+    rootSessionId: string,
     scopeId: string,
-    scope?: TScope,
+    invocation?: { scopeId: string; scope: TScope },
   ): Promise<void> {
-    const existing = state.tombstoneCleanups.get(sessionId);
+    const existing = state.tombstoneCleanups.get(rootSessionId);
     if (existing) return existing;
     let cleanup!: Promise<void>;
-    cleanup = this.finishTombstoneCleanupInternal(state, sessionId, scopeId, scope).finally(() => {
-      if (state.tombstoneCleanups.get(sessionId) === cleanup) {
-        state.tombstoneCleanups.delete(sessionId);
+    cleanup = this.finishTombstoneCleanupInternal(
+      state,
+      rootSessionId,
+      scopeId,
+      invocation,
+    ).finally(() => {
+      if (state.tombstoneCleanups.get(rootSessionId) === cleanup) {
+        state.tombstoneCleanups.delete(rootSessionId);
       }
     });
-    state.tombstoneCleanups.set(sessionId, cleanup);
+    state.tombstoneCleanups.set(rootSessionId, cleanup);
     return cleanup;
   }
 
   private async finishTombstoneCleanupInternal(
     state: IStorageState,
-    sessionId: string,
+    rootSessionId: string,
     scopeId: string,
-    scope?: TScope,
+    invocation?: { scopeId: string; scope: TScope },
   ): Promise<void> {
-    const retained = state.retainedSessionCleanups.get(sessionId);
-    if (retained) {
+    for (const descendantRoot of this.descendantTombstoneRoots(state, rootSessionId)) {
+      await this.finishTombstoneCleanup(state, descendantRoot, scopeId, invocation);
+    }
+    const group = this.tombstoneGroup(state, rootSessionId);
+    if (group.length === 0) return;
+    const groupIds = new Set(group.map((tombstone) => tombstone.sessionId));
+    const reason = this.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
+    const contextFor = (
+      sessionId: string,
+      retained?: IRetainedSessionCleanup,
+    ): IFlexAgentContextInvocation<TScope> | undefined => invocation
+      ? this.createCompactorContext(
+          invocation.scopeId,
+          invocation.scope,
+          state.storageKey,
+          sessionId,
+        )
+      : retained?.stored.compactorContext as IFlexAgentContextInvocation<TScope> | undefined;
+    for (const sessionId of groupIds) {
+      const retained = state.retainedSessionCleanups.get(sessionId);
+      const context = contextFor(sessionId, retained);
+      if (retained) {
+        this.abortCompactorLifecycle(retained.stored, reason);
+        this.cancelStoredPromptQueue(retained.stored, reason, undefined, context);
+      }
+      const run = state.activeRuns.get(sessionId);
+      if (run) this.cancelRun(run, reason, context);
+    }
+    await Promise.allSettled([...groupIds]
+      .map((sessionId) => state.sessionInitializations.get(sessionId))
+      .filter((completion): completion is Promise<void> => completion !== undefined));
+    for (const tombstone of group) {
+      const sessionId = tombstone.sessionId;
+      const retained = state.retainedSessionCleanups.get(sessionId);
       const errors: unknown[] = [];
-      const reason = this.trustInternalError(new FlexHarnessAbortError('The session was deleted.'));
-      const invocation = scope === undefined
-        ? retained.stored.compactorContext
-        : this.createCompactorContext(scopeId, scope, state.storageKey, sessionId);
-      this.abortCompactorLifecycle(retained.stored, reason);
-      this.cancelStoredPromptQueue(retained.stored, reason, undefined, invocation);
       const run = state.activeRuns.get(sessionId);
-      if (run) this.cancelRun(run, reason, invocation as IFlexAgentContextInvocation<TScope>);
-      if (run) {
-        const settled = await Promise.allSettled([run.completion]);
-        if (settled[0].status === 'rejected') {
-          this.appendUnexpectedErrors(errors, settled[0].reason);
-        }
-      }
-      if (!retained.stored.agentSessionAbortCompleted) {
+      const context = contextFor(sessionId, retained);
+      if (retained && !retained.stored.agentSessionAbortCompleted) {
         try {
-          await this.abortStoredSession(retained.stored, reason, invocation);
+          await this.abortStoredSession(retained.stored, reason, context);
         } catch (error) {
           errors.push(this.projectOperationError(
             error,
@@ -3981,53 +4959,66 @@ export class FlexHarness<TScope = unknown> {
           ));
         }
       }
-      if (retained.stored.promptQueueDrain) {
-        const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
+      if (run) {
+        const settled = await Promise.allSettled([run.completion]);
         if (settled[0].status === 'rejected') {
           this.appendUnexpectedErrors(errors, settled[0].reason);
         }
       }
-      try {
-        await this.closeStoredSession(retained.stored, invocation);
-      } catch (error) {
-        this.appendUnexpectedErrors(errors, this.projectOperationError(
-          error,
-          'toolCleanup',
-          scopeId,
-          sessionId,
-          'session-delete',
-        ));
+      if (retained) {
+        if (retained.stored.promptQueueDrain) {
+          const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
+          if (settled[0].status === 'rejected') errors.push(settled[0].reason);
+        }
+        try {
+          await this.closeStoredSession(retained.stored, context);
+        } catch (error) {
+          this.appendUnexpectedErrors(errors, this.projectOperationError(
+            error,
+            'toolCleanup',
+            scopeId,
+            sessionId,
+            'session-delete',
+          ));
+        }
       }
       if (errors.length > 0) {
-        if (state.lifecycle === 'retired' && !this.storedSessionCleanupCompleted(retained.stored)) {
-          this.orphanedStoredSessions.add(retained.stored);
-        }
+        if (
+          retained
+          && state.lifecycle === 'retired'
+          && !this.storedSessionCleanupCompleted(retained.stored)
+        ) this.orphanedStoredSessions.add(retained.stored);
         throw combineErrors(errors);
       }
-      this.purgeStoredPromptQueue(retained.stored);
-    }
-    if (!retained?.domainsCompleted) {
-      if (this.hasOrphanedSessionResources(state.storageKey, sessionId)) {
-        throw new Error(`Session "${sessionId}" still has runtime cleanup ownership.`);
+      if (retained) this.purgeStoredPromptQueue(retained.stored);
+      if (!retained?.domainsCompleted) {
+        if (this.hasOrphanedSessionResources(state.storageKey, sessionId)) {
+          throw new Error(`Session "${sessionId}" still has runtime cleanup ownership.`);
+        }
+        await this.cleanupSessionDomains(state.storageKey, sessionId);
+        if (retained) retained.domainsCompleted = true;
       }
-      await this.cleanupSessionDomains(state.storageKey, sessionId);
-      if (retained) retained.domainsCompleted = true;
     }
     await this.mutateScope(state, () => {
-      state.tombstones.delete(sessionId);
-      state.retainedSessionCleanups.delete(sessionId);
+      for (const tombstone of group) {
+        state.tombstones.delete(tombstone.sessionId);
+        state.retainedSessionCleanups.delete(tombstone.sessionId);
+      }
     }, true);
   }
 
   private async fenceNamespace(state: IStorageState, currentRun: IActiveRun, cause: unknown): Promise<void> {
     if (state.lifecycle === 'retired') return;
+    if (this.storageDrains.has(state.storageKey)) {
+      state.fenceAdditionalErrors.push(cause);
+      return;
+    }
     if (state.fenceInProgress) {
       state.fenceAdditionalErrors.push(cause);
       return;
     }
     state.fenceInProgress = true;
     state.lifecycle = 'fenced';
-    const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
     const reason = this.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
     if (!state.compactorLifecycleController.signal.aborted) {
       state.compactorLifecycleController.abort(reason);
@@ -4056,23 +5047,49 @@ export class FlexHarness<TScope = unknown> {
       }
       const otherRuns = [...state.activeRuns.values()].filter((run) => run !== currentRun);
       for (const run of otherRuns) this.cancelRun(run, reason, contextFor(run.sessionId));
-      const runResults = await Promise.allSettled(otherRuns.map((run) => run.completion));
+      const dependentRuns = otherRuns.filter((run) =>
+        this.sessionsAreDependencyRelated(state, currentRun.sessionId, run.sessionId));
+      const independentRuns = otherRuns.filter((run) => !dependentRuns.includes(run));
+      const runResults = await Promise.allSettled(independentRuns.map((run) => run.completion));
       for (const result of runResults) {
         if (result.status === 'rejected') this.appendUnexpectedErrors(cleanupErrors, result.reason);
       }
+      if (dependentRuns.length > 0) {
+        state.fenceAdditionalErrors.push(cause, ...cleanupErrors);
+        const stateLoad = this.stateLoads.get(state.storageKey);
+        if (!stateLoad) {
+          throw combineErrors([cause, ...cleanupErrors, new Error(
+            'The fenced namespace no longer has durable cleanup ownership.',
+          )]);
+        }
+        const deferredDrain = this.drainStorage(
+          state.storageKey,
+          stateLoad,
+          reason,
+          { scopeId: invocation.scopeId, scope: invocation.scope },
+        );
+        void deferredDrain.catch(() => undefined);
+        return;
+      }
+      const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
       await Promise.allSettled([...state.sessionInitializations.values()]);
       cleanupErrors.push(...await this.closeOrphanedResources(state.storageKey));
       await state.scopeQueue;
-      const currentTombstoneCleanup = state.tombstoneCleanups.get(currentRun.sessionId);
+      const currentTombstoneRoot = state.tombstones.get(currentRun.sessionId)?.rootSessionId
+        ?? currentRun.sessionId;
+      const currentTombstoneCleanup = state.tombstoneCleanups.get(currentTombstoneRoot);
+      const currentTombstoneSessions = new Set(
+        this.tombstoneGroup(state, currentTombstoneRoot).map((tombstone) => tombstone.sessionId),
+      );
       if (currentTombstoneCleanup) {
         this.retainOrphanedTombstoneCleanup(
           state.storageKey,
-          currentRun.sessionId,
+          currentTombstoneRoot,
           currentTombstoneCleanup,
         );
       }
       const tombstoneAttempts = [...state.tombstoneCleanups.entries()]
-        .filter(([sessionId]) => sessionId !== currentRun.sessionId);
+        .filter(([rootSessionId]) => rootSessionId !== currentTombstoneRoot);
       const tombstoneResults = await Promise.allSettled(
         tombstoneAttempts.map(([, cleanup]) => cleanup),
       );
@@ -4080,11 +5097,14 @@ export class FlexHarness<TScope = unknown> {
         if (result.status === 'rejected') this.appendUnexpectedErrors(cleanupErrors, result.reason);
       }
       const attemptedTombstones = new Set(tombstoneAttempts.map(([sessionId]) => sessionId));
+      const attemptedTombstoneSessions = new Set([...attemptedTombstones].flatMap((rootSessionId) =>
+        this.tombstoneGroup(state, rootSessionId).map((tombstone) => tombstone.sessionId)));
       const storedSessions = new Set([
         ...state.sessions.values(),
         ...[...state.retainedSessionCleanups]
           .filter(([sessionId]) =>
-            sessionId !== currentRun.sessionId && !attemptedTombstones.has(sessionId))
+            !currentTombstoneSessions.has(sessionId)
+            && !attemptedTombstoneSessions.has(sessionId))
           .map(([, retained]) => retained.stored),
       ]);
       for (const stored of storedSessions) {
@@ -4119,15 +5139,16 @@ export class FlexHarness<TScope = unknown> {
       if (cleanupErrors.length > 0) throw combineErrors([cause, ...cleanupErrors]);
       state.lifecycle = 'retired';
       state.sessions.clear();
-      const currentRetainedCleanup = state.retainedSessionCleanups.get(currentRun.sessionId);
+      const currentRetainedCleanups = [...state.retainedSessionCleanups]
+        .filter(([sessionId]) => currentTombstoneSessions.has(sessionId));
       state.retainedSessionCleanups.clear();
-      if (currentRetainedCleanup) {
-        state.retainedSessionCleanups.set(currentRun.sessionId, currentRetainedCleanup);
+      for (const [sessionId, retained] of currentRetainedCleanups) {
+        state.retainedSessionCleanups.set(sessionId, retained);
       }
       state.sessionDeletions.clear();
       state.tombstoneCleanups.clear();
       if (currentTombstoneCleanup) {
-        state.tombstoneCleanups.set(currentRun.sessionId, currentTombstoneCleanup);
+        state.tombstoneCleanups.set(currentTombstoneRoot, currentTombstoneCleanup);
       }
       state.activeRuns.clear();
       state.pendingPermissions.clear();
@@ -4143,6 +5164,75 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private deferNamespaceDrain(
+    state: IStorageState,
+    cause: unknown,
+    invocation?: { scopeId: string; scope: TScope },
+  ): void {
+    state.lifecycle = 'fenced';
+    state.fenceAdditionalErrors.push(cause);
+    const stateLoad = this.stateLoads.get(state.storageKey);
+    if (!stateLoad) return;
+    const drain = this.drainStorage(
+      state.storageKey,
+      stateLoad,
+      this.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.')),
+      invocation,
+    );
+    void drain.catch(() => undefined);
+  }
+
+  private sessionsAreDependencyRelated(
+    state: IStorageState,
+    leftSessionId: string,
+    rightSessionId: string,
+  ): boolean {
+    return this.isSessionAncestor(state, leftSessionId, rightSessionId)
+      || this.isSessionAncestor(state, rightSessionId, leftSessionId);
+  }
+
+  private isSessionAncestor(
+    state: IStorageState,
+    ancestorSessionId: string,
+    descendantSessionId: string,
+  ): boolean {
+    const visited = new Set<string>();
+    let currentId: string | undefined = descendantSessionId;
+    while (currentId) {
+      if (visited.has(currentId)) return false;
+      visited.add(currentId);
+      const parentSessionId = this.sessionParentSessionId(state, currentId);
+      if (parentSessionId === ancestorSessionId) return true;
+      currentId = parentSessionId;
+    }
+    return false;
+  }
+
+  private sessionAncestryDepth(state: IStorageState, sessionId: string): number {
+    const visited = new Set<string>();
+    let currentId: string | undefined = sessionId;
+    let depth = 0;
+    while (currentId) {
+      if (visited.has(currentId)) return depth;
+      visited.add(currentId);
+      const parentSessionId = this.sessionParentSessionId(state, currentId);
+      if (!parentSessionId) return depth;
+      depth++;
+      currentId = parentSessionId;
+    }
+    return depth;
+  }
+
+  private sessionParentSessionId(state: IStorageState, sessionId: string): string | undefined {
+    return this.sessionMetadata(state, sessionId)?.parentSessionId
+      ?? state.tombstones.get(sessionId)?.parentSessionId;
+  }
+
+  private sessionMetadata(state: IStorageState, sessionId: string): IFlexSession | undefined {
+    return state.sessions.get(sessionId)?.session
+      ?? state.retainedSessionCleanups.get(sessionId)?.stored.session;
+  }
+
   private async closeStoredSession(
     stored: IStoredSessionState,
     context: IFlexAgentContextInvocation<unknown> = stored.compactorContext!,
@@ -4497,20 +5587,27 @@ export class FlexHarness<TScope = unknown> {
       }
       this.purgeStoredPromptQueue(stored);
     }
-    for (const sessionId of [...state.tombstones.keys()]) {
-      if (attemptedTombstones.has(sessionId)) continue;
-      const retained = state.retainedSessionCleanups.get(sessionId);
+    const roots = this.orderTombstoneRootsChildFirst(
+      state,
+      [...new Set([...state.tombstones.values()].map((tombstone) =>
+        tombstone.rootSessionId ?? tombstone.sessionId))],
+    );
+    for (const rootSessionId of roots) {
+      if (attemptedTombstones.has(rootSessionId)) continue;
+      if (this.descendantTombstoneRoots(state, rootSessionId).length > 0) continue;
+      const retained = state.retainedSessionCleanups.get(rootSessionId);
       try {
         await this.finishTombstoneCleanup(
           state,
-          sessionId,
+          rootSessionId,
           invocation?.scopeId ?? retained?.stored.session.scopeId ?? state.scopeIdHint,
-          invocation?.scope,
+          invocation,
         );
       } catch (error) {
         this.appendUnexpectedErrors(errors, error);
       }
     }
+    errors.push(...state.fenceAdditionalErrors.splice(0));
     if (errors.length > 0) throw combineErrors(errors);
     state.lifecycle = 'retired';
     state.sessions.clear();