@modelprofile.com/flexharness 9.6.1 → 9.8.0

package/ts/classes.flexharness.ts

@@ -79,6 +79,7 @@ import type {
   IFlexPendingReversionRelease,
   IFlexRedoSessionResult,
   IFlexResolvedModel,
+  IFlexResolvedSessionConfiguration,
   IFlexResolvedScope,
   IFlexResourceToolProviderDescriptor,
   IFlexRunFinishedEvent,
@@ -86,6 +87,7 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionPermissionPolicyContext,
   IFlexSessionActivity,
   IFlexSessionGeneration,
   IFlexSessionGenerationCohortEntry,
@@ -154,6 +156,7 @@ import {
 } from './utils.prompt.js';
 import {
   maxSubagentNameBytes,
+  normalizeAllowedTools,
   normalizeAgentSessionPolicy,
   normalizeBuiltInTools,
   normalizeSlashCommands,
@@ -212,6 +215,7 @@ import {
   validatePromptOptions,
   validateSlashCommandExecutionOptions,
   validateSessionGenerationId,
+  validateSessionConfigurationRef,
   validateUpdateProjectTaskInput,
   validateUpdateSessionOptions,
   validateUtf8String,
@@ -396,6 +400,10 @@ interface IActiveRun {
   reservedUserMessage?: IFlexMessage;
   reservedAssistantMessage?: IFlexMessage;
   modelResolution?: IFlexResolvedModel;
+  subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  allowedTools?: readonly string[];
+  agentAllowedTools?: readonly string[];
+  permissionPolicy?: IFlexResolvedSessionConfiguration<unknown>['permissionPolicy'];
   delegatedRunAdmissionOwner?: IDelegatedRunAdmissionOwner;
   delegatedRunAdmissionClose?: Promise<void>;
   completion: Promise<IFlexPromptResult>;
@@ -511,6 +519,22 @@ interface IActiveSlashCommandListing {
   completion: Promise<unknown>;
 }
 
+interface IResolvedSessionConfiguration<TScope> {
+  subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
+  allowedTools?: readonly string[];
+  permissionPolicy?: IFlexResolvedSessionConfiguration<TScope>['permissionPolicy'];
+}
+
+interface ISessionConfigurationOwner<TScope> {
+  storageKey: string;
+  sessionId: string;
+  controller: AbortController;
+  completion: Promise<IResolvedSessionConfiguration<TScope>>;
+  settled: boolean;
+  waiters: number;
+}
+
 interface ISlashCommandInvocationOwner {
   scopeId: string;
   storageKey: string;
@@ -743,6 +767,7 @@ function containsStoreCommitUncertainty(error: unknown, seen = new Set<unknown>(
 export class FlexHarness<TScope = unknown> {
   private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
   private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
+  private readonly sessionConfigurationResolver: IFlexHarnessOptions<TScope>['sessionConfigurationResolver'];
   private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
   private readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
@@ -764,6 +789,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly maxSubagentDepth: number;
   private readonly maxSubagentCallsPerRun: number;
   private readonly stateLoads = new Map<string, Promise<IStorageState>>();
+  private readonly sessionConfigurations = new Map<string, ISessionConfigurationOwner<TScope>>();
   private readonly scopeAdmissions = new Map<string, IScopeAdmissionState>();
   private readonly scopeRetirements = new Map<string, Promise<void>>();
   private readonly storageDrains = new Map<string, Promise<void>>();
@@ -810,6 +836,7 @@ export class FlexHarness<TScope = unknown> {
     }
     this.scopeResolver = options.scopeResolver;
     this.modelResolver = options.modelResolver;
+    this.sessionConfigurationResolver = options.sessionConfigurationResolver;
     this.toolProvider = options.toolProvider;
     this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
@@ -878,13 +905,14 @@ export class FlexHarness<TScope = unknown> {
       throw new FlexHarnessValidationError('createSession options must be a plain object.');
     }
     const unsupported = Object.keys(options).find(
-      (key) => !['sessionId', 'sessionGenerationId', 'title'].includes(key),
+      (key) => !['sessionId', 'sessionGenerationId', 'configurationRef', 'title'].includes(key),
     );
     if (unsupported) throw new FlexHarnessValidationError(`createSession does not support "${unsupported}".`);
     const requestedSessionGenerationId = options.sessionGenerationId;
     if (requestedSessionGenerationId !== undefined) {
       validateSessionGenerationId(requestedSessionGenerationId);
     }
+    if (options.configurationRef !== undefined) validateSessionConfigurationRef(options.configurationRef);
     const resolved = await this.resolveState(scopeId);
     const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
     validateIdentifier(sessionId, 'sessionId');
@@ -933,6 +961,7 @@ export class FlexHarness<TScope = unknown> {
           sessionId,
           sessionGenerationId: requestedSessionGenerationId ?? createSessionGenerationId(),
           sessionGenerationSequence: resolved.state.revision + 1,
+          ...(options.configurationRef === undefined ? {} : { configurationRef: options.configurationRef }),
           ...(options.title ? { title: options.title } : {}),
           createdAt: timestamp,
           updatedAt: timestamp,
@@ -1205,6 +1234,9 @@ export class FlexHarness<TScope = unknown> {
           sessionId,
           sessionGenerationId: createSessionGenerationId(),
           sessionGenerationSequence: state.revision + 1,
+          ...(parent?.session.configurationRef === undefined
+            ? {}
+            : { configurationRef: parent.session.configurationRef }),
           ...(options.title === undefined ? {} : { title: options.title }),
           createdAt: options.createdAt,
           updatedAt: options.updatedAt,
@@ -1800,6 +1832,12 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<void> {
     const { deletedSessions, descendantRoots } = reservation;
     const reason = this.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
+    const configurationSettlement = this.abortSessionConfigurations(
+      state.storageKey,
+      reason,
+      new Set(deletedSessions.map((deleted) => deleted.sessionId)),
+    );
+    if (configurationSettlement) await configurationSettlement;
     const slashCommandErrors: unknown[] = [];
     for (const deleted of deletedSessions) {
       const listingSettlement = this.abortSlashCommandListings(
@@ -1940,16 +1978,165 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot(createBoundedTransferMessage(this.requireMessage(stored, messageId)));
   }
 
+  private async resolveSessionConfiguration(
+    scopeId: string,
+    scope: TScope,
+    state: IStorageState,
+    stored: IStoredSessionState,
+    signal?: AbortSignal,
+  ): Promise<IResolvedSessionConfiguration<TScope>> {
+    const configurationRef = stored.session.configurationRef;
+    if (configurationRef === undefined) {
+      return { subagents: this.subagents, slashCommands: this.slashCommands };
+    }
+    const sessionId = stored.session.sessionId;
+    const generation = requireSessionGeneration(stored.session);
+    const key = JSON.stringify([
+      state.storageKey,
+      sessionId,
+      generation.sessionGenerationId,
+      generation.sessionGenerationSequence,
+      configurationRef,
+    ]);
+    let owner = this.sessionConfigurations.get(key);
+    if (!owner) {
+      const controller = new AbortController();
+      const parent = stored.session.parentSessionId === undefined
+        ? undefined
+        : state.sessions.get(stored.session.parentSessionId);
+      if (stored.session.parentSessionId !== undefined && !parent) {
+        throw this.trustInternalError(new FlexHarnessAbortError('The session parent is no longer available.'));
+      }
+      const parentGeneration = parent === undefined ? undefined : requireSessionGeneration(parent.session);
+      const context = Object.freeze({
+        scopeId,
+        scope,
+        storageKey: state.storageKey,
+        sessionId,
+        ...generation,
+        configurationRef,
+        ...(parent === undefined ? {} : {
+          parentSessionId: parent.session.sessionId,
+          parentSessionGenerationId: parentGeneration!.sessionGenerationId,
+          parentSessionGenerationSequence: parentGeneration!.sessionGenerationSequence,
+        }),
+        ...(stored.session.agent === undefined ? {} : { agent: stored.session.agent }),
+        depth: stored.session.depth ?? 0,
+        signal: controller.signal,
+      });
+      let rejectAbort!: (reason: unknown) => void;
+      const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject; });
+      const onAbort = () => rejectAbort(controller.signal.reason);
+      controller.signal.addEventListener('abort', onAbort, { once: true });
+      const resolved = Promise.resolve().then(() => {
+        if (!this.sessionConfigurationResolver) {
+          throw new Error('A sessionConfigurationResolver is required for bound sessions.');
+        }
+        return this.sessionConfigurationResolver.resolveSessionConfiguration(context);
+      });
+      const completion = Promise.race([resolved, aborted]).then((configuration) => {
+        controller.signal.throwIfAborted();
+        if (
+          state.lifecycle !== 'active'
+          || state.sessions.get(sessionId) !== stored
+          || stored.session.configurationRef !== configurationRef
+          || stored.session.sessionGenerationId !== generation.sessionGenerationId
+          || stored.session.sessionGenerationSequence !== generation.sessionGenerationSequence
+        ) {
+          throw this.trustInternalError(new FlexHarnessAbortError(
+            'The session configuration lost its session generation ownership.',
+          ));
+        }
+        if (
+          !configuration
+          || typeof configuration !== 'object'
+          || Array.isArray(configuration)
+          || ![Object.prototype, null].includes(Object.getPrototypeOf(configuration))
+          || Reflect.ownKeys(configuration).some((name) =>
+            typeof name !== 'string' || !['subagents', 'slashCommands', 'allowedTools', 'permissionPolicy'].includes(name))
+        ) throw new FlexHarnessValidationError('Resolved session configuration is invalid.');
+        if (configuration.permissionPolicy !== undefined && typeof configuration.permissionPolicy !== 'function') {
+          throw new FlexHarnessValidationError('Resolved session permissionPolicy must be a function.');
+        }
+        return Object.freeze({
+          subagents: normalizeSubagents(configuration.subagents),
+          slashCommands: normalizeSlashCommands(configuration.slashCommands),
+          allowedTools: normalizeAllowedTools(configuration.allowedTools),
+          permissionPolicy: configuration.permissionPolicy,
+        });
+      }).catch((error: unknown) => {
+        if (this.sessionConfigurations.get(key)?.completion === completion) {
+          this.sessionConfigurations.delete(key);
+        }
+        if (controller.signal.aborted) throw controller.signal.reason;
+        throw this.projectOperationError(
+          error,
+          'sessionConfigurationResolver',
+          scopeId,
+          sessionId,
+          'session-configuration',
+        );
+      }).finally(() => {
+        controller.signal.removeEventListener('abort', onAbort);
+        const current = this.sessionConfigurations.get(key);
+        if (current?.completion === completion) current.settled = true;
+      });
+      owner = { storageKey: state.storageKey, sessionId, controller, completion, settled: false, waiters: 0 };
+      this.sessionConfigurations.set(key, owner);
+    }
+    owner.waiters++;
+    let onConsumerAbort: (() => void) | undefined;
+    const consumerAbort = signal && new Promise<never>((_resolve, reject) => {
+      onConsumerAbort = () => reject(signal.reason ?? this.trustInternalError(
+        new FlexHarnessAbortError('Session configuration resolution was aborted.'),
+      ));
+      signal.addEventListener('abort', onConsumerAbort, { once: true });
+      if (signal.aborted) onConsumerAbort();
+    });
+    try {
+      return await (consumerAbort
+        ? Promise.race([owner.completion, consumerAbort])
+        : owner.completion);
+    } finally {
+      if (signal && onConsumerAbort) signal.removeEventListener('abort', onConsumerAbort);
+      owner.waiters--;
+      if (owner.waiters === 0 && !owner.settled && !owner.controller.signal.aborted) {
+        if (this.sessionConfigurations.get(key) === owner) this.sessionConfigurations.delete(key);
+        owner.controller.abort(this.trustInternalError(new FlexHarnessAbortError(
+          'Session configuration resolution has no active callers.',
+        )));
+      }
+    }
+  }
+
+  private abortSessionConfigurations(
+    storageKey: string,
+    reason: FlexHarnessAbortError,
+    sessionIds?: ReadonlySet<string>,
+  ): Promise<void> | undefined {
+    const owners = [...this.sessionConfigurations.entries()].filter(([, owner]) =>
+      owner.storageKey === storageKey && (sessionIds === undefined || sessionIds.has(owner.sessionId)));
+    if (owners.length === 0) return undefined;
+    for (const [key, owner] of owners) {
+      this.sessionConfigurations.delete(key);
+      if (!owner.controller.signal.aborted) owner.controller.abort(reason);
+    }
+    return Promise.allSettled(owners.map(([, owner]) => owner.completion)).then(() => undefined);
+  }
+
   public async listSlashCommands(
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexSlashCommandDescriptor[]> {
-    const { state } = await this.resolveState(scopeId);
+    const { scope, state } = await this.resolveState(scopeId);
     return this.trackSlashCommandListing(scopeId, state, sessionId, async (signal) => {
       await this.awaitReversionOperation(state.scopeQueue, signal);
       signal.throwIfAborted();
       this.assertStateAcceptingWork(state);
       const stored = this.requireSession(state, sessionId);
+      const configuration = await this.resolveSessionConfiguration(
+        scopeId, scope.scope, state, stored, signal,
+      );
       await this.reconcileContextAvailability(state, stored);
       signal.throwIfAborted();
       const sessionAvailable = this.isSessionAvailableForSlashCommand(state, stored);
@@ -1965,6 +2152,7 @@ export class FlexHarness<TScope = unknown> {
         stored,
         sessionAvailable,
         reversionIdleReason,
+        configuration.slashCommands,
       );
       if (stored.session.origin === undefined) return descriptors;
       return publicSnapshot(descriptors.map((descriptor): IFlexSlashCommandDescriptor => ({
@@ -1980,6 +2168,7 @@ export class FlexHarness<TScope = unknown> {
     stored: IStoredSessionState,
     sessionAvailable: boolean,
     reversionIdleReason?: string,
+    slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>> = this.slashCommands,
   ): IFlexSlashCommandDescriptor[] {
     const sessionAvailability = sessionAvailable
       ? {}
@@ -2058,7 +2247,7 @@ export class FlexHarness<TScope = unknown> {
         workspaceReversion: workspaceReversion(redoUnit),
       },
     ];
-    for (const registration of this.slashCommands.values()) {
+    for (const registration of slashCommands.values()) {
       const template = typeof registration.template === 'string';
       const availability = template
         ? this.slashCommandPromptAvailability(
@@ -2087,6 +2276,26 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
     untouchedInput: string,
     options: IFlexSlashCommandExecutionOptions = {},
+  ): Promise<TFlexSlashCommandExecutionResult> {
+    return this.executeSlashCommandInternal(scopeId, sessionId, untouchedInput, options, false);
+  }
+
+  /** Resolves the exact session configuration before looking up custom commands. */
+  public async executeSessionSlashCommand(
+    scopeId: string,
+    sessionId: string,
+    untouchedInput: string,
+    options: IFlexSlashCommandExecutionOptions = {},
+  ): Promise<TFlexSlashCommandExecutionResult> {
+    return this.executeSlashCommandInternal(scopeId, sessionId, untouchedInput, options, true);
+  }
+
+  private async executeSlashCommandInternal(
+    scopeId: string,
+    sessionId: string,
+    untouchedInput: string,
+    options: IFlexSlashCommandExecutionOptions,
+    sessionAware: boolean,
   ): Promise<TFlexSlashCommandExecutionResult> {
     const currentInvocation = this.slashCommandInvocationContext.getStore();
     if (currentInvocation?.scopeId === scopeId && currentInvocation.sessionId === sessionId) {
@@ -2094,8 +2303,8 @@ export class FlexHarness<TScope = unknown> {
     }
     const parsed = parseSlashCommand(untouchedInput);
     if (parsed.type !== 'parsed') return parsed;
-    const registration = this.slashCommands.get(parsed.name);
-    if (!isReservedSlashCommandName(parsed.name) && !registration) {
+    let registration = sessionAware ? undefined : this.slashCommands.get(parsed.name);
+    if (!sessionAware && !isReservedSlashCommandName(parsed.name) && !registration) {
       return Object.freeze({
         type: 'unknown',
         input: parsed.input,
@@ -2111,6 +2320,31 @@ export class FlexHarness<TScope = unknown> {
     this.assertStateAcceptingWork(state);
     const stored = this.requireSession(state, sessionId);
     this.assertSessionWritable(stored);
+    if (sessionAware) {
+      const configuration = await this.resolveSessionConfiguration(
+        scopeId, scope.scope, state, stored, options.signal,
+      );
+      this.assertStateAcceptingWork(state);
+      if (state.sessions.get(sessionId) !== stored) {
+        throw this.trustInternalError(new FlexHarnessAbortError(
+          'The session was deleted during slash command resolution.',
+        ));
+      }
+      registration = configuration.slashCommands.get(parsed.name);
+      if (!isReservedSlashCommandName(parsed.name) && !registration) {
+        return Object.freeze({
+          type: 'unknown',
+          input: parsed.input,
+          name: parsed.name,
+          rawArguments: parsed.rawArguments,
+          arguments: parsed.arguments,
+        });
+      }
+    } else if (stored.session.configurationRef !== undefined) {
+      throw new FlexHarnessValidationError(
+        'A bound session requires executeSessionSlashCommand().',
+      );
+    }
     const sessionKey = this.slashCommandSessionKey(state.storageKey, sessionId);
     const invocationOwner = this.slashCommandInvocationContext.getStore();
     if (invocationOwner?.sessionKey === sessionKey) {
@@ -3733,6 +3967,7 @@ export class FlexHarness<TScope = unknown> {
 
   private createActiveRun(queued: IQueuedPrompt): IActiveRun {
     return {
+      subagents: this.subagents,
       state: queued.state,
       stored: queued.stored,
       originCompactorContext: this.createCompactorContext(
@@ -4959,6 +5194,22 @@ export class FlexHarness<TScope = unknown> {
     signal: AbortSignal,
   ): Promise<plugins.IAgentGenerationLease> {
     signal.throwIfAborted();
+    const configuration = await this.resolveSessionConfiguration(
+      run.scopeId,
+      run.scope as TScope,
+      run.state,
+      run.stored,
+      signal,
+    );
+    run.subagents = configuration.subagents;
+    run.allowedTools = configuration.allowedTools;
+    run.permissionPolicy = configuration.permissionPolicy as IActiveRun['permissionPolicy'];
+    const agent = run.stored.session.agent;
+    if (agent !== undefined) {
+      const definition = configuration.subagents.get(agent);
+      if (!definition) throw new FlexHarnessValidationError(`Subagent "${agent}" is disabled.`);
+      run.agentAllowedTools = definition.allowedTools;
+    }
     await this.prepareRunReversion(run, signal);
     run.phase = 'running';
     const queued = run.stored.outstandingPromptsById.get(run.queueId);
@@ -5069,9 +5320,16 @@ export class FlexHarness<TScope = unknown> {
         const providedTools = toolHandle?.tools;
         const combinedTools: Record<string, unknown> = { ...(providedTools ?? {}) };
         Object.assign(combinedTools, this.createBuiltInTools(run));
-        tools = Object.keys(combinedTools).length > 0
+        const globalNames = run.allowedTools === undefined ? undefined : new Set(run.allowedTools);
+        const agentNames = run.agentAllowedTools === undefined ? undefined : new Set(run.agentAllowedTools);
+        const admittedTools = globalNames === undefined && agentNames === undefined
+          ? combinedTools
+          : Object.fromEntries(Object.entries(combinedTools).filter(([name]) =>
+              (globalNames === undefined || globalNames.has(name))
+              && (agentNames === undefined || agentNames.has(name))));
+        tools = Object.keys(admittedTools).length > 0
           ? wrapToolSet(
-              combinedTools as TFlexAgentToolSet,
+              admittedTools as TFlexAgentToolSet,
               this.toolOutputLimits,
               (toolError) => this.projectExternalError(run, toolError, 'toolExecution'),
             )
@@ -5121,7 +5379,7 @@ 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) {
+    if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
       names.add('delegate');
     }
     if (this.builtInTools.renameSession) names.add('rename_session');
@@ -5144,7 +5402,7 @@ export class FlexHarness<TScope = unknown> {
 
   private createBuiltInTools(run: IActiveRun): Record<string, unknown> {
     const tools: Record<string, unknown> = {};
-    if (this.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
+    if (run.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);
@@ -5475,7 +5733,7 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private createSubagentTool(run: IActiveRun): unknown {
-    const available = [...this.subagents.values()]
+    const available = [...run.subagents.values()]
       .map((definition) => `- ${definition.name}: ${definition.description}`)
       .join('\n');
     return plugins.tool({
@@ -5527,7 +5785,7 @@ export class FlexHarness<TScope = unknown> {
       validateUtf8String(input.taskId, 'taskId', maxSubagentTaskIdBytes, true);
     }
     validateUtf8String(toolCallId, 'delegate toolCallId', maxTransferIdentifierBytes, true);
-    const definition = this.subagents.get(input.subagentType);
+    const definition = run.subagents.get(input.subagentType);
     if (!definition || (run.stored.session.depth ?? 0) >= this.maxSubagentDepth) {
       throw new FlexHarnessValidationError(`Subagent "${input.subagentType}" is not available.`);
     }
@@ -5738,7 +5996,7 @@ export class FlexHarness<TScope = unknown> {
         if (state.activeRuns.get(run.sessionId) !== run || run.callbacksClosed) {
           throw new FlexHarnessAbortError('The parent run no longer owns this subagent request.');
         }
-        if (run.stored.session.agent !== undefined && !this.subagents.has(run.stored.session.agent)) {
+        if (run.stored.session.agent !== undefined && !run.subagents.has(run.stored.session.agent)) {
           throw new FlexHarnessValidationError(`Parent subagent "${run.stored.session.agent}" is disabled.`);
         }
         if ((run.stored.session.depth ?? 0) >= this.maxSubagentDepth) {
@@ -5760,8 +6018,11 @@ export class FlexHarness<TScope = unknown> {
           if (
             existing.session.parentSessionId !== run.sessionId
             || existing.session.agent !== definition.name
+            || existing.session.configurationRef !== run.stored.session.configurationRef
           ) {
-            throw new FlexHarnessValidationError(`Task session "${sessionId}" is not owned by this parent and agent.`);
+            throw new FlexHarnessValidationError(
+              `Task session "${sessionId}" is not owned by this parent, agent, and configuration.`,
+            );
           }
           if (
             taskId === undefined
@@ -5802,6 +6063,9 @@ export class FlexHarness<TScope = unknown> {
           sessionId,
           sessionGenerationId: createSessionGenerationId(),
           sessionGenerationSequence: state.revision + 1,
+          ...(run.stored.session.configurationRef === undefined
+            ? {}
+            : { configurationRef: run.stored.session.configurationRef }),
           title: `Subagent: ${definition.name}`,
           createdAt: timestamp,
           updatedAt: timestamp,
@@ -7522,8 +7786,10 @@ export class FlexHarness<TScope = unknown> {
     if (state.activeRuns.get(run.sessionId) !== run || run.callbacksClosed) {
       throw new FlexHarnessPermissionStateError(`Run "${run.runId}" no longer accepts permission requests.`);
     }
-    if (input.rememberKey && run.stored.rememberedPermissionKeys.has(input.rememberKey)) return;
-    const request: IFlexPermissionRequest = {
+    if (!run.permissionPolicy && input.rememberKey && run.stored.rememberedPermissionKeys.has(input.rememberKey)) {
+      return;
+    }
+    const candidate: IFlexPermissionRequest = {
       permissionId: plugins.crypto.randomUUID(),
       scopeId: run.scopeId,
       sessionId: run.sessionId,
@@ -7540,6 +7806,33 @@ export class FlexHarness<TScope = unknown> {
           : { metadata: normalizeJsonValue(input.metadata, this.toolOutputLimits) }),
       createdAt: new Date().toISOString(),
     };
+    const policyDecision = run.permissionPolicy
+      ? await this.decideSessionPermissionPolicy(state, run, candidate)
+      : 'inherit';
+    if (policyDecision === 'allow' || policyDecision === 'deny') {
+      this.emitEvent(run.scopeId, run.stored.session, {
+        type: 'permission.resolved',
+        runId: run.runId,
+        request: publicSnapshot(candidate),
+        decision: policyDecision === 'allow' ? 'once' : 'reject',
+        origin: 'policy',
+      });
+      if (policyDecision === 'deny') {
+        const rejection = this.trustInternalError(
+          new FlexHarnessPermissionRejectedError(candidate.permissionId),
+        );
+        this.abortRunInternally(run, rejection);
+        throw rejection;
+      }
+      return;
+    }
+    if (policyDecision === 'inherit'
+      && input.rememberKey && run.stored.rememberedPermissionKeys.has(input.rememberKey)) return;
+    const request: IFlexPermissionRequest = { ...candidate };
+    if (policyDecision === 'ask') {
+      delete request.rememberKey;
+      request.requiresExplicitResponse = true;
+    }
     let resolvePermission!: () => void;
     let rejectPermission!: (error: unknown) => void;
     const promise = new Promise<void>((resolve, reject) => {
@@ -7587,6 +7880,70 @@ export class FlexHarness<TScope = unknown> {
     return promise;
   }
 
+  private async decideSessionPermissionPolicy(
+    state: IStorageState,
+    run: IActiveRun,
+    request: IFlexPermissionRequest,
+  ): Promise<'inherit' | 'allow' | 'ask' | 'deny'> {
+    const policy = run.permissionPolicy!;
+    const signal = run.controller.signal;
+    const context: Readonly<IFlexSessionPermissionPolicyContext<unknown>> = Object.freeze({
+      scopeId: run.scopeId,
+      scope: run.scope,
+      storageKey: state.storageKey,
+      sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
+      runId: run.runId,
+      configurationRef: run.stored.session.configurationRef!,
+      ...(run.stored.session.agent === undefined ? {} : { agent: run.stored.session.agent }),
+      request: publicSnapshot(request),
+      signal,
+    });
+    let onAbort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      onAbort = () => reject(signal.reason ?? this.trustInternalError(new FlexHarnessAbortError()));
+    });
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    let decision: unknown;
+    try {
+      decision = await Promise.race([
+        Promise.resolve().then(() => {
+          signal.throwIfAborted();
+          return policy(context);
+        }),
+        aborted,
+      ]);
+      if (!['inherit', 'allow', 'ask', 'deny'].includes(decision as string)) {
+        throw new FlexHarnessValidationError('Session permissionPolicy returned an invalid decision.');
+      }
+    } catch (error) {
+      if (signal.aborted) throw signal.reason;
+      const projected = this.projectExternalError(run, error, 'permissionPolicy');
+      this.abortRunInternally(run, projected);
+      throw projected;
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+    }
+    signal.throwIfAborted();
+    const generation = requireSessionGeneration(run.stored.session);
+    if (
+      state.lifecycle !== 'active'
+      || state.activeRuns.get(run.sessionId) !== run
+      || state.sessions.get(run.sessionId) !== run.stored
+      || run.callbacksClosed
+      || generation.sessionGenerationId !== request.sessionGenerationId
+      || generation.sessionGenerationSequence !== request.sessionGenerationSequence
+    ) {
+      const ownershipError = this.trustInternalError(new FlexHarnessAbortError(
+        'Permission policy lost its exact run ownership.',
+      ));
+      this.abortRunInternally(run, ownershipError);
+      throw ownershipError;
+    }
+    return decision as 'inherit' | 'allow' | 'ask' | 'deny';
+  }
+
   private async applyPermissionResponse(
     state: IStorageState,
     pending: IPendingPermission,
@@ -10254,6 +10611,8 @@ export class FlexHarness<TScope = unknown> {
       return;
     }
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
+    const configurationSettlement = this.abortSessionConfigurations(storageKey, reason);
+    if (configurationSettlement) await configurationSettlement;
     for (const staged of [...state.sessionImports.values()]) {
       if (staged.phase === 'staging') this.releaseStagedSessionImport(staged);
     }
@@ -10444,6 +10803,7 @@ export class FlexHarness<TScope = unknown> {
     this.scopeRetirements.clear();
     this.storageDrains.clear();
     this.storageCompactorLifecycleControllers.clear();
+    this.sessionConfigurations.clear();
   }
 
   private async abortSlashCommandExecutions(