@modelprofile.com/flexharness 5.2.0 → 5.3.1

package/ts/classes.flexharness.ts

@@ -35,6 +35,8 @@ import type {
   IFlexCreateSessionOptions,
   IFlexDeleteSessionGenerationCohortInput,
   IFlexDeleteSessionGenerationCohortResult,
+  IFlexDelegatedRunAdmissionContext,
+  IFlexDelegatedRunAdmissionLease,
   IFlexErrorInfo,
   IFlexEventArchiveMetadata,
   IFlexExecutionContextHandle,
@@ -49,6 +51,7 @@ import type {
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
   IFlexProjectGoalResult,
+  IFlexProjectManagementSessionContext,
   IFlexProjectManagementSnapshot,
   IFlexProjectManagementTombstone,
   IFlexProjectManagementWriteContext,
@@ -85,6 +88,7 @@ import type {
   IFlexSlashCommandExecutionOptions,
   IFlexSlashCommandHandlerRegistration,
   IFlexSubagentDefinition,
+  IFlexSubagentProvenance,
   IFlexTerminalProjection,
   IFlexToolHandle,
   IFlexToolMessagePart,
@@ -297,6 +301,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 +336,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 +344,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 +410,7 @@ interface IQueuedPrompt {
   startedAt?: string;
   prompt?: INormalizedFlexPrompt;
   options?: IFlexPromptOptions;
+  delegationSeed?: IDelegatedRunAdmissionSeed;
   byteSize: number;
   completion: Promise<IFlexPromptResult>;
   resolveCompletion: (result: IFlexPromptResult) => void;
@@ -493,6 +547,7 @@ const maxBackgroundExecutions = 100;
 const maxSubagentTaskDescriptionBytes = 256;
 const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
+const maxSubagentPermissionMetadataBytes = 16 * 1024;
 const maxSubagentResultTextBytes = 64 * 1024;
 const defaultMaxSubagentDepth = 1;
 const maximumMaxSubagentDepth = 8;
@@ -630,6 +685,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 +749,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);
@@ -1326,8 +1383,13 @@ export class FlexHarness<TScope = unknown> {
     const rootDepth = stored.session.depth ?? 0;
     const deletedAt = new Date().toISOString();
     const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
+    const provenanceBySessionId = new Map(subtree.map((entry) => [
+      entry.session.sessionId,
+      this.createSubagentProvenance(state, entry.session),
+    ]));
     for (const entry of subtree) {
       const entrySessionId = entry.session.sessionId;
+      const subagent = provenanceBySessionId.get(entrySessionId);
       state.sessions.delete(entrySessionId);
       state.retainedSessionCleanups.set(entrySessionId, {
         stored: entry,
@@ -1342,6 +1404,7 @@ export class FlexHarness<TScope = unknown> {
         ...(entry.session.parentSessionId === undefined
           ? {}
           : { parentSessionId: entry.session.parentSessionId }),
+        ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
       });
     }
     return {
@@ -1779,7 +1842,7 @@ export class FlexHarness<TScope = unknown> {
             promptOptions,
             undefined,
             undefined,
-            false,
+            undefined,
             signal,
             true,
           );
@@ -3085,7 +3148,7 @@ export class FlexHarness<TScope = unknown> {
     options: IFlexPromptOptions,
     scheduleKey?: string,
     debounceMs?: number,
-    subagentAdmission = false,
+    delegationSeed?: IDelegatedRunAdmissionSeed,
     admissionSignal?: AbortSignal,
     slashCommandAdmission = false,
   ): Promise<{
@@ -3145,11 +3208,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 +3254,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 +3263,7 @@ export class FlexHarness<TScope = unknown> {
         ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
         prompt: normalizedPrompt,
         options: normalizedOptions,
+        ...(delegationSeed === undefined ? {} : { delegationSeed }),
         byteSize,
         completion,
         resolveCompletion,
@@ -3318,6 +3385,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 +3404,260 @@ 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,
+      originParentRunId: seed.originParentRunId,
+      originParentToolCallId: seed.originParentToolCallId,
+      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 +3665,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 +3739,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 +3865,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 +3927,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 +3951,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 +4029,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;
@@ -3829,10 +4184,11 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<IFlexProjectManagementSnapshot> {
     const store = this.stores.projectManagement;
     const generation = requireSessionGeneration(stored.session);
+    const sessionContext = this.createProjectManagementSessionContext(state, stored.session);
     const record = await store.load(
       state.storageKey,
       stored.session.sessionId,
-      Object.freeze({ ...generation }),
+      sessionContext,
     );
     if (record === undefined) {
       return createEmptyFlexProjectManagementSnapshot(
@@ -3925,6 +4281,52 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot({ revision: snapshot.revision, state: snapshot });
   }
 
+  private createSubagentProvenance(
+    state: IStorageState,
+    session: Readonly<IFlexSession>,
+  ): Readonly<IFlexSubagentProvenance> | undefined {
+    if (session.parentSessionId === undefined) return undefined;
+    if (
+      session.parentRunId === undefined
+      || session.parentToolCallId === undefined
+      || session.agent === undefined
+      || session.depth === undefined
+    ) throw new FlexHarnessValidationError('Subagent session provenance is incomplete.');
+    const parent = state.sessions.get(session.parentSessionId)?.session
+      ?? state.tombstones.get(session.parentSessionId);
+    if (!parent) {
+      throw new FlexHarnessValidationError(
+        `Subagent session "${session.sessionId}" has no exact parent provenance.`,
+      );
+    }
+    const parentGeneration = requireSessionGeneration(parent);
+    return Object.freeze({
+      parentSessionId: session.parentSessionId,
+      parentSessionGenerationId: parentGeneration.sessionGenerationId,
+      parentSessionGenerationSequence: parentGeneration.sessionGenerationSequence,
+      originParentRunId: session.parentRunId,
+      originParentToolCallId: session.parentToolCallId,
+      agent: session.agent,
+      depth: session.depth,
+    });
+  }
+
+  private createProjectManagementSessionContext(
+    state: IStorageState,
+    session: Readonly<IFlexSession | IFlexSessionTombstone>,
+  ): Readonly<IFlexProjectManagementSessionContext> {
+    const source = 'deletedAt' in session
+      ? session.subagent
+      : this.createSubagentProvenance(state, session);
+    const subagent = source === undefined
+      ? undefined
+      : Object.freeze({ ...cloneSerializable(source) });
+    return Object.freeze({
+      ...requireSessionGeneration(session),
+      ...(subagent === undefined ? {} : { subagent }),
+    });
+  }
+
   private projectTaskResult(
     snapshot: IFlexProjectManagementSnapshot,
     task: IFlexProjectTask,
@@ -4613,15 +5015,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;
+        }
+      },
     });
   }
 
@@ -4690,16 +5104,20 @@ export class FlexHarness<TScope = unknown> {
     run.controller.signal.addEventListener('abort', abortChild, { once: true });
     if (run.controller.signal.aborted) abortChild();
     try {
+      const permissionMetadata = {
+        agent: definition.name,
+        description: input.description,
+        childSessionId: reservedSessionId,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+      };
+      if (jsonBytes(permissionMetadata) > maxSubagentPermissionMetadataBytes) {
+        throw new FlexHarnessValidationError('Subagent permission metadata exceeds its byte limit.');
+      }
       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 }),
-        },
-      });
+      }, Object.freeze(permissionMetadata));
       const acquired = await this.acquireSubagentSession(
         run,
         definition,
@@ -4716,6 +5134,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 +5147,7 @@ export class FlexHarness<TScope = unknown> {
         childOptions,
         undefined,
         undefined,
-        true,
+        delegationSeed,
         run.controller.signal,
       );
       admission = await queued.started;
@@ -4777,6 +5201,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 +5325,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 = {
@@ -4941,6 +5405,7 @@ export class FlexHarness<TScope = unknown> {
       ) throw projected;
       if (state.tombstones.has(sessionId)) throw projected;
       try {
+        const subagent = this.createSubagentProvenance(state, metadata);
         await this.mutateScope(state, () => {
           if (state.sessions.get(sessionId) !== placeholder) return;
           state.sessions.delete(sessionId);
@@ -4951,6 +5416,7 @@ export class FlexHarness<TScope = unknown> {
             rootSessionId: sessionId,
             depth: 0,
             parentSessionId: run.sessionId,
+            ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
           });
         }, true);
         completeInitialization();
@@ -6430,10 +6896,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) {
@@ -6516,6 +6984,7 @@ export class FlexHarness<TScope = unknown> {
     state: IStorageState,
     run: IActiveRun,
     input: IFlexPermissionRequestInput,
+    exactMetadata?: TJsonValue,
   ): Promise<void> {
     validateIdentifier(input.kind, 'permission kind');
     validateIdentifier(input.description, 'permission description');
@@ -6538,9 +7007,11 @@ export class FlexHarness<TScope = unknown> {
       description: truncateUtf8(input.description, maxTransferMetadataBytes),
       ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
       ...(input.rememberKey ? { rememberKey: input.rememberKey } : {}),
-      ...(input.metadata === undefined
-        ? {}
-        : { metadata: normalizeJsonValue(input.metadata, this.toolOutputLimits) }),
+      ...(exactMetadata !== undefined
+        ? { metadata: cloneSerializable(exactMetadata) }
+        : input.metadata === undefined
+          ? {}
+          : { metadata: normalizeJsonValue(input.metadata, this.toolOutputLimits) }),
       createdAt: new Date().toISOString(),
     };
     let resolvePermission!: () => void;
@@ -7166,6 +7637,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 +7792,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',
@@ -7347,7 +7852,7 @@ export class FlexHarness<TScope = unknown> {
               scopeId,
               scope,
             );
-            await this.cleanupSessionDomains(storageKey, tombstone);
+            await this.cleanupSessionDomains(state, tombstone);
           }
           for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
           scopeChanged = true;
@@ -8328,16 +8833,17 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async cleanupSessionDomains(
-    storageKey: string,
+    state: IStorageState,
     tombstone: IFlexSessionTombstone,
   ): Promise<void> {
+    const storageKey = state.storageKey;
     const sessionId = tombstone.sessionId;
     const projectManagementCleanup = async (): Promise<void> => {
       await this.projectManagementQueues.get(
         this.projectManagementKey(storageKey, sessionId),
       );
       await this.tombstoneProjectManagementSession(
-        storageKey,
+        state,
         tombstone,
       );
     };
@@ -8355,18 +8861,20 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async tombstoneProjectManagementSession(
-    storageKey: string,
+    state: IStorageState,
     sessionTombstone: IFlexSessionTombstone,
   ): Promise<void> {
+    const storageKey = state.storageKey;
     const store = this.stores.projectManagement;
     const sessionId = sessionTombstone.sessionId;
     const generation = requireSessionGeneration(sessionTombstone);
+    const sessionContext = this.createProjectManagementSessionContext(state, sessionTombstone);
     let lastConflict: FlexHarnessStoreConflictError | undefined;
     for (let attempt = 0; attempt <= maxProjectManagementTombstoneConflicts; attempt++) {
       const current = await store.load(
         storageKey,
         sessionId,
-        Object.freeze({ ...generation }),
+        sessionContext,
       );
       if (current !== undefined) {
         assertFlexProjectManagementRecord(current);
@@ -8407,6 +8915,7 @@ export class FlexHarness<TScope = unknown> {
           sessionId,
           tombstone,
           expectedRevision,
+          sessionContext,
         );
       } catch (error) {
         if (!(error instanceof FlexHarnessStoreConflictError)) throw error;
@@ -8576,6 +9085,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]);
@@ -8621,7 +9133,7 @@ export class FlexHarness<TScope = unknown> {
           releaseContext.scope,
           retained?.stored,
         );
-        await this.cleanupSessionDomains(state.storageKey, tombstone);
+        await this.cleanupSessionDomains(state, tombstone);
         if (retained) retained.domainsCompleted = true;
       }
     }
@@ -8680,7 +9192,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 +9213,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 +9303,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 +9741,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 +9842,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();