@opengeni/core 0.12.7 → 0.14.3

package/src/domain/session-tool-policy.ts

@@ -10,7 +10,6 @@ import {
 } from "@opengeni/contracts";
 import type { Database } from "@opengeni/db";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
-import { enabledCapabilityMcpToolRefs } from "./resources";
 
 const MANDATORY_SESSION_MCP_SERVER_IDS = ["opengeni"] as const;
 const PROJECTABLE_REGISTRY_ID = /^[A-Za-z0-9_-]+$/;
@@ -21,11 +20,8 @@ export type ResolvedSessionToolPolicy = {
 };
 
 export type SessionToolPolicyInput = {
-  toolPolicy?: SessionToolPolicy | null;
+  toolPolicy: SessionToolPolicy;
   sessionTools: ToolRef[];
-  turnTools?: ToolRef[];
-  /** Undefined preserves the legacy merge path for pre-provenance callers. */
-  turnToolsProvided?: boolean;
   availableMcpServerIds: Iterable<string>;
   /** Current omitted-tools defaults, intentionally narrower than all servers. */
   defaultMcpServerIds?: Iterable<string>;
@@ -35,6 +31,12 @@ function sortedIds(ids: Iterable<string>): string[] {
   return [...new Set(ids)].sort();
 }
 
+/** Every configured runtime MCP defaults on; mandatory carrier IDs are separate. */
+export function defaultSessionMcpServerIds(servers: Iterable<{ id: string }>): string[] {
+  const mandatory = new Set<string>(MANDATORY_SESSION_MCP_SERVER_IDS);
+  return sortedIds([...servers].map((server) => server.id).filter((id) => !mandatory.has(id)));
+}
+
 function projectIds(ids: readonly string[]): { ids: string[]; truncated: boolean } {
   const projectable = ids.filter(
     (id) =>
@@ -52,33 +54,27 @@ function projectIds(ids: readonly string[]): { ids: string[]; truncated: boolean
  * Resolve the same ID-only policy used by API projections and worker turns.
  * This function never receives endpoint URLs, credentials, schemas, or live
  * probe results. `availableMcpServerIds` is the resolved runtime registry;
- * `defaultMcpServerIds` is the capability-only omitted-tools set.
+ * `defaultMcpServerIds` is the current configured omitted-tools default.
  */
 export function resolveSessionToolPolicy(input: SessionToolPolicyInput): ResolvedSessionToolPolicy {
-  const policy = input.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null };
+  const policy = input.toolPolicy;
   const availableIds = new Set(input.availableMcpServerIds);
-  // Never infer omitted-tools defaults from the full runtime registry: static
-  // MCPs are explicit-only unless they are capability-derived defaults.
   const defaultIds = new Set(input.defaultMcpServerIds ?? []);
   const mandatoryIds: string[] = MANDATORY_SESSION_MCP_SERVER_IDS.filter((id) =>
     availableIds.has(id),
   );
   const mandatoryIdSet = new Set<string>(mandatoryIds);
-  const selectedRefs =
-    input.turnToolsProvided === true
-      ? mergeToolRefs([], input.turnTools ?? [])
-      : input.turnToolsProvided === false
-        ? mergeToolRefs([], input.sessionTools)
-        : mergeToolRefs(input.sessionTools, input.turnTools ?? []);
-  const tracksWorkspaceDefaults =
-    policy.mode === "workspace_default" && input.turnToolsProvided !== true;
+  const selectedRefs = mergeToolRefs([], input.sessionTools);
+  const tracksWorkspaceDefaults = policy.mode === "workspace_default";
 
-  // Optional capability refs are a historical materialization of a
-  // workspace-default selection. They may outlive an installation or its
-  // credentials; do not hand an unavailable optional ref to runtime, where it
-  // would otherwise be an unknown MCP id. Strict historical refs intentionally
-  // remain so their fail-loud compatibility contract is preserved.
-  let toolRefs = selectedRefs.filter((tool) => tool.optional !== true || availableIds.has(tool.id));
+  // Persisted refs may outlive a capability installation, deployment config,
+  // or its credentials. Admission remains strict for newly requested refs, but
+  // turn-time materialization must not hand any no-longer-registered id to the
+  // runtime router: doing so fails before the model can respond and traps the
+  // session in an "Unknown MCP server id" loop. Keep the stale selection in the
+  // effective-policy projection below, while executable refs contain only the
+  // registry that is available for this exact turn.
+  let toolRefs = selectedRefs.filter((tool) => availableIds.has(tool.id));
   if (tracksWorkspaceDefaults) {
     toolRefs = mergeToolRefs(
       toolRefs,
@@ -168,19 +164,6 @@ export function resolveSessionToolPolicy(input: SessionToolPolicyInput): Resolve
   };
 }
 
-/**
- * Native provider tools that belong to the workspace-default capability set
- * follow the same omission/narrowing fence as deferred MCP tools. A durable
- * workspace-default policy receives them; fixed historical policies and an
- * explicit per-turn replacement do not. Provider support remains a separate
- * runtime gate and must also be true before a native tool is attached.
- */
-export function sessionToolPolicyAllowsDefaultNativeTools(
-  policy: SessionEffectiveToolPolicy,
-): boolean {
-  return policy.mode === "workspace_default" && policy.lazyRouter.state === "required";
-}
-
 /** Current full runtime registry IDs, including configured static servers. */
 export async function workspaceSessionToolPolicyServerIds(
   db: Database,
@@ -191,14 +174,14 @@ export async function workspaceSessionToolPolicyServerIds(
   return sortedIds(runtimeSettings.mcpServers.map((server) => server.id));
 }
 
-/** Current omitted-tools defaults; this preserves capability-first behavior. */
+/** Current omitted-tools defaults: every configured runtime MCP is on. */
 export async function workspaceSessionToolPolicyDefaultServerIds(
   db: Database,
   workspaceId: string,
   settings: Settings,
 ): Promise<string[]> {
   const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
-  return sortedIds(enabledCapabilityMcpToolRefs(settings, runtimeSettings).map((tool) => tool.id));
+  return defaultSessionMcpServerIds(runtimeSettings.mcpServers);
 }
 
 /** Add a bounded, secret-safe effective projection to a session response. */
@@ -214,7 +197,7 @@ export function sessionWithEffectiveToolPolicy(
   return {
     ...session,
     effectiveToolPolicy: resolveSessionToolPolicy({
-      ...(session.toolPolicy ? { toolPolicy: session.toolPolicy } : {}),
+      toolPolicy: session.toolPolicy,
       sessionTools: session.tools,
       availableMcpServerIds: availableIds,
       defaultMcpServerIds: workspaceDefaultServerIds,

package/src/domain/sessions.ts

@@ -1,4 +1,4 @@
-import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex";
+import { CODEX_MODEL_ID_PREFIX, isCodexBilledModel } from "@opengeni/codex";
 import {
   canonicalizeConfiguredModelId,
   configuredAllowedModels,
@@ -10,11 +10,13 @@ import {
   CreateSessionRequest,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   DEFAULT_FIRST_PARTY_MCP_TOOLS,
+  FIRST_PARTY_MCP_TOOL_NAMES,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   SessionSpawnDenial,
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
+  latencyModeForMetadata,
   reasoningEffortForMetadata,
   stableJson,
   type AccessGrant,
@@ -105,7 +107,6 @@ import {
   validateFileResources,
   validateGitHubRepositorySelection,
   validateToolRefs,
-  validateToolRefsForSessionPolicy,
   withDefaultEnabledCapabilityMcpTools,
 } from "./resources";
 
@@ -131,16 +132,16 @@ export class SessionSpawnDeniedError extends Error {
 
 /**
  * Resolve per-session first-party tool visibility without consulting
- * authorization. Top-level omission uses the minimal runtime default (stored
- * as null); child omission snapshots the parent's exact effective selection.
- * Explicit [] is authoritative and must never widen.
+ * authorization. Top-level omission snapshots the complete runtime default;
+ * child omission snapshots the parent's exact effective selection. Explicit
+ * [] is authoritative and must never widen.
  */
 export function resolveFirstPartyMcpToolsForCreate(
   requested: FirstPartyMcpToolName[] | undefined,
   parentStored: FirstPartyMcpToolName[] | null | undefined,
-): FirstPartyMcpToolName[] | null {
+): FirstPartyMcpToolName[] {
   if (requested !== undefined) return [...requested];
-  if (parentStored === undefined) return null;
+  if (parentStored === undefined) return [...DEFAULT_FIRST_PARTY_MCP_TOOLS];
   return [...(parentStored ?? DEFAULT_FIRST_PARTY_MCP_TOOLS)];
 }
 
@@ -514,10 +515,12 @@ export async function createAndStartSession(input: {
   // Public admission always supplies provenance; optional keeps internal
   // callers that predate durable tool-policy provenance source-compatible
   // during the rolling deploy.
-  toolPolicy?: SessionToolPolicy;
+  toolPolicy: SessionToolPolicy;
   clientEventId?: string;
   model: string;
   reasoningEffort: Settings["openaiReasoningEffort"];
+  /** Session default Fast/standard; mirrored into metadata when set. */
+  latencyMode?: "standard" | "priority" | "fast";
   turnExecutionPolicy: TurnExecutionPolicyV1;
   sandboxBackend: Settings["sandboxBackend"];
   metadata: Record<string, unknown>;
@@ -541,7 +544,7 @@ export async function createAndStartSession(input: {
   firstPartyMcpPermissions?: Permission[] | null;
   // Model-visible first-party tool names. Authorization remains controlled by
   // firstPartyMcpPermissions and the target resource checks.
-  firstPartyMcpTools?: FirstPartyMcpToolName[] | null;
+  firstPartyMcpTools: FirstPartyMcpToolName[];
   // Encrypted DB rows plus matching safe metadata for create-time per-session
   // MCP servers. Metadata is the only shape emitted in events/responses.
   mcpServers?: CreateSessionMcpServerInput[];
@@ -587,6 +590,7 @@ export async function createAndStartSession(input: {
     ...input.metadata,
     model: input.model,
     reasoningEffort: input.reasoningEffort,
+    ...(input.latencyMode !== undefined ? { latencyMode: input.latencyMode } : {}),
   };
   // Keyed creation is intentionally handled only by the database admission
   // transaction below. Its workspace/key lock replays either the successful
@@ -602,7 +606,7 @@ export async function createAndStartSession(input: {
       resources: input.resources,
       skills: input.skills ?? [],
       tools: input.tools,
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
       ...(input.createdBy ? { createdBy: input.createdBy } : {}),
       ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -613,7 +617,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
-      firstPartyMcpTools: input.firstPartyMcpTools ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       createIdempotencyKey: input.createIdempotencyKey,
@@ -647,7 +651,7 @@ export async function createAndStartSession(input: {
       resources: input.resources,
       skills: input.skills ?? [],
       tools: input.tools,
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
       ...(input.createdBy ? { createdBy: input.createdBy } : {}),
       ...(input.createdByContext ? { createdByContext: input.createdByContext } : {}),
@@ -658,7 +662,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
-      firstPartyMcpTools: input.firstPartyMcpTools ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       sandboxGroupId: input.sandboxGroupId ?? null,
@@ -692,7 +696,7 @@ async function finishStartSession(
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
-    toolPolicy?: SessionToolPolicy;
+    toolPolicy: SessionToolPolicy;
     clientEventId?: string;
     model: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
@@ -750,7 +754,7 @@ async function finishStartSession(
     reasoningEffortFallback: input.reasoningEffort,
     turnExecutionPolicy: input.turnExecutionPolicy,
     createdEventPayload: {
-      ...(input.toolPolicy ? { toolPolicy: input.toolPolicy } : {}),
+      toolPolicy: input.toolPolicy,
       ...(input.variableSet
         ? { variableSetId: input.variableSet.id, variableSetName: input.variableSet.name }
         : {}),
@@ -834,6 +838,36 @@ export function assertConfiguredModel(settings: Settings, model: string | null |
   canonicalConfiguredModel(settings, model);
 }
 
+export const CODEX_COMPACTION_V2_PROVIDER_LOCKED = "codex_compaction_v2_provider_locked" as const;
+
+/** Session is frozen on Codex remote compaction v2; non-Codex models are refused. */
+export class CodexCompactionV2ProviderLockedError extends Error {
+  readonly code = CODEX_COMPACTION_V2_PROVIDER_LOCKED;
+  readonly productModelId: string;
+
+  constructor(productModelId: string) {
+    super(
+      `session is locked to Codex remote compaction v2; model "${productModelId}" is not a Codex subscription model`,
+    );
+    this.name = "CodexCompactionV2ProviderLockedError";
+    this.productModelId = productModelId;
+  }
+}
+
+/**
+ * Fail closed when a remote_v2 session would run a non-Codex product model.
+ * Portable sessions and non-Codex sessions keep free mid-session provider swap.
+ */
+export function assertSessionAllowsProductModel(
+  session: Pick<Session, "codexCompactionMode">,
+  productModelId: string | null | undefined,
+): void {
+  if (productModelId === null || productModelId === undefined) return;
+  if (session.codexCompactionMode !== "remote_v2") return;
+  if (isCodexBilledModel(productModelId)) return;
+  throw new CodexCompactionV2ProviderLockedError(productModelId);
+}
+
 /**
  * Reject a model the WORKSPACE's model policy blocks, at the same choke points
  * as assertConfiguredModel — a 422 at the edge instead of a queued turn the
@@ -902,6 +936,13 @@ export function reasoningEffortForSession(
   return reasoningEffortForMetadata(metadata, fallback);
 }
 
+export function latencyModeForSession(
+  metadata: Record<string, unknown>,
+  fallback: "standard" | "priority" | "fast" = "standard",
+): "standard" | "priority" | "fast" {
+  return latencyModeForMetadata(metadata, fallback);
+}
+
 /**
  * Appends a `user.message` to an existing session and enqueues the resulting
  * turn, merging requested resources/tools into the session and waking the
@@ -920,10 +961,9 @@ export async function postUserMessageTurn(input: {
   text: string;
   turnInstructions?: string | null;
   resources: ResourceRef[];
-  tools: ToolRef[];
-  toolsProvided: boolean;
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
+  latencyMode?: "standard" | "priority" | "fast" | null;
   clientEventId?: string;
   mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
   delivery?: "send" | "steer";
@@ -943,6 +983,16 @@ export async function postUserMessageTurn(input: {
   // model inherits the session's model downstream (always a configured id).
   assertConfiguredModel(settings, requestedModel);
   await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, requestedModel);
+  const sessionForModelGate = await requireSession(db, workspaceId, sessionId);
+  const effectiveModelForGate = requestedModel ?? sessionForModelGate.model;
+  try {
+    assertSessionAllowsProductModel(sessionForModelGate, effectiveModelForGate);
+  } catch (error) {
+    if (error instanceof CodexCompactionV2ProviderLockedError) {
+      throw new HTTPException(422, { message: error.message, cause: error });
+    }
+    throw error;
+  }
   const operationKey = input.clientEventId ?? crypto.randomUUID();
   let result;
   try {
@@ -965,10 +1015,9 @@ export async function postUserMessageTurn(input: {
           text: input.text,
           turnInstructions: input.turnInstructions ?? null,
           resources: input.resources,
-          tools: input.tools,
-          toolsProvided: input.toolsProvided,
           model: requestedModel,
           reasoningEffort: requestedReasoningEffort,
+          latencyMode: input.latencyMode ?? null,
           reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
           turnExecutionPolicy: input.turnExecutionPolicy,
           source: input.origin === "operator" ? "api" : "user",
@@ -1224,12 +1273,15 @@ export async function createSessionForRequest(
   // default-model session would otherwise be born blocked).
   await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
   const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
+  const latencyMode = payload.latencyMode ?? "standard";
   const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
     modelId: model,
     requestedModelId: payload.model ?? null,
     modelSource: payload.model === undefined ? "deployment" : "explicit",
     reasoningEffort,
     reasoningSource: payload.reasoningEffort === undefined ? "deployment" : "explicit",
+    latencyMode,
+    latencyModeSource: payload.latencyMode === undefined ? "deployment" : "explicit",
   });
   // Parent linkage was resolved above, before context validation. A child with
   // no explicit permission override inherits the creating session's effective
@@ -1298,15 +1350,14 @@ export async function createSessionForRequest(
   }
   // Tool visibility is independent from permission authority. A child that
   // omits the field inherits the parent's exact effective selection; a
-  // top-level omission resolves to the fixed minimal default at execution.
+  // top-level omission selects the complete catalog.
   const firstPartyMcpTools = resolveFirstPartyMcpToolsForCreate(
     payload.firstPartyMcpTools,
     parentSession ? parentSession.firstPartyMcpTools : undefined,
   );
   if (payload.goal) {
-    const effectiveTools = firstPartyMcpTools ?? [...DEFAULT_FIRST_PARTY_MCP_TOOLS];
     const missingGoalTools = ["goal_update", "goal_complete", "goal_pause"].filter(
-      (name) => !effectiveTools.includes(name as FirstPartyMcpToolName),
+      (name) => !firstPartyMcpTools.includes(name as FirstPartyMcpToolName),
     );
     if (missingGoalTools.length > 0) {
       throw new HTTPException(422, {
@@ -1552,6 +1603,7 @@ export async function createSessionForRequest(
       ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
       model,
       reasoningEffort,
+      latencyMode,
       turnExecutionPolicy,
       // A shared spawn inherits the box's backend; a caller-supplied
       // sandboxBackend on a shared spawn is ignored (it is the same box). A
@@ -1636,8 +1688,7 @@ export async function createSessionForRequest(
  * `POST /sessions/:id/events` and the first-party MCP `session_send_message`
  * tool: resource/tool validation, usage limits, the locked append + turn
  * enqueue, and usage recording. `toolsProvided: false` durably preserves an
- * absent `tools` key so execution inherits the session policy; an explicit
- * empty array is a deliberate per-turn narrowing.
+ * Tool selection is durable session state and never rides a follow-up prompt.
  */
 export async function acceptSessionUserMessage(
   deps: AcceptSessionUserMessageDependencies,
@@ -1648,10 +1699,9 @@ export async function acceptSessionUserMessage(
     text: string;
     turnInstructions?: string | null;
     resources?: ResourceRef[];
-    tools?: ToolRef[];
-    toolsProvided: boolean;
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
+    latencyMode?: "standard" | "priority" | "fast" | null;
     clientEventId?: string;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
     delivery?: "send" | "steer";
@@ -1660,23 +1710,12 @@ export async function acceptSessionUserMessage(
     expectedDraftRevision?: number | null;
   },
 ): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
-  if (input.toolsProvided && !deps.settings.sessionTurnToolReplacementEnabled) {
-    throw new HTTPException(503, {
-      message:
-        "explicit follow-up tool replacement is temporarily unavailable until provenance-aware turn workers finish rolling out; omit tools to inherit the session policy and retry",
-    });
-  }
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   await requireSessionAuthorization(deps, grant, {
     sessionId,
     operation: input.delivery === "steer" ? "session.steer" : "session.append",
     surface: "core",
   });
-  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
-    db,
-    workspaceId,
-    settings,
-  );
   // Hoisted above requireLimit so the codex-billed predicate can resolve the
   // turn's effective model (a follow-up turn inherits the session's model). A
   // pure read with no side effects.
@@ -1687,43 +1726,31 @@ export async function acceptSessionUserMessage(
   if (effectiveModel === null) {
     throw new Error("effective follow-up model unexpectedly resolved to null");
   }
+  try {
+    assertSessionAllowsProductModel(existingSession, effectiveModel);
+  } catch (error) {
+    if (error instanceof CodexCompactionV2ProviderLockedError) {
+      throw new HTTPException(422, { message: error.message, cause: error });
+    }
+    throw error;
+  }
   const sessionReasoningEffort = reasoningEffortForSession(
     existingSession.metadata,
     settings.openaiReasoningEffort,
   );
   const effectiveReasoningEffort = input.reasoningEffort ?? sessionReasoningEffort;
+  const sessionLatencyMode = latencyModeForSession(existingSession.metadata, "standard");
+  const effectiveLatencyMode = input.latencyMode ?? sessionLatencyMode;
   const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
     modelId: effectiveModel,
     requestedModelId: input.model ?? null,
     modelSource: input.model == null ? "session" : "explicit",
     reasoningEffort: effectiveReasoningEffort,
     reasoningSource: input.reasoningEffort == null ? "session" : "explicit",
+    latencyMode: effectiveLatencyMode,
+    latencyModeSource: input.latencyMode == null ? "session" : "explicit",
   });
-  const runtimeSettings = settingsWithSessionMcpServerMetadata(
-    capabilityRuntimeSettings,
-    existingSession.mcpServers,
-  );
   const requestedResources = normalizeResources(input.resources ?? []);
-  const tracksWorkspaceDefaults = existingSession.toolPolicy?.mode === "workspace_default";
-  const sessionPolicyTools = withFirstPartyTools(
-    tracksWorkspaceDefaults
-      ? withDefaultEnabledCapabilityMcpTools(
-          availableToolRefs(existingSession.tools, runtimeSettings),
-          settings,
-          capabilityRuntimeSettings,
-        )
-      : existingSession.tools,
-    runtimeSettings,
-  );
-  const validatedTools = input.toolsProvided
-    ? validateToolRefsForSessionPolicy({
-        requested: input.tools ?? [],
-        settings: runtimeSettings,
-        allowedTools: sessionPolicyTools,
-        message: "message tools may only narrow the session tool policy",
-      })
-    : [];
-  const requestedTools = input.toolsProvided ? validatedTools : [];
   await requireLimit(deps, {
     accountId: grant.accountId,
     workspaceId,
@@ -1757,10 +1784,9 @@ export async function acceptSessionUserMessage(
     text: input.text,
     turnInstructions: input.turnInstructions ?? null,
     resources: requestedResources,
-    tools: requestedTools,
-    toolsProvided: input.toolsProvided,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
+    latencyMode: input.latencyMode ?? null,
     reasoningEffortFallback: sessionReasoningEffort,
     turnExecutionPolicy,
     mcpCredentialUpdates,
@@ -1919,7 +1945,8 @@ export async function updateSessionMcpApprovalPolicy(
 function toolPolicyAuditSnapshot(
   session: Session,
   tools: ToolRef[],
-  policy = session.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null },
+  firstPartyMcpTools: FirstPartyMcpToolName[],
+  policy = session.toolPolicy,
 ) {
   // Tool policy refs contain only public server ids and the optional/strict
   // execution mode; they never carry URLs, names, headers, credentials,
@@ -1951,6 +1978,8 @@ function toolPolicyAuditSnapshot(
       .map((tool) => tool.id),
     toolRefs,
     toolCount: allToolRefs.length,
+    firstPartyMcpTools: [...firstPartyMcpTools].sort(),
+    firstPartyMcpToolCount: firstPartyMcpTools.length,
     truncated: allToolRefs.length > toolRefs.length,
   };
 }
@@ -2004,10 +2033,14 @@ export async function updateSessionToolPolicy(
         return withFirstPartyTools(validatedTools, runtimeSettings);
       })()
     : null;
+  const explicitRequestedFirstPartyTools = explicitRequest
+    ? [...explicitRequest.firstPartyMcpTools]
+    : null;
   const workspaceDefaultTools = withFirstPartyTools(
     withDefaultEnabledCapabilityMcpTools([], deps.settings, capabilityRuntimeSettings),
     runtimeSettings,
   );
+  const workspaceDefaultFirstPartyTools = [...FIRST_PARTY_MCP_TOOL_NAMES];
   const events = await appendSessionEventsWithLockedSessionUpdate(
     deps.db,
     grant.workspaceId,
@@ -2019,6 +2052,7 @@ export async function updateSessionToolPolicy(
       }
 
       let nextTools: ToolRef[];
+      let nextFirstPartyMcpTools: FirstPartyMcpToolName[];
       let nextPolicy: SessionToolPolicy;
       if (session.parentSessionId) {
         const parent = await context.getLockedSession(session.parentSessionId);
@@ -2036,6 +2070,9 @@ export async function updateSessionToolPolicy(
             : parent.tools,
           runtimeSettings,
         );
+        const parentFirstPartyMcpTools = [
+          ...(parent.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS),
+        ];
         if (requestedMode === "workspace_default") {
           if (!parentTracksWorkspaceDefaults) {
             throw new HTTPException(403, {
@@ -2044,6 +2081,7 @@ export async function updateSessionToolPolicy(
             });
           }
           nextTools = parentEffective;
+          nextFirstPartyMcpTools = parentFirstPartyMcpTools;
           nextPolicy = {
             mode: "workspace_default",
             inheritedFromSessionId: parent.id,
@@ -2055,6 +2093,16 @@ export async function updateSessionToolPolicy(
             parentEffective,
             "session tools may only narrow the parent session tool policy",
           );
+          const parentFirstPartySet = new Set(parentFirstPartyMcpTools);
+          const widenedFirstPartyTool = explicitRequestedFirstPartyTools!.find(
+            (tool) => !parentFirstPartySet.has(tool),
+          );
+          if (widenedFirstPartyTool) {
+            throw new HTTPException(403, {
+              message: `session OpenGeni tools may only narrow the parent policy: ${widenedFirstPartyTool}`,
+            });
+          }
+          nextFirstPartyMcpTools = explicitRequestedFirstPartyTools!;
           nextPolicy = {
             mode: "explicit",
             inheritedFromSessionId: parent.id,
@@ -2063,20 +2111,29 @@ export async function updateSessionToolPolicy(
       } else {
         nextTools =
           requestedMode === "workspace_default" ? workspaceDefaultTools : explicitRequestedTools!;
+        nextFirstPartyMcpTools =
+          requestedMode === "workspace_default"
+            ? workspaceDefaultFirstPartyTools
+            : explicitRequestedFirstPartyTools!;
         nextPolicy = { mode: requestedMode, inheritedFromSessionId: null };
       }
 
-      const currentPolicy = session.toolPolicy ?? {
-        mode: "legacy" as const,
-        inheritedFromSessionId: null,
-      };
+      const currentPolicy = session.toolPolicy;
       // JSONB normalizes object-key order on the round trip, so plain
       // JSON.stringify would turn an identical retry into a second mutation
       // (and version bump) merely because the persisted key order differs from
       // the request object. Compare canonical JSON instead.
       const unchanged =
-        stableJson({ tools: session.tools, policy: currentPolicy }) ===
-        stableJson({ tools: nextTools, policy: nextPolicy });
+        stableJson({
+          tools: session.tools,
+          firstPartyMcpTools: session.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS,
+          policy: currentPolicy,
+        }) ===
+        stableJson({
+          tools: nextTools,
+          firstPartyMcpTools: nextFirstPartyMcpTools,
+          policy: nextPolicy,
+        });
       if (unchanged) {
         return { events: [] };
       }
@@ -2087,8 +2144,18 @@ export async function updateSessionToolPolicy(
           {
             type: "session.tool_policy.updated" as const,
             payload: {
-              before: toolPolicyAuditSnapshot(session, session.tools, currentPolicy),
-              after: toolPolicyAuditSnapshot(session, nextTools, nextPolicy),
+              before: toolPolicyAuditSnapshot(
+                session,
+                session.tools,
+                [...(session.firstPartyMcpTools ?? DEFAULT_FIRST_PARTY_MCP_TOOLS)],
+                currentPolicy,
+              ),
+              after: toolPolicyAuditSnapshot(
+                session,
+                nextTools,
+                nextFirstPartyMcpTools,
+                nextPolicy,
+              ),
               version: nextVersion,
               effectiveFrom: "next_attempt",
             },
@@ -2096,6 +2163,7 @@ export async function updateSessionToolPolicy(
         ],
         update: {
           tools: nextTools,
+          firstPartyMcpTools: nextFirstPartyMcpTools,
           toolPolicy: nextPolicy,
           toolPolicyVersion: nextVersion,
           expectedToolPolicyVersion: request.expectedVersion,

package/src/domain/slack-bot.ts

@@ -1,9 +1,9 @@
 import {
   OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
-  OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   OpenGeniSlackBotConnectionMetadata,
+  areOpenGeniSlackBotScopesAccepted,
   type AccessGrant,
   type ConnectionMetadata,
   type OpenGeniSlackBotConnectionMetadata as OpenGeniSlackBotMetadata,
@@ -30,15 +30,13 @@ export function isOpenGeniSlackBotConnection(
       Pick<ConnectionMetadataWithVerification, "verifiedInstallAt" | "verifiedInstallVersion">
     >,
 ): boolean {
-  const granted = new Set(connection.grantedScopes);
   return (
     connection.verifiedInstallAt != null &&
     connection.verifiedInstallVersion === connection.version &&
     connection.subjectId === null &&
     connection.providerDomain === "slack.com" &&
     connection.kind === "app_install" &&
-    granted.size === OPENGENI_SLACK_BOT_REQUIRED_SCOPES.length &&
-    OPENGENI_SLACK_BOT_REQUIRED_SCOPES.every((scope) => granted.has(scope)) &&
+    areOpenGeniSlackBotScopesAccepted(connection.grantedScopes) &&
     openGeniSlackBotMetadata(connection.metadata)?.credentialRole ===
       OPENGENI_SLACK_BOT_CREDENTIAL_ROLE
   );