@modelprofile.com/flexharness 3.3.0 → 3.5.0

package/ts/classes.flexharness.ts

@@ -16,6 +16,7 @@ import {
   errorToInfo,
 } from './errors.js';
 import type {
+  IFlexAgentContextInvocation,
   IFlexAgentSessionPolicy,
   IFlexAttachmentMessagePart,
   IFlexBackgroundExecution,
@@ -49,6 +50,7 @@ import type {
   IFlexScopeSnapshot,
   IFlexSession,
   IFlexSessionTombstone,
+  IFlexSubagentDefinition,
   IFlexTerminalProjection,
   IFlexToolHandle,
   IFlexToolMessagePart,
@@ -96,6 +98,7 @@ type TRunPhase =
 
 interface IStoredSessionState {
   storageKey: string;
+  compactorContext?: IFlexAgentContextInvocation<unknown>;
   session: IFlexSession;
   messages: IFlexMessage[];
   stagedTerminals: IFlexTerminalProjection[];
@@ -113,6 +116,7 @@ interface IStoredSessionState {
   executionContextCloseCompleted: boolean;
   jobStoreReleased: boolean;
   jobs?: NonNullable<plugins.IToolExecutionContext['jobs']>;
+  compactorLifecycleController: AbortController;
   promptQueue: IQueuedPrompt[];
   outstandingPromptsById: Map<string, IQueuedPrompt>;
   terminalPromptQueueEntries: Map<string, IFlexPromptQueueEntry>;
@@ -139,6 +143,12 @@ interface IOrphanedProviderRelease {
   release: () => Promise<void>;
 }
 
+interface IOrphanedTombstoneCleanup {
+  storageKey: string;
+  sessionId: string;
+  completion: Promise<void>;
+}
+
 interface IOrphanedExecutionContextOwner {
   storageKey: string;
   sessionId: string;
@@ -146,6 +156,7 @@ interface IOrphanedExecutionContextOwner {
 
 interface IStorageState {
   storageKey: string;
+  compactorLifecycleController: AbortController;
   scopeIdHint: string;
   revision: number;
   sessions: Map<string, IStoredSessionState>;
@@ -167,6 +178,8 @@ interface IStorageState {
 interface IActiveRun {
   state: IStorageState;
   stored: IStoredSessionState;
+  originCompactorContext: IFlexAgentContextInvocation<unknown>;
+  deferredCompactorContext?: IFlexAgentContextInvocation<unknown>;
   scopeId: string;
   scope: unknown;
   sessionId: string;
@@ -187,6 +200,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;
@@ -269,6 +284,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'];
 };
@@ -297,6 +324,19 @@ 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 repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
 const externalErrorFallback: IFlexErrorInfo = Object.freeze({
@@ -396,6 +436,102 @@ function validateIdentifier(value: string, name: string): void {
   }
 }
 
+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.`);
@@ -694,7 +830,9 @@ function resolvePromptQueueLimits(
   return resolved;
 }
 
-function normalizeAgentSessionPolicy(policy: IFlexAgentSessionPolicy = {}): IFlexAgentSessionPolicy {
+function normalizeAgentSessionPolicy<TScope>(
+  policy: IFlexAgentSessionPolicy<TScope> = {},
+): IFlexAgentSessionPolicy<TScope> {
   return {
     ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
     ...(policy.contextCompactor === undefined ? {} : { contextCompactor: policy.contextCompactor }),
@@ -723,15 +861,19 @@ export class FlexHarness<TScope = unknown> {
   private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
   private readonly stores: IFlexHarnessStores;
-  private readonly agentSessionPolicy: IFlexAgentSessionPolicy;
+  private readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
   private readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
   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>>();
   private readonly storageDrains = new Map<string, Promise<void>>();
+  private readonly storageCompactorLifecycleControllers = new Map<string, AbortController>();
   private orphanedResourceQueue: Promise<void> = Promise.resolve();
   private readonly listeners = new Set<TFlexHarnessEventListener>();
   private readonly trustedInternalErrors = new WeakSet<object>();
@@ -741,7 +883,15 @@ export class FlexHarness<TScope = unknown> {
     IOrphanedExecutionContextOwner
   >();
   private readonly orphanedProviderReleases = new Map<string, IOrphanedProviderRelease>();
+  private readonly orphanedTombstoneCleanups = new Map<string, IOrphanedTombstoneCleanup>();
   private readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
+  private readonly compactorInvocationContext = new plugins.AsyncLocalStorage<
+    IFlexAgentContextInvocation<TScope>
+  >();
+  private readonly deferredCompactorContexts = new WeakMap<
+    IFlexAgentContextInvocation<unknown>,
+    IFlexAgentContextInvocation<unknown>
+  >();
   private sequence = 0;
   private promptQueueSequence = 0;
   private pendingPromptAdmissions = 0;
@@ -763,6 +913,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[]> {
@@ -828,6 +991,7 @@ export class FlexHarness<TScope = unknown> {
           updatedAt: timestamp,
           status: 'idle',
           activity: { status: 'idle' },
+          depth: 0,
         };
         resolved.state.sessions.set(
           sessionId,
@@ -841,6 +1005,7 @@ export class FlexHarness<TScope = unknown> {
         metadata,
         scopeId,
         resolved.scope.scope,
+        placeholder.compactorLifecycleController,
       );
       const loaded = await initialization;
       if (resolved.state.sessions.get(sessionId) !== placeholder) {
@@ -867,6 +1032,8 @@ export class FlexHarness<TScope = unknown> {
       const tombstone: IFlexSessionTombstone = {
         sessionId,
         deletedAt: new Date().toISOString(),
+        rootSessionId: sessionId,
+        depth: 0,
       };
       let tombstoneCommitted = false;
       let domainCleanupCompleted = false;
@@ -876,7 +1043,13 @@ export class FlexHarness<TScope = unknown> {
           resolved.state.tombstones.set(sessionId, tombstone);
         }, true);
         tombstoneCommitted = true;
-        await this.finishTombstoneCleanup(resolved.state, sessionId, scopeId);
+        completeInitialization();
+        await this.finishTombstoneCleanup(
+          resolved.state,
+          sessionId,
+          scopeId,
+          { scopeId, scope: resolved.scope.scope },
+        );
         domainCleanupCompleted = true;
       } catch (cleanupError) {
         const projectedCleanup = this.projectOperationError(
@@ -898,6 +1071,7 @@ export class FlexHarness<TScope = unknown> {
                 this.trustInternalError(new FlexHarnessAbortError(
                   'The session namespace was fenced after uncertain creation cleanup.',
                 )),
+                { scopeId, scope: resolved.scope.scope },
               );
             } catch {
               // The projected creation and cleanup errors remain safe for the caller.
@@ -950,56 +1124,115 @@ export class FlexHarness<TScope = unknown> {
   }
 
   public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
-    const { state } = await this.resolveState(scopeId);
+    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, sessionId).finally(() => {
-      if (state.sessionDeletions.get(sessionId) === deletion) {
-        state.sessionDeletions.delete(sessionId);
+    deletion = this.deleteSessionInternal(state, scopeId, scope.scope, sessionId).finally(() => {
+      if (state.sessionDeletions.get(deletionKey) === deletion) {
+        state.sessionDeletions.delete(deletionKey);
       }
     });
-    state.sessionDeletions.set(sessionId, deletion);
+    state.sessionDeletions.set(deletionKey, deletion);
     return deletion;
   }
 
   private async deleteSessionInternal(
     state: IStorageState,
     scopeId: string,
+    scope: TScope,
     sessionId: string,
   ): 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);
+        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);
+      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[]> {
@@ -1177,7 +1410,7 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<boolean> {
     validateIdentifier(queueId, 'queueId');
     requireTransferIdentifier(queueId, 'queueId');
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     const queued = stored.outstandingPromptsById.get(queueId);
     if (!queued) {
@@ -1187,6 +1420,7 @@ export class FlexHarness<TScope = unknown> {
     return this.cancelQueuedPrompt(
       queued,
       this.trustInternalError(new FlexHarnessAbortError('The queued prompt was cancelled.')),
+      this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
     );
   }
 
@@ -1196,20 +1430,28 @@ export class FlexHarness<TScope = unknown> {
     scheduleKey: string,
   ): Promise<boolean> {
     validateIdentifier(scheduleKey, 'scheduleKey');
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     const queued = [...stored.outstandingPromptsById.values()]
       .find((entry) => entry.scheduleKey === scheduleKey);
     if (!queued) return false;
     const cancellation = this.trustInternalError(new FlexHarnessAbortError('The scheduled run was cancelled.'));
-    return this.cancelQueuedPrompt(queued, cancellation);
+    return this.cancelQueuedPrompt(
+      queued,
+      cancellation,
+      this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+    );
   }
 
   public async abort(scopeId: string, sessionId: string): Promise<boolean> {
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const run = state.activeRuns.get(sessionId);
     if (!run || run.phase === 'finalizing' || run.phase === 'promoting') return false;
-    this.cancelRun(run, this.trustInternalError(new FlexHarnessAbortError()));
+    this.cancelRun(
+      run,
+      this.trustInternalError(new FlexHarnessAbortError()),
+      this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+    );
     return true;
   }
 
@@ -1233,12 +1475,16 @@ export class FlexHarness<TScope = unknown> {
     decision: TFlexPermissionDecision,
   ): Promise<void> {
     validateIdentifier(permissionId, 'permissionId');
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const pending = state.pendingPermissions.get(permissionId);
     if (!pending || pending.request.sessionId !== sessionId) {
       throw new FlexHarnessNotFoundError('Permission', permissionId);
     }
-    const response = pending.responseQueue.then(() => this.applyPermissionResponse(state, pending, decision));
+    const context = this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId);
+    const response = pending.responseQueue.then(() => this.withCompactorContext(
+      context,
+      () => this.applyPermissionResponse(state, pending, decision, context),
+    ));
     pending.responseQueue = response.then(() => undefined, () => undefined);
     return response;
   }
@@ -1275,7 +1521,7 @@ export class FlexHarness<TScope = unknown> {
     if (!reconciliation || typeof reconciliation !== 'object' || Array.isArray(reconciliation)) {
       throw new FlexHarnessValidationError('Tool execution reconciliation must be a plain object.');
     }
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     this.assertStateAcceptingWork(state);
     let canonical: plugins.TAgentToolExecutionReconciliationOptions;
@@ -1299,7 +1545,10 @@ export class FlexHarness<TScope = unknown> {
       throw new FlexHarnessValidationError('Unknown tool execution reconciliation.');
     }
     try {
-      await stored.agentSession.reconcileToolExecution(intentId, canonical);
+      await this.withCompactorContext(
+        this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+        () => stored.agentSession.reconcileToolExecution(intentId, canonical),
+      );
     } catch (error) {
       throw this.projectOperationError(error, 'agentSession', scopeId, sessionId, 'tool-reconciliation');
     }
@@ -1311,22 +1560,28 @@ export class FlexHarness<TScope = unknown> {
     event: IJsonObject & { type: string },
   ): Promise<void> {
     this.validateRuntimeEvent(event);
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     this.assertStateAcceptingWork(state);
     try {
-      await stored.agentSession.pushRuntimeEvent(cloneSerializable(event));
+      await this.withCompactorContext(
+        this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+        () => stored.agentSession.pushRuntimeEvent(cloneSerializable(event)),
+      );
     } catch (error) {
       throw this.projectOperationError(error, 'agentSession', scopeId, sessionId, 'runtime-event');
     }
   }
 
   public async compactSession(scopeId: string, sessionId: string): Promise<void> {
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     this.assertStateAcceptingWork(state);
     try {
-      await stored.agentSession.compact();
+      await this.withCompactorContext(
+        this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+        () => stored.agentSession.compact(),
+      );
     } catch (error) {
       throw this.projectOperationError(error, 'agentSession', scopeId, sessionId, 'compaction');
     }
@@ -1403,11 +1658,14 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<void> {
     validateIdentifier(executionId, 'executionId');
     requireTransferIdentifier(executionId, 'executionId');
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
     this.assertStateAcceptingWork(state);
     try {
-      await stored.agentSession.abortBackgroundExecution(executionId);
+      await this.withCompactorContext(
+        this.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+        () => stored.agentSession.abortBackgroundExecution(executionId),
+      );
     } catch (error) {
       throw this.projectOperationError(error, 'agentSession', scopeId, sessionId, 'background-abort');
     }
@@ -1461,6 +1719,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);
@@ -1481,20 +1741,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.`,
@@ -1560,7 +1835,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();
@@ -1636,6 +1913,12 @@ export class FlexHarness<TScope = unknown> {
     return {
       state: queued.state,
       stored: queued.stored,
+      originCompactorContext: this.createCompactorContext(
+        queued.scopeId,
+        queued.scope as TScope,
+        queued.state.storageKey,
+        queued.sessionId,
+      ),
       scopeId: queued.scopeId,
       scope: queued.scope,
       sessionId: queued.sessionId,
@@ -1653,6 +1936,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,
@@ -1676,11 +1961,14 @@ export class FlexHarness<TScope = unknown> {
     const options = queued.options!;
     let projectionReserved = false;
     try {
-      run.transaction = await run.stored.agentSession.beginGeneration(
-        cloneSerializable(prompt.modelMessage.content) as Parameters<
-          plugins.IAgentSession['beginGeneration']
-        >[0],
-        { generationId: run.runId },
+      run.transaction = await this.withRunCompactorContext(
+        run,
+        () => run.stored.agentSession.beginGeneration(
+          cloneSerializable(prompt.modelMessage.content) as Parameters<
+            plugins.IAgentSession['beginGeneration']
+          >[0],
+          { generationId: run.runId },
+        ),
       );
       this.assertPromptPromotion(queued, run);
       const reservation = this.createReservation(run, prompt);
@@ -1759,13 +2047,13 @@ export class FlexHarness<TScope = unknown> {
       prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
         this.prepareGeneration(run, options, context.abortSignal),
     };
-    const generation = run.scheduleKey
+    const generation = this.withRunCompactorContext(run, () => run.scheduleKey
       ? run.stored.agentSession.scheduleGenerate({
           key: run.scheduleKey,
           debounceMs: run.debounceMs,
           ...generateOptions,
         })
-      : run.stored.agentSession.generate(generateOptions);
+      : run.stored.agentSession.generate(generateOptions));
     const execution = this.executeRun(run, generation).then(
       (result) => this.finishQueuedPrompt(queued, 'completed', undefined, result),
       (error) => this.finishQueuedPrompt(
@@ -1853,7 +2141,11 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
-  private cancelQueuedPrompt(queued: IQueuedPrompt, reason: FlexHarnessAbortError): boolean {
+  private cancelQueuedPrompt(
+    queued: IQueuedPrompt,
+    reason: FlexHarnessAbortError,
+    context?: IFlexAgentContextInvocation<TScope>,
+  ): boolean {
     if (queued.stored.outstandingPromptsById.get(queued.queueId) !== queued) return false;
     if (queued.status === 'queued') {
       this.finishQueuedPrompt(queued, 'cancelled', reason);
@@ -1863,7 +2155,7 @@ export class FlexHarness<TScope = unknown> {
     const run = queued.state.activeRuns.get(queued.sessionId);
     if (!run || run.queueId !== queued.queueId) return false;
     if (run.phase === 'finalizing' || run.phase === 'promoting') return false;
-    this.cancelRun(run, reason);
+    this.cancelRun(run, reason, context);
     return true;
   }
 
@@ -1871,10 +2163,15 @@ export class FlexHarness<TScope = unknown> {
     stored: IStoredSessionState,
     reason: FlexHarnessAbortError,
     excludedQueueId?: string,
+    context?: IFlexAgentContextInvocation<unknown>,
   ): void {
     for (const queued of [...stored.outstandingPromptsById.values()]) {
       if (queued.queueId === excludedQueueId) continue;
-      this.cancelQueuedPrompt(queued, reason);
+      this.cancelQueuedPrompt(
+        queued,
+        reason,
+        context as IFlexAgentContextInvocation<TScope> | undefined,
+      );
     }
   }
 
@@ -1908,7 +2205,10 @@ export class FlexHarness<TScope = unknown> {
       if (run.controller.signal.aborted) throw run.controller.signal.reason;
       run.phase = 'finalizing';
       try {
-        await run.stored.agentSession.finalizeGeneration(run.transaction!, 'accepted');
+        await this.withRunCompactorContext(
+          run,
+          () => run.stored.agentSession.finalizeGeneration(run.transaction!, 'accepted'),
+        );
       } catch (error) {
         const projected = this.projectExternalError(run, error, 'agentSession');
         await this.fenceNamespace(run.state, run, projected);
@@ -1978,7 +2278,10 @@ export class FlexHarness<TScope = unknown> {
     run.phase = 'finalizing';
     const desiredOutcome: TCanonicalOutcome = cancelled || !generated ? 'interrupted' : 'rejected';
     try {
-      await run.stored.agentSession.finalizeGeneration(run.transaction!, desiredOutcome);
+      await this.withRunCompactorContext(
+        run,
+        () => run.stored.agentSession.finalizeGeneration(run.transaction!, desiredOutcome),
+      );
     } catch (finalizationError) {
       errors.push(this.projectExternalError(run, finalizationError, 'agentSession'));
     }
@@ -2030,28 +2333,36 @@ 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 toolOutcome = Promise.resolve()
-      .then(() => this.toolProvider?.provideTools({
+      .then(() => this.toolProvider?.provideTools(Object.freeze({
         scopeId: run.scopeId,
         scope: run.scope as TScope,
         sessionId: run.sessionId,
         runId: run.runId,
+        ...resolverRelationship,
         signal,
         requestPermission: (request) => this.requestPermission(run.state, run, request),
-      }))
+      })))
       .then(
         (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
         (error): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
@@ -2118,9 +2429,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'),
             )
@@ -2168,6 +2491,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,
@@ -2352,11 +3095,14 @@ export class FlexHarness<TScope = unknown> {
   private emitTerminalProjection(run: IActiveRun, terminal: IFlexTerminalProjection): void {
     for (const part of terminal.assistantMessage.parts) {
       const callbackPart = run.callbackParts.find((entry) => entry.partId === part.partId);
-      if (
-        (part.type === 'reasoning' || part.type === 'tool')
-        && callbackPart?.type === part.type
-        && callbackPart.status === 'running'
-      ) {
+      const shouldComplete = part.type === 'text'
+        ? callbackPart?.type === 'text'
+        : part.type === 'reasoning'
+          ? callbackPart?.type === 'reasoning' && callbackPart.status === 'running'
+          : part.type === 'tool'
+            ? callbackPart?.type === 'tool' && callbackPart.status === 'running'
+            : false;
+      if (shouldComplete) {
         this.emitPartEvent(run, 'part.completed', part);
       }
     }
@@ -2617,6 +3363,7 @@ export class FlexHarness<TScope = unknown> {
     state: IStorageState,
     pending: IPendingPermission,
     decision: TFlexPermissionDecision,
+    context: IFlexAgentContextInvocation<TScope>,
   ): Promise<void> {
     if (pending.settled) {
       throw new FlexHarnessPermissionStateError(`Permission "${pending.request.permissionId}" has already been resolved.`);
@@ -2714,7 +3461,7 @@ export class FlexHarness<TScope = unknown> {
       const rejection = this.trustInternalError(
         new FlexHarnessPermissionRejectedError(pending.request.permissionId),
       );
-      this.abortRunInternally(pending.run, rejection);
+      this.abortRunInternally(pending.run, rejection, context);
       pending.reject(rejection);
     } else {
       pending.resolve();
@@ -2818,19 +3565,50 @@ export class FlexHarness<TScope = unknown> {
     pending.reject(error);
   }
 
-  private cancelRun(run: IActiveRun, reason: FlexHarnessAbortError): void {
-    if (run.internalFailure === undefined) run.ownerCancellation ??= reason;
-    this.rejectRunPermissions(run.state, run, reason);
-    if (!run.controller.signal.aborted) run.controller.abort(reason);
-    if (run.phase === 'admitting') return;
-    if (run.scheduleKey) run.stored.agentSession.cancelScheduledGeneration(run.scheduleKey, reason);
-    else run.stored.agentSession.abortCurrentGeneration(reason);
+  private cancelRun(
+    run: IActiveRun,
+    reason: FlexHarnessAbortError,
+    context?: IFlexAgentContextInvocation<TScope>,
+  ): void {
+    const invocationContext = context ?? this.createRunCompactorContext(run);
+    if (run.internalFailure === undefined && run.ownerCancellation === undefined) {
+      run.ownerCancellation = reason;
+      run.deferredCompactorContext = invocationContext;
+      this.deferredCompactorContexts.set(run.originCompactorContext, invocationContext);
+    }
+    this.withCompactorContext(
+      (run.deferredCompactorContext ?? invocationContext) as IFlexAgentContextInvocation<TScope>,
+      () => {
+        this.rejectRunPermissions(run.state, run, reason);
+        if (!run.controller.signal.aborted) run.controller.abort(reason);
+        if (run.phase === 'admitting') return;
+        if (run.scheduleKey) {
+          run.stored.agentSession.cancelScheduledGeneration(run.scheduleKey, reason);
+        } else {
+          run.stored.agentSession.abortCurrentGeneration(reason);
+        }
+      },
+    );
   }
 
-  private abortRunInternally(run: IActiveRun, error: unknown): void {
-    run.internalFailure ??= error ?? new Error('Internal FlexHarness run failure.');
-    if (!run.controller.signal.aborted) run.controller.abort(run.internalFailure);
-    run.stored.agentSession.abortCurrentGeneration(run.internalFailure);
+  private abortRunInternally(
+    run: IActiveRun,
+    error: unknown,
+    context?: IFlexAgentContextInvocation<TScope>,
+  ): void {
+    const invocationContext = context ?? this.createRunCompactorContext(run);
+    if (run.internalFailure === undefined) {
+      run.internalFailure = error ?? new Error('Internal FlexHarness run failure.');
+      run.deferredCompactorContext = invocationContext;
+      this.deferredCompactorContexts.set(run.originCompactorContext, invocationContext);
+    }
+    this.withCompactorContext(
+      (run.deferredCompactorContext ?? invocationContext) as IFlexAgentContextInvocation<TScope>,
+      () => {
+        if (!run.controller.signal.aborted) run.controller.abort(run.internalFailure);
+        run.stored.agentSession.abortCurrentGeneration(run.internalFailure);
+      },
+    );
   }
 
   private async rollbackAdmission(
@@ -2841,7 +3619,10 @@ export class FlexHarness<TScope = unknown> {
     const errors: unknown[] = [];
     if (run.transaction) {
       try {
-        await run.stored.agentSession.finalizeGeneration(run.transaction, 'interrupted');
+        await this.withRunCompactorContext(
+          run,
+          () => run.stored.agentSession.finalizeGeneration(run.transaction!, 'interrupted'),
+        );
       } catch (error) {
         errors.push(this.projectExternalError(run, error, 'agentSession'));
       }
@@ -3068,6 +3849,7 @@ export class FlexHarness<TScope = unknown> {
     storageKey: string,
     scopeId: string,
     scope: TScope,
+    compactorLifecycleController: AbortController,
   ): Promise<IStorageState> {
     const snapshot = cloneSerializable(await this.stores.scopes.load(storageKey) ?? {
       schemaVersion: 1,
@@ -3077,6 +3859,7 @@ export class FlexHarness<TScope = unknown> {
     } satisfies IFlexScopeSnapshot);
     const state: IStorageState = {
       storageKey,
+      compactorLifecycleController,
       scopeIdHint: scopeId,
       revision: snapshot.revision,
       sessions: new Map(),
@@ -3105,10 +3888,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.
@@ -3141,6 +3951,7 @@ export class FlexHarness<TScope = unknown> {
   private createUninitializedStoredSession(
     session: IFlexSession,
     storageKey: string,
+    compactorLifecycleController = new AbortController(),
   ): IStoredSessionState {
     const unavailable = new Proxy({} as plugins.IAgentSession, {
       get() {
@@ -3164,6 +3975,7 @@ export class FlexHarness<TScope = unknown> {
       agentEventStoreReleased: true,
       executionContextCloseCompleted: true,
       jobStoreReleased: true,
+      compactorLifecycleController,
       promptQueue: [],
       outstandingPromptsById: new Map(),
       terminalPromptQueueEntries: new Map(),
@@ -3176,8 +3988,15 @@ export class FlexHarness<TScope = unknown> {
     metadata: IFlexSession,
     scopeId: string,
     scope: TScope,
+    compactorLifecycleController = new AbortController(),
   ): Promise<IStoredSessionState> {
     const sessionId = metadata.sessionId;
+    const compactorContext = this.createCompactorContext(
+      scopeId,
+      scope,
+      state.storageKey,
+      sessionId,
+    );
     const [projectionResult, permissionResult, eventStoreResult, jobStoreResult] = await Promise.allSettled([
       this.stores.projections.load(state.storageKey, sessionId),
       this.stores.permissions.load(state.storageKey, sessionId),
@@ -3216,13 +4035,16 @@ export class FlexHarness<TScope = unknown> {
     let executionContextHandle: IFlexExecutionContextHandle | undefined;
     try {
       if (this.executionContextProvider) {
-        executionContextHandle = await this.executionContextProvider.provideExecutionContext({
-          scopeId,
-          scope,
-          storageKey: state.storageKey,
-          sessionId,
-          jobStore,
-        });
+        executionContextHandle = await this.withCompactorContext(
+          compactorContext,
+          () => this.executionContextProvider!.provideExecutionContext({
+            scopeId,
+            scope,
+            storageKey: state.storageKey,
+            sessionId,
+            jobStore,
+          }),
+        );
         if (
           executionContextHandle
           && (!executionContextHandle.context
@@ -3233,6 +4055,7 @@ export class FlexHarness<TScope = unknown> {
       }
       const stored: IStoredSessionState = {
         storageKey: state.storageKey,
+        compactorContext,
         session: cloneSerializable(metadata),
         messages: cloneSerializable(projection?.messages ?? []),
         stagedTerminals: cloneSerializable(projection?.stagedTerminals ?? []),
@@ -3250,21 +4073,75 @@ export class FlexHarness<TScope = unknown> {
         executionContextCloseCompleted: executionContextHandle?.close === undefined,
         jobStoreReleased: this.stores.jobs.releaseSession === undefined,
         jobs: executionContextHandle?.context.jobs,
+        compactorLifecycleController,
         promptQueue: [],
         outstandingPromptsById: new Map(),
         terminalPromptQueueEntries: new Map(),
         outstandingPromptBytes: 0,
       };
+      const {
+        contextCompactor,
+        ...agentSessionPolicy
+      } = this.agentSessionPolicy;
+      const executionContext = executionContextHandle?.context;
+      const jobContext = executionContext?.jobs;
+      const contextualExecutionContext = executionContext && jobContext?.subscribe
+        ? {
+            ...executionContext,
+            jobs: {
+              start: jobContext.start.bind(jobContext),
+              get: jobContext.get.bind(jobContext),
+              list: jobContext.list.bind(jobContext),
+              ...(jobContext.abort ? { abort: jobContext.abort.bind(jobContext) } : {}),
+              subscribe: (listener: Parameters<NonNullable<typeof jobContext.subscribe>>[0]) =>
+                jobContext.subscribe!((event) =>
+                  this.withCompactorContext(compactorContext, () => listener(event))),
+            },
+          }
+        : executionContext;
       const agentSessionOptions: plugins.IAgentSessionOptions & {
         transactionOutcomeErrorProjector: (error: unknown) => string;
       } = {
-        ...this.agentSessionPolicy,
+        ...agentSessionPolicy,
         sessionId,
         eventStore,
-        executionContext: executionContextHandle?.context,
+        executionContext: contextualExecutionContext,
         contextBuilder: ({ events }) => hydrateAgentMessages(
           (this.agentSessionPolicy.contextBuilder ?? ((options) => plugins.buildModelMessages(options.events)))({ events }),
         ),
+        ...(contextCompactor
+          ? {
+              contextCompactor: async (messages, events, options) => {
+                const ambientContext = this.compactorInvocationContext.getStore();
+                const invocationContext = ambientContext
+                  ? (this.deferredCompactorContexts.get(ambientContext) ?? ambientContext) as
+                    IFlexAgentContextInvocation<TScope>
+                  : undefined;
+                if (
+                  !invocationContext
+                  || invocationContext.storageKey !== state.storageKey
+                  || invocationContext.sessionId !== sessionId
+                ) {
+                  throw new Error('Agent context compaction is missing its exact FlexHarness invocation context.');
+                }
+                return contextCompactor(messages, events, {
+                  ...options,
+                  ...invocationContext,
+                  scope: invocationContext.scope as TScope,
+                  abortSignal: options.abortSignal
+                    ? AbortSignal.any([
+                        options.abortSignal,
+                        state.compactorLifecycleController.signal,
+                        stored.compactorLifecycleController.signal,
+                      ])
+                    : AbortSignal.any([
+                        state.compactorLifecycleController.signal,
+                        stored.compactorLifecycleController.signal,
+                      ]),
+                });
+              },
+            }
+          : {}),
         transactionOutcomeErrorProjector: () => 'The model operation failed.',
         onToken: (delta) => this.onTextDelta(state, sessionId, delta),
         onReasoningStart: (id) => this.onReasoningStart(state, sessionId, id),
@@ -3273,7 +4150,10 @@ export class FlexHarness<TScope = unknown> {
         onToolCallStart: (event) => this.onToolStart(state, sessionId, event),
         onToolCallFinish: (event) => this.onToolFinish(state, sessionId, event),
       };
-      stored.agentSession = await plugins.AgentSession.create(agentSessionOptions);
+      stored.agentSession = await this.withCompactorContext(
+        compactorContext,
+        () => plugins.AgentSession.create(agentSessionOptions),
+      );
       return stored;
     } catch (error) {
       const cleanupErrors: unknown[] = [];
@@ -3740,38 +4620,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,
+    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).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,
+    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.'));
-      this.cancelStoredPromptQueue(retained.stored, reason);
       const run = state.activeRuns.get(sessionId);
-      if (run) this.cancelRun(run, reason);
-      if (!retained.stored.agentSessionAbortCompleted) {
+      const context = contextFor(sessionId, retained);
+      if (retained && !retained.stored.agentSessionAbortCompleted) {
         try {
-          await this.abortStoredSession(retained.stored, reason);
+          await this.abortStoredSession(retained.stored, reason, context);
         } catch (error) {
           errors.push(this.projectOperationError(
             error,
@@ -3784,70 +4762,135 @@ export class FlexHarness<TScope = unknown> {
       }
       if (run) {
         const settled = await Promise.allSettled([run.completion]);
-        if (settled[0].status === 'rejected' && !isAbortError(settled[0].reason)) {
-          errors.push(settled[0].reason);
+        if (settled[0].status === 'rejected') {
+          this.appendUnexpectedErrors(errors, settled[0].reason);
         }
       }
-      if (retained.stored.promptQueueDrain) {
-        const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
-        if (settled[0].status === 'rejected') errors.push(settled[0].reason);
+      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',
+          ));
+        }
       }
-      try {
-        await this.closeStoredSession(retained.stored);
-      } catch (error) {
-        errors.push(this.projectOperationError(
-          error,
-          'toolCleanup',
-          scopeId,
-          sessionId,
-          'session-delete',
-        ));
+      if (errors.length > 0) {
+        if (
+          retained
+          && state.lifecycle === 'retired'
+          && !this.storedSessionCleanupCompleted(retained.stored)
+        ) this.orphanedStoredSessions.add(retained.stored);
+        throw combineErrors(errors);
       }
-      if (errors.length > 0) 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);
+    }
     const cleanupErrors: unknown[] = [];
+    const ambientContext = this.compactorInvocationContext.getStore();
+    const invocation = ambientContext?.storageKey === state.storageKey
+      && ambientContext.sessionId === currentRun.sessionId
+      ? ambientContext
+      : this.effectiveRunCompactorContext(currentRun);
+    const contextFor = (sessionId: string) => this.createCompactorContext(
+      invocation.scopeId,
+      invocation.scope,
+      state.storageKey,
+      sessionId,
+    );
     try {
       for (const stored of state.sessions.values()) {
+        this.abortCompactorLifecycle(stored, reason);
         this.cancelStoredPromptQueue(
           stored,
           reason,
           stored === currentRun.stored ? currentRun.queueId : undefined,
+          contextFor(stored.session.sessionId),
         );
       }
       const otherRuns = [...state.activeRuns.values()].filter((run) => run !== currentRun);
-      for (const run of otherRuns) this.cancelRun(run, reason);
-      const runResults = await Promise.allSettled(otherRuns.map((run) => run.completion));
+      for (const run of otherRuns) this.cancelRun(run, reason, contextFor(run.sessionId));
+      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 tombstoneAttempts = [...state.tombstoneCleanups.entries()];
+      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,
+          currentTombstoneRoot,
+          currentTombstoneCleanup,
+        );
+      }
+      const tombstoneAttempts = [...state.tombstoneCleanups.entries()]
+        .filter(([rootSessionId]) => rootSessionId !== currentTombstoneRoot);
       const tombstoneResults = await Promise.allSettled(
         tombstoneAttempts.map(([, cleanup]) => cleanup),
       );
@@ -3855,15 +4898,19 @@ 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]) => !attemptedTombstones.has(sessionId))
+          .filter(([sessionId]) =>
+            !currentTombstoneSessions.has(sessionId)
+            && !attemptedTombstoneSessions.has(sessionId))
           .map(([, retained]) => retained.stored),
       ]);
       for (const stored of storedSessions) {
         try {
-          await this.abortStoredSession(stored, reason);
+          await this.abortStoredSession(stored, reason, contextFor(stored.session.sessionId));
         } catch (error) {
           cleanupErrors.push(this.projectOperationError(
             error,
@@ -3874,7 +4921,7 @@ export class FlexHarness<TScope = unknown> {
           ));
         }
         try {
-          await this.closeStoredSession(stored);
+          await this.closeStoredSession(stored, contextFor(stored.session.sessionId));
         } catch (error) {
           if (!this.storedSessionCleanupCompleted(stored)) {
             cleanupErrors.push(this.projectOperationError(
@@ -3893,24 +4940,111 @@ export class FlexHarness<TScope = unknown> {
       if (cleanupErrors.length > 0) throw combineErrors([cause, ...cleanupErrors]);
       state.lifecycle = 'retired';
       state.sessions.clear();
+      const currentRetainedCleanups = [...state.retainedSessionCleanups]
+        .filter(([sessionId]) => currentTombstoneSessions.has(sessionId));
       state.retainedSessionCleanups.clear();
+      for (const [sessionId, retained] of currentRetainedCleanups) {
+        state.retainedSessionCleanups.set(sessionId, retained);
+      }
       state.sessionDeletions.clear();
       state.tombstoneCleanups.clear();
+      if (currentTombstoneCleanup) {
+        state.tombstoneCleanups.set(currentTombstoneRoot, currentTombstoneCleanup);
+      }
       state.activeRuns.clear();
       state.pendingPermissions.clear();
       state.initializingSessions.clear();
       state.sessionInitializations.clear();
       this.stateLoads.delete(state.storageKey);
+      if (
+        this.storageCompactorLifecycleControllers.get(state.storageKey)
+        === state.compactorLifecycleController
+      ) this.storageCompactorLifecycleControllers.delete(state.storageKey);
     } finally {
       state.fenceInProgress = false;
     }
   }
 
-  private async closeStoredSession(stored: IStoredSessionState): Promise<void> {
+  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!,
+  ): Promise<void> {
     const errors: unknown[] = [];
     if (!stored.agentSessionCloseCompleted) {
       try {
-        await stored.agentSession.close();
+        await this.withCompactorContext(
+          context,
+          () => stored.agentSession.close(),
+        );
         if (!stored.agentSession.closeCleanupCompleted) {
           throw new Error('AgentSession.close() resolved before cleanup ownership was released.');
         }
@@ -3960,9 +5094,13 @@ export class FlexHarness<TScope = unknown> {
   private async abortStoredSession(
     stored: IStoredSessionState,
     reason: FlexHarnessAbortError,
+    context: IFlexAgentContextInvocation<unknown> = stored.compactorContext!,
   ): Promise<void> {
     if (stored.agentSessionAbortCompleted) return;
-    await stored.agentSession.abortSession(reason, { abortBackgroundJobs: true });
+    await this.withCompactorContext(
+      context,
+      () => stored.agentSession.abortSession(reason, { abortBackgroundJobs: true }),
+    );
     stored.agentSessionAbortCompleted = true;
   }
 
@@ -4018,6 +5156,29 @@ export class FlexHarness<TScope = unknown> {
         retained.storageKey === storageKey && retained.sessionId === sessionId);
   }
 
+  private retainOrphanedTombstoneCleanup(
+    storageKey: string,
+    sessionId: string,
+    completion: Promise<void>,
+  ): void {
+    const key = JSON.stringify([storageKey, sessionId]);
+    if (this.orphanedTombstoneCleanups.has(key)) return;
+    const retained: IOrphanedTombstoneCleanup = { storageKey, sessionId, completion };
+    this.orphanedTombstoneCleanups.set(key, retained);
+    void completion.then(
+      () => {
+        if (this.orphanedTombstoneCleanups.get(key) === retained) {
+          this.orphanedTombstoneCleanups.delete(key);
+        }
+      },
+      () => {
+        if (this.orphanedTombstoneCleanups.get(key) === retained) {
+          this.orphanedTombstoneCleanups.delete(key);
+        }
+      },
+    );
+  }
+
   private closeOrphanedResources(storageKey?: string): Promise<unknown[]> {
     const operation = this.orphanedResourceQueue.then(() =>
       this.closeOrphanedResourcesInternal(storageKey));
@@ -4027,6 +5188,14 @@ export class FlexHarness<TScope = unknown> {
 
   private async closeOrphanedResourcesInternal(storageKey?: string): Promise<unknown[]> {
     const errors: unknown[] = [];
+    const tombstoneCleanups = [...this.orphanedTombstoneCleanups.values()]
+      .filter((retained) => storageKey === undefined || retained.storageKey === storageKey);
+    const tombstoneResults = await Promise.allSettled(
+      tombstoneCleanups.map((retained) => retained.completion),
+    );
+    for (const result of tombstoneResults) {
+      if (result.status === 'rejected') this.appendUnexpectedErrors(errors, result.reason);
+    }
     for (const stored of [...this.orphanedStoredSessions]) {
       if (storageKey !== undefined && stored.storageKey !== storageKey) continue;
       try {
@@ -4067,6 +5236,7 @@ export class FlexHarness<TScope = unknown> {
       ...[...this.orphanedStoredSessions].map((stored) => stored.storageKey),
       ...[...this.orphanedExecutionContexts.values()].map((owner) => owner.storageKey),
       ...[...this.orphanedProviderReleases.values()].map((retained) => retained.storageKey),
+      ...[...this.orphanedTombstoneCleanups.values()].map((retained) => retained.storageKey),
     ]);
   }
 
@@ -4089,7 +5259,12 @@ export class FlexHarness<TScope = unknown> {
       }
     } else {
       try {
-        await this.drainStorage(scope.storageKey, stateLoad, this.createScopeRetirementError());
+        await this.drainStorage(
+          scope.storageKey,
+          stateLoad,
+          this.createScopeRetirementError(),
+          { scopeId, scope: scope.scope },
+        );
       } catch (error) {
         this.appendUnexpectedErrors(errors, error);
       }
@@ -4101,15 +5276,25 @@ export class FlexHarness<TScope = unknown> {
     storageKey: string,
     stateLoad: Promise<IStorageState>,
     reason: FlexHarnessAbortError,
+    invocation?: { scopeId: string; scope: TScope },
   ): Promise<void> {
+    const compactorController = this.storageCompactorLifecycleControllers.get(storageKey);
+    if (compactorController && !compactorController.signal.aborted) {
+      compactorController.abort(reason);
+    }
     const existing = this.storageDrains.get(storageKey);
     if (existing) return existing;
     let completed = false;
     let drain!: Promise<void>;
-    drain = this.drainStorageInternal(storageKey, stateLoad, reason).then(() => {
+    drain = this.drainStorageInternal(storageKey, stateLoad, reason, invocation).then(() => {
       completed = true;
     }).finally(() => {
-      if (completed && this.stateLoads.get(storageKey) === stateLoad) this.stateLoads.delete(storageKey);
+      if (completed && this.stateLoads.get(storageKey) === stateLoad) {
+        this.stateLoads.delete(storageKey);
+        if (this.storageCompactorLifecycleControllers.get(storageKey) === compactorController) {
+          this.storageCompactorLifecycleControllers.delete(storageKey);
+        }
+      }
       if (this.storageDrains.get(storageKey) === drain) this.storageDrains.delete(storageKey);
     });
     this.storageDrains.set(storageKey, drain);
@@ -4120,6 +5305,7 @@ export class FlexHarness<TScope = unknown> {
     storageKey: string,
     stateLoad: Promise<IStorageState>,
     reason: FlexHarnessAbortError,
+    invocation?: { scopeId: string; scope: TScope },
   ): Promise<void> {
     let state: IStorageState;
     try {
@@ -4132,14 +5318,35 @@ export class FlexHarness<TScope = unknown> {
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
     const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
     const errors: unknown[] = [];
-    for (const stored of state.sessions.values()) this.cancelStoredPromptQueue(stored, reason);
+    const contextFor = (sessionId: string) => invocation
+      ? this.createCompactorContext(invocation.scopeId, invocation.scope, storageKey, sessionId)
+      : undefined;
+    for (const stored of state.sessions.values()) {
+      this.abortCompactorLifecycle(stored, reason);
+      this.cancelStoredPromptQueue(
+        stored,
+        reason,
+        undefined,
+        contextFor(stored.session.sessionId),
+      );
+    }
     for (const run of state.activeRuns.values()) {
-      if (run.phase !== 'finalizing' && run.phase !== 'promoting') this.cancelRun(run, reason);
+      if (run.phase !== 'finalizing' && run.phase !== 'promoting') {
+        this.cancelRun(run, reason, contextFor(run.sessionId));
+      }
     }
     for (const pending of [...state.pendingPermissions.values()]) this.rejectPending(state, pending, reason);
+    const runResults = await Promise.allSettled([...state.activeRuns.values()].map((run) => run.completion));
+    for (const result of runResults) {
+      if (result.status === 'rejected') this.appendUnexpectedErrors(errors, result.reason);
+    }
     for (const stored of state.sessions.values()) {
       try {
-        await this.abortStoredSession(stored, reason);
+        await this.abortStoredSession(
+          stored,
+          reason,
+          contextFor(stored.session.sessionId),
+        );
       } catch (error) {
         errors.push(this.projectOperationError(
           error,
@@ -4150,10 +5357,6 @@ export class FlexHarness<TScope = unknown> {
         ));
       }
     }
-    const runResults = await Promise.allSettled([...state.activeRuns.values()].map((run) => run.completion));
-    for (const result of runResults) {
-      if (result.status === 'rejected') this.appendUnexpectedErrors(errors, result.reason);
-    }
     await Promise.allSettled([...state.sessionInitializations.values()]);
     errors.push(...await this.closeOrphanedResources(state.storageKey));
     await state.scopeQueue;
@@ -4173,7 +5376,7 @@ export class FlexHarness<TScope = unknown> {
     errors.push(...await this.settleDetachedCleanups(state, detachedCleanupAttempts));
     for (const stored of state.sessions.values()) {
       try {
-        await this.closeStoredSession(stored);
+        await this.closeStoredSession(stored, contextFor(stored.session.sessionId));
       } catch (error) {
         this.appendUnexpectedErrors(errors, this.projectOperationError(
           error,
@@ -4185,19 +5388,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,
-          retained?.stored.session.scopeId ?? state.scopeIdHint,
+          rootSessionId,
+          invocation?.scopeId ?? retained?.stored.session.scopeId ?? state.scopeIdHint,
+          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();
@@ -4240,10 +5451,12 @@ export class FlexHarness<TScope = unknown> {
     }
     this.listeners.clear();
     if (errors.length > 0) throw combineErrors(errors);
+    this.compactorInvocationContext.disable();
     this.stateLoads.clear();
     this.scopeAdmissions.clear();
     this.scopeRetirements.clear();
     this.storageDrains.clear();
+    this.storageCompactorLifecycleControllers.clear();
   }
 
   private appendUnexpectedErrors(target: unknown[], error: unknown): void {
@@ -4252,6 +5465,12 @@ export class FlexHarness<TScope = unknown> {
     } else if (!isAbortError(error)) target.push(error);
   }
 
+  private abortCompactorLifecycle(stored: IStoredSessionState, reason: FlexHarnessAbortError): void {
+    if (!stored.compactorLifecycleController.signal.aborted) {
+      stored.compactorLifecycleController.abort(reason);
+    }
+  }
+
   private async resolveState(
     scopeId: string,
   ): Promise<{ scope: IFlexResolvedScope<TScope>; state: IStorageState }> {
@@ -4279,10 +5498,26 @@ export class FlexHarness<TScope = unknown> {
         ) throw this.createScopeRetirementError();
         stateLoad = this.stateLoads.get(scope.storageKey);
         if (!stateLoad) {
-          stateLoad = this.loadState(scope.storageKey, scopeId, scope.scope);
+          const compactorLifecycleController = new AbortController();
+          this.storageCompactorLifecycleControllers.set(
+            scope.storageKey,
+            compactorLifecycleController,
+          );
+          stateLoad = this.loadState(
+            scope.storageKey,
+            scopeId,
+            scope.scope,
+            compactorLifecycleController,
+          );
           this.stateLoads.set(scope.storageKey, stateLoad);
           void stateLoad.catch(() => {
-            if (this.stateLoads.get(scope.storageKey) === stateLoad) this.stateLoads.delete(scope.storageKey);
+            if (this.stateLoads.get(scope.storageKey) === stateLoad) {
+              this.stateLoads.delete(scope.storageKey);
+              if (
+                this.storageCompactorLifecycleControllers.get(scope.storageKey)
+                === compactorLifecycleController
+              ) this.storageCompactorLifecycleControllers.delete(scope.storageKey);
+            }
           });
         }
       }
@@ -4328,6 +5563,37 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private createCompactorContext(
+    scopeId: string,
+    scope: TScope,
+    storageKey: string,
+    sessionId: string,
+  ): IFlexAgentContextInvocation<TScope> {
+    return Object.freeze({ scopeId, scope, storageKey, sessionId });
+  }
+
+  private withCompactorContext<TResult>(
+    context: IFlexAgentContextInvocation<unknown>,
+    operation: () => TResult,
+  ): TResult {
+    return this.compactorInvocationContext.run(
+      context as IFlexAgentContextInvocation<TScope>,
+      operation,
+    );
+  }
+
+  private createRunCompactorContext(run: IActiveRun): IFlexAgentContextInvocation<TScope> {
+    return run.originCompactorContext as IFlexAgentContextInvocation<TScope>;
+  }
+
+  private effectiveRunCompactorContext(run: IActiveRun): IFlexAgentContextInvocation<TScope> {
+    return (run.deferredCompactorContext ?? run.originCompactorContext) as IFlexAgentContextInvocation<TScope>;
+  }
+
+  private withRunCompactorContext<TResult>(run: IActiveRun, operation: () => TResult): TResult {
+    return this.withCompactorContext(this.effectiveRunCompactorContext(run), operation);
+  }
+
   private requireSession(state: IStorageState, sessionId: string): IStoredSessionState {
     validateIdentifier(sessionId, 'sessionId');
     requireTransferIdentifier(sessionId, 'sessionId');