@modelprofile.com/flexharness 5.2.0 → 5.3.0

package/ts/classes.flexharness.ts

@@ -35,6 +35,8 @@ import type {
   IFlexCreateSessionOptions,
   IFlexDeleteSessionGenerationCohortInput,
   IFlexDeleteSessionGenerationCohortResult,
+  IFlexDelegatedRunAdmissionContext,
+  IFlexDelegatedRunAdmissionLease,
   IFlexErrorInfo,
   IFlexEventArchiveMetadata,
   IFlexExecutionContextHandle,
@@ -297,6 +299,7 @@ interface IStorageState {
   tombstones: Map<string, IFlexSessionTombstone>;
   tombstoneCleanups: Map<string, Promise<void>>;
   activeRuns: Map<string, IActiveRun>;
+  delegatedRunAdmissionOwners: Set<IDelegatedRunAdmissionOwner>;
   pendingPermissions: Map<string, IPendingPermission>;
   scopeQueue: Promise<void>;
   lifecycle: 'active' | 'retiring' | 'fenced' | 'retired';
@@ -331,6 +334,7 @@ interface IActiveRun {
   callbacksClosed: boolean;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
+  trustedToolExecutionErrors: Map<string, Error>;
   subagentCallCount: number;
   subagentSessionIds: Set<string>;
   pendingPermissionIds: Set<string>;
@@ -338,9 +342,56 @@ interface IActiveRun {
   reservedUserMessage?: IFlexMessage;
   reservedAssistantMessage?: IFlexMessage;
   modelResolution?: IFlexResolvedModel;
+  delegatedRunAdmissionOwner?: IDelegatedRunAdmissionOwner;
+  delegatedRunAdmissionClose?: Promise<void>;
   completion: Promise<IFlexPromptResult>;
 }
 
+interface IDelegatedRunAdmissionSeed {
+  readonly state: IStorageState;
+  readonly childStored: IStoredSessionState;
+  readonly parentRun: IActiveRun;
+  readonly parentStored: IStoredSessionState;
+  readonly scopeId: string;
+  readonly scope: unknown;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly sessionGenerationId: string;
+  readonly sessionGenerationSequence: number;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly parentQueueId: string;
+  readonly parentRunId: string;
+  readonly parentToolCallId: string;
+  readonly agent: string;
+  readonly depth: number;
+}
+
+type TDelegatedRunAdmissionOwnerStatus =
+  | 'acquiring'
+  | 'acquired'
+  | 'close-requested'
+  | 'retrying'
+  | 'closed';
+
+interface IDelegatedRunAdmissionOwner {
+  readonly storageState: IStorageState;
+  readonly run: IActiveRun;
+  readonly context: Readonly<IFlexDelegatedRunAdmissionContext<unknown>>;
+  status: TDelegatedRunAdmissionOwnerStatus;
+  acquisitionSettled: boolean;
+  acquisitionDetached: boolean;
+  acquisitionCompletion?: Promise<void>;
+  acquisitionError?: Error;
+  lease?: IFlexDelegatedRunAdmissionLease;
+  closeAttempt?: Promise<void>;
+  closeAttemptSequence: number;
+  closeFailure?: { sequence: number; error: Error };
+}
+
 interface IQueuedPrompt {
   state: IStorageState;
   stored: IStoredSessionState;
@@ -357,6 +408,7 @@ interface IQueuedPrompt {
   startedAt?: string;
   prompt?: INormalizedFlexPrompt;
   options?: IFlexPromptOptions;
+  delegationSeed?: IDelegatedRunAdmissionSeed;
   byteSize: number;
   completion: Promise<IFlexPromptResult>;
   resolveCompletion: (result: IFlexPromptResult) => void;
@@ -630,6 +682,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
   private readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
+  private readonly delegatedRunAdmissionProvider: IFlexHarnessOptions<TScope>['delegatedRunAdmissionProvider'];
   private readonly stores: IFlexHarnessStores;
   private readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
   private readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
@@ -693,6 +746,7 @@ export class FlexHarness<TScope = unknown> {
     this.toolProvider = options.toolProvider;
     this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
+    this.delegatedRunAdmissionProvider = options.delegatedRunAdmissionProvider;
     this.stores = requireHarnessStores(options.stores ?? new InMemoryFlexHarnessStores());
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
@@ -1779,7 +1833,7 @@ export class FlexHarness<TScope = unknown> {
             promptOptions,
             undefined,
             undefined,
-            false,
+            undefined,
             signal,
             true,
           );
@@ -3085,7 +3139,7 @@ export class FlexHarness<TScope = unknown> {
     options: IFlexPromptOptions,
     scheduleKey?: string,
     debounceMs?: number,
-    subagentAdmission = false,
+    delegationSeed?: IDelegatedRunAdmissionSeed,
     admissionSignal?: AbortSignal,
     slashCommandAdmission = false,
   ): Promise<{
@@ -3145,11 +3199,14 @@ export class FlexHarness<TScope = unknown> {
       if (stored.pendingReversion) {
         throw new FlexHarnessSessionBusyError(sessionId, 'has a pending reversion operation');
       }
-      if (stored.session.agent !== undefined && !subagentAdmission) {
+      if (stored.session.agent !== undefined && delegationSeed === undefined) {
         throw new FlexHarnessValidationError(
           'Subagent sessions can only be prompted through the foreground delegate tool.',
         );
       }
+      if (delegationSeed !== undefined) {
+        this.assertDelegatedRunAdmissionOwnership(delegationSeed, state, stored, scopeId);
+      }
       if (stored.outstandingPromptsById.size >= this.promptQueueLimits.maxOutstandingPromptsPerSession) {
         throw new FlexHarnessQueueFullError(
           `Session "${sessionId}" has reached its outstanding prompt limit.`,
@@ -3188,7 +3245,7 @@ export class FlexHarness<TScope = unknown> {
         state,
         stored,
         scopeId,
-        scope: resolved.scope.scope,
+        scope: delegationSeed === undefined ? resolved.scope.scope : delegationSeed.scope,
         sessionId,
         queueId: plugins.crypto.randomUUID(),
         queueSequence: ++this.promptQueueSequence,
@@ -3197,6 +3254,7 @@ export class FlexHarness<TScope = unknown> {
         ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
         prompt: normalizedPrompt,
         options: normalizedOptions,
+        ...(delegationSeed === undefined ? {} : { delegationSeed }),
         byteSize,
         completion,
         resolveCompletion,
@@ -3318,6 +3376,7 @@ export class FlexHarness<TScope = unknown> {
       callbacksClosed: false,
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
+      trustedToolExecutionErrors: new Map(),
       subagentCallCount: 0,
       subagentSessionIds: new Set(),
       pendingPermissionIds: new Set(),
@@ -3336,6 +3395,258 @@ export class FlexHarness<TScope = unknown> {
       || run.stored.outstandingPromptsById.get(run.queueId) !== queued
       || run.state.activeRuns.get(run.sessionId) !== run
     ) throw this.trustInternalError(new FlexHarnessAbortError('The prompt was retired during admission.'));
+    if (queued.delegationSeed) {
+      this.assertDelegatedRunAdmissionOwnership(
+        queued.delegationSeed,
+        run.state,
+        run.stored,
+        run.scopeId,
+      );
+      if (
+        run.queueId !== queued.queueId
+        || run.runId !== queued.runId
+        || run.sessionId !== queued.delegationSeed.sessionId
+      ) {
+        throw this.trustInternalError(
+          new FlexHarnessAbortError('The delegated prompt lost its exact child run ownership.'),
+        );
+      }
+    }
+  }
+
+  private assertDelegatedRunAdmissionOwnership(
+    seed: IDelegatedRunAdmissionSeed,
+    state: IStorageState,
+    childStored: IStoredSessionState,
+    scopeId: string,
+  ): void {
+    const child = childStored.session;
+    const parentRun = seed.parentRun;
+    const parent = seed.parentStored.session;
+    const parentPartId = parentRun.toolPartIds.get(seed.parentToolCallId);
+    const parentPart = parentRun.callbackParts.find((part): part is IFlexToolMessagePart =>
+      part.type === 'tool'
+      && part.partId === parentPartId
+      && part.toolCallId === seed.parentToolCallId);
+    if (
+      seed.state !== state
+      || seed.storageKey !== state.storageKey
+      || seed.scopeId !== scopeId
+      || seed.childStored !== childStored
+      || childStored.storageKey !== seed.storageKey
+      || state.sessions.get(seed.sessionId) !== childStored
+      || state.tombstones.has(seed.sessionId)
+      || state.initializingSessions.has(seed.sessionId)
+      || child.sessionId !== seed.sessionId
+      || child.sessionGenerationId !== seed.sessionGenerationId
+      || child.sessionGenerationSequence !== seed.sessionGenerationSequence
+      || child.parentSessionId !== seed.parentSessionId
+      || child.parentRunId !== seed.originParentRunId
+      || child.parentToolCallId !== seed.originParentToolCallId
+      || child.agent !== seed.agent
+      || child.depth !== seed.depth
+      || seed.parentStored !== parentRun.stored
+      || seed.parentStored.storageKey !== seed.storageKey
+      || parentRun.state !== state
+      || parentRun.scopeId !== seed.scopeId
+      || parentRun.scope !== seed.scope
+      || parentRun.sessionId !== seed.parentSessionId
+      || parentRun.queueId !== seed.parentQueueId
+      || parentRun.runId !== seed.parentRunId
+      || state.sessions.get(seed.parentSessionId) !== seed.parentStored
+      || state.tombstones.has(seed.parentSessionId)
+      || parent.sessionId !== seed.parentSessionId
+      || parent.sessionGenerationId !== seed.parentSessionGenerationId
+      || parent.sessionGenerationSequence !== seed.parentSessionGenerationSequence
+      || state.activeRuns.get(seed.parentSessionId) !== parentRun
+      || parentRun.callbacksClosed
+      || parentRun.controller.signal.aborted
+      || parentPart?.status !== 'running'
+    ) {
+      throw this.trustInternalError(
+        new FlexHarnessAbortError('The delegated prompt lost its exact parent or child ownership.'),
+      );
+    }
+  }
+
+  private async acquireDelegatedRunAdmission(
+    queued: IQueuedPrompt,
+    run: IActiveRun,
+  ): Promise<void> {
+    const seed = queued.delegationSeed;
+    const provider = this.delegatedRunAdmissionProvider;
+    if (!seed || !provider) return;
+    const context = Object.freeze({
+      scopeId: seed.scopeId,
+      scope: seed.scope as TScope,
+      storageKey: seed.storageKey,
+      sessionId: seed.sessionId,
+      sessionGenerationId: seed.sessionGenerationId,
+      sessionGenerationSequence: seed.sessionGenerationSequence,
+      queueId: queued.queueId,
+      runId: run.runId,
+      parentSessionId: seed.parentSessionId,
+      parentSessionGenerationId: seed.parentSessionGenerationId,
+      parentSessionGenerationSequence: seed.parentSessionGenerationSequence,
+      parentQueueId: seed.parentQueueId,
+      parentRunId: seed.parentRunId,
+      parentToolCallId: seed.parentToolCallId,
+      agent: seed.agent,
+      depth: seed.depth,
+      signal: run.controller.signal,
+    });
+    const owner: IDelegatedRunAdmissionOwner = {
+      storageState: run.state,
+      run,
+      context,
+      status: 'acquiring',
+      acquisitionSettled: false,
+      acquisitionDetached: false,
+      closeAttemptSequence: 0,
+    };
+    run.state.delegatedRunAdmissionOwners.add(owner);
+    run.delegatedRunAdmissionOwner = owner;
+    const acquisition = Promise.resolve()
+      .then(() => provider.acquireDelegatedRunAdmission(context))
+      .then((lease) => this.normalizeDelegatedRunAdmissionLease(lease))
+      .then(
+        (lease) => {
+          owner.lease = lease;
+          owner.acquisitionSettled = true;
+          if (owner.status === 'acquiring') owner.status = 'acquired';
+          if (owner.status === 'close-requested') {
+            void this.startDelegatedRunAdmissionCloseAttempt(owner).catch(() => undefined);
+          }
+        },
+        (error: unknown) => {
+          owner.acquisitionError = this.projectExternalError(
+            run,
+            error,
+            'delegatedRunAdmissionProvider',
+          );
+          owner.acquisitionSettled = true;
+          owner.status = 'closed';
+          run.state.delegatedRunAdmissionOwners.delete(owner);
+        },
+      );
+    owner.acquisitionCompletion = acquisition;
+
+    let resolveAbort!: () => void;
+    const abort = new Promise<'aborted'>((resolve) => {
+      resolveAbort = () => resolve('aborted');
+    });
+    run.controller.signal.addEventListener('abort', resolveAbort, { once: true });
+    if (run.controller.signal.aborted) resolveAbort();
+    try {
+      const outcome = await Promise.race([
+        acquisition.then(() => 'settled' as const),
+        abort,
+      ]);
+      if (outcome === 'aborted') {
+        owner.acquisitionDetached = true;
+        throw run.controller.signal.reason ?? this.trustInternalError(new FlexHarnessAbortError());
+      }
+      if (run.controller.signal.aborted) {
+        throw run.controller.signal.reason ?? this.trustInternalError(new FlexHarnessAbortError());
+      }
+      if (owner.acquisitionError) throw owner.acquisitionError;
+      if (owner.status !== 'acquired' || !owner.lease) {
+        throw this.trustInternalError(
+          new FlexHarnessAbortError('The delegated run admission was retired during acquisition.'),
+        );
+      }
+    } finally {
+      run.controller.signal.removeEventListener('abort', resolveAbort);
+    }
+  }
+
+  private normalizeDelegatedRunAdmissionLease(
+    value: IFlexDelegatedRunAdmissionLease,
+  ): IFlexDelegatedRunAdmissionLease {
+    if (!value || (typeof value !== 'object' && typeof value !== 'function')) {
+      throw new FlexHarnessValidationError(
+        'Delegated run admission provider returned an invalid lease.',
+      );
+    }
+    const close = value.close;
+    if (typeof close !== 'function') {
+      throw new FlexHarnessValidationError(
+        'Delegated run admission provider returned an invalid lease.',
+      );
+    }
+    return Object.freeze({ close: () => close.call(value) });
+  }
+
+  private requestDelegatedRunAdmissionClose(
+    owner: IDelegatedRunAdmissionOwner,
+  ): Promise<void> {
+    const priorAttemptSequence = owner.closeAttemptSequence;
+    const joinedAttempt = owner.closeAttempt;
+    if (owner.status === 'closed') return Promise.resolve();
+    if (owner.status !== 'retrying') owner.status = 'close-requested';
+    return (async () => {
+      await owner.acquisitionCompletion;
+      if (owner.status === 'closed') return;
+      if (joinedAttempt) {
+        await joinedAttempt;
+        return;
+      }
+      if (owner.closeAttempt) {
+        await owner.closeAttempt;
+        return;
+      }
+      if (owner.closeFailure && owner.closeFailure.sequence > priorAttemptSequence) {
+        throw owner.closeFailure.error;
+      }
+      await this.startDelegatedRunAdmissionCloseAttempt(owner);
+    })();
+  }
+
+  private startDelegatedRunAdmissionCloseAttempt(
+    owner: IDelegatedRunAdmissionOwner,
+  ): Promise<void> {
+    if (owner.closeAttempt) return owner.closeAttempt;
+    if (!owner.lease) {
+      throw new Error('Acquired delegated run admission has no lease.');
+    }
+    owner.status = 'retrying';
+    owner.closeFailure = undefined;
+    const sequence = ++owner.closeAttemptSequence;
+    let attempt!: Promise<void>;
+    attempt = Promise.resolve()
+      .then(() => owner.lease!.close())
+      .then(() => {
+        owner.status = 'closed';
+        delete owner.lease;
+        owner.storageState.delegatedRunAdmissionOwners.delete(owner);
+      }, (error: unknown) => {
+        const projected = this.projectExternalError(
+          owner.run,
+          error,
+          'delegatedRunAdmissionProvider',
+        );
+        owner.closeFailure = { sequence, error: projected };
+        owner.status = 'close-requested';
+        throw projected;
+      })
+      .finally(() => {
+        if (owner.closeAttempt === attempt) owner.closeAttempt = undefined;
+      });
+    owner.closeAttempt = attempt;
+    return attempt;
+  }
+
+  private async closeRunDelegatedRunAdmission(
+    run: IActiveRun,
+    awaitSettlement = true,
+  ): Promise<void> {
+    const owner = run.delegatedRunAdmissionOwner;
+    if (!owner) return;
+    if (!run.delegatedRunAdmissionClose) {
+      run.delegatedRunAdmissionClose = this.requestDelegatedRunAdmissionClose(owner);
+      void run.delegatedRunAdmissionClose.catch(() => undefined);
+    }
+    if (awaitSettlement) await run.delegatedRunAdmissionClose;
   }
 
   private async promoteQueuedPrompt(queued: IQueuedPrompt, run: IActiveRun): Promise<void> {
@@ -3343,13 +3654,19 @@ export class FlexHarness<TScope = unknown> {
     const options = queued.options!;
     let projectionReserved = false;
     try {
+      this.assertPromptPromotion(queued, run);
+      await this.acquireDelegatedRunAdmission(queued, run);
+      this.assertPromptPromotion(queued, run);
       await this.commitRevertedBranch(run.state, run.stored, run.scopeId, run.scope as TScope);
+      this.assertPromptPromotion(queued, run);
+      const generationPrompt = cloneSerializable(prompt.modelMessage.content) as Parameters<
+        plugins.IAgentSession['beginGeneration']
+      >[0];
+      this.assertPromptPromotion(queued, run);
       run.transaction = await this.withRunCompactorContext(
         run,
         () => run.stored.agentSession.beginGeneration(
-          cloneSerializable(prompt.modelMessage.content) as Parameters<
-            plugins.IAgentSession['beginGeneration']
-          >[0],
+          generationPrompt,
           { generationId: run.runId },
         ),
       );
@@ -3411,10 +3728,21 @@ export class FlexHarness<TScope = unknown> {
       let cleanupErrors: unknown[] = [];
       let cleanupFailure: unknown;
       try {
-        cleanupErrors = await this.rollbackAdmission(run, projectionReserved, safeError);
+        await this.closeRunDelegatedRunAdmission(
+          run,
+          !run.delegatedRunAdmissionOwner?.acquisitionDetached,
+        );
+      } catch (closeError) {
+        cleanupErrors.push(closeError);
+      }
+      try {
+        cleanupErrors.push(...await this.rollbackAdmission(run, projectionReserved, safeError));
       } catch (rollbackError) {
         cleanupFailure = rollbackError;
       }
+      if (cleanupFailure !== undefined && cleanupErrors.length > 0) {
+        cleanupFailure = combineErrors([cleanupFailure, ...cleanupErrors]);
+      }
       if (run.state.lifecycle === 'fenced' && cleanupFailure === undefined) {
         const combined = combineErrors([safeError, ...cleanupErrors]);
         try {
@@ -3526,6 +3854,7 @@ export class FlexHarness<TScope = unknown> {
     stored.outstandingPromptBytes = Math.max(0, stored.outstandingPromptBytes - queued.byteSize);
     delete queued.prompt;
     delete queued.options;
+    delete queued.delegationSeed;
     const terminal: IFlexPromptQueueEntry = {
       ...this.projectPromptQueueEntry(queued),
       status,
@@ -3587,6 +3916,11 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private purgeStoredPromptQueue(stored: IStoredSessionState): void {
+    for (const queued of stored.outstandingPromptsById.values()) {
+      delete queued.prompt;
+      delete queued.options;
+      delete queued.delegationSeed;
+    }
     stored.promptQueue.length = 0;
     stored.outstandingPromptsById.clear();
     stored.terminalPromptQueueEntries.clear();
@@ -3606,6 +3940,7 @@ export class FlexHarness<TScope = unknown> {
       const result = normalizeRunResult(rawResult);
       if (!run.modelResolution) throw new FlexHarnessValidationError('Generation completed without a resolved model.');
       await this.finalizeRunReversion(run, 'completed');
+      await this.closeRunDelegatedRunAdmission(run);
       const terminal = this.buildTerminal(run, 'completed', result);
       try {
         await this.mutateProjection(run.state, run.stored, () => {
@@ -3683,10 +4018,19 @@ export class FlexHarness<TScope = unknown> {
       ? run.ownerCancellation!
       : this.projectExternalError(run, error, generated ? 'persistence' : 'agentSession');
     const errors: unknown[] = [safeError];
+    let reversionFailed = false;
     try {
       await this.finalizeRunReversion(run, cancelled ? 'cancelled' : 'failed');
     } catch (reversionError) {
       errors.push(reversionError);
+      reversionFailed = true;
+    }
+    try {
+      await this.closeRunDelegatedRunAdmission(run);
+    } catch (closeError) {
+      if (!errors.includes(closeError)) errors.push(closeError);
+    }
+    if (reversionFailed) {
       const combined = combineErrors(errors);
       await this.fenceNamespace(run.state, run, combined);
       throw combined;
@@ -4613,15 +4957,27 @@ export class FlexHarness<TScope = unknown> {
       .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}`,
+      description: `Run one configured FlexHarness subagent in the foreground and return its final text. Omit taskId to create a new child. Supply taskId only to resume the exact child ID returned by an earlier completed delegate call in a later parent run.\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(),
+        taskId: plugins.z.string()
+          .describe('Omit for a new child. For a later-run resume, use only the exact taskId returned by an earlier completed delegate call.')
+          .optional(),
       }).strict(),
-      execute: (input: IFlexSubagentTaskInput, options?: { toolCallId?: string }) =>
-        this.executeSubagentTask(run, input, options?.toolCallId),
+      execute: async (input: IFlexSubagentTaskInput, options?: { toolCallId?: string }) => {
+        try {
+          return await this.executeSubagentTask(run, input, options?.toolCallId);
+        } catch (error) {
+          if (
+            options?.toolCallId
+            && error instanceof FlexHarnessValidationError
+            && this.trustedInternalErrors.has(error)
+          ) run.trustedToolExecutionErrors.set(options.toolCallId, error);
+          throw error;
+        }
+      },
     });
   }
 
@@ -4716,6 +5072,12 @@ export class FlexHarness<TScope = unknown> {
         ...(definition.system === undefined ? {} : { system: definition.system }),
         ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
       };
+      const delegationSeed = this.createDelegatedRunAdmissionSeed(
+        run,
+        child,
+        definition,
+        toolCallId,
+      );
       queued = await this.enqueuePromptInternal(
         run.scopeId,
         child.session.sessionId,
@@ -4723,7 +5085,7 @@ export class FlexHarness<TScope = unknown> {
         childOptions,
         undefined,
         undefined,
-        true,
+        delegationSeed,
         run.controller.signal,
       );
       admission = await queued.started;
@@ -4777,6 +5139,42 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private createDelegatedRunAdmissionSeed(
+    run: IActiveRun,
+    child: IStoredSessionState,
+    definition: Readonly<IFlexSubagentDefinition>,
+    toolCallId: string,
+  ): IDelegatedRunAdmissionSeed {
+    const childGeneration = requireSessionGeneration(child.session);
+    const parentGeneration = requireSessionGeneration(run.stored.session);
+    if (!child.session.parentRunId || !child.session.parentToolCallId) {
+      throw new FlexHarnessValidationError('Subagent session origin metadata is missing.');
+    }
+    const seed = Object.freeze({
+      state: run.state,
+      childStored: child,
+      parentRun: run,
+      parentStored: run.stored,
+      scopeId: run.scopeId,
+      scope: run.scope,
+      storageKey: run.state.storageKey,
+      sessionId: child.session.sessionId,
+      ...childGeneration,
+      originParentRunId: child.session.parentRunId,
+      originParentToolCallId: child.session.parentToolCallId,
+      parentSessionId: run.sessionId,
+      parentSessionGenerationId: parentGeneration.sessionGenerationId,
+      parentSessionGenerationSequence: parentGeneration.sessionGenerationSequence,
+      parentQueueId: run.queueId,
+      parentRunId: run.runId,
+      parentToolCallId: toolCallId,
+      agent: definition.name,
+      depth: (run.stored.session.depth ?? 0) + 1,
+    });
+    this.assertDelegatedRunAdmissionOwnership(seed, run.state, child, run.scopeId);
+    return seed;
+  }
+
   private async acquireSubagentSession(
     run: IActiveRun,
     definition: Readonly<IFlexSubagentDefinition>,
@@ -4865,7 +5263,11 @@ export class FlexHarness<TScope = unknown> {
           return;
         }
         if (taskId !== undefined || state.tombstones.has(sessionId)) {
-          throw new FlexHarnessNotFoundError('Subagent task', sessionId);
+          throw this.trustInternalError(
+            new FlexHarnessValidationError(
+              'The supplied taskId does not identify a resumable child. Omit taskId to create a new child, or use only an exact taskId returned by an earlier completed delegate call.',
+            ),
+          );
         }
         const timestamp = new Date().toISOString();
         metadata = {
@@ -6430,10 +6832,12 @@ export class FlexHarness<TScope = unknown> {
     const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
     if (!part || part.type !== 'tool' || part.status !== 'running') return;
     try {
+      const trustedExecutionError = run.trustedToolExecutionErrors.get(event.toolCallId);
+      run.trustedToolExecutionErrors.delete(event.toolCallId);
       const output = event.success ? normalizeJsonValue(event.output, this.toolOutputLimits) : undefined;
       const projectedError = event.success
         ? undefined
-        : this.projectExternalError(run, event.error, 'toolCallback');
+        : this.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback');
       const bytes = event.success ? jsonBytes(output) : Buffer.byteLength(projectedError!.message);
       if (!this.reserveCallbackCapacity(run, 1, bytes, 0)) return;
       if (event.success) {
@@ -7166,6 +7570,39 @@ export class FlexHarness<TScope = unknown> {
       .filter((error): error is Error => error !== undefined);
   }
 
+  private delegatedRunAdmissionOwnersForGeneration(
+    state: IStorageState,
+    session: Readonly<Pick<
+      IFlexSession,
+      'sessionId' | 'sessionGenerationId' | 'sessionGenerationSequence'
+    >>,
+  ): IDelegatedRunAdmissionOwner[] {
+    return [...state.delegatedRunAdmissionOwners].filter((owner) =>
+      owner.storageState === state
+      && owner.context.sessionId === session.sessionId
+      && owner.context.sessionGenerationId === session.sessionGenerationId
+      && owner.context.sessionGenerationSequence === session.sessionGenerationSequence);
+  }
+
+  private async settleDelegatedRunAdmissionOwners(
+    owners: readonly IDelegatedRunAdmissionOwner[],
+  ): Promise<Error[]> {
+    const results = await Promise.allSettled(
+      owners.map((owner) => this.requestDelegatedRunAdmissionClose(owner)),
+    );
+    return results.flatMap((result, index) => {
+      if (result.status === 'fulfilled') return [];
+      const error = result.reason instanceof Error
+        ? result.reason
+        : this.projectExternalError(
+            owners[index].run,
+            result.reason,
+            'delegatedRunAdmissionProvider',
+          );
+      return [error];
+    });
+  }
+
   private projectExternalError(
     run: IActiveRun,
     error: unknown,
@@ -7288,6 +7725,7 @@ export class FlexHarness<TScope = unknown> {
       tombstones: new Map(snapshot.tombstones.map((entry) => [entry.sessionId, entry])),
       tombstoneCleanups: new Map(),
       activeRuns: new Map(),
+      delegatedRunAdmissionOwners: new Set(),
       pendingPermissions: new Map(),
       scopeQueue: Promise.resolve(),
       lifecycle: 'active',
@@ -8576,6 +9014,9 @@ export class FlexHarness<TScope = unknown> {
           this.appendUnexpectedErrors(errors, settled[0].reason);
         }
       }
+      errors.push(...await this.settleDelegatedRunAdmissionOwners(
+        this.delegatedRunAdmissionOwnersForGeneration(state, tombstone),
+      ));
       if (retained) {
         if (retained.stored.promptQueueDrain) {
           const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
@@ -8680,7 +9121,11 @@ export class FlexHarness<TScope = unknown> {
       for (const result of runResults) {
         if (result.status === 'rejected') this.appendUnexpectedErrors(cleanupErrors, result.reason);
       }
-      if (dependentRuns.length > 0) {
+      if (
+        dependentRuns.length > 0
+        || (currentRun.delegatedRunAdmissionOwner !== undefined
+          && state.delegatedRunAdmissionOwners.has(currentRun.delegatedRunAdmissionOwner))
+      ) {
         state.fenceAdditionalErrors.push(cause, ...cleanupErrors);
         const stateLoad = this.stateLoads.get(state.storageKey);
         if (!stateLoad) {
@@ -8697,6 +9142,9 @@ export class FlexHarness<TScope = unknown> {
         void deferredDrain.catch(() => undefined);
         return;
       }
+      cleanupErrors.push(...await this.settleDelegatedRunAdmissionOwners([
+        ...state.delegatedRunAdmissionOwners,
+      ]));
       const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
       await Promise.allSettled([...state.sessionInitializations.values()]);
       cleanupErrors.push(...await this.closeOrphanedResources(state.storageKey));
@@ -8784,6 +9232,7 @@ export class FlexHarness<TScope = unknown> {
         state.tombstoneCleanups.set(currentTombstoneRoot, currentTombstoneCleanup);
       }
       state.activeRuns.clear();
+      state.delegatedRunAdmissionOwners.clear();
       state.pendingPermissions.clear();
       state.initializingSessions.clear();
       state.sessionInitializations.clear();
@@ -9221,6 +9670,9 @@ export class FlexHarness<TScope = unknown> {
     for (const result of runResults) {
       if (result.status === 'rejected') this.appendUnexpectedErrors(errors, result.reason);
     }
+    errors.push(...await this.settleDelegatedRunAdmissionOwners([
+      ...state.delegatedRunAdmissionOwners,
+    ]));
     for (const stored of state.sessions.values()) {
       try {
         await this.abortStoredSession(
@@ -9319,6 +9771,7 @@ export class FlexHarness<TScope = unknown> {
     state.sessionDeletions.clear();
     state.tombstoneCleanups.clear();
     state.activeRuns.clear();
+    state.delegatedRunAdmissionOwners.clear();
     state.pendingPermissions.clear();
     state.initializingSessions.clear();
     state.sessionInitializations.clear();