@modelprofile.com/flexharness 3.8.0 → 4.0.1

package/ts/classes.flexharness.ts

@@ -18,6 +18,7 @@ import {
   errorToInfo,
 } from './errors.js';
 import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
   FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
   FLEX_REVERSION_DEFAULT_LIMITS,
   FLEX_REVERSION_MAXIMUM_LIMITS,
@@ -33,6 +34,7 @@ import type {
   IFlexAttachmentMessagePart,
   IFlexBackgroundExecution,
   IFlexCallbackLimits,
+  IFlexCreateProjectTaskInput,
   IFlexCreateSessionOptions,
   IFlexErrorInfo,
   IFlexEventArchiveMetadata,
@@ -47,6 +49,15 @@ import type {
   IFlexPermissionRequest,
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
+  IFlexProjectGoalResult,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectManagementWriteContext,
+  IFlexProjectScratchpadResult,
+  IFlexProjectStateResult,
+  IFlexProjectTask,
+  IFlexProjectTaskResult,
+  IFlexProjectTasksResult,
   IFlexPromptAdmission,
   IFlexPromptQueueAdmission,
   IFlexPromptQueueEntry,
@@ -81,6 +92,7 @@ import type {
   IFlexUncertainToolExecution,
   IFlexUndoSessionResult,
   IFlexUpdateSessionOptions,
+  IFlexUpdateProjectTaskInput,
   IFlexUsage,
   IJsonObject,
   TFlexAgentRunResult,
@@ -93,6 +105,8 @@ import type {
   TFlexHarnessEventListener,
   TFlexMessagePart,
   TFlexPermissionDecision,
+  TFlexProjectTaskPriority,
+  TFlexProjectTaskStatus,
   TFlexPrompt,
   TFlexPromptPart,
   TFlexPromptQueueStatus,
@@ -114,6 +128,11 @@ import {
   normalizeJsonValue,
   resolveJsonLimits,
 } from './utils.json.js';
+import {
+  assertFlexProjectManagementRecord,
+  assertFlexProjectManagementSnapshot,
+  createEmptyFlexProjectManagementSnapshot,
+} from './utils.projectmanagement.js';
 import {
   hydrateAgentMessages,
   normalizeFlexPrompt,
@@ -397,6 +416,47 @@ interface IFlexSubagentAcquisition {
   created: boolean;
 }
 
+interface INormalizedProjectManagementTools {
+  readonly task: boolean;
+  readonly goal: boolean;
+  readonly scratchpad: boolean;
+}
+
+interface INormalizedBuiltInTools {
+  readonly renameSession: boolean;
+  readonly projectManagement?: INormalizedProjectManagementTools;
+}
+
+type TProjectTaskToolInput =
+  | { action: 'list' }
+  | {
+      action: 'create';
+      id?: string;
+      content: string;
+      status?: TFlexProjectTaskStatus;
+      priority?: TFlexProjectTaskPriority;
+    }
+  | {
+      action: 'update';
+      id: string;
+      content?: string;
+      status?: TFlexProjectTaskStatus;
+      priority?: TFlexProjectTaskPriority;
+    }
+  | { action: 'delete'; id: string }
+  | { action: 'clear' };
+
+type TProjectGoalToolInput =
+  | { action: 'get' }
+  | { action: 'set'; goal: string }
+  | { action: 'clear' };
+
+type TProjectScratchpadToolInput =
+  | { action: 'get' }
+  | { action: 'set'; content: string }
+  | { action: 'append'; content: string }
+  | { action: 'clear' };
+
 type TEventDetails = Record<string, unknown> & {
   type: TFlexHarnessEvent['type'];
 };
@@ -444,6 +504,7 @@ const maxResourceToolNameBytes = 512;
 const maxSlashCommandRegistrations = 128;
 const maxSlashCommandDescriptionBytes = 2048;
 const maxSlashCommandTemplateBytes = FLEX_SLASH_COMMAND_MAX_INPUT_BYTES;
+const maxProjectManagementTombstoneConflicts = 8;
 const resourceToolStemLength = 16;
 const repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
@@ -455,6 +516,43 @@ const externalErrorFallback: IFlexErrorInfo = Object.freeze({
   code: 'FLEX_EXTERNAL_ERROR',
 });
 
+function createSessionGenerationId(): string {
+  return `generation_${plugins.crypto.randomUUID()}`;
+}
+
+function deriveLegacySessionGenerationId(
+  storageKey: string,
+  sessionId: string,
+  createdAt: string,
+): string {
+  const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
+    'flexharness-legacy-session-generation-v1',
+    storageKey,
+    sessionId,
+    createdAt,
+  ])).digest('hex');
+  return `legacy_${digest}`;
+}
+
+function requireSessionGeneration(
+  session: Pick<
+    IFlexSession | IFlexSessionTombstone,
+    'sessionGenerationId' | 'sessionGenerationSequence'
+  >,
+): { sessionGenerationId: string; sessionGenerationSequence: number } {
+  if (
+    !session.sessionGenerationId
+    || !Number.isSafeInteger(session.sessionGenerationSequence)
+    || Number(session.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessValidationError('Session generation metadata is missing.');
+  }
+  return {
+    sessionGenerationId: session.sessionGenerationId,
+    sessionGenerationSequence: session.sessionGenerationSequence as number,
+  };
+}
+
 function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return Boolean(
     value
@@ -663,6 +761,58 @@ function normalizeSubagents(
   return Object.freeze(normalized);
 }
 
+function normalizeBuiltInTools(
+  options: IFlexHarnessOptions<unknown>['builtInTools'],
+): INormalizedBuiltInTools {
+  if (options === undefined) return Object.freeze({ renameSession: false });
+  if (
+    !options
+    || typeof options !== 'object'
+    || Array.isArray(options)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+  ) {
+    throw new FlexHarnessValidationError('builtInTools must be a plain object.');
+  }
+  const unsupported = Object.keys(options)
+    .find((key) => !['renameSession', 'projectManagement'].includes(key));
+  if (unsupported) throw new FlexHarnessValidationError(`builtInTools does not support "${unsupported}".`);
+  if (options.renameSession !== undefined && typeof options.renameSession !== 'boolean') {
+    throw new FlexHarnessValidationError('builtInTools.renameSession must be a boolean.');
+  }
+  const projectManagement = options.projectManagement;
+  if (projectManagement === undefined) {
+    return Object.freeze({ renameSession: options.renameSession ?? false });
+  }
+  if (
+    !projectManagement
+    || typeof projectManagement !== 'object'
+    || Array.isArray(projectManagement)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(projectManagement))
+  ) {
+    throw new FlexHarnessValidationError('builtInTools.projectManagement must be a plain object.');
+  }
+  const unsupportedProjectOption = Object.keys(projectManagement)
+    .find((key) => !['task', 'goal', 'scratchpad'].includes(key));
+  if (unsupportedProjectOption) {
+    throw new FlexHarnessValidationError(
+      `builtInTools.projectManagement does not support "${unsupportedProjectOption}".`,
+    );
+  }
+  for (const key of ['task', 'goal', 'scratchpad'] as const) {
+    if (projectManagement[key] !== undefined && typeof projectManagement[key] !== 'boolean') {
+      throw new FlexHarnessValidationError(`builtInTools.projectManagement.${key} must be a boolean.`);
+    }
+  }
+  return Object.freeze({
+    renameSession: options.renameSession ?? false,
+    projectManagement: Object.freeze({
+      task: projectManagement.task ?? true,
+      goal: projectManagement.goal ?? true,
+      scratchpad: projectManagement.scratchpad ?? true,
+    }),
+  });
+}
+
 function normalizeSlashCommands<TScope>(
   registrations: readonly TFlexSlashCommandRegistration<TScope>[] | undefined,
 ): ReadonlyMap<string, TRegisteredSlashCommand<TScope>> {
@@ -997,13 +1147,81 @@ function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void
   const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived');
   if (unsupportedKey) throw new FlexHarnessValidationError(`updateSession does not support "${unsupportedKey}".`);
   if (Object.prototype.hasOwnProperty.call(options, 'title') && options.title !== null) {
-    validateIdentifier(options.title!, 'title');
+    validateUtf8String(
+      options.title,
+      'title',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
+      true,
+    );
   }
   if (Object.prototype.hasOwnProperty.call(options, 'archived') && typeof options.archived !== 'boolean') {
     throw new FlexHarnessValidationError('archived must be a boolean.');
   }
 }
 
+function validateProjectTaskStatus(value: unknown): asserts value is TFlexProjectTaskStatus {
+  if (!['pending', 'in_progress', 'completed', 'cancelled'].includes(String(value))) {
+    throw new FlexHarnessValidationError('Project task status is invalid.');
+  }
+}
+
+function validateProjectTaskPriority(value: unknown): asserts value is TFlexProjectTaskPriority {
+  if (!['high', 'medium', 'low'].includes(String(value))) {
+    throw new FlexHarnessValidationError('Project task priority is invalid.');
+  }
+}
+
+function validateProjectTaskId(value: unknown): asserts value is string {
+  validateUtf8String(
+    value,
+    'project task id',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes,
+    true,
+  );
+}
+
+function validateProjectTaskContent(value: unknown): asserts value is string {
+  validateUtf8String(
+    value,
+    'project task content',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes,
+    true,
+  );
+}
+
+function validateCreateProjectTaskInput(input: IFlexCreateProjectTaskInput): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new FlexHarnessValidationError('Project task create input must be a plain object.');
+  }
+  const unsupported = Object.keys(input)
+    .find((key) => !['id', 'content', 'status', 'priority'].includes(key));
+  if (unsupported) {
+    throw new FlexHarnessValidationError(`Project task create input does not support "${unsupported}".`);
+  }
+  validateProjectTaskId(input.id);
+  validateProjectTaskContent(input.content);
+  if (input.status !== undefined) validateProjectTaskStatus(input.status);
+  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
+}
+
+function validateUpdateProjectTaskInput(input: IFlexUpdateProjectTaskInput): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new FlexHarnessValidationError('Project task update input must be a plain object.');
+  }
+  const keys = Object.keys(input);
+  const unsupported = keys.find((key) => !['id', 'content', 'status', 'priority'].includes(key));
+  if (unsupported) {
+    throw new FlexHarnessValidationError(`Project task update input does not support "${unsupported}".`);
+  }
+  if (!keys.some((key) => key !== 'id')) {
+    throw new FlexHarnessValidationError('Project task update requires a changed field.');
+  }
+  validateProjectTaskId(input.id);
+  if (input.content !== undefined) validateProjectTaskContent(input.content);
+  if (input.status !== undefined) validateProjectTaskStatus(input.status);
+  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
+}
+
 function validatePromptOptions(options: IFlexPromptOptions, scheduled: boolean): void {
   if (!options || typeof options !== 'object' || Array.isArray(options)) {
     throw new FlexHarnessValidationError('Prompt options must be a plain object.');
@@ -1128,6 +1346,22 @@ function normalizeAgentSessionPolicy<TScope>(
   };
 }
 
+function requireHarnessStores(stores: IFlexHarnessStores): IFlexHarnessStores {
+  const projectManagement = stores?.projectManagement;
+  if (
+    !projectManagement
+    || typeof projectManagement.load !== 'function'
+    || typeof projectManagement.save !== 'function'
+    || typeof projectManagement.tombstoneSession !== 'function'
+    || typeof projectManagement.purgeNamespace !== 'function'
+  ) {
+    throw new FlexHarnessValidationError(
+      'stores.projectManagement requires load/save/tombstoneSession/purgeNamespace methods.',
+    );
+  }
+  return stores;
+}
+
 export class FlexHarness<TScope = unknown> {
   private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
   private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
@@ -1144,6 +1378,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly reversionPolicy: TFlexReversionPolicy;
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  private readonly builtInTools: INormalizedBuiltInTools;
   private readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
   private readonly maxSubagentDepth: number;
   private readonly maxSubagentCallsPerRun: number;
@@ -1164,6 +1399,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly orphanedTombstoneCleanups = new Map<string, IOrphanedTombstoneCleanup>();
   private readonly orphanedTombstoneOwners = new Map<string, IOrphanedTombstoneOwner<TScope>>();
   private readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
+  private readonly projectManagementQueues = new Map<string, Promise<void>>();
   private readonly activeSlashCommandExecutions = new Map<string, IActiveSlashCommandExecution>();
   private readonly activeSlashCommandListings = new Set<IActiveSlashCommandListing>();
   private readonly compactorInvocationContext = new plugins.AsyncLocalStorage<
@@ -1195,7 +1431,7 @@ export class FlexHarness<TScope = unknown> {
     this.toolProvider = options.toolProvider;
     this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
-    this.stores = options.stores ?? new InMemoryFlexHarnessStores();
+    this.stores = requireHarnessStores(options.stores ?? new InMemoryFlexHarnessStores());
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
@@ -1222,6 +1458,7 @@ export class FlexHarness<TScope = unknown> {
     }
     this.externalErrorProjector = options.externalErrorProjector;
     this.subagents = normalizeSubagents(options.subagents);
+    this.builtInTools = normalizeBuiltInTools(options.builtInTools);
     this.slashCommands = normalizeSlashCommands(options.slashCommands);
     this.maxSubagentDepth = resolveBoundedPositiveInteger(
       options.maxSubagentDepth,
@@ -1261,7 +1498,14 @@ export class FlexHarness<TScope = unknown> {
     const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
     validateIdentifier(sessionId, 'sessionId');
     requireTransferIdentifier(sessionId, 'sessionId');
-    if (options.title !== undefined) validateIdentifier(options.title, 'title');
+    if (options.title !== undefined) {
+      validateUtf8String(
+        options.title,
+        'title',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
+        true,
+      );
+    }
     await resolved.state.scopeQueue;
     if (
       resolved.state.sessions.has(sessionId)
@@ -1296,6 +1540,8 @@ export class FlexHarness<TScope = unknown> {
         metadata = {
           scopeId,
           sessionId,
+          sessionGenerationId: createSessionGenerationId(),
+          sessionGenerationSequence: resolved.state.revision + 1,
           ...(options.title ? { title: options.title } : {}),
           createdAt: timestamp,
           updatedAt: timestamp,
@@ -1341,6 +1587,7 @@ export class FlexHarness<TScope = unknown> {
       if (!scopeReserved) throw projectedError;
       const tombstone: IFlexSessionTombstone = {
         sessionId,
+        ...requireSessionGeneration(metadata),
         deletedAt: new Date().toISOString(),
         rootSessionId: sessionId,
         depth: 0,
@@ -1468,6 +1715,181 @@ export class FlexHarness<TScope = unknown> {
     return result;
   }
 
+  public async getProjectState(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectStateResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectStateResult(snapshot);
+  }
+
+  public async listProjectTasks(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectTasksResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectTasksResult(snapshot, snapshot.tasks);
+  }
+
+  public async createProjectTask(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexCreateProjectTaskInput,
+  ): Promise<IFlexProjectTaskResult> {
+    validateCreateProjectTaskInput(input);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.createProjectTaskInState(
+      state,
+      stored,
+      input,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async updateProjectTask(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexUpdateProjectTaskInput,
+  ): Promise<IFlexProjectTaskResult> {
+    validateUpdateProjectTaskInput(input);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.updateProjectTaskInState(
+      state,
+      stored,
+      input,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async deleteProjectTask(
+    scopeId: string,
+    sessionId: string,
+    taskId: string,
+  ): Promise<IFlexProjectTaskResult> {
+    validateProjectTaskId(taskId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.deleteProjectTaskInState(
+      state,
+      stored,
+      taskId,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectTasks(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectTasksResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.clearProjectTasksInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async getProjectGoal(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectGoalResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectGoalResult(snapshot);
+  }
+
+  public async setProjectGoal(
+    scopeId: string,
+    sessionId: string,
+    goal: string,
+  ): Promise<IFlexProjectGoalResult> {
+    validateUtf8String(
+      goal,
+      'project goal',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+      true,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.setProjectGoalInState(
+      state,
+      stored,
+      goal,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectGoal(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectGoalResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.clearProjectGoalInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async getProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const snapshot = await this.readProjectManagementState(state, stored);
+    return this.projectScratchpadResult(snapshot);
+  }
+
+  public async setProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+    content: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    validateUtf8String(
+      content,
+      'project scratchpad',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.setProjectScratchpadInState(
+      state,
+      stored,
+      content,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async appendProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+    content: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    validateUtf8String(
+      content,
+      'project scratchpad append',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+    );
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.appendProjectScratchpadInState(
+      state,
+      stored,
+      content,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
+  public async clearProjectScratchpad(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    return this.clearProjectScratchpadInState(
+      state,
+      stored,
+      Object.freeze({ actor: 'application' }),
+    );
+  }
+
   public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
     this.assertNoAmbientSlashCommandTeardown({ scopeId, sessionId });
     const { scope, state } = await this.resolveState(scopeId);
@@ -1536,6 +1958,7 @@ export class FlexHarness<TScope = unknown> {
         });
         state.tombstones.set(entrySessionId, {
           sessionId: entrySessionId,
+          ...requireSessionGeneration(entry.session),
           deletedAt,
           rootSessionId: sessionId,
           depth: (entry.session.depth ?? rootDepth) - rootDepth,
@@ -2007,7 +2430,7 @@ export class FlexHarness<TScope = unknown> {
     )) return 'Session already has an active slash command execution.';
     if (stored.pendingReversion) return 'Session has a pending reversion operation.';
     if (stored.session.agent !== undefined) {
-      return 'Subagent sessions can only be prompted through the foreground task tool.';
+      return 'Subagent sessions can only be prompted through the foreground delegate tool.';
     }
     if (stored.outstandingPromptsById.size >= this.promptQueueLimits.maxOutstandingPromptsPerSession) {
       return 'Session has reached its outstanding prompt limit.';
@@ -3287,7 +3710,7 @@ export class FlexHarness<TScope = unknown> {
       }
       if (stored.session.agent !== undefined && !subagentAdmission) {
         throw new FlexHarnessValidationError(
-          'Subagent sessions can only be prompted through the foreground task tool.',
+          'Subagent sessions can only be prompted through the foreground delegate tool.',
         );
       }
       if (stored.outstandingPromptsById.size >= this.promptQueueLimits.maxOutstandingPromptsPerSession) {
@@ -3894,6 +4317,412 @@ export class FlexHarness<TScope = unknown> {
     throw errors.length > 1 ? combineErrors(errors) : terminalError;
   }
 
+  private requireProjectManagementTools(): INormalizedProjectManagementTools {
+    const projectManagement = this.builtInTools.projectManagement;
+    if (!projectManagement) {
+      throw new FlexHarnessValidationError('Project management is not configured for this FlexHarness.');
+    }
+    return projectManagement;
+  }
+
+  private projectManagementKey(storageKey: string, sessionId: string): string {
+    return JSON.stringify([storageKey, sessionId]);
+  }
+
+  private queueProjectManagementOperation<TResult>(
+    storageKey: string,
+    sessionId: string,
+    operation: () => Promise<TResult>,
+  ): Promise<TResult> {
+    const key = this.projectManagementKey(storageKey, sessionId);
+    const previous = this.projectManagementQueues.get(key) ?? Promise.resolve();
+    const result = previous.then(operation);
+    const barrier = result.then(() => undefined, () => undefined);
+    this.projectManagementQueues.set(key, barrier);
+    void barrier.then(() => {
+      if (this.projectManagementQueues.get(key) === barrier) {
+        this.projectManagementQueues.delete(key);
+      }
+    });
+    return result;
+  }
+
+  private async awaitProjectManagementOperations(
+    storageKey: string,
+    sessionIds: Iterable<string>,
+  ): Promise<void> {
+    const barriers = [...new Set(sessionIds)]
+      .map((sessionId) => this.projectManagementQueues.get(
+        this.projectManagementKey(storageKey, sessionId),
+      ))
+      .filter((barrier): barrier is Promise<void> => barrier !== undefined);
+    await Promise.all(barriers);
+  }
+
+  private async resolveProjectManagementSession(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<{ state: IStorageState; stored: IStoredSessionState }> {
+    this.requireProjectManagementTools();
+    const { state } = await this.resolveState(scopeId);
+    await state.scopeQueue;
+    this.assertOpen();
+    this.assertStateAcceptingWork(state);
+    return { state, stored: this.requireSession(state, sessionId) };
+  }
+
+  private assertProjectManagementSession(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): void {
+    this.assertOpen();
+    this.assertStateAcceptingWork(state);
+    if (
+      state.sessions.get(stored.session.sessionId) !== stored
+      || state.tombstones.has(stored.session.sessionId)
+    ) {
+      throw new FlexHarnessNotFoundError('Session', stored.session.sessionId);
+    }
+  }
+
+  private async loadProjectManagementState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): Promise<IFlexProjectManagementSnapshot> {
+    const store = this.stores.projectManagement;
+    const generation = requireSessionGeneration(stored.session);
+    const record = await store.load(state.storageKey, stored.session.sessionId);
+    if (record === undefined) {
+      return createEmptyFlexProjectManagementSnapshot(
+        generation.sessionGenerationId,
+        generation.sessionGenerationSequence,
+      );
+    }
+    assertFlexProjectManagementRecord(record);
+    if (record.sessionGenerationId === generation.sessionGenerationId) {
+      if (record.sessionGenerationSequence !== generation.sessionGenerationSequence) {
+        throw new FlexHarnessStoreConflictError(
+          this.projectManagementKey(state.storageKey, stored.session.sessionId),
+          0,
+          record.revision,
+        );
+      }
+      if (!('deletedAt' in record)) return cloneSerializable(record);
+      throw new FlexHarnessNotFoundError('Project management state', stored.session.sessionId);
+    }
+    if (
+      'deletedAt' in record
+      && record.sessionGenerationSequence < generation.sessionGenerationSequence
+    ) {
+      return createEmptyFlexProjectManagementSnapshot(
+        generation.sessionGenerationId,
+        generation.sessionGenerationSequence,
+      );
+    }
+    throw new FlexHarnessStoreConflictError(
+      this.projectManagementKey(state.storageKey, stored.session.sessionId),
+      0,
+      record.revision,
+    );
+  }
+
+  private readProjectManagementState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): Promise<IFlexProjectManagementSnapshot> {
+    return this.queueProjectManagementOperation(
+      state.storageKey,
+      stored.session.sessionId,
+      async () => {
+        this.assertProjectManagementSession(state, stored);
+        const snapshot = await this.loadProjectManagementState(state, stored);
+        this.assertProjectManagementSession(state, stored);
+        return publicSnapshot(snapshot);
+      },
+    );
+  }
+
+  private mutateProjectManagementState<TResult>(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+    mutation: (
+      snapshot: IFlexProjectManagementSnapshot,
+    ) => { changed: boolean; value: TResult },
+  ): Promise<{ snapshot: IFlexProjectManagementSnapshot; value: TResult }> {
+    return this.queueProjectManagementOperation(
+      state.storageKey,
+      stored.session.sessionId,
+      async () => {
+        this.assertProjectManagementSession(state, stored);
+        const snapshot = await this.loadProjectManagementState(state, stored);
+        this.assertProjectManagementSession(state, stored);
+        const expectedRevision = snapshot.revision;
+        const result = mutation(snapshot);
+        if (result.changed) {
+          snapshot.revision = expectedRevision + 1;
+          assertFlexProjectManagementSnapshot(snapshot);
+          this.assertProjectManagementSession(state, stored);
+          await this.stores.projectManagement.save(
+            state.storageKey,
+            stored.session.sessionId,
+            cloneSerializable(snapshot),
+            expectedRevision,
+            Object.freeze(cloneSerializable(writeContext)),
+          );
+        }
+        return {
+          snapshot: publicSnapshot(snapshot),
+          value: result.value === undefined ? result.value : publicSnapshot(result.value),
+        };
+      },
+    );
+  }
+
+  private projectStateResult(snapshot: IFlexProjectManagementSnapshot): IFlexProjectStateResult {
+    return publicSnapshot({ revision: snapshot.revision, state: snapshot });
+  }
+
+  private projectTaskResult(
+    snapshot: IFlexProjectManagementSnapshot,
+    task: IFlexProjectTask,
+  ): IFlexProjectTaskResult {
+    return publicSnapshot({ revision: snapshot.revision, task, state: snapshot });
+  }
+
+  private projectTasksResult(
+    snapshot: IFlexProjectManagementSnapshot,
+    tasks: IFlexProjectTask[],
+  ): IFlexProjectTasksResult {
+    return publicSnapshot({ revision: snapshot.revision, tasks, state: snapshot });
+  }
+
+  private projectGoalResult(snapshot: IFlexProjectManagementSnapshot): IFlexProjectGoalResult {
+    return publicSnapshot({
+      revision: snapshot.revision,
+      goal: snapshot.goal ?? null,
+      state: snapshot,
+    });
+  }
+
+  private projectScratchpadResult(
+    snapshot: IFlexProjectManagementSnapshot,
+  ): IFlexProjectScratchpadResult {
+    return publicSnapshot({
+      revision: snapshot.revision,
+      scratchpad: snapshot.scratchpad,
+      state: snapshot,
+    });
+  }
+
+  private async createProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    input: IFlexCreateProjectTaskInput,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const status = input.status ?? 'pending';
+    const priority = input.priority ?? 'medium';
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const existing = snapshot.tasks.find((task) => task.id === input.id);
+        if (existing) {
+          if (
+            existing.content === input.content
+            && existing.status === status
+            && existing.priority === priority
+          ) return { changed: false, value: existing };
+          throw new FlexHarnessValidationError(
+            `Project task "${input.id}" already exists with different creation data.`,
+          );
+        }
+        if (snapshot.tasks.length >= FLEX_PROJECT_MANAGEMENT_LIMITS.maxTasks) {
+          throw new FlexHarnessValidationError('Project task count has reached its limit.');
+        }
+        const timestamp = new Date().toISOString();
+        const task: IFlexProjectTask = {
+          id: input.id,
+          content: input.content,
+          status,
+          priority,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        };
+        snapshot.tasks.push(task);
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async updateProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    input: IFlexUpdateProjectTaskInput,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const task = snapshot.tasks.find((entry) => entry.id === input.id);
+        if (!task) throw new FlexHarnessNotFoundError('Project task', input.id);
+        const changed = (input.content !== undefined && input.content !== task.content)
+          || (input.status !== undefined && input.status !== task.status)
+          || (input.priority !== undefined && input.priority !== task.priority);
+        if (!changed) return { changed: false, value: task };
+        if (input.content !== undefined) task.content = input.content;
+        if (input.status !== undefined) task.status = input.status;
+        if (input.priority !== undefined) task.priority = input.priority;
+        task.updatedAt = new Date().toISOString();
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async deleteProjectTaskInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    taskId: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTaskResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const index = snapshot.tasks.findIndex((task) => task.id === taskId);
+        if (index < 0) throw new FlexHarnessNotFoundError('Project task', taskId);
+        const [task] = snapshot.tasks.splice(index, 1);
+        return { changed: true, value: task };
+      },
+    );
+    return this.projectTaskResult(result.snapshot, result.value);
+  }
+
+  private async clearProjectTasksInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectTasksResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        const tasks = snapshot.tasks;
+        if (tasks.length === 0) return { changed: false, value: [] as IFlexProjectTask[] };
+        snapshot.tasks = [];
+        return { changed: true, value: tasks };
+      },
+    );
+    return this.projectTasksResult(result.snapshot, result.value);
+  }
+
+  private async setProjectGoalInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    goal: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectGoalResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.goal === goal) return { changed: false, value: undefined };
+        snapshot.goal = goal;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectGoalResult(result.snapshot);
+  }
+
+  private async clearProjectGoalInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectGoalResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.goal === undefined) return { changed: false, value: undefined };
+        delete snapshot.goal;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectGoalResult(result.snapshot);
+  }
+
+  private async setProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    content: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.scratchpad === content) return { changed: false, value: undefined };
+        snapshot.scratchpad = content;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
+  private async appendProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    content: string,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (content.length === 0) return { changed: false, value: undefined };
+        const appended = `${snapshot.scratchpad}${content}`;
+        validateUtf8String(
+          appended,
+          'project scratchpad',
+          FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+        );
+        snapshot.scratchpad = appended;
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
+  private async clearProjectScratchpadInState(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<IFlexProjectScratchpadResult> {
+    const result = await this.mutateProjectManagementState(
+      state,
+      stored,
+      writeContext,
+      (snapshot) => {
+        if (snapshot.scratchpad.length === 0) return { changed: false, value: undefined };
+        snapshot.scratchpad = '';
+        return { changed: true, value: undefined };
+      },
+    );
+    return this.projectScratchpadResult(result.snapshot);
+  }
+
   private async prepareGeneration(
     run: IActiveRun,
     options: IFlexPromptOptions,
@@ -4006,17 +4835,8 @@ export class FlexHarness<TScope = unknown> {
       let tools: TFlexAgentToolSet | undefined;
       try {
         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);
-        }
+        Object.assign(combinedTools, this.createBuiltInTools(run));
         tools = Object.keys(combinedTools).length > 0
           ? wrapToolSet(
               combinedTools as TFlexAgentToolSet,
@@ -4067,6 +4887,283 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private enabledBuiltInToolNames(run: IActiveRun): Set<string> {
+    const names = new Set<string>();
+    if (this.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
+      names.add('delegate');
+    }
+    if (this.builtInTools.renameSession) names.add('rename_session');
+    const projectManagement = this.builtInTools.projectManagement;
+    if (projectManagement?.task) names.add('task');
+    if (projectManagement?.goal) names.add('goal');
+    if (projectManagement?.scratchpad) names.add('scratchpad');
+    return names;
+  }
+
+  private assertNoBuiltInToolCollisions(run: IActiveRun, tools: TFlexAgentToolSet): void {
+    const reserved = this.enabledBuiltInToolNames(run);
+    const collision = Object.keys(tools).find((name) => reserved.has(name));
+    if (collision) {
+      throw new FlexHarnessValidationError(
+        `Tool provider cannot define enabled built-in tool "${collision}".`,
+      );
+    }
+  }
+
+  private createBuiltInTools(run: IActiveRun): Record<string, unknown> {
+    const tools: Record<string, unknown> = {};
+    if (this.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
+      tools.delegate = this.createSubagentTool(run);
+    }
+    if (this.builtInTools.renameSession) tools.rename_session = this.createRenameSessionTool(run);
+    const projectManagement = this.builtInTools.projectManagement;
+    if (projectManagement?.task) tools.task = this.createProjectTaskTool(run);
+    if (projectManagement?.goal) tools.goal = this.createProjectGoalTool(run);
+    if (projectManagement?.scratchpad) tools.scratchpad = this.createProjectScratchpadTool(run);
+    return tools;
+  }
+
+  private createRenameSessionTool(run: IActiveRun): unknown {
+    return plugins.tool({
+      description: 'Set the current FlexHarness session title.',
+      inputSchema: plugins.z.object({
+        title: plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes),
+      }).strict(),
+      execute: async ({ title }: { title: string }) => {
+        validateUtf8String(
+          title,
+          'title',
+          FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
+          true,
+        );
+        let session!: IFlexSession;
+        await this.mutateScope(run.state, () => {
+          if (run.state.sessions.get(run.sessionId) !== run.stored) {
+            throw new FlexHarnessNotFoundError('Session', run.sessionId);
+          }
+          run.stored.session.title = title;
+          run.stored.session.updatedAt = new Date().toISOString();
+          session = publicSnapshot(run.stored.session);
+        });
+        this.emitEvent(run.scopeId, run.sessionId, {
+          type: 'session.updated',
+          session,
+        });
+        return { session };
+      },
+    });
+  }
+
+  private createProjectTaskTool(run: IActiveRun): unknown {
+    const status = plugins.z.enum(['pending', 'in_progress', 'completed', 'cancelled']);
+    const priority = plugins.z.enum(['high', 'medium', 'low']);
+    const id = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes);
+    const content = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes);
+    return plugins.tool({
+      description: 'List, create, update, delete, or clear session-local project tasks.',
+      inputSchema: plugins.z.discriminatedUnion('action', [
+        plugins.z.object({ action: plugins.z.literal('list') }).strict(),
+        plugins.z.object({
+          action: plugins.z.literal('create'),
+          id: id.optional(),
+          content,
+          status: status.optional(),
+          priority: priority.optional(),
+        }).strict(),
+        plugins.z.object({
+          action: plugins.z.literal('update'),
+          id,
+          content: content.optional(),
+          status: status.optional(),
+          priority: priority.optional(),
+        }).strict().refine(
+          (input) => input.content !== undefined
+            || input.status !== undefined
+            || input.priority !== undefined,
+          { message: 'Task update requires content, status, or priority.' },
+        ),
+        plugins.z.object({ action: plugins.z.literal('delete'), id }).strict(),
+        plugins.z.object({ action: plugins.z.literal('clear') }).strict(),
+      ]),
+      execute: (
+        input: TProjectTaskToolInput,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectTaskTool(run, input, options?.toolCallId),
+    });
+  }
+
+  private createProjectGoalTool(run: IActiveRun): unknown {
+    return plugins.tool({
+      description: 'Get, set, or clear the session-local project goal.',
+      inputSchema: plugins.z.discriminatedUnion('action', [
+        plugins.z.object({ action: plugins.z.literal('get') }).strict(),
+        plugins.z.object({
+          action: plugins.z.literal('set'),
+          goal: plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes),
+        }).strict(),
+        plugins.z.object({ action: plugins.z.literal('clear') }).strict(),
+      ]),
+      execute: (
+        input: TProjectGoalToolInput,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectGoalTool(run, input, options?.toolCallId),
+    });
+  }
+
+  private createProjectScratchpadTool(run: IActiveRun): unknown {
+    const content = plugins.z.string().max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes);
+    return plugins.tool({
+      description: 'Get, set, append to, or clear the session-local project scratchpad.',
+      inputSchema: plugins.z.discriminatedUnion('action', [
+        plugins.z.object({ action: plugins.z.literal('get') }).strict(),
+        plugins.z.object({ action: plugins.z.literal('set'), content }).strict(),
+        plugins.z.object({ action: plugins.z.literal('append'), content }).strict(),
+        plugins.z.object({ action: plugins.z.literal('clear') }).strict(),
+      ]),
+      execute: (
+        input: TProjectScratchpadToolInput,
+        options?: { toolCallId?: string },
+      ) => this.executeProjectScratchpadTool(run, input, options?.toolCallId),
+    });
+  }
+
+  private projectManagementAgentWriteContext(
+    run: IActiveRun,
+    toolCallId: string | undefined,
+  ): IFlexProjectManagementWriteContext {
+    return Object.freeze({
+      actor: 'agent' as const,
+      runId: run.runId,
+      ...(run.stored.session.agent === undefined ? {} : { agent: run.stored.session.agent }),
+      ...(toolCallId === undefined ? {} : { toolCallId }),
+    });
+  }
+
+  private async executeProjectTaskTool(
+    run: IActiveRun,
+    input: TProjectTaskToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectStateResult | IFlexProjectTaskResult | IFlexProjectTasksResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'list') {
+      const snapshot = await this.readProjectManagementState(run.state, run.stored);
+      return this.projectTasksResult(snapshot, snapshot.tasks);
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'create') {
+      const id = input.id ?? (() => {
+        validateUtf8String(
+          toolCallId,
+          'task toolCallId',
+          maxTransferIdentifierBytes,
+          true,
+        );
+        return this.createProjectTaskId(
+          run.state.storageKey,
+          run.sessionId,
+          run.runId,
+          toolCallId,
+        );
+      })();
+      const createInput: IFlexCreateProjectTaskInput = {
+        id,
+        content: input.content,
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+      };
+      validateCreateProjectTaskInput(createInput);
+      return this.createProjectTaskInState(run.state, run.stored, createInput, writeContext);
+    }
+    if (input.action === 'update') {
+      const updateInput: IFlexUpdateProjectTaskInput = {
+        id: input.id,
+        ...(input.content === undefined ? {} : { content: input.content }),
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+      };
+      validateUpdateProjectTaskInput(updateInput);
+      return this.updateProjectTaskInState(run.state, run.stored, updateInput, writeContext);
+    }
+    if (input.action === 'delete') {
+      validateProjectTaskId(input.id);
+      return this.deleteProjectTaskInState(run.state, run.stored, input.id, writeContext);
+    }
+    return this.clearProjectTasksInState(run.state, run.stored, writeContext);
+  }
+
+  private async executeProjectGoalTool(
+    run: IActiveRun,
+    input: TProjectGoalToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectGoalResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'get') {
+      return this.projectGoalResult(await this.readProjectManagementState(run.state, run.stored));
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'set') {
+      validateUtf8String(
+        input.goal,
+        'project goal',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+        true,
+      );
+      return this.setProjectGoalInState(run.state, run.stored, input.goal, writeContext);
+    }
+    return this.clearProjectGoalInState(run.state, run.stored, writeContext);
+  }
+
+  private async executeProjectScratchpadTool(
+    run: IActiveRun,
+    input: TProjectScratchpadToolInput,
+    toolCallId: string | undefined,
+  ): Promise<IFlexProjectScratchpadResult> {
+    this.assertProjectManagementSession(run.state, run.stored);
+    if (input.action === 'get') {
+      return this.projectScratchpadResult(
+        await this.readProjectManagementState(run.state, run.stored),
+      );
+    }
+    const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
+    if (input.action === 'set') {
+      validateUtf8String(
+        input.content,
+        'project scratchpad',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+      );
+      return this.setProjectScratchpadInState(run.state, run.stored, input.content, writeContext);
+    }
+    if (input.action === 'append') {
+      validateUtf8String(
+        input.content,
+        'project scratchpad append',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+      );
+      return this.appendProjectScratchpadInState(
+        run.state,
+        run.stored,
+        input.content,
+        writeContext,
+      );
+    }
+    return this.clearProjectScratchpadInState(run.state, run.stored, writeContext);
+  }
+
+  private createProjectTaskId(
+    storageKey: string,
+    sessionId: string,
+    runId: string,
+    toolCallId: string,
+  ): string {
+    return `task_${sha256Hex(JSON.stringify([
+      'flexharness-project-task-v1',
+      storageKey,
+      sessionId,
+      runId,
+      toolCallId,
+    ]))}`;
+  }
+
   private createSubagentTool(run: IActiveRun): unknown {
     const available = [...this.subagents.values()]
       .map((definition) => `- ${definition.name}: ${definition.description}`)
@@ -4097,16 +5194,16 @@ export class FlexHarness<TScope = unknown> {
     }
     validateUtf8String(
       input.description,
-      'task description',
+      'delegate description',
       maxSubagentTaskDescriptionBytes,
       true,
     );
-    validateUtf8String(input.prompt, 'task prompt', maxSubagentPromptBytes, true);
+    validateUtf8String(input.prompt, 'delegate 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);
+    validateUtf8String(toolCallId, 'delegate 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.`);
@@ -4330,6 +5427,8 @@ export class FlexHarness<TScope = unknown> {
         metadata = {
           scopeId: run.scopeId,
           sessionId,
+          sessionGenerationId: createSessionGenerationId(),
+          sessionGenerationSequence: state.revision + 1,
           title: `Subagent: ${definition.name}`,
           createdAt: timestamp,
           updatedAt: timestamp,
@@ -4403,6 +5502,7 @@ export class FlexHarness<TScope = unknown> {
           state.sessions.delete(sessionId);
           state.tombstones.set(sessionId, {
             sessionId,
+            ...requireSessionGeneration(metadata!),
             deletedAt: new Date().toISOString(),
             rootSessionId: sessionId,
             depth: 0,
@@ -4458,12 +5558,12 @@ export class FlexHarness<TScope = unknown> {
     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.`);
+      throw new FlexHarnessValidationError(`Running delegate 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.');
+      throw run.callbackError ?? new FlexHarnessCallbackOverflowError('Delegate metadata exceeded callback limits.');
     }
     part.childSessionId = childSessionId;
     if (model !== undefined) part.model = cloneSerializable(model);
@@ -6264,6 +7364,7 @@ export class FlexHarness<TScope = unknown> {
         throw new FlexHarnessValidationError('Tool handle close must be a function.');
       }
       const tools = handle.tools;
+      this.assertNoBuiltInToolCollisions(run, tools);
       const closeHandle = close;
       return {
         tools,
@@ -6603,6 +7704,28 @@ export class FlexHarness<TScope = unknown> {
       sessions: [],
       tombstones: [],
     } satisfies IFlexScopeSnapshot);
+    let scopeChanged = false;
+    const repairedGenerationSequence = snapshot.revision + 1;
+    for (const session of snapshot.sessions) {
+      if (session.sessionGenerationId !== undefined) continue;
+      session.sessionGenerationId = deriveLegacySessionGenerationId(
+        storageKey,
+        session.sessionId,
+        session.createdAt,
+      );
+      session.sessionGenerationSequence = repairedGenerationSequence;
+      scopeChanged = true;
+    }
+    for (const tombstone of snapshot.tombstones) {
+      if (tombstone.sessionGenerationId !== undefined) continue;
+      tombstone.sessionGenerationId = deriveLegacySessionGenerationId(
+        storageKey,
+        tombstone.sessionId,
+        tombstone.deletedAt,
+      );
+      tombstone.sessionGenerationSequence = repairedGenerationSequence;
+      scopeChanged = true;
+    }
     const state: IStorageState = {
       storageKey,
       compactorLifecycleController,
@@ -6625,7 +7748,6 @@ export class FlexHarness<TScope = unknown> {
       detachedCleanups: new Set(),
     };
     const loadedSessions: IStoredSessionState[] = [];
-    let scopeChanged = false;
     try {
       for (const metadata of snapshot.sessions) {
         if (state.tombstones.has(metadata.sessionId)) continue;
@@ -6677,7 +7799,7 @@ export class FlexHarness<TScope = unknown> {
               scopeId,
               scope,
             );
-            await this.cleanupSessionDomains(storageKey, tombstone.sessionId);
+            await this.cleanupSessionDomains(storageKey, tombstone);
           }
           for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
           scopeChanged = true;
@@ -7637,12 +8759,26 @@ export class FlexHarness<TScope = unknown> {
     stored.projectionReconciliationRequired = false;
   }
 
-  private async cleanupSessionDomains(storageKey: string, sessionId: string): Promise<void> {
+  private async cleanupSessionDomains(
+    storageKey: string,
+    tombstone: IFlexSessionTombstone,
+  ): Promise<void> {
+    const sessionId = tombstone.sessionId;
+    const projectManagementCleanup = async (): Promise<void> => {
+      await this.projectManagementQueues.get(
+        this.projectManagementKey(storageKey, sessionId),
+      );
+      await this.tombstoneProjectManagementSession(
+        storageKey,
+        tombstone,
+      );
+    };
     const results = await Promise.allSettled([
       this.stores.agentEvents.deleteSession(storageKey, sessionId),
       this.stores.jobs.deleteSession(storageKey, sessionId),
       this.stores.projections.deleteSession(storageKey, sessionId),
       this.stores.permissions.deleteSession(storageKey, sessionId),
+      projectManagementCleanup(),
     ]);
     const errors = results
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
@@ -7650,6 +8786,66 @@ export class FlexHarness<TScope = unknown> {
     if (errors.length > 0) throw combineErrors(errors);
   }
 
+  private async tombstoneProjectManagementSession(
+    storageKey: string,
+    sessionTombstone: IFlexSessionTombstone,
+  ): Promise<void> {
+    const store = this.stores.projectManagement;
+    const sessionId = sessionTombstone.sessionId;
+    const generation = requireSessionGeneration(sessionTombstone);
+    let lastConflict: FlexHarnessStoreConflictError | undefined;
+    for (let attempt = 0; attempt <= maxProjectManagementTombstoneConflicts; attempt++) {
+      const current = await store.load(storageKey, sessionId);
+      if (current !== undefined) {
+        assertFlexProjectManagementRecord(current);
+        if (current.sessionGenerationId === generation.sessionGenerationId) {
+          if (current.sessionGenerationSequence !== generation.sessionGenerationSequence) {
+            throw new FlexHarnessStoreConflictError(
+              this.projectManagementKey(storageKey, sessionId),
+              0,
+              current.revision,
+            );
+          }
+          if ('deletedAt' in current) return;
+        } else if (
+          !('deletedAt' in current)
+          || current.sessionGenerationSequence >= generation.sessionGenerationSequence
+        ) {
+          throw new FlexHarnessStoreConflictError(
+            this.projectManagementKey(storageKey, sessionId),
+            0,
+            current.revision,
+          );
+        }
+      }
+      if (attempt === maxProjectManagementTombstoneConflicts) break;
+      const expectedRevision = current === undefined
+        || current.sessionGenerationId !== generation.sessionGenerationId
+        ? 0
+        : current.revision;
+      const tombstone: IFlexProjectManagementTombstone = {
+        schemaVersion: 1,
+        revision: expectedRevision + 1,
+        ...generation,
+        deletedAt: sessionTombstone.deletedAt,
+      };
+      try {
+        await store.tombstoneSession(
+          storageKey,
+          sessionId,
+          tombstone,
+          expectedRevision,
+        );
+      } catch (error) {
+        if (!(error instanceof FlexHarnessStoreConflictError)) throw error;
+        lastConflict = error;
+      }
+    }
+    throw lastConflict ?? new FlexHarnessValidationError(
+      `Project management tombstone for session "${sessionId}" could not be durably confirmed.`,
+    );
+  }
+
   private collectSessionSubtree(
     state: IStorageState,
     rootSessionId: string,
@@ -7845,7 +9041,7 @@ export class FlexHarness<TScope = unknown> {
           releaseContext.scope,
           retained?.stored,
         );
-        await this.cleanupSessionDomains(state.storageKey, sessionId);
+        await this.cleanupSessionDomains(state.storageKey, tombstone);
         if (retained) retained.domainsCompleted = true;
       }
     }
@@ -7925,6 +9121,13 @@ export class FlexHarness<TScope = unknown> {
       await Promise.allSettled([...state.sessionInitializations.values()]);
       cleanupErrors.push(...await this.closeOrphanedResources(state.storageKey));
       await state.scopeQueue;
+      await this.awaitProjectManagementOperations(
+        state.storageKey,
+        [
+          ...state.sessions.keys(),
+          ...state.retainedSessionCleanups.keys(),
+        ],
+      );
       const currentTombstoneRoot = state.tombstones.get(currentRun.sessionId)?.rootSessionId
         ?? currentRun.sessionId;
       const currentTombstoneCleanup = state.tombstoneCleanups.get(currentTombstoneRoot);
@@ -8458,6 +9661,13 @@ export class FlexHarness<TScope = unknown> {
     await Promise.allSettled([...state.sessionInitializations.values()]);
     errors.push(...await this.closeOrphanedResources(state.storageKey));
     await state.scopeQueue;
+    await this.awaitProjectManagementOperations(
+      state.storageKey,
+      [
+        ...state.sessions.keys(),
+        ...state.retainedSessionCleanups.keys(),
+      ],
+    );
     await Promise.all([...state.sessions.values()].flatMap((stored) => [
       stored.projectionQueue,
       stored.permissionQueue,