@modelprofile.com/flexharness 5.3.0 → 5.3.1

package/readme.md

@@ -250,11 +250,15 @@ Public writes use `{ actor: 'application' }`. Tool writes use `{ actor: 'agent',
 
 `FLEX_PROJECT_MANAGEMENT_LIMITS` exports the hard UTF-8 and aggregate limits: goal 8 KiB, scratchpad 128 KiB, task content 8 KiB, task ID 512 bytes, title 2048 bytes, 512 tasks, and a 1 MiB serialized snapshot. The aggregate bound leaves room for worst-case JSON escaping of a controller-valid scratchpad. Loaded snapshots reject extra fields, duplicate IDs, invalid status/priority/timestamps, non-JSON data, wrong schema/revision, and every exceeded bound before use.
 
-`IFlexProjectManagementStore` is exact per `(storageKey, sessionId)`: `load`, CAS `save`, CAS `tombstoneSession`, and `purgeNamespace` must not collapse multiple sessions or storage namespaces. `load()` returns `TFlexProjectManagementRecord | undefined` and receives the current session generation as an optional third argument; FlexHarness always supplies it, while two-argument callers and stores remain compatible. Same-generation live saves use normal revision CAS, and a same-generation tombstone permanently rejects later live saves. A higher `sessionGenerationSequence` with a different `sessionGenerationId` may replace only an older tombstone using expected revision `0`; it cannot replace a live record. This resets the PM revision for a recreated core session while stale saves and tombstones from older generations remain fenced. Deleting a recreated session that made no PM writes still replaces the prior-generation tombstone with a revision-1 tombstone for the new generation.
+`IFlexProjectManagementStore` is exact per `(storageKey, sessionId)`: `load`, CAS `save`, CAS `tombstoneSession`, and `purgeNamespace` must not collapse multiple sessions or storage namespaces. `load()` returns `TFlexProjectManagementRecord | undefined` and receives an optional `IFlexProjectManagementSessionContext` as its third argument; `tombstoneSession()` receives the same optional context as its fifth argument. FlexHarness always supplies both, while existing two-argument loads, four-argument tombstones, and shorter store implementations remain compatible.
+
+`IFlexProjectManagementSessionContext` contains `sessionGenerationId`, `sessionGenerationSequence`, and optional `subagent`. The atomic `IFlexSubagentProvenance` block contains `parentSessionId`, `parentSessionGenerationId`, `parentSessionGenerationSequence`, `originParentRunId`, `originParentToolCallId`, `agent`, and actual session `depth`. Both the context and its separately cloned nested block are frozen.
+
+Same-generation live saves use normal revision CAS, and a same-generation tombstone permanently rejects later live saves. A higher `sessionGenerationSequence` with a different `sessionGenerationId` may replace only an older tombstone using expected revision `0`; it cannot replace a live record. This resets the PM revision for a recreated core session while stale saves and tombstones from older generations remain fenced. Deleting a recreated session that made no PM writes still replaces the prior-generation tombstone with a revision-1 tombstone for the new generation.
 
 Every newly created core session exposes and persists a `sessionGenerationId` plus its monotonic `sessionGenerationSequence`. FlexHarness generates a strong random ID when `sessionGenerationId` is omitted. Applications may supply the ID to `createSession()` when they need to persist creation authority before dispatch; a supplied ID must be nonblank, contain no control characters, and fit within `FLEX_SESSION_GENERATION_ID_MAX_BYTES` (128 UTF-8 bytes). FlexHarness still assigns the sequence atomically. A legacy scope session without those fields is assigned a deterministic bounded ID derived from its immutable `storageKey`, `sessionId`, and `createdAt`; FlexHarness persists the repaired scope snapshot before accepting work. Grouped core deletion tombstones retain both fields after live metadata is removed.
 
-Normal Flex session cleanup always waits in-flight local project operations, then loads and CAS-tombstones `stores.projectManagement`, regardless of whether PM tools are enabled in that harness. If a concurrent same-generation save wins first, cleanup reloads and retries within a bounded attempt count; unresolved conflict or store failure retains the core Flex session cleanup tombstone for a later retry. The durable PM tombstone is not physically removed during normal session cleanup.
+Normal Flex session cleanup always waits in-flight local project operations, then loads and CAS-tombstones `stores.projectManagement`, regardless of whether PM tools are enabled in that harness. Child cleanup persists one complete `IFlexSubagentProvenance` block on its core tombstone before live metadata is removed. One cleanup invocation reuses the identical doubly frozen context object across bounded CAS retries; restart or a later cleanup invocation reconstructs a new frozen context from the persisted provenance. If a concurrent same-generation save wins first, cleanup reloads and retries; unresolved conflict or store failure retains the core Flex session cleanup tombstone for a later retry. The durable PM tombstone is not physically removed during normal session cleanup.
 
 `purgeNamespace(storageKey)` is the explicit destructive reclamation operation and physically removes every live record and tombstone in that exact PM namespace. Applications may call it only after serializing every scope alias, preventing new admission, awaiting `retireScope()` on every harness owner, and deleting or purging the application-owned core scope namespace. `retireScope()` itself remains non-destructive and never calls `purgeNamespace()`. Purging PM first, purging only one alias, or racing a stale harness can remove the fence that makes session-generation reuse safe.
 
@@ -275,7 +279,7 @@ interface IDelegateInput {
 }
 ```
 
-Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and bounded agent/task metadata. The controller answers it through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
+Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and separately bounded harness-owned agent/task metadata. Its metadata includes `childSessionId`, the exact ID reserved for this call: FlexHarness derives it deterministically when `taskId` is omitted and copies the supplied candidate when `taskId` is present. A resume also retains that candidate as `taskId`. This block is not truncated by `toolOutputLimits`. The reserved ID binds permission handling before child creation but does not prove that the child exists or is owned: applications must treat the later delegated admission context as authoritative. The controller answers through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
 
 Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` remains limited to `sessionId`, `sessionGenerationId`, and `title`. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the foreground `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
 
@@ -294,7 +298,7 @@ Omitting `taskId` creates a deterministic child for the parent session, run, and
 
 Supplying `taskId` deliberately resumes an idle, live child from a later run of the same immutable parent session and the same configured agent. The caller must use the exact ID returned by an earlier completed delegate call; an unknown ID fails with safe corrective guidance and never creates a child under the supplied label. Resume starts a new child prompt while retaining the child's original parent run and tool-call origin. A child owned by another parent or agent, a deleted child, an active child, a same-run resume, or a second acquisition of the same child within one later parent run is rejected. Parent cancellation propagates only to the exact child run started by that delegate call.
 
-`delegatedRunAdmissionProvider` optionally adds an application-owned admission lease around each internally delegated child run. The public contracts are `IFlexDelegatedRunAdmissionProvider<TScope>`, `IFlexDelegatedRunAdmissionContext<TScope>`, and `IFlexDelegatedRunAdmissionLease`. The provider is never called for root prompts or direct public prompt APIs. It receives a frozen context containing the resolved `scopeId`, exact captured `scope`, and `storageKey`; the exact child `sessionId`, session generation, queue, and run; the exact current parent session generation, queue, run, and delegate `toolCallId`; the child agent and depth; and the child run `AbortSignal`. For `taskId` resume, `parentQueueId`, `parentRunId`, and `parentToolCallId` identify the current delegate invocation, while the durable child session retains its original `parentRunId` and `parentToolCallId` creation metadata.
+`delegatedRunAdmissionProvider` optionally adds an application-owned admission lease around each internally delegated child run. The public contracts are `IFlexDelegatedRunAdmissionProvider<TScope>`, `IFlexDelegatedRunAdmissionContext<TScope>`, and `IFlexDelegatedRunAdmissionLease`. The provider is never called for root prompts or direct public prompt APIs. It receives a frozen context containing the resolved `scopeId`, exact captured `scope`, and `storageKey`; the exact child `sessionId`, session generation, queue, and run; the exact current parent session generation, queue, run, and delegate `toolCallId`; immutable `originParentRunId` and `originParentToolCallId`; the child agent and depth; and the child run `AbortSignal`. For `taskId` resume, the current parent queue/run/tool-call fields identify this delegate invocation, while the origin fields remain fixed to the invocation that created the durable child.
 
 ```typescript
 delegatedRunAdmissionProvider: {
@@ -314,6 +318,8 @@ delegatedRunAdmissionProvider: {
         queueId: context.parentQueueId,
         runId: context.parentRunId,
         toolCallId: context.parentToolCallId,
+        originRunId: context.originParentRunId,
+        originToolCallId: context.originParentToolCallId,
       },
       signal: context.signal,
     });
@@ -328,7 +334,9 @@ Acquisition completes before generation-side branch reversion, context compactio
 
 For a normally acquired lease, FlexHarness gives `close()` an awaited attempt after SmartAgent generation and before canonical accepted, rejected, or interrupted finalization and the terminal `prompt.finished` event. If an abort detaches an acquisition that ignores its signal, the run may settle before acquisition returns; FlexHarness retains that owner and closes any late lease. `close()` must be idempotent and safe to retry after rejection. A close failure prevents successful child acceptance and remains owned by the exact child session generation for retry by later exact-session deletion, scope retirement, or disposal. Retirement and disposal truthfully wait for late acquisition and lease cleanup.
 
-Limits are validated and frozen at construction: at most 32 unique definitions; names are non-empty and at most 128 UTF-8 bytes; descriptions 2048 bytes; optional model hints 512 bytes; optional system prompts 64 KiB; and optional `maxSteps` a positive safe integer. `maxSubagentDepth` defaults to 1 and must be a positive safe integer at most 8. `maxSubagentCallsPerRun` defaults to 32 and must be a positive safe integer at most 128. A call slot is consumed synchronously at the start of every schema-valid delegate execution, before semantic bounds, subagent type/depth validation, permission, or child work. Inputs rejected by the tool schema never start delegate execution and do not consume a slot. After successful semantic validation, the child ID is reserved for the rest of the parent run, including after permission rejection or later failure. Permission rejection creates no child session. Omitting `taskId` reserves a deterministic new child ID; supplying `taskId` reserves and resumes that existing child after permission. Delegate descriptions are non-empty and at most 256 UTF-8 bytes, prompts non-empty and at most 64 KiB, subagent types at most 128 bytes, and task IDs at most 512 bytes.
+Limits are validated and frozen at construction: at most 32 unique definitions; names are non-empty and at most 128 UTF-8 bytes; descriptions 2048 bytes; optional model hints 512 bytes; optional system prompts 64 KiB; and optional `maxSteps` a positive safe integer. `maxSubagentDepth` defaults to 1 and must be a positive safe integer at most 8. `maxSubagentCallsPerRun` defaults to 32 and must be a positive safe integer at most 128. A call slot is consumed synchronously at the start of every schema-valid delegate execution, before semantic bounds, subagent type/depth validation, permission, or child work. Inputs rejected by the tool schema never start delegate execution and do not consume a slot. After successful semantic validation, the child ID candidate is reserved for the rest of the parent run, including after permission rejection or later failure. Permission rejection creates no child session. Omitting `taskId` reserves a deterministic new child ID; supplying `taskId` reserves that unverified candidate and attempts resume after permission only if it identifies a resumable child. Delegate descriptions are non-empty and at most 256 UTF-8 bytes, prompts non-empty and at most 64 KiB, subagent types at most 128 bytes, and task IDs at most 512 bytes.
+
+Scope snapshots remain schema 1 and legacy child tombstones without `subagent` provenance continue to load. New child tombstones write the atomic provenance block and reject partial, parent-generation-mismatched, depth-mismatched, or duplicate-origin records. FlexHarness versions before this provenance addition reject that new optional key under their strict reader, so downgrading or mixing old readers with newly written scope snapshots is unsupported.
 
 ## Sessions And Prompts
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '5.3.0',
+  version: '5.3.1',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }

package/ts/classes.flexharness.ts

@@ -51,6 +51,7 @@ import type {
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
   IFlexProjectGoalResult,
+  IFlexProjectManagementSessionContext,
   IFlexProjectManagementSnapshot,
   IFlexProjectManagementTombstone,
   IFlexProjectManagementWriteContext,
@@ -87,6 +88,7 @@ import type {
   IFlexSlashCommandExecutionOptions,
   IFlexSlashCommandHandlerRegistration,
   IFlexSubagentDefinition,
+  IFlexSubagentProvenance,
   IFlexTerminalProjection,
   IFlexToolHandle,
   IFlexToolMessagePart,
@@ -545,6 +547,7 @@ const maxBackgroundExecutions = 100;
 const maxSubagentTaskDescriptionBytes = 256;
 const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
+const maxSubagentPermissionMetadataBytes = 16 * 1024;
 const maxSubagentResultTextBytes = 64 * 1024;
 const defaultMaxSubagentDepth = 1;
 const maximumMaxSubagentDepth = 8;
@@ -1380,8 +1383,13 @@ export class FlexHarness<TScope = unknown> {
     const rootDepth = stored.session.depth ?? 0;
     const deletedAt = new Date().toISOString();
     const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
+    const provenanceBySessionId = new Map(subtree.map((entry) => [
+      entry.session.sessionId,
+      this.createSubagentProvenance(state, entry.session),
+    ]));
     for (const entry of subtree) {
       const entrySessionId = entry.session.sessionId;
+      const subagent = provenanceBySessionId.get(entrySessionId);
       state.sessions.delete(entrySessionId);
       state.retainedSessionCleanups.set(entrySessionId, {
         stored: entry,
@@ -1396,6 +1404,7 @@ export class FlexHarness<TScope = unknown> {
         ...(entry.session.parentSessionId === undefined
           ? {}
           : { parentSessionId: entry.session.parentSessionId }),
+        ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
       });
     }
     return {
@@ -3491,6 +3500,8 @@ export class FlexHarness<TScope = unknown> {
       parentQueueId: seed.parentQueueId,
       parentRunId: seed.parentRunId,
       parentToolCallId: seed.parentToolCallId,
+      originParentRunId: seed.originParentRunId,
+      originParentToolCallId: seed.originParentToolCallId,
       agent: seed.agent,
       depth: seed.depth,
       signal: run.controller.signal,
@@ -4173,10 +4184,11 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<IFlexProjectManagementSnapshot> {
     const store = this.stores.projectManagement;
     const generation = requireSessionGeneration(stored.session);
+    const sessionContext = this.createProjectManagementSessionContext(state, stored.session);
     const record = await store.load(
       state.storageKey,
       stored.session.sessionId,
-      Object.freeze({ ...generation }),
+      sessionContext,
     );
     if (record === undefined) {
       return createEmptyFlexProjectManagementSnapshot(
@@ -4269,6 +4281,52 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot({ revision: snapshot.revision, state: snapshot });
   }
 
+  private createSubagentProvenance(
+    state: IStorageState,
+    session: Readonly<IFlexSession>,
+  ): Readonly<IFlexSubagentProvenance> | undefined {
+    if (session.parentSessionId === undefined) return undefined;
+    if (
+      session.parentRunId === undefined
+      || session.parentToolCallId === undefined
+      || session.agent === undefined
+      || session.depth === undefined
+    ) throw new FlexHarnessValidationError('Subagent session provenance is incomplete.');
+    const parent = state.sessions.get(session.parentSessionId)?.session
+      ?? state.tombstones.get(session.parentSessionId);
+    if (!parent) {
+      throw new FlexHarnessValidationError(
+        `Subagent session "${session.sessionId}" has no exact parent provenance.`,
+      );
+    }
+    const parentGeneration = requireSessionGeneration(parent);
+    return Object.freeze({
+      parentSessionId: session.parentSessionId,
+      parentSessionGenerationId: parentGeneration.sessionGenerationId,
+      parentSessionGenerationSequence: parentGeneration.sessionGenerationSequence,
+      originParentRunId: session.parentRunId,
+      originParentToolCallId: session.parentToolCallId,
+      agent: session.agent,
+      depth: session.depth,
+    });
+  }
+
+  private createProjectManagementSessionContext(
+    state: IStorageState,
+    session: Readonly<IFlexSession | IFlexSessionTombstone>,
+  ): Readonly<IFlexProjectManagementSessionContext> {
+    const source = 'deletedAt' in session
+      ? session.subagent
+      : this.createSubagentProvenance(state, session);
+    const subagent = source === undefined
+      ? undefined
+      : Object.freeze({ ...cloneSerializable(source) });
+    return Object.freeze({
+      ...requireSessionGeneration(session),
+      ...(subagent === undefined ? {} : { subagent }),
+    });
+  }
+
   private projectTaskResult(
     snapshot: IFlexProjectManagementSnapshot,
     task: IFlexProjectTask,
@@ -5046,16 +5104,20 @@ export class FlexHarness<TScope = unknown> {
     run.controller.signal.addEventListener('abort', abortChild, { once: true });
     if (run.controller.signal.aborted) abortChild();
     try {
+      const permissionMetadata = {
+        agent: definition.name,
+        description: input.description,
+        childSessionId: reservedSessionId,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+      };
+      if (jsonBytes(permissionMetadata) > maxSubagentPermissionMetadataBytes) {
+        throw new FlexHarnessValidationError('Subagent permission metadata exceeds its byte limit.');
+      }
       await this.requestPermission(run.state, run, {
         kind: 'subagent.start',
         description: `Start foreground subagent "${definition.name}": ${input.description}`,
         toolCallId,
-        metadata: {
-          agent: definition.name,
-          description: input.description,
-          ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
-        },
-      });
+      }, Object.freeze(permissionMetadata));
       const acquired = await this.acquireSubagentSession(
         run,
         definition,
@@ -5343,6 +5405,7 @@ export class FlexHarness<TScope = unknown> {
       ) throw projected;
       if (state.tombstones.has(sessionId)) throw projected;
       try {
+        const subagent = this.createSubagentProvenance(state, metadata);
         await this.mutateScope(state, () => {
           if (state.sessions.get(sessionId) !== placeholder) return;
           state.sessions.delete(sessionId);
@@ -5353,6 +5416,7 @@ export class FlexHarness<TScope = unknown> {
             rootSessionId: sessionId,
             depth: 0,
             parentSessionId: run.sessionId,
+            ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
           });
         }, true);
         completeInitialization();
@@ -6920,6 +6984,7 @@ export class FlexHarness<TScope = unknown> {
     state: IStorageState,
     run: IActiveRun,
     input: IFlexPermissionRequestInput,
+    exactMetadata?: TJsonValue,
   ): Promise<void> {
     validateIdentifier(input.kind, 'permission kind');
     validateIdentifier(input.description, 'permission description');
@@ -6942,9 +7007,11 @@ export class FlexHarness<TScope = unknown> {
       description: truncateUtf8(input.description, maxTransferMetadataBytes),
       ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
       ...(input.rememberKey ? { rememberKey: input.rememberKey } : {}),
-      ...(input.metadata === undefined
-        ? {}
-        : { metadata: normalizeJsonValue(input.metadata, this.toolOutputLimits) }),
+      ...(exactMetadata !== undefined
+        ? { metadata: cloneSerializable(exactMetadata) }
+        : input.metadata === undefined
+          ? {}
+          : { metadata: normalizeJsonValue(input.metadata, this.toolOutputLimits) }),
       createdAt: new Date().toISOString(),
     };
     let resolvePermission!: () => void;
@@ -7785,7 +7852,7 @@ export class FlexHarness<TScope = unknown> {
               scopeId,
               scope,
             );
-            await this.cleanupSessionDomains(storageKey, tombstone);
+            await this.cleanupSessionDomains(state, tombstone);
           }
           for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
           scopeChanged = true;
@@ -8766,16 +8833,17 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async cleanupSessionDomains(
-    storageKey: string,
+    state: IStorageState,
     tombstone: IFlexSessionTombstone,
   ): Promise<void> {
+    const storageKey = state.storageKey;
     const sessionId = tombstone.sessionId;
     const projectManagementCleanup = async (): Promise<void> => {
       await this.projectManagementQueues.get(
         this.projectManagementKey(storageKey, sessionId),
       );
       await this.tombstoneProjectManagementSession(
-        storageKey,
+        state,
         tombstone,
       );
     };
@@ -8793,18 +8861,20 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async tombstoneProjectManagementSession(
-    storageKey: string,
+    state: IStorageState,
     sessionTombstone: IFlexSessionTombstone,
   ): Promise<void> {
+    const storageKey = state.storageKey;
     const store = this.stores.projectManagement;
     const sessionId = sessionTombstone.sessionId;
     const generation = requireSessionGeneration(sessionTombstone);
+    const sessionContext = this.createProjectManagementSessionContext(state, sessionTombstone);
     let lastConflict: FlexHarnessStoreConflictError | undefined;
     for (let attempt = 0; attempt <= maxProjectManagementTombstoneConflicts; attempt++) {
       const current = await store.load(
         storageKey,
         sessionId,
-        Object.freeze({ ...generation }),
+        sessionContext,
       );
       if (current !== undefined) {
         assertFlexProjectManagementRecord(current);
@@ -8845,6 +8915,7 @@ export class FlexHarness<TScope = unknown> {
           sessionId,
           tombstone,
           expectedRevision,
+          sessionContext,
         );
       } catch (error) {
         if (!(error instanceof FlexHarnessStoreConflictError)) throw error;
@@ -9062,7 +9133,7 @@ export class FlexHarness<TScope = unknown> {
           releaseContext.scope,
           retained?.stored,
         );
-        await this.cleanupSessionDomains(state.storageKey, tombstone);
+        await this.cleanupSessionDomains(state, tombstone);
         if (retained) retained.domainsCompleted = true;
       }
     }

package/ts/interfaces.ts

@@ -441,6 +441,7 @@ export interface IFlexSessionTombstone {
   rootSessionId?: string;
   depth?: number;
   parentSessionId?: string;
+  subagent?: IFlexSubagentProvenance;
 }
 
 export interface IFlexScopeSnapshot {
@@ -582,6 +583,16 @@ export interface IFlexSessionGeneration {
   sessionGenerationSequence: number;
 }
 
+export interface IFlexSubagentProvenance {
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
+  readonly agent: string;
+  readonly depth: number;
+}
+
 export interface IFlexSessionGenerationCohortEntry extends IFlexSessionGeneration {
   sessionId: string;
 }
@@ -649,11 +660,15 @@ export interface IFlexProjectManagementWriteContext {
   toolCallId?: string;
 }
 
+export interface IFlexProjectManagementSessionContext extends IFlexSessionGeneration {
+  readonly subagent?: Readonly<IFlexSubagentProvenance>;
+}
+
 export interface IFlexProjectManagementStore {
   load(
     storageKey: string,
     sessionId: string,
-    sessionGeneration?: Readonly<IFlexSessionGeneration>,
+    sessionContext?: Readonly<IFlexProjectManagementSessionContext>,
   ): Promise<TFlexProjectManagementRecord | undefined>;
   save(
     storageKey: string,
@@ -667,6 +682,7 @@ export interface IFlexProjectManagementStore {
     sessionId: string,
     tombstone: IFlexProjectManagementTombstone,
     expectedRevision: number,
+    sessionContext?: Readonly<IFlexProjectManagementSessionContext>,
   ): Promise<void>;
   purgeNamespace(storageKey: string): Promise<void>;
 }
@@ -980,6 +996,8 @@ export interface IFlexDelegatedRunAdmissionContext<TScope> extends IFlexSessionG
   readonly parentQueueId: string;
   readonly parentRunId: string;
   readonly parentToolCallId: string;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
   readonly agent: string;
   readonly depth: number;
   readonly signal: AbortSignal;

package/ts/utils.json.ts

@@ -15,6 +15,7 @@ import type {
   IFlexProjectionSnapshotV2,
   IFlexProjectionSnapshotV3,
   IFlexScopeSnapshot,
+  IFlexSubagentProvenance,
   TFlexAgentModelMessage,
   TJsonValue,
 } from './interfaces.js';
@@ -546,6 +547,68 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   };
 }
 
+function validateSubagentProvenance(
+  value: unknown,
+  path: string,
+): IFlexSubagentProvenance {
+  const provenance = requireRecord(value, path);
+  requireOnlyKeys(provenance, [
+    'parentSessionId',
+    'parentSessionGenerationId',
+    'parentSessionGenerationSequence',
+    'originParentRunId',
+    'originParentToolCallId',
+    'agent',
+    'depth',
+  ], path);
+  const parentSessionId = requireString(
+    provenance.parentSessionId,
+    `${path}.parentSessionId`,
+  );
+  const parentSessionGenerationId = requireString(
+    provenance.parentSessionGenerationId,
+    `${path}.parentSessionGenerationId`,
+  );
+  if (
+    Buffer.byteLength(parentSessionGenerationId, 'utf8')
+      > FLEX_SESSION_GENERATION_ID_MAX_BYTES
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.parentSessionGenerationId exceeds ${FLEX_SESSION_GENERATION_ID_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(provenance.parentSessionGenerationSequence)
+    || Number(provenance.parentSessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.parentSessionGenerationSequence must be a positive integer.`,
+    );
+  }
+  const originParentRunId = requireString(
+    provenance.originParentRunId,
+    `${path}.originParentRunId`,
+  );
+  const originParentToolCallId = requireString(
+    provenance.originParentToolCallId,
+    `${path}.originParentToolCallId`,
+  );
+  const agent = requireString(provenance.agent, `${path}.agent`);
+  requireNonNegativeInteger(provenance.depth, `${path}.depth`);
+  if (provenance.depth === 0) {
+    throw new FlexHarnessStoreFormatError(`${path}.depth must be positive.`);
+  }
+  return {
+    parentSessionId,
+    parentSessionGenerationId,
+    parentSessionGenerationSequence: provenance.parentSessionGenerationSequence as number,
+    originParentRunId,
+    originParentToolCallId,
+    agent,
+    depth: provenance.depth as number,
+  };
+}
+
 function validateModel(value: unknown, path: string): void {
   const model = requireRecord(value, path);
   requireOnlyKeys(model, ['provider', 'model', 'displayName', 'variant'], path);
@@ -811,9 +874,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
   const tombstoneIds = new Set<string>();
   const tombstones = new Map<string, {
     sessionId: string;
+    sessionGenerationId?: string;
+    sessionGenerationSequence?: number;
     rootSessionId?: string;
     depth?: number;
     parentSessionId?: string;
+    subagent?: IFlexSubagentProvenance;
   }>();
   for (let index = 0; index < snapshot.tombstones.length; index++) {
     const path = `$snapshot.tombstones[${index}]`;
@@ -828,11 +894,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         'rootSessionId',
         'depth',
         'parentSessionId',
+        'subagent',
       ],
       path,
     );
     const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
-    validateOptionalSessionGeneration(tombstone, path);
+    const generation = validateOptionalSessionGeneration(tombstone, path);
     requireString(tombstone.deletedAt, `${path}.deletedAt`);
     const parentSessionId = tombstone.parentSessionId === undefined
       ? undefined
@@ -840,6 +907,19 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
     if (parentSessionId === sessionId) {
       throw new FlexHarnessStoreFormatError(`${path} cannot be its own parent.`);
     }
+    const subagent = tombstone.subagent === undefined
+      ? undefined
+      : validateSubagentProvenance(tombstone.subagent, `${path}.subagent`);
+    if (subagent && generation.sessionGenerationId === undefined) {
+      throw new FlexHarnessStoreFormatError(
+        `${path}.subagent requires exact session generation fields.`,
+      );
+    }
+    if (subagent && subagent.parentSessionId !== parentSessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `${path}.subagent does not match its parentSessionId.`,
+      );
+    }
     const hasRoot = tombstone.rootSessionId !== undefined;
     const hasDepth = tombstone.depth !== undefined;
     if (hasRoot !== hasDepth) {
@@ -864,11 +944,26 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
       );
     }
     tombstoneIds.add(sessionId);
+    if (subagent) {
+      const origin = JSON.stringify([
+        subagent.parentSessionId,
+        subagent.originParentRunId,
+        subagent.originParentToolCallId,
+      ]);
+      if (origins.has(origin)) {
+        throw new FlexHarnessStoreFormatError(
+          'Snapshot contains duplicate subagent invocation origins.',
+        );
+      }
+      origins.add(origin);
+    }
     tombstones.set(sessionId, {
       sessionId,
+      ...generation,
       ...(hasRoot ? { rootSessionId: tombstone.rootSessionId as string } : {}),
       ...(hasDepth ? { depth: tombstone.depth as number } : {}),
       ...(parentSessionId === undefined ? {} : { parentSessionId }),
+      ...(subagent === undefined ? {} : { subagent }),
     });
   }
   for (const [index, tombstone] of snapshot.tombstones.entries()) {
@@ -894,6 +989,26 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         `Snapshot tombstone "${tombstone.sessionId}" has no parent "${tombstone.parentSessionId}".`,
       );
     }
+    if (tombstone.subagent) {
+      const parent = parentSession ?? parentTombstone!;
+      if (
+        parent.sessionGenerationId !== tombstone.subagent.parentSessionGenerationId
+        || parent.sessionGenerationSequence
+          !== tombstone.subagent.parentSessionGenerationSequence
+      ) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot tombstone "${tombstone.sessionId}" has inconsistent parent generation provenance.`,
+        );
+      }
+      const parentDepth = parent.parentSessionId === undefined
+        ? 0
+        : parentSession?.depth ?? parentTombstone?.subagent?.depth;
+      if (parentDepth === undefined || tombstone.subagent.depth !== parentDepth + 1) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot tombstone "${tombstone.sessionId}" has inconsistent session depth provenance.`,
+        );
+      }
+    }
     if (tombstone.depth !== undefined && tombstone.depth > 0) {
       if (
         !parentTombstone