@opengeni/core 0.11.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "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.1",
-    "@opengeni/contracts": "^0.19.0",
-    "@opengeni/db": "^0.12.1",
-    "@opengeni/documents": "^0.2.31",
-    "@opengeni/events": "^0.3.22",
+    "@opengeni/config": "^0.7.7",
+    "@opengeni/contracts": "^0.20.0",
+    "@opengeni/db": "^0.13.0",
+    "@opengeni/documents": "^0.2.37",
+    "@opengeni/events": "^0.3.28",
     "@opengeni/observability": "^0.3.0",
-    "@opengeni/runtime": "^0.13.4",
-    "@opengeni/storage": "^0.2.25",
+    "@opengeni/runtime": "^0.13.11",
+    "@opengeni/storage": "^0.2.31",
     "hono": "^4.12.18"
   },
   "engines": {

package/src/application/new-session-drafts.ts

@@ -6,7 +6,14 @@ import {
 } from "@opengeni/contracts";
 import {
   getNewSessionDraftInTransaction,
+  getEnrollment,
+  getRig,
+  getSandbox,
+  getVariableSet,
   NewSessionDraftAccessError,
+  newSessionDraftToolsProvided,
+  publicNewSessionDraftOptions,
+  requireFile,
   saveNewSessionDraftInTransaction,
   withWorkspaceSubjectRls,
 } from "@opengeni/db";
@@ -14,15 +21,21 @@ import { HTTPException } from "hono/http-exception";
 import type { AppDependencies } from "../dependencies";
 import { settingsWithEnabledCapabilityMcpServers } from "../domain/capabilities";
 import {
+  isAuthoritativeGitHubRepositorySelectionError,
   normalizeResources,
   validateFileResources,
   validateGitHubRepositorySelection,
   validateToolRefs,
 } from "../domain/resources";
+import { hasPermission } from "../access";
 import { assertConfiguredModel, assertWorkspaceModelPolicyAllows } from "../domain/sessions";
 
 type NewSessionDraftDependencies = Pick<AppDependencies, "settings" | "db" | "objectStorage">;
 
+function hasOwn(value: unknown, key: string): boolean {
+  return typeof value === "object" && value !== null && Object.hasOwn(value, key);
+}
+
 function mapNewSessionDraft(
   row: Awaited<ReturnType<typeof getNewSessionDraftInTransaction>>,
 ): NewSessionDraftValue | null {
@@ -31,14 +44,110 @@ function mapNewSessionDraft(
     revision: row.revision,
     text: row.text,
     resources: row.resources,
-    tools: row.tools,
+    tools: newSessionDraftToolsProvided(row) ? row.tools : [],
+    toolsProvided: newSessionDraftToolsProvided(row),
     model: row.model,
     reasoningEffort: row.reasoningEffort,
-    options: row.sessionOptions,
+    options: publicNewSessionDraftOptions(row),
     updatedAt: row.updatedAt.toISOString(),
   });
 }
 
+async function hydrateNewSessionDraft(
+  deps: Pick<NewSessionDraftDependencies, "db" | "settings">,
+  grant: AccessGrant,
+  workspaceId: string,
+  row: Awaited<ReturnType<typeof getNewSessionDraftInTransaction>>,
+): Promise<NewSessionDraftValue | null> {
+  if (!row) return null;
+  const mapped = mapNewSessionDraft(row);
+  if (!mapped) return null;
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    deps.db,
+    workspaceId,
+    deps.settings,
+  );
+  const resources = [] as NewSessionDraftValue["resources"];
+  for (const resource of mapped.resources) {
+    if (resource.kind === "repository") {
+      try {
+        await validateGitHubRepositorySelection(deps.db, workspaceId, [resource]);
+        resources.push(resource);
+      } catch (error) {
+        if (isAuthoritativeGitHubRepositorySelectionError(error)) {
+          // Repository authorization can be revoked after the draft was saved.
+          // The next form must not present the stale identity as selectable.
+          continue;
+        }
+        // A catalog/database outage is not proof that a repository was revoked.
+        // Preserve the resource so a later retry cannot autosave its deletion.
+        resources.push(resource);
+      }
+      continue;
+    }
+    try {
+      const file = await requireFile(deps.db, workspaceId, resource.fileId);
+      if (file.status === "ready") resources.push(resource);
+    } catch {
+      // Missing, foreign, failed, and pending files are stale draft state.
+    }
+  }
+
+  const options = { ...mapped.options };
+  if (options.variableSetId) {
+    if (
+      !hasPermission(grant.permissions, "variable-sets:use") ||
+      !(await getVariableSet(deps.db, workspaceId, options.variableSetId))
+    ) {
+      delete options.variableSetId;
+    }
+  }
+  if (options.rigId) {
+    const rig = await getRig(deps.db, workspaceId, options.rigId);
+    if (!rig?.activeVersion) delete options.rigId;
+  }
+  if (options.targetSandboxId) {
+    const sandbox = await getSandbox(deps.db, workspaceId, options.targetSandboxId);
+    const enrollment = sandbox?.enrollmentId
+      ? await getEnrollment(deps.db, workspaceId, sandbox.enrollmentId)
+      : null;
+    if (
+      !sandbox ||
+      sandbox.kind !== "selfhosted" ||
+      !enrollment ||
+      enrollment.status !== "active"
+    ) {
+      delete options.targetSandboxId;
+      delete options.workingDir;
+      delete options.sandboxBackend;
+    }
+  }
+
+  let tools: NewSessionDraftValue["tools"] = [];
+  if (mapped.toolsProvided) {
+    try {
+      tools = validateToolRefs(mapped.tools, runtimeSettings);
+    } catch {
+      // A revoked/disabled MCP selection is removed while explicitness remains
+      // true, so an explicit empty policy cannot silently widen to defaults.
+      tools = mapped.tools.filter((tool) => {
+        try {
+          validateToolRefs([tool], runtimeSettings);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    }
+  }
+  return {
+    ...mapped,
+    resources,
+    tools,
+    options,
+  };
+}
+
 /** Read the authenticated actor's server-authoritative pre-session composer state. */
 export async function getActorNewSessionDraft(
   deps: Pick<NewSessionDraftDependencies, "settings" | "db">,
@@ -52,11 +161,12 @@ export async function getActorNewSessionDraft(
     }),
   );
   return (
-    mapNewSessionDraft(row) ?? {
+    (await hydrateNewSessionDraft(deps, grant, workspaceId, row)) ?? {
       revision: 0,
       text: "",
       resources: [],
       tools: [],
+      toolsProvided: false,
       model: deps.settings.openaiModel,
       reasoningEffort: deps.settings.openaiReasoningEffort,
       options: {},
@@ -79,13 +189,18 @@ export async function saveActorNewSessionDraft(
   rawInput: unknown,
 ): Promise<NewSessionDraftValue> {
   const input = SaveNewSessionDraftRequest.parse(rawInput);
+  // The pre-marker client contract required `tools` and had no
+  // `toolsProvided`. Its array—including []—was the user's complete selection.
+  // Do this presence check before Zod's default turns the missing marker into
+  // false, preserving old-client → new-server intent safely.
+  const toolsProvided = hasOwn(rawInput, "toolsProvided") ? input.toolsProvided : true;
   const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(
     deps.db,
     workspaceId,
     deps.settings,
   );
   const resources = normalizeResources(input.resources);
-  const tools = validateToolRefs(input.tools, runtimeSettings);
+  const tools = toolsProvided ? validateToolRefs(input.tools, runtimeSettings) : [];
   await validateGitHubRepositorySelection(deps.db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !deps.objectStorage) {
     throw new HTTPException(503, { message: "object storage is not configured" });
@@ -105,6 +220,7 @@ export async function saveActorNewSessionDraft(
           text: input.text,
           resources,
           tools,
+          toolsProvided,
           model: input.model,
           reasoningEffort: input.reasoningEffort,
           options: input.options,

package/src/dependencies.ts

@@ -106,6 +106,8 @@ export type AppDependencies = {
   managedAuth?: ManagedAuth | null;
   /** Injectable Codex HTTP transport for deterministic API/provider tests. */
   codexFetch?: typeof fetch;
+  /** Injectable Slack Web API transport for deterministic bot-connection tests. */
+  slackFetch?: typeof fetch;
   // The API process's OWN agent-loop-free sandbox client (constructed from
   // settings via @opengeni/runtime/sandbox). Undefined when sandboxBackend=none.
   // This is the foundation of the API-direct control plane: the API resumes

package/src/domain/resources.ts

@@ -301,6 +301,15 @@ export async function validateGitHubRepositorySelection(
   }
 }
 
+/**
+ * A 422 from repository selection validation is an authoritative stale or
+ * revoked identity. Other failures (for example a database/catalog outage)
+ * leave the result unknown and must not cause draft hydration to delete it.
+ */
+export function isAuthoritativeGitHubRepositorySelectionError(error: unknown): boolean {
+  return error instanceof HTTPException && error.status === 422;
+}
+
 export async function validateFileResources(
   db: Database,
   workspaceId: string,

package/src/domain/scheduled-tasks.ts

@@ -6,6 +6,7 @@ import type {
   CreateScheduledTaskRequest as CreateScheduledTaskPayload,
   UpdateScheduledTaskRequest as UpdateScheduledTaskPayload,
 } from "@opengeni/contracts";
+import { OPENGENI_SLACK_BOT_SESSION_METADATA_KEY } from "@opengeni/contracts";
 import {
   createScheduledTask,
   deleteScheduledTask,
@@ -24,6 +25,10 @@ import type { ObjectStorageDependency } from "../dependencies";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { validateVariableSetAttachment } from "./environments";
 import { assertWorkspaceModelPolicyAllows, canonicalConfiguredModel } from "./sessions";
+import {
+  hasReservedOpenGeniSlackBotSessionMetadata,
+  validateOpenGeniSlackBotConnectionSelection,
+} from "./slack-bot";
 import {
   normalizeResources,
   validateFileResources,
@@ -197,7 +202,7 @@ export async function validatedScheduledTaskUpdate(input: {
     if (willHaveVariableSet) {
       requirePermission(input.grant, "variable-sets:use");
     }
-    update.agentConfig = await validateScheduledTaskAgentConfig({
+    const nextAgentConfig = await validateScheduledTaskAgentConfig({
       settings: input.settings,
       db: input.db,
       objectStorage: input.objectStorage,
@@ -206,6 +211,18 @@ export async function validatedScheduledTaskUpdate(input: {
       payload: { agentConfig: input.payload.agentConfig },
       ...(input.toolsProvided !== undefined ? { toolsProvided: input.toolsProvided } : {}),
     });
+    if (
+      input.existing.reusableSessionId &&
+      input.existing.runMode === "reusable_session" &&
+      (input.existing.agentConfig.slackBotConnectionId ?? null) !==
+        (nextAgentConfig.slackBotConnectionId ?? null)
+    ) {
+      throw new HTTPException(409, {
+        message:
+          "cannot change the OpenGeni Slack bot connection of a task with a live reusable session; recreate the task",
+      });
+    }
+    update.agentConfig = nextAgentConfig;
   }
   return update;
 }
@@ -355,11 +372,24 @@ async function validateScheduledTaskAgentConfig(input: {
   if (!prompt) {
     throw new HTTPException(422, { message: "scheduled task prompt is required" });
   }
+  if (hasReservedOpenGeniSlackBotSessionMetadata(input.payload.agentConfig.metadata)) {
+    throw new HTTPException(422, {
+      message: `${OPENGENI_SLACK_BOT_SESSION_METADATA_KEY} is reserved for scheduler routing`,
+    });
+  }
   await validateGitHubRepositorySelection(input.db, input.workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !input.objectStorage) {
     throw new HTTPException(503, { message: "object storage is not configured" });
   }
   await validateFileResources(input.db, input.workspaceId, resources);
+  if (input.payload.agentConfig.slackBotConnectionId) {
+    await validateOpenGeniSlackBotConnectionSelection(
+      input.db,
+      input.grant,
+      input.workspaceId,
+      input.payload.agentConfig.slackBotConnectionId,
+    );
+  }
   const requestedMaxDepth = input.payload.agentConfig.maxNestedAgentDepth;
   if (requestedMaxDepth !== undefined) {
     const workspace = await requireWorkspace(input.db, input.workspaceId);

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

@@ -113,18 +113,17 @@ export function resolveSessionToolPolicy(input: SessionToolPolicyInput): Resolve
   const configuredIds = effectiveIds.filter((id) => availableIds.has(id));
   const configuredIdSet = new Set(configuredIds);
   const droppedIds = effectiveIds.filter((id) => !configuredIdSet.has(id));
-  const deferredIds = tracksWorkspaceDefaults
-    ? sortedIds(
-        toolRefs
-          .filter(
-            (tool) =>
-              tool.optional === true &&
-              configuredIdSet.has(tool.id) &&
-              !mandatoryIdSet.has(tool.id),
-          )
-          .map((tool) => tool.id),
-      )
-    : [];
+  // Lazy discovery is scoped to the effective MCP allow-list, not only to
+  // workspace-default capability refs. An explicitly selected connector is
+  // directly callable from this same materialized list, so excluding it from
+  // the existing router creates a false "no connected sources" result. The
+  // mandatory first-party OpenGeni server stays eager; every other configured
+  // effective server is eligible for bounded schema disclosure.
+  const deferredIds = sortedIds(
+    toolRefs
+      .filter((tool) => configuredIdSet.has(tool.id) && !mandatoryIdSet.has(tool.id))
+      .map((tool) => tool.id),
+  );
   const selectedIds = sortedIds(
     selectedRefs
       .filter(
@@ -151,7 +150,7 @@ export function resolveSessionToolPolicy(input: SessionToolPolicyInput): Resolve
       effectiveIds: projections.effective.ids,
       mandatoryIds: projections.mandatory.ids,
       lazyRouter: {
-        state: tracksWorkspaceDefaults ? "required" : "disabled",
+        state: deferredIds.length > 0 ? "required" : "disabled",
         deferredIds: projections.deferred.ids,
       },
       configuredIds: projections.configured.ids,
@@ -169,6 +168,19 @@ 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,

package/src/domain/sessions.ts

@@ -9,11 +9,13 @@ import {
 import {
   CreateSessionRequest,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   SessionSpawnDenial,
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
   reasoningEffortForMetadata,
+  stableJson,
   type AccessGrant,
   type CreateSessionResponse,
   type GoalSpec,
@@ -27,6 +29,7 @@ import {
   type SessionMcpServerInput,
   type SessionMcpServerMetadata,
   type UpdateSessionMcpApprovalPolicyResponse,
+  type UpdateSessionToolPolicyRequest,
   type SessionAuthorizationPort,
   type SessionToolPolicy,
   type SessionTurn,
@@ -69,6 +72,7 @@ import {
   AgentCommandAuthorityError,
   SessionSpawnDeniedDbError,
   SessionControlConflictError,
+  SessionToolPolicyVersionConflictError,
   type SessionCommandActor,
 } from "@opengeni/db";
 import {
@@ -89,6 +93,7 @@ import { requireSessionAuthorization } from "../session-authorization";
 import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
 import { requireVariableSetEncryption, validateVariableSetAttachment } from "./environments";
+import { hasReservedOpenGeniSlackBotSessionMetadata } from "./slack-bot";
 import {
   assertToolRefsSubset,
   availableToolRefs,
@@ -104,6 +109,9 @@ import {
 const reservedSessionMcpServerIds = new Set(["opengeni", "files", "docs", "codex_apps"]);
 const maxSessionMcpCredentialHeaders = 16;
 const maxSessionMcpCredentialHeaderValueLength = 4096;
+// Keep the durable snapshot below the shared event-preview array boundary so
+// the generic lossy projection cannot silently rewrite this audit fact.
+const maxToolPolicyAuditRefs = 40;
 // RFC 9110 field-name token characters.
 const sessionMcpCredentialHeaderName = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
 
@@ -1021,6 +1029,11 @@ export async function createSessionForRequest(
 ): Promise<Session> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
+  if (hasReservedOpenGeniSlackBotSessionMetadata(payload.metadata)) {
+    throw new HTTPException(422, {
+      message: `${OPENGENI_SLACK_BOT_SESSION_METADATA_KEY} is reserved for scheduler routing`,
+    });
+  }
   // A committed keyed denial is the idempotent outcome even if mutable
   // resources, policy, authorization, or budget have changed since the first
   // attempt. Replay it before any of those checks, just as a keyed successful
@@ -1856,6 +1869,200 @@ export async function updateSessionMcpApprovalPolicy(
   };
 }
 
+function toolPolicyAuditSnapshot(
+  session: Session,
+  tools: ToolRef[],
+  policy = session.toolPolicy ?? { mode: "legacy" as const, inheritedFromSessionId: null },
+) {
+  // Tool policy refs contain only public server ids and the optional/strict
+  // execution mode; they never carry URLs, names, headers, credentials,
+  // schemas, or arguments. The request is capped at 64 refs and the mandatory
+  // first-party server can add one more, so the complete snapshot remains a
+  // small bounded payload rather than silently dropping security-relevant
+  // optional/strict changes.
+  const allToolRefs = mergeToolRefs([], tools)
+    .sort((left, right) => {
+      // Keep the mandatory first-party authority visible even when the
+      // bounded audit preview has to omit the middle of a large selection.
+      const leftMandatory = left.kind === "mcp" && left.id === "opengeni";
+      const rightMandatory = right.kind === "mcp" && right.id === "opengeni";
+      if (leftMandatory !== rightMandatory) return leftMandatory ? -1 : 1;
+      return `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`);
+    })
+    .map((tool) => ({
+      kind: tool.kind,
+      id: tool.id,
+      ...(tool.optional === undefined ? {} : { optional: tool.optional }),
+    }));
+  const toolRefs = allToolRefs.slice(0, maxToolPolicyAuditRefs);
+  return {
+    mode: policy.mode,
+    inheritedFromSessionId: policy.inheritedFromSessionId,
+    // IDs only: no MCP URLs, names, headers, credentials, schemas, or args.
+    toolIds: [...toolRefs]
+      .sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`))
+      .map((tool) => tool.id),
+    toolRefs,
+    toolCount: allToolRefs.length,
+    truncated: allToolRefs.length > toolRefs.length,
+  };
+}
+
+/**
+ * Replace the durable session tool policy. The target and its parent (when
+ * present) are locked by the DB event-writer helper, and the update/event are
+ * committed under one version-fenced transaction. An already claimed turn
+ * keeps its immutable snapshot; the next attempt observes this policy.
+ */
+export async function updateSessionToolPolicy(
+  deps: {
+    db: Database;
+    bus: EventBus;
+    settings: Settings;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
+  grant: AccessGrant,
+  sessionId: string,
+  request: UpdateSessionToolPolicyRequest,
+): Promise<Session> {
+  await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation: "session.tool_policy.write",
+    surface: "core",
+  });
+  requirePermission(grant, "sessions:control");
+
+  const existingSession = await requireSession(deps.db, grant.workspaceId, sessionId);
+  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    deps.db,
+    grant.workspaceId,
+    deps.settings,
+  );
+  const runtimeSettings = settingsWithSessionMcpServerMetadata(
+    capabilityRuntimeSettings,
+    existingSession.mcpServers,
+  );
+  const explicitRequest = request.mode === "workspace_default" ? null : request;
+  const requestedMode = explicitRequest ? "explicit" : "workspace_default";
+  const explicitRequestedTools = explicitRequest
+    ? (() => {
+        const validatedTools = validateToolRefs(explicitRequest.tools, runtimeSettings);
+        const validatedIds = new Set(validatedTools.map((tool) => `${tool.kind}:${tool.id}`));
+        const unknown = explicitRequest.tools.find(
+          (tool) => !validatedIds.has(`${tool.kind}:${tool.id}`),
+        );
+        if (unknown) {
+          throw new HTTPException(422, { message: `unknown MCP server id: ${unknown.id}` });
+        }
+        return withFirstPartyTools(validatedTools, runtimeSettings);
+      })()
+    : null;
+  const workspaceDefaultTools = withFirstPartyTools(
+    withDefaultEnabledCapabilityMcpTools([], deps.settings, capabilityRuntimeSettings),
+    runtimeSettings,
+  );
+  const events = await appendSessionEventsWithLockedSessionUpdate(
+    deps.db,
+    grant.workspaceId,
+    sessionId,
+    async (session, context) => {
+      const currentVersion = session.toolPolicyVersion ?? 1;
+      if (request.expectedVersion !== currentVersion) {
+        throw new SessionToolPolicyVersionConflictError(currentVersion);
+      }
+
+      let nextTools: ToolRef[];
+      let nextPolicy: SessionToolPolicy;
+      if (session.parentSessionId) {
+        const parent = await context.getLockedSession(session.parentSessionId);
+        if (!parent) {
+          throw new HTTPException(409, { message: "parent session is no longer available" });
+        }
+        const parentTracksWorkspaceDefaults = parent.toolPolicy?.mode === "workspace_default";
+        const parentEffective = withFirstPartyTools(
+          parentTracksWorkspaceDefaults
+            ? withDefaultEnabledCapabilityMcpTools(
+                availableToolRefs(parent.tools, runtimeSettings),
+                deps.settings,
+                runtimeSettings,
+              )
+            : parent.tools,
+          runtimeSettings,
+        );
+        if (requestedMode === "workspace_default") {
+          if (!parentTracksWorkspaceDefaults) {
+            throw new HTTPException(403, {
+              message:
+                "a child may adopt workspace defaults only while its parent tracks workspace defaults",
+            });
+          }
+          nextTools = parentEffective;
+          nextPolicy = {
+            mode: "workspace_default",
+            inheritedFromSessionId: parent.id,
+          };
+        } else {
+          nextTools = explicitRequestedTools!;
+          assertToolRefsSubset(
+            nextTools,
+            parentEffective,
+            "session tools may only narrow the parent session tool policy",
+          );
+          nextPolicy = {
+            mode: "explicit",
+            inheritedFromSessionId: parent.id,
+          };
+        }
+      } else {
+        nextTools =
+          requestedMode === "workspace_default" ? workspaceDefaultTools : explicitRequestedTools!;
+        nextPolicy = { mode: requestedMode, inheritedFromSessionId: null };
+      }
+
+      const currentPolicy = session.toolPolicy ?? {
+        mode: "legacy" as const,
+        inheritedFromSessionId: null,
+      };
+      // 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 });
+      if (unchanged) {
+        return { events: [] };
+      }
+
+      const nextVersion = currentVersion + 1;
+      return {
+        events: [
+          {
+            type: "session.tool_policy.updated" as const,
+            payload: {
+              before: toolPolicyAuditSnapshot(session, session.tools, currentPolicy),
+              after: toolPolicyAuditSnapshot(session, nextTools, nextPolicy),
+              version: nextVersion,
+              effectiveFrom: "next_attempt",
+            },
+          },
+        ],
+        update: {
+          tools: nextTools,
+          toolPolicy: nextPolicy,
+          toolPolicyVersion: nextVersion,
+          expectedToolPolicyVersion: request.expectedVersion,
+        },
+      };
+    },
+    { lockParentSession: true },
+  );
+  if (events.length > 0) {
+    await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, events);
+  }
+  return await requireSession(deps.db, grant.workspaceId, sessionId);
+}
+
 export async function readSessionLineage(
   deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">,
   grant: AccessGrant,