@opengeni/core 0.12.5 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.12.5",
+  "version": "0.12.10",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -35,14 +35,14 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/codex": "^0.2.7",
-    "@opengeni/config": "^0.7.10",
-    "@opengeni/contracts": "^0.21.0",
-    "@opengeni/db": "^0.13.4",
-    "@opengeni/documents": "^0.2.41",
-    "@opengeni/events": "^0.3.32",
+    "@opengeni/config": "^0.7.13",
+    "@opengeni/contracts": "^0.23.0",
+    "@opengeni/db": "^0.14.3",
+    "@opengeni/documents": "^0.2.45",
+    "@opengeni/events": "^0.3.36",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.14.0",
-    "@opengeni/storage": "^0.2.34",
+    "@opengeni/runtime": "^0.14.3",
+    "@opengeni/storage": "^0.2.37",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/access/index.ts

@@ -236,6 +236,9 @@ async function delegatedAccessContext(
         metadata: {
           delegated: true,
           ...(payload.sessionId ? { sessionId: payload.sessionId } : {}),
+          ...(payload.firstPartyMcpTools !== undefined
+            ? { firstPartyMcpTools: payload.firstPartyMcpTools }
+            : {}),
           // Caller identity: the turn that minted this token. Tools classify the
           // CALLER from this instead of re-reading the live active pointer.
           ...(payload.turnId ? { turnId: payload.turnId } : {}),

package/src/application/session-commands.ts

@@ -7,6 +7,7 @@ import type {
   AccessGrant,
   SessionAuthorizationOperation,
   SessionAuthorizationPort,
+  SessionAuthorizationSurface,
   SessionCommandReceipt,
   SessionControlRequest,
   SessionControlResponse,
@@ -55,6 +56,8 @@ export type HumanSessionCommandContext = {
   workspaceId: string;
   sessionId: string;
   subjectId: string;
+  /** See AgentSessionCommandContext.authorizationSurface. */
+  authorizationSurface?: SessionAuthorizationSurface;
 };
 
 export type AgentSessionCommandContext = {
@@ -65,6 +68,13 @@ export type AgentSessionCommandContext = {
   callerTurnId: string;
   callerAttemptId: string;
   callerExecutionGeneration: number;
+  /**
+   * The trusted adapter surface that owns this command's one authorization
+   * decision. Direct core callers omit it and retain the canonical `core`
+   * surface; adapters that delegate the complete command set it explicitly so
+   * they do not authorize once at the edge and then repeat the host call here.
+   */
+  authorizationSurface?: SessionAuthorizationSurface;
 };
 
 type SessionAuthorizationCommandDeps = {
@@ -104,7 +114,7 @@ async function authorizeHumanSessionCommand(
   return await requireSessionAuthorization(deps, humanAccessGrant(context), {
     sessionId: context.sessionId,
     operation,
-    surface: "core",
+    surface: context.authorizationSurface ?? "core",
   });
 }
 
@@ -117,7 +127,7 @@ async function authorizeAgentSessionCommand(
   return await requireSessionAuthorization(deps, agentAccessGrant(context), {
     sessionId: targetSessionId,
     operation,
-    surface: "core",
+    surface: context.authorizationSurface ?? "core",
   });
 }
 
@@ -339,7 +349,12 @@ export async function controlAgentSessionWorkstream(
     reason?: string | null;
   },
 ) {
-  await authorizeAgentSessionCommand(deps, context, input.targetSessionId, "session.control");
+  const authorization = await authorizeAgentSessionCommand(
+    deps,
+    context,
+    input.targetSessionId,
+    "session.control",
+  );
   const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
     scoped.transaction((tx) =>
       mutateSessionControlInTransaction(tx as unknown as Database, {
@@ -358,7 +373,7 @@ export async function controlAgentSessionWorkstream(
   ]);
   await publishWorkspaceControlEvent(deps, context.workspaceId, result.workspaceControlEventId);
   await requestControlWakeDispatch(deps, result.wakeCount);
-  return result;
+  return { ...result, authorization };
 }
 
 function receipt(row: SessionCommandReceiptRow): SessionCommandReceipt {
@@ -384,8 +399,6 @@ function composerDraft(
     revision: row.revision,
     text: row.text,
     resources: row.resources as ComposerDraft["resources"],
-    tools: row.tools as ComposerDraft["tools"],
-    toolsProvided: row.toolsProvided,
     model: row.model,
     reasoningEffort: row.reasoningEffort as ComposerDraft["reasoningEffort"],
     sourceTurnId: row.sourceTurnId,
@@ -648,8 +661,6 @@ export async function getHumanComposerDraft(
     revision: 0,
     text: "",
     resources: [],
-    tools: [],
-    toolsProvided: false,
     model: session.model,
     reasoningEffort: reasoningEffortForMetadata(session.metadata, "medium"),
     sourceTurnId: null,

package/src/dependencies.ts

@@ -5,6 +5,7 @@ import type {
   GitHubAppApiPort,
   ScheduledTask,
   SessionAuthorizationPort,
+  TurnInitiator,
 } from "@opengeni/contracts";
 import type { Database } from "@opengeni/db";
 import type { DocumentServices } from "@opengeni/documents";
@@ -53,8 +54,9 @@ export type SessionWorkflowClient = {
   deleteScheduledTaskSchedule: (input: { temporalScheduleId: string }) => Promise<void>;
   triggerScheduledTask: (input: {
     task: ScheduledTask;
-    agentRunUsageIdempotencyKey?: string;
-    triggerWorkflowId?: string;
+    agentRunUsageIdempotencyKey: string;
+    triggerWorkflowId: string;
+    initiator: TurnInitiator;
   }) => Promise<void>;
   startRigVerification: (input: {
     workspaceId: string;

package/src/domain/capabilities.ts

@@ -12,6 +12,12 @@ import {
   type EnableCapabilityRequest,
   type McpServerConnectionRef,
 } from "@opengeni/contracts";
+import {
+  CODEX_APPS_MCP_SERVER_ID,
+  CODEX_APPS_MCP_SERVER_NAME,
+  CODEX_APPS_MCP_URL,
+  CODEX_APPS_STARTUP_TIMEOUT_MS,
+} from "@opengeni/codex";
 import {
   decryptVariableSetValue,
   decryptedCapabilityHeaders,
@@ -711,7 +717,36 @@ export async function settingsWithEnabledCapabilityMcpServers(
   settings: Settings,
 ): Promise<Settings> {
   const enabled = await listEnabledMcpCapabilityServers(db, workspaceId);
-  return settingsWithMcpCapabilityServers(settings, enabled);
+  return settingsWithCodexAppsMcpServer(settingsWithMcpCapabilityServers(settings, enabled));
+}
+
+/**
+ * Register Codex Apps as an optional runtime MCP when the deployment enables
+ * it. Registration only makes the server selectable; the session tool policy
+ * decides whether the model sees it, and Codex credential resolution
+ * independently decides whether calls can authenticate.
+ */
+export function settingsWithCodexAppsMcpServer(settings: Settings): Settings {
+  if (
+    !settings.codexConnectedAppsEnabled ||
+    settings.mcpServers.some((server) => server.id === CODEX_APPS_MCP_SERVER_ID)
+  ) {
+    return settings;
+  }
+  return {
+    ...settings,
+    mcpServers: [
+      ...settings.mcpServers,
+      {
+        id: CODEX_APPS_MCP_SERVER_ID,
+        name: CODEX_APPS_MCP_SERVER_NAME,
+        url: CODEX_APPS_MCP_URL,
+        timeoutMs: CODEX_APPS_STARTUP_TIMEOUT_MS,
+        // Availability is credential-specific, so discover on every run.
+        cacheToolsList: false,
+      },
+    ],
+  };
 }
 
 export function settingsWithMcpCapabilityServers(

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

@@ -21,11 +21,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>;
@@ -55,7 +52,7 @@ function projectIds(ids: readonly string[]): { ids: string[]; truncated: boolean
  * `defaultMcpServerIds` is the capability-only omitted-tools set.
  */
 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.
@@ -64,14 +61,8 @@ export function resolveSessionToolPolicy(input: SessionToolPolicyInput): Resolve
     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
@@ -214,7 +205,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

@@ -9,6 +9,8 @@ import {
 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,
@@ -19,6 +21,7 @@ import {
   type AccessGrant,
   type CreateSessionResponse,
   type GoalSpec,
+  type FirstPartyMcpToolName,
   type Permission,
   type ReasoningEffort,
   type ResourceRef,
@@ -103,7 +106,6 @@ import {
   validateFileResources,
   validateGitHubRepositorySelection,
   validateToolRefs,
-  validateToolRefsForSessionPolicy,
   withDefaultEnabledCapabilityMcpTools,
 } from "./resources";
 
@@ -127,6 +129,21 @@ 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.
+ */
+export function resolveFirstPartyMcpToolsForCreate(
+  requested: FirstPartyMcpToolName[] | undefined,
+  parentStored: FirstPartyMcpToolName[] | null | undefined,
+): FirstPartyMcpToolName[] {
+  if (requested !== undefined) return [...requested];
+  if (parentStored === undefined) return [...DEFAULT_FIRST_PARTY_MCP_TOOLS];
+  return [...(parentStored ?? DEFAULT_FIRST_PARTY_MCP_TOOLS)];
+}
+
 function sessionSpawnDeniedMessage(denial: SessionSpawnDenial): string {
   if (denial.code === "nested_agent_depth_override_forbidden") {
     return `requested nested-agent depth limit ${denial.requestedMaxNestedAgentDepthOverride ?? "unknown"} exceeds inherited limit ${denial.effectiveMaxNestedAgentDepth}; workspace:admin is required to increase it`;
@@ -497,7 +514,7 @@ 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"];
@@ -522,6 +539,9 @@ export async function createAndStartSession(input: {
   instructions?: string | null;
   // Validated against the creating grant before this is called.
   firstPartyMcpPermissions?: Permission[] | null;
+  // Model-visible first-party tool names. Authorization remains controlled by
+  // firstPartyMcpPermissions and the target resource checks.
+  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[];
@@ -582,7 +602,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 } : {}),
@@ -593,6 +613,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       createIdempotencyKey: input.createIdempotencyKey,
@@ -626,7 +647,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 } : {}),
@@ -637,6 +658,7 @@ export async function createAndStartSession(input: {
       rigId: input.rigId ?? null,
       rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
+      firstPartyMcpTools: input.firstPartyMcpTools,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
       sandboxGroupId: input.sandboxGroupId ?? null,
@@ -670,7 +692,7 @@ async function finishStartSession(
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
-    toolPolicy?: SessionToolPolicy;
+    toolPolicy: SessionToolPolicy;
     clientEventId?: string;
     model: string;
     reasoningEffort: Settings["openaiReasoningEffort"];
@@ -728,7 +750,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 }
         : {}),
@@ -898,8 +920,6 @@ export async function postUserMessageTurn(input: {
   text: string;
   turnInstructions?: string | null;
   resources: ResourceRef[];
-  tools: ToolRef[];
-  toolsProvided: boolean;
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
   clientEventId?: string;
@@ -943,8 +963,6 @@ 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,
           reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
@@ -1142,12 +1160,10 @@ export async function createSessionForRequest(
     );
     toolPolicy = { mode: "workspace_default", inheritedFromSessionId: null };
   }
-  // The first-party MCP server is attached to EVERY session. It hosts the
-  // session's own metadata tool (set_session_title) + goal tools, and — only
-  // when the grant carries the permission — the orchestration/variableSet/
-  // github tools. Capability is gated per-tool by permission, never by whether
-  // the server is attached, so a bare chat still gets titling while the
-  // dangerous tools stay off by default.
+  // The first-party MCP server is attached to EVERY session. Registration is
+  // independently intersected with the exact model-visible selection and the
+  // tool's permission/target authorization predicate, so attachment alone
+  // exposes nothing.
   const tools = withFirstPartyTools(selectedTools, runtimeSettings);
   await validateGitHubRepositorySelection(db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
@@ -1276,6 +1292,23 @@ export async function createSessionForRequest(
         "goal-bearing sessions require goals:manage in the resulting first-party MCP permission set",
     });
   }
+  // Tool visibility is independent from permission authority. A child that
+  // omits the field inherits the parent's exact effective selection; a
+  // top-level omission selects the complete catalog.
+  const firstPartyMcpTools = resolveFirstPartyMcpToolsForCreate(
+    payload.firstPartyMcpTools,
+    parentSession ? parentSession.firstPartyMcpTools : undefined,
+  );
+  if (payload.goal) {
+    const missingGoalTools = ["goal_update", "goal_complete", "goal_pause"].filter(
+      (name) => !firstPartyMcpTools.includes(name as FirstPartyMcpToolName),
+    );
+    if (missingGoalTools.length > 0) {
+      throw new HTTPException(422, {
+        message: `goal-bearing sessions require first-party MCP tools: ${missingGoalTools.join(", ")}`,
+      });
+    }
+  }
   // Parent linkage: a worker is linked to its manager ONLY from the
   // worker-signed sessionId claim on the creating grant — the manager
   // session's own id, signed into the delegated token by the worker and never
@@ -1541,6 +1574,7 @@ export async function createSessionForRequest(
       // time. Not surfaced as an event.
       instructions: payload.instructions ?? null,
       firstPartyMcpPermissions,
+      firstPartyMcpTools,
       mcpServers: sessionMcpServers.dbServers,
       sessionMcpServers: sessionMcpServers.metadata,
       parentSessionId,
@@ -1597,8 +1631,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,
@@ -1609,8 +1642,6 @@ export async function acceptSessionUserMessage(
     text: string;
     turnInstructions?: string | null;
     resources?: ResourceRef[];
-    tools?: ToolRef[];
-    toolsProvided: boolean;
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
     clientEventId?: string;
@@ -1621,23 +1652,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.
@@ -1660,31 +1680,7 @@ export async function acceptSessionUserMessage(
     reasoningEffort: effectiveReasoningEffort,
     reasoningSource: input.reasoningEffort == 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,
@@ -1718,8 +1714,6 @@ 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,
     reasoningEffortFallback: sessionReasoningEffort,
@@ -1880,7 +1874,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,
@@ -1912,6 +1907,8 @@ function toolPolicyAuditSnapshot(
       .map((tool) => tool.id),
     toolRefs,
     toolCount: allToolRefs.length,
+    firstPartyMcpTools: [...firstPartyMcpTools].sort(),
+    firstPartyMcpToolCount: firstPartyMcpTools.length,
     truncated: allToolRefs.length > toolRefs.length,
   };
 }
@@ -1965,10 +1962,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,
@@ -1980,6 +1981,7 @@ export async function updateSessionToolPolicy(
       }
 
       let nextTools: ToolRef[];
+      let nextFirstPartyMcpTools: FirstPartyMcpToolName[];
       let nextPolicy: SessionToolPolicy;
       if (session.parentSessionId) {
         const parent = await context.getLockedSession(session.parentSessionId);
@@ -1997,6 +1999,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, {
@@ -2005,6 +2010,7 @@ export async function updateSessionToolPolicy(
             });
           }
           nextTools = parentEffective;
+          nextFirstPartyMcpTools = parentFirstPartyMcpTools;
           nextPolicy = {
             mode: "workspace_default",
             inheritedFromSessionId: parent.id,
@@ -2016,6 +2022,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,
@@ -2024,20 +2040,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: [] };
       }
@@ -2048,8 +2073,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",
             },
@@ -2057,6 +2092,7 @@ export async function updateSessionToolPolicy(
         ],
         update: {
           tools: nextTools,
+          firstPartyMcpTools: nextFirstPartyMcpTools,
           toolPolicy: nextPolicy,
           toolPolicyVersion: nextVersion,
           expectedToolPolicyVersion: request.expectedVersion,