@opengeni/api-router 3.0.1 → 3.1.2

package/src/mcp/server.ts

@@ -1,4 +1,7 @@
 import {
+  getSessionSystemUpdateById,
+  getSessionMessageOutcomeEvent,
+  setSessionTargetContext,
   getAttemptToolCatalog,
   createChannel,
   listChannels,
@@ -9,20 +12,32 @@ import {
   setSessionChannel,
 } from "@opengeni/db";
 import { createHash, randomUUID } from "node:crypto";
+import { assertGoalResumeAllowed } from "@opengeni/core";
+import { mintEnrollToken } from "../sandbox/enrollment";
+import { enableMachineScreenControl, enrollmentAccess } from "../sandbox/screen-control";
+import { registerNotificationTools } from "./notification-tools";
+import { capabilityAccountReadiness } from "./capability-account-readiness";
 import {
   prepareWorkspaceArtifactUpload,
   prepareWorkspaceArtifactPublication,
   workspaceArtifactDownloads,
 } from "../site-uploads";
 import {
+  sessionTargetContext,
+  SetSessionTargetRequest,
   CreateScheduledTaskRequest,
+  ScheduledTaskAgentConfigInput,
+  ResourceRef,
+  ToolRef,
+  SessionMcpServerInput,
   CreateSessionRequest,
   GoalSpec,
+  SessionGoalReportRequirements,
+  SessionGoalReportDeliveries,
   boundSessionMcpText as capSessionDiscoveryText,
   compactSessionMcpListRow,
   sessionMcpIncludesRelatedWork,
   FIRST_PARTY_MCP_TOOL_NAMES,
-  defaultRepositoryMountPath,
   SESSION_EVENT_RAW_DELTA_TYPES,
   SessionEventLatestClass,
   SessionEventPayloadMode,
@@ -33,17 +48,16 @@ import {
   SessionEventType,
   stableJson,
   compactSessionEventResult,
+  turnCompletedReply,
   sessionEventLatestClassToSemanticClass,
   SessionMcpCredentialUpdateInput,
   ToolAuthNeededPayload,
-  VariableSetVariableName,
   capabilityCatalogItemIsTrustedForExposure,
   type AccessGrant,
   type CapabilityCatalogItem,
   type GitHubRepository,
   type FirstPartyMcpToolName,
-  type Permission,
-  type ResourceRef,
+  Permission,
   type SessionAuthorizationOperation,
   type SessionAuthorizationActor,
   type SessionAuthorizationSurface,
@@ -61,8 +75,8 @@ import {
   SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
   SESSION_GOAL_TEXT_MAX_BYTES,
   SESSION_INSTRUCTIONS_MAX_CHARACTERS,
+  AGENT_IDENTITY_MAX_CHARACTERS,
   SESSION_TITLE_MAX_CHARACTERS,
-  MAX_SELECTED_VARIABLE_SETS,
   sessionGoalUtf8Bytes,
   TASK_NOTE_LIST_DEFAULT_LIMIT,
   TASK_NOTE_LIST_MAX_LIMIT,
@@ -80,27 +94,27 @@ import {
   type WorkClaimSubjectFilter,
   type SessionStatus,
   SubmitHumanInputResponseRequest,
+  FIRST_PARTY_MCP_CALLER_META_KEY,
 } from "@opengeni/contracts";
 import {
-  countVariableSets,
+  SessionCreateConnectionSelectionUnavailableError,
   beginRigChangeVerificationAttempt,
-  createVariableSet,
-  decryptVariableSetValue,
-  encryptVariableSetValue,
   getSession,
+  getScheduledTaskRevisionAuthoritySubject,
   getSessionGoal,
   getSessionMcpMonitoringSummary,
   getSessionQueueSnapshot,
   getSessionTurn,
+  getSessionTurnMcpAccountBindings,
   getOrCreatePreferenceRegistrySnapshot,
   getPreferenceRegistryFullContent,
-  getVariableSet,
-  getVariableSetByName,
   listScheduledTaskRuns,
   listScheduledTasks,
   listSessionEventPage,
   listOutstandingSessionSystemUpdates,
   listSessionDiscoverySummaries,
+  getSandbox,
+  authorizePersonalMachineForAttempt,
   listEnrollments,
   projectEffectiveControlForRelatedAccess,
   projectSessionForRelatedAccess,
@@ -112,10 +126,8 @@ import {
   listSocialPosts,
   recordAuditEvent,
   removeEnrollment,
-  readVariableSetSecretAtomically,
   recordSyncedSocialPosts,
-  listVariableSets,
-  requireScheduledTask,
+  getScheduledTaskIncludingDeleted,
   requireSession,
   type MemoryAgentScope,
   serializeEffectiveSessionControl,
@@ -124,7 +136,6 @@ import {
   waitForSessionInputWithEvent,
   SESSION_INPUT_WAIT_MAX_SECONDS,
   SESSION_INPUT_WAIT_MIN_SECONDS,
-  setVariableSetVariable,
   updateSessionGoalWithEvent,
   upsertSessionGoalWithEvent,
   RigChangeTransitionError,
@@ -160,32 +171,64 @@ import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/ser
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { HTTPException } from "hono/http-exception";
 import * as z4 from "zod/v4";
+import { normalizeObjectSchema } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { ApiHttpError, scheduledTaskTargetAccessHttpError } from "../http/api-error";
+import { assertDescribedToolInput, contractToolInput } from "./contract-input";
+import { registerSiteDataTools } from "./site-data-tools";
+import { registerSitePublicationTools } from "./site-publication-tools";
+import { registerSiteSqlTools } from "./site-sql-tools";
+import { siteSqlGatewayConfig } from "../site-sql/gateway";
+import { resolveSiteAgentDataContext } from "../site-publishing/agent-data-tools";
+import {
+  resolveScheduledTaskCreateInput,
+  scheduledTaskCreateToolInput as buildScheduledTaskCreateToolInput,
+  scheduledTaskCreateToolValidation,
+} from "./scheduled-task-input";
+import { editableArtifactActorForGrant } from "../routes/editable-artifacts";
+import { readOnlySessionRefusal } from "../routes/session-history-imports";
+import { vaultProviderRegistryFor } from "../routes/vault-providers";
 import { registerKnowledgeEntryTools } from "./knowledge-entries";
+import { registerSecretTools } from "./secret-tools";
+import {
+  attemptSecretWriteContext,
+  prepareSecretAnswers,
+  SecretAnswerRejectedError,
+  splitSecretAnswers,
+} from "../secret-answers";
+import { isVaultError, vaultErrorFromDatabase } from "@opengeni/db";
 import {
   FIRST_PARTY_TOOL_AUTHORIZATION,
   type FirstPartyToolAuthorization,
 } from "./first-party-tool-permissions";
 import {
-  hasLiteralPermission,
   hasPermission,
   authorizedSocialConnectionsForGrant,
-  authorizedAtlassianConnectionsForGrant,
   buildCapabilityCatalog,
+  CONNECTED_MACHINE_CAPABILITY_ID,
   nativeConnectionCapabilityRecommendations,
+  OPENGENI_BROWSER_EXTENSION_URL,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
   resolveWorkspaceCatalogSettings,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  dispatchWithSessionAuthorizationReadReuse,
   searchCapabilityCatalogItems,
+  suggestCapabilityCatalogItems,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
-import { recordWorkspaceUsage, requireLimit, workflowIdForSession } from "@opengeni/core";
+import {
+  recordWorkspaceUsage,
+  requireLimit,
+  resolveScheduledTaskPreflightModel,
+  workflowIdForSession,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   githubBindingStatus,
   listWorkspaceGitHubInstallationBindings,
+  githubRepositoryResourceRef,
   listWorkspaceGitHubRepositories,
 } from "../github-access";
 import { githubBrowserBaseUrl, githubBrowserGrantClaims } from "../github-browser-flow";
@@ -209,18 +252,22 @@ import {
   proposeRigChangeForApi,
   requireRigChangeForApi,
   requireRigForApi,
-  assertAllowedVariableSetVariableName,
-  MAX_ENVIRONMENTS_PER_WORKSPACE,
-  MAX_VARIABLES_PER_ENVIRONMENT,
-  recordVariableSetAuditEvent,
-  requireVariableSetEncryption,
 } from "@opengeni/core";
 import {
+  assertNotSiteClampedAgent,
   captureScheduledTaskRestoreState,
   createValidatedScheduledTask,
   manualScheduledTaskTriggerUsageKey,
   manualScheduledTaskTriggerWorkflowId,
   scheduledTaskForGrant,
+  pauseScheduledTaskAsAdmin,
+  pausePrivateScheduledTaskAsAdmin,
+  requirePausableScheduledTask,
+  requireVisibleScheduledTask,
+  scheduledTaskAccess,
+  scheduledTaskViewerForGrant,
+  siteViewerForGrant,
+  resolveNewSiteAudience,
   scheduledTaskRunForGrant,
   scheduledTaskToolsProvided,
   scheduledTaskTriggerToken,
@@ -230,6 +277,7 @@ import {
   validateScheduledTaskMachineTarget,
   validateScheduledTaskTarget,
   updateScheduledTaskForApi,
+  triggerScheduledTaskForGrant,
   validatedScheduledTaskUpdate,
 } from "@opengeni/core";
 import {
@@ -242,7 +290,9 @@ import {
   sendAgentSessionMessage,
   steerAgentSession,
   updateSessionTitle,
+  setSessionModel,
   sessionWithEffectiveToolPolicy,
+  workspaceSessionEffectiveToolsContext,
   workspaceSessionToolPolicyDefaultServerIds,
   workspaceSessionToolPolicyServerIds,
   type AgentSessionCommandContext,
@@ -252,6 +302,7 @@ import {
   listFleet,
   provisionSandbox,
   runOnSandbox,
+  createRunOnSecretResolver,
   swapActiveSandbox,
   type FleetContext,
   type FleetServices,
@@ -274,6 +325,17 @@ import {
   boundRigDetailMcp,
   SESSION_EVENT_MCP_MAX_BYTES,
 } from "./session-view";
+import { completeChildReadSequences } from "./child-read-evidence";
+import {
+  sessionEventAuditSelectorMessage,
+  addUnknownSessionEventTypeIssues,
+  unknownSessionEventTypeMessage,
+} from "./session-event-errors";
+import {
+  acknowledgeConsumedChildEvents,
+  listOutstandingSessionSystemUpdatesForAttempt,
+  recordConsumedChildAnswers,
+} from "@opengeni/db";
 import {
   SESSION_WAIT_COMPLETION_EVENT_TYPES,
   SESSION_WAIT_DEFAULT_SECONDS,
@@ -281,8 +343,10 @@ import {
   SESSION_WAIT_EVENTS_PER_TARGET,
   SESSION_WAIT_MAX_SECONDS,
   SESSION_WAIT_MAX_TARGETS,
+  sessionWaitChangeEventMatches,
   sessionWaitCompletionEventMatches,
   waitForSessionChanges,
+  withOwnPendingUpdateKinds,
 } from "./session-wait";
 import {
   mcpMutationReceipt,
@@ -293,24 +357,45 @@ import {
   boundScheduledTaskDetailMcp,
   boundScheduledTaskMcpPage,
   scheduledTaskMcpSummary,
+  scheduledTaskPromptPage,
 } from "./scheduled-task-view";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
 import {
   createOpenGeniSlackBotClient,
+  prepareSlackBotPost,
   resolveSlackBotConnectionForTool,
+  sendSlackBotPost,
+  type OpenGeniSlackBotClient,
 } from "../integrations/slack-bot";
+import { uploadSlackTaskFile } from "../integrations/slack-task-file-upload";
 import { createFikenClient, resolveFikenConnectionForTool } from "../integrations/fiken";
 import {
-  browseAtlassianSources,
-  getAtlassianLiveItem,
-  searchAtlassianLive,
-} from "../integrations/atlassian";
-import { AtlassianConnectionMetadata } from "@opengeni/contracts/atlassian";
+  allowanceExhaustedMessage,
+  parseAllowanceExhaustedRefusal,
+} from "@opengeni/contracts/allowance-refusal";
 import { registerEditableArtifactAgentTools } from "./editable-artifacts";
 import { registerCompanyProfileAgentAdminTools } from "./company-profile-agent-admin";
 import { mintSandboxCodemodeToken } from "@opengeni/runtime/sandbox";
 import { deleteScheduledTaskWithDurableCleanup } from "../scheduled-task-deletion";
 import { observeWorkDiscovery, summarizeWorkDiscoveryRows } from "../work-discovery-observability";
+import { orchestrationFailureDiagnostic } from "./orchestration-failure-diagnostic";
+import { loadCodexSessionPointerProjection } from "../codex-session-pointers";
+import {
+  afterSiteArtifactMutation,
+  requireSiteVersionPublishOpen,
+  SITE_AGENT_OTHER_SITE_MESSAGE,
+  siteAgentMayChangeArtifact,
+} from "../site-publishing/service";
+import { sitePlatformBrakeToolRefusal } from "../site-publishing/platform-usage";
+import {
+  siteAgentClampRefusal,
+  siteAgentClampedToolResult,
+  siteAgentComputeRefusal,
+} from "./site-agent-clamp-tools";
+import {
+  registerSessionAdminAccessTools,
+  type SessionAdminAccessDispatch,
+} from "./session-admin-access-tools";
 
 export type McpServerOptions = {
   // Origin of the HTTP request that reached the MCP route. Browser-oriented
@@ -325,6 +410,13 @@ export type McpServerOptions = {
    * save into that private layer. Omitted/null keeps the workspace layer.
    */
   sessionMemory?: MemoryAgentScope | null | undefined;
+  /**
+   * Set by the route only when the bound session has admin access right now
+   * (allowed by the organization, given by an owner or admin who still is
+   * one). It adds the admin tools whatever the session's tool selection;
+   * each call checks the access again.
+   */
+  sessionAdminAccess?: SessionAdminAccessDispatch | null | undefined;
 };
 
 const ORCHESTRATION_FAILURE_CODE_MAX_LENGTH = 128;
@@ -336,11 +428,11 @@ const ORCHESTRATION_FAILURE_MESSAGE_MAX_UTF8_BYTES = 1_024;
 // API-wide request-body ceiling for this 200-code-point field.
 const MCP_DISCOVERY_QUERY_MAX_UTF16_CODE_UNITS = WORK_DISCOVERY_QUERY_MAX_CHARS * 8;
 
-type OrchestrationToolName = "session_create" | "session_send_message";
+type OrchestrationToolName = "session_create" | "session_send_message" | "session_steer";
 
 function boundedOrchestrationFailureMessage(value: string): string {
   const normalized = value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
-  if (!normalized) return "OpenGeni could not complete the request.";
+  if (!normalized) return "Opengeni could not complete the request.";
   const encoded = new TextEncoder().encode(normalized);
   if (encoded.byteLength <= ORCHESTRATION_FAILURE_MESSAGE_MAX_UTF8_BYTES) return normalized;
   let end = ORCHESTRATION_FAILURE_MESSAGE_MAX_UTF8_BYTES;
@@ -405,7 +497,40 @@ function sessionCreateValidationFailureResult(error: z4.ZodError) {
   };
 }
 
-function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknown) {
+export function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknown) {
+  if (
+    tool === "session_create" &&
+    error instanceof SessionCreateConnectionSelectionUnavailableError
+  ) {
+    return {
+      error: {
+        code: "session_create_connection_selection_unavailable",
+        message: error.message,
+        retryable: false,
+      },
+    };
+  }
+  // An archived or imported session is read-only: say so, so the calling agent
+  // starts a new session instead of retrying.
+  const readOnly = readOnlySessionRefusal(error);
+  if (readOnly) {
+    return {
+      error: {
+        code: `${tool}_session_read_only`,
+        message: readOnly.message,
+        reason: readOnly.code,
+        retryable: false,
+      },
+    };
+  }
+  const allowance =
+    (error instanceof HTTPException ? parseAllowanceExhaustedRefusal(error.cause) : null) ??
+    parseAllowanceExhaustedRefusal(error);
+  if (allowance) {
+    return {
+      error: { ...allowance, message: allowanceExhaustedMessage(allowance), retryable: false },
+    };
+  }
   if (error instanceof SessionSpawnDeniedError) {
     const denial = sessionSpawnDenialEnvelope(error);
     return {
@@ -421,7 +546,7 @@ function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknow
         code: orchestrationFailureCode(tool, error),
         message:
           error.status >= 500
-            ? "OpenGeni is temporarily unavailable — retry."
+            ? "Opengeni is temporarily unavailable — retry."
             : boundedOrchestrationFailureMessage(error.message),
       },
     };
@@ -474,21 +599,229 @@ function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknow
   return {
     error: {
       code: `${tool}_failed`,
-      message: "OpenGeni could not complete the request.",
+      message: "Opengeni could not complete the request.",
     },
   };
 }
 
-function orchestrationFailureResult(tool: OrchestrationToolName, error: unknown) {
+function orchestrationFailureResult(
+  tool: OrchestrationToolName,
+  error: unknown,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+) {
   const envelope = orchestrationFailureEnvelope(tool, error);
+  let result: Record<string, unknown> = envelope;
+  if (envelope.error.code === `${tool}_failed` || envelope.error.code === `${tool}_unavailable`) {
+    try {
+      result = {
+        error: {
+          ...envelope.error,
+          ...orchestrationFailureDiagnostic(deps, tool, error, exactAgentAttemptClaims(grant)),
+        },
+      };
+    } catch {
+      // Diagnostic construction must never replace the original tool outcome.
+    }
+  }
   return {
-    content: [{ type: "text" as const, text: JSON.stringify(envelope, null, 2) }],
-    structuredContent: envelope,
+    content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
     isError: true as const,
   };
 }
 
 const FIRST_PARTY_MCP_TOOL_NAME_SET = new Set<string>(FIRST_PARTY_MCP_TOOL_NAMES);
+// Tool names whose input passed `assertDescribedToolInput` in this process.
+// The check is about code structure, which cannot change while the process
+// runs, so converting every input to JSON Schema per request only re-proves it.
+const DESCRIBED_TOOL_INPUTS = new Set<string>();
+
+/**
+ * Build a caller-independent tool input once per process. Zod construction and
+ * JSON Schema conversion are a large part of building the per-request server.
+ */
+function staticToolInput<T>(build: () => T): () => T {
+  let value: T | undefined;
+  return () => (value ??= build());
+}
+
+const scheduledTaskCreateToolProjection = staticToolInput(buildScheduledTaskCreateToolInput);
+const scheduledTaskUpdateToolInput = staticToolInput(() =>
+  contractToolInput(
+    z4
+      .object({
+        ...UpdateScheduledTaskRequest.out.shape,
+        id: z4.string().uuid(),
+        action: CreateScheduledTaskRequest.options[1].out.shape.action.optional(),
+        agentConfig: z4
+          .object(ScheduledTaskAgentConfigInput.shape)
+          .omit({ slackBotChannelId: true, toolPolicy: true })
+          .strict()
+          .optional(),
+      })
+      // Only a person pins connector accounts; agents never do.
+      .omit({
+        agentLearning: true,
+        connectionAuthorities: true,
+        pinnedAccounts: true,
+        pinnedAccountsRequired: true,
+        variableSetId: true,
+        environmentId: true,
+      })
+      .strict(),
+    UpdateScheduledTaskRequest,
+  ),
+);
+
+const sessionCreateToolInputs = new Map<string, ReturnType<typeof buildSessionCreateToolInput>>();
+
+/** Distinct selections are few; cache each built contract for reuse. */
+function sessionCreateToolInput(allowedTools: readonly FirstPartyMcpToolName[]) {
+  const key = allowedTools.join(",");
+  let input = sessionCreateToolInputs.get(key);
+  if (!input) {
+    if (sessionCreateToolInputs.size >= 256) sessionCreateToolInputs.clear();
+    input = buildSessionCreateToolInput(allowedTools);
+    sessionCreateToolInputs.set(key, input);
+  }
+  return input;
+}
+
+function buildSessionCreateToolInput(allowedTools: readonly FirstPartyMcpToolName[]) {
+  const capabilityToggle = z4.boolean().optional();
+  const sessionCreateAgentInput = z4
+    .object({
+      capabilities: z4
+        .union([
+          z4.enum(["all", "none"]),
+          z4
+            .object({
+              from: z4.enum(["all", "none"]),
+              webSearch: capabilityToggle,
+              humanInput: capabilityToggle,
+              skills: z4
+                .union([z4.literal("read"), z4.literal("manage"), z4.literal(false)])
+                .optional(),
+              goals: capabilityToggle,
+              subagents: capabilityToggle,
+              knowledge: capabilityToggle,
+              schedules: capabilityToggle,
+              artifacts: capabilityToggle,
+              browser: capabilityToggle,
+              media: capabilityToggle,
+              workspaceFiles: capabilityToggle,
+              workspaceConnectors: capabilityToggle,
+              workspaceAdmin: capabilityToggle,
+            })
+            .strict(),
+        ])
+        .optional(),
+      identity: z4.string().min(1).max(AGENT_IDENTITY_MAX_CHARACTERS).nullable().optional(),
+      instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
+      renderer: z4.enum(["opengeni", "markdown"]).optional(),
+    })
+    .strict()
+    .optional()
+    .describe(
+      "Optional agent configuration for the child. Omit to inherit this session's. capabilities 'all' means everything this session has; 'none' keeps only essentials; an object starts from one and switches capabilities off (or back on within this session's own set). A child may only narrow: enabling a capability this session lacks is rejected. For a worker that must not start, message, or follow other sessions, use agent: { capabilities: { from: 'all', subagents: false } } and omit firstPartyMcpTools. This keeps the parent's other capabilities and tool selections; the worker's final answer still reaches its parent automatically.",
+    );
+  const sessionCreateInput = z4
+    .object({
+      initialMessage: z4.string().min(1),
+      projectId: z4
+        .string()
+        .uuid()
+        .nullable()
+        .optional()
+        .describe(
+          "Workspace project to file the new session into. Omit for existing default behavior; does not change runtime or visibility.",
+        ),
+      title: z4
+        .string()
+        .min(1)
+        .max(SESSION_TITLE_MAX_CHARACTERS)
+        .optional()
+        .describe(
+          "Concise semantic title for the child session. Omit only when the delegated goal or initial message already provides a suitable title; Opengeni derives a sensitive-safe bounded fallback from that text.",
+        ),
+      instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
+      goal: GoalSpec.optional(),
+      resources: z4
+        .array(ResourceRef)
+        .optional()
+        .describe(
+          "Omit to inherit parent repositories only. Files are never inherited automatically; explicitly include file resources to attach them. An empty array inherits no resources.",
+        ),
+      tools: z4.array(ToolRef).optional(),
+      mcpServers: z4.array(SessionMcpServerInput).optional(),
+      rigId: z4.string().uuid().optional(),
+      model: z4
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Model for the worker. Omit to inherit the exact calling turn's model, including its Codex subscription billing path.",
+        ),
+      reasoningEffort: CreateSessionRequest.out.shape.reasoningEffort.describe(
+        "Omit to inherit the exact calling turn's reasoning effort.",
+      ),
+      latencyMode: z4
+        .enum(["standard", "priority", "fast"])
+        .optional()
+        .describe(
+          "Omit for standard latency, even when model and reasoning are inherited. Fast or priority must be selected explicitly and supported by the model.",
+        ),
+      sandboxBackend: CreateSessionRequest.out.shape.sandboxBackend,
+      // Model-only structural coupling: workingDir cannot exist without a
+      // targetSandboxId because both live inside one optional object. The
+      // handler maps this back to the stable public REST/SDK request fields.
+      machineTarget: z4
+        .object({
+          targetSandboxId: z4.string().uuid(),
+          workingDir: z4.string().optional(),
+        })
+        .strict()
+        .optional(),
+      metadata: z4.record(z4.string(), z4.unknown()).optional(),
+      idempotencyKey: z4.string().min(1).max(200).optional(),
+      firstPartyMcpPermissions: z4
+        .array(Permission)
+        .optional()
+        .describe(
+          "Optional first-party capability set for the child. Omit to inherit this session's effective permissions. An explicit set may only narrow capabilities held by this session. A goal-bearing child requires goals:manage in the resulting set; creation fails rather than adding it implicitly.",
+        ),
+      firstPartyMcpTools: z4
+        .array(
+          allowedTools.length
+            ? z4.enum(allowedTools as [FirstPartyMcpToolName, ...FirstPartyMcpToolName[]])
+            : z4.never(),
+        )
+        .optional()
+        .describe(
+          "Exact model-visible first-party tool selection for the child. Omit it in almost every case: omission inherits this session's effective selection, which is what workers normally need. The allowed values are exactly the tools this session holds that a child may keep. An explicit array replaces the entire inherited selection, including browser, computer, and scheduling tools; it is not an additions list. Do not construct a partial list merely because a worker has a specialist role or bounded task. For a worker that must not coordinate other sessions, prefer agent.capabilities with from: 'all' and subagents: false. Use an explicit array only for deliberate per-tool restrictions. A tool outside the allowed values is rejected, and [] selects no tools from this server. This does not grant permissions.",
+        ),
+      // The child's agent-access scope and end-user label are never model
+      // choices: it inherits this session's exactly. Only the Memory
+      // selector may be narrowed here (workspace > user > off).
+      memoryScope: z4
+        .enum(["workspace", "user", "off"])
+        .optional()
+        .describe(
+          "Optional Memory selector for the child. Omit to inherit this session's selector. An explicit value may only narrow it (workspace > user > off); off gives the child no Memory tools. Use task notes for task-local findings.",
+        ),
+      // Omission is the ordinary safe sharing path. Literal "shared" remains
+      // available to advanced REST/SDK callers but is intentionally absent
+      // from the model surface because it turns compatibility drift into a
+      // deterministic failure instead of the omission path's safe own-box fallback.
+      sandbox: z4.union([z4.literal("new"), z4.object({ groupId: z4.string().uuid() })]).optional(),
+      agent: sessionCreateAgentInput,
+    })
+    .strict();
+  return contractToolInput(sessionCreateInput, sessionCreateInput, {
+    jsonObjectFields: ["agent", "goal", "machineTarget"],
+  });
+}
 
 class PolicyMcpServer extends McpServer {
   private registeredToolCount = 0;
@@ -497,10 +830,27 @@ class PolicyMcpServer extends McpServer {
     private readonly grant: AccessGrant,
     private readonly sessionId: string | null,
     private readonly selectedTools: ReadonlySet<FirstPartyMcpToolName> | null,
+    private readonly sessionAdminAccess: boolean = false,
   ) {
     super({ name: "opengeni", version: "1.0.0" });
   }
 
+  /**
+   * Whether a selection-governed tool is both selected and authorized for this
+   * grant. Admin-access tools are never selection-governed, so a child
+   * selection can never carry them.
+   */
+  holdsSelectableTool(toolName: FirstPartyMcpToolName): boolean {
+    const policy: FirstPartyToolAuthorization = FIRST_PARTY_TOOL_AUTHORIZATION[toolName];
+    if (policy.adminAccessRequired) return false;
+    const authorized =
+      (policy.allOf?.every((permission) => hasPermission(this.grant.permissions, permission)) ??
+        true) &&
+      (policy.anyOf?.some((permission) => hasPermission(this.grant.permissions, permission)) ??
+        true);
+    return authorized && (this.selectedTools === null || this.selectedTools.has(toolName));
+  }
+
   override registerTool<
     OutputArgs extends ZodRawShapeCompat | AnySchema,
     InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined,
@@ -521,14 +871,15 @@ class PolicyMcpServer extends McpServer {
     if (catalogued) {
       const toolName = name as FirstPartyMcpToolName;
       const policy: FirstPartyToolAuthorization = FIRST_PARTY_TOOL_AUTHORIZATION[toolName];
-      const authorized =
-        (!policy.sessionRequired || this.sessionId !== null) &&
-        (policy.allOf?.every((permission) => hasPermission(this.grant.permissions, permission)) ??
-          true) &&
-        (policy.anyOf?.some((permission) => hasPermission(this.grant.permissions, permission)) ??
-          true);
-      const selected = this.selectedTools === null || this.selectedTools.has(toolName);
-      admitted = authorized && selected;
+      if (policy.adminAccessRequired) {
+        // Admin access, not the tool selection or the agent's own
+        // permissions, decides: the tools act as the person who gave it.
+        admitted = this.sessionId !== null && this.sessionAdminAccess;
+      } else {
+        admitted =
+          (!policy.sessionRequired || this.sessionId !== null) &&
+          this.holdsSelectableTool(toolName);
+      }
     }
     if (!admitted) {
       return {
@@ -544,8 +895,23 @@ class PolicyMcpServer extends McpServer {
         remove() {},
       };
     }
+    if (config.inputSchema && !DESCRIBED_TOOL_INPUTS.has(name)) {
+      const schema =
+        normalizeObjectSchema(config.inputSchema) ??
+        (Object.keys(config.inputSchema).length === 0 ? z4.object({}) : undefined);
+      if (!schema) throw new Error(`${name}: MCP input must be an object schema`);
+      assertDescribedToolInput(
+        z4.toJSONSchema(schema as z4.ZodType, { io: "input", target: "draft-7" }),
+        name,
+      );
+      DESCRIBED_TOOL_INPUTS.add(name);
+    }
     this.registeredToolCount += 1;
-    return super.registerTool(name, config, cb);
+    const handler = cb as (...args: unknown[]) => unknown;
+    return super.registerTool(name, config, ((...args: unknown[]) =>
+      dispatchWithSessionAuthorizationReadReuse(() =>
+        handler(...args),
+      )) as ToolCallback<InputArgs>);
   }
 
   ensureToolsListHandler(): void {
@@ -565,6 +931,51 @@ class PolicyMcpServer extends McpServer {
   }
 }
 
+export function slackBotFileContentResult(
+  result: Awaited<ReturnType<OpenGeniSlackBotClient["fileContent"]>>,
+) {
+  if (!("image" in result)) {
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      structuredContent: {
+        kind: "text" as const,
+        fileId: result.file.id,
+        contentType: result.contentType,
+        content: result.content,
+        sizeBytes: null,
+        nextOffset: result.nextOffset,
+      },
+    };
+  }
+  return {
+    structuredContent: {
+      kind: "image" as const,
+      fileId: result.file.id,
+      contentType: result.image.contentType,
+      content: null,
+      sizeBytes: result.image.bytes.byteLength,
+      nextOffset: null,
+    },
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({
+          channel: result.channel,
+          file: result.file,
+          contentType: result.image.contentType,
+          sizeBytes: result.image.bytes.byteLength,
+          receipt: result.receipt,
+        }),
+      },
+      {
+        type: "image" as const,
+        mimeType: result.image.contentType,
+        data: Buffer.from(result.image.bytes).toString("base64"),
+      },
+    ],
+  };
+}
+
 export function buildOpenGeniMcpServer(
   deps: ApiRouteDeps,
   grant: AccessGrant,
@@ -628,7 +1039,23 @@ export function buildOpenGeniMcpServer(
     typeof nestedAgentDepth !== "number" ||
     typeof effectiveMaxNestedAgentDepth !== "number" ||
     nestedAgentDepth < effectiveMaxNestedAgentDepth;
-  const server = new PolicyMcpServer(grant, sessionId, selectedTools);
+  const sessionAdminAccess =
+    sessionId !== null && exactAgentAttemptClaims(grant) !== null
+      ? (options.sessionAdminAccess ?? null)
+      : null;
+  const server = new PolicyMcpServer(grant, sessionId, selectedTools, sessionAdminAccess !== null);
+  if (sessionId !== null && sessionAdminAccess !== null) {
+    registerSessionAdminAccessTools({
+      server,
+      db: deps.db,
+      grant,
+      sessionId,
+      access: sessionAdminAccess,
+      authorize: async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+    });
+  }
   // set_session_title names the agent's OWN session — pure session metadata,
   // not a goal operation — so it is available on every session, gated only on
   // the signed sessionId (NOT goals:manage, and NOT on a goal existing).
@@ -651,6 +1078,21 @@ export function buildOpenGeniMcpServer(
       },
     );
   }
+  // Notifications reach the person who started this session: their inbox and,
+  // when new, their phones (see notification-tools.ts).
+  if (sessionId !== null) {
+    registerNotificationTools({
+      server,
+      deps,
+      grant,
+      sessionId,
+      authorize: async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      attempt: () => exactAgentCommandContext(grant, sessionId),
+      json,
+    });
+  }
   // PolicyMcpServer applies each tool's own permission contract. Register this
   // mixed group for every session so session-level wait_for_input remains
   // available with sessions:control even when goals:manage is intentionally
@@ -662,12 +1104,15 @@ export function buildOpenGeniMcpServer(
   // Reading existing Knowledge and Skills remains available when authoring is Off.
   if (sessionId !== null) {
     registerKnowledgeEntryTools(server, deps, grant, sessionId);
+    // secret_* (capability `secrets`): gated by permission and the signed
+    // tool selection like every catalogued tool; agent attempts only.
+    registerSecretTools(server, deps, grant, sessionId);
   }
   server.registerTool(
     "artifacts_list",
     {
       description:
-        "List the generic published artifacts in this workspace and their current versions.",
+        "List the published Sites you can see in this workspace (shared with the workspace, or Only me Sites that belong to the person you act for) and their current versions and audience.",
       inputSchema: {},
     },
     async () => {
@@ -676,7 +1121,11 @@ export function buildOpenGeniMcpServer(
       }
       return json(
         redactWorkspaceArtifactListProvenance(
-          await listWorkspaceArtifacts(deps.db, grant.workspaceId),
+          await listWorkspaceArtifacts(
+            deps.db,
+            grant.workspaceId,
+            await siteViewerForGrant(deps.db, grant),
+          ),
         ),
       );
     },
@@ -701,11 +1150,55 @@ export function buildOpenGeniMcpServer(
       authorize: async () => {
         await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
       },
+      // A Site-started agent does not propose or confirm the organization profile.
+      refuseSiteAgent: async () =>
+        await siteAgentClampRefusal(deps, grant, "the organization profile"),
       json,
     });
   }
   if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
     registerWorkspaceArtifactTools(server, deps, grant, sessionId, json);
+    // A published Site's own agent: its Site Data and Site SQL tools are
+    // pinned to that Site and act as the conversation's viewer. Resolve on
+    // every call: a long-lived MCP server must observe audience revocations.
+    const siteAgent = () =>
+      resolveSiteAgentDataContext(
+        deps,
+        { accountId: grant.accountId, workspaceId: grant.workspaceId },
+        sessionId,
+      );
+    registerSiteDataTools(
+      server,
+      deps,
+      grant,
+      async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      json,
+      siteAgent,
+    );
+    // Site SQL tools need a configured gateway (they also reach databases
+    // that already exist after the deployment stops offering Site SQL).
+    if (siteSqlGatewayConfig(deps.settings) !== null)
+      registerSiteSqlTools(
+        server,
+        deps,
+        grant,
+        async () => {
+          await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+        },
+        json,
+        siteAgent,
+      );
+    registerSitePublicationTools(
+      server,
+      deps,
+      grant,
+      async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      json,
+    );
     registerSandboxFileArtifactTool(server, deps, grant, sessionId, json);
     registerEditableArtifactAgentTools({
       server,
@@ -733,14 +1226,13 @@ export function buildOpenGeniMcpServer(
   registerRigTools(server, deps, grant, can, sessionId, json);
   registerSlackBotTools(server, deps, grant, sessionId, json);
   registerFikenTools(server, deps, grant, sessionId, json);
-  registerAtlassianTools(server, deps, grant, json);
 
-  // Orchestration, variableSet, and GitHub status tools are permission-gated
+  // Orchestration, secret, and GitHub status tools are permission-gated
   // at registration: a grant without the permission does not see the tool.
   // Sandboxed workers reach this server with the first-party delegated
   // permission set (firstPartyMcpPermissions in @opengeni/runtime), which is
-  // POWERFUL BY DEFAULT — it carries sessions:*, variable sets:*, and github:use,
-  // so agents can spawn/read sessions, manage variable set variables, inspect
+  // POWERFUL BY DEFAULT — it carries sessions:*, secrets:*, and github:use,
+  // so agents can spawn/read sessions, use and save vault secrets, inspect
   // GitHub connection availability, and use already-bound repository resources
   // out of the box. GitHub installation credentials are refreshed host-side and
   // never returned through a model-visible MCP tool. A user DEMOTES a specific
@@ -753,10 +1245,14 @@ export function buildOpenGeniMcpServer(
     can,
     sessionId,
     sessionCreateVisible,
+    // A child selection may only narrow this session's: advertise exactly the
+    // deployment-allowed tools this session holds, never the whole catalog.
+    allowedFirstPartyMcpToolsForSession(deps.settings, FIRST_PARTY_MCP_TOOL_NAMES).filter((tool) =>
+      server.holdsSelectableTool(tool),
+    ),
     json,
   );
   registerProjectTools(server, deps, grant, can, json);
-  registerVariableSetTools(server, deps, grant, can, sessionId, json);
   if (sessionId !== null && can("workspace:read")) {
     registerCapabilityDiscoveryTools(server, deps, grant, sessionId, json);
   }
@@ -797,8 +1293,7 @@ export function buildOpenGeniMcpServer(
     server.registerTool(
       "social_connections_list",
       {
-        description:
-          "List connected social media accounts available to social media analysis packs.",
+        description: "List connected social media accounts available for analysis.",
         inputSchema: { limit: z4.number().int().positive().optional() },
       },
       async ({ limit }) =>
@@ -812,7 +1307,7 @@ export function buildOpenGeniMcpServer(
     server.registerTool(
       "social_posts_recent",
       {
-        description: "List recent social media posts imported or synced into OpenGeni.",
+        description: "List recent social media posts imported or synced into Opengeni.",
         inputSchema: {
           connectionIds: z4.array(z4.string().uuid()).optional(),
           since: z4.string().optional(),
@@ -1001,7 +1496,7 @@ export function buildOpenGeniMcpServer(
 
     // Provider-scoped aliases are the canonical tools advertised by the X and
     // Reddit Integration cards. The legacy social_* names remain available to
-    // existing Packs/sessions, but these names bind the provider in the tool
+
     // identity and reject a near-identical Connection from the other adapter.
     for (const provider of ["x", "reddit"] as const) {
       const providerName = provider === "x" ? "X" : "Reddit";
@@ -1127,7 +1622,7 @@ export function buildOpenGeniMcpServer(
       "social_posts_sync",
       {
         description:
-          "Sync the connected account's own recent posts from the provider into OpenGeni's social_posts store (idempotent), so social_posts_recent and daily analysis see fresh data.",
+          "Sync the connected account's own recent posts from the provider into Opengeni's social_posts store (idempotent), so social_posts_recent and daily analysis see fresh data.",
         inputSchema: {
           connectionId: z4.string().uuid(),
           limit: z4.number().int().positive().optional(),
@@ -1224,7 +1719,7 @@ export function buildOpenGeniMcpServer(
       server.registerTool(
         `${provider}_posts_sync`,
         {
-          description: `Sync one exact connected ${providerName} account's recent posts into OpenGeni (idempotent).`,
+          description: `Sync one exact connected ${providerName} account's recent posts into Opengeni (idempotent).`,
           inputSchema: {
             connectionId: z4.string().uuid(),
             limit: z4.number().int().positive().optional(),
@@ -1318,6 +1813,16 @@ export function buildOpenGeniMcpServer(
   }
 
   if (can("scheduled_tasks:manage") || can("scheduled_tasks:run")) {
+    // Someone else's Only me schedule is indistinguishable from a missing one.
+    const requireVisibleTask = async (id: string) => {
+      try {
+        return await requireVisibleScheduledTask(deps.db, grant, id);
+      } catch (error) {
+        if (error instanceof HTTPException && error.status === 404)
+          throw new Error(`Scheduled task not found: ${id}`, { cause: error });
+        throw error;
+      }
+    };
     server.registerTool(
       "scheduled_tasks_list",
       {
@@ -1331,7 +1836,15 @@ export function buildOpenGeniMcpServer(
       async ({ limit: requestedLimit, offset: requestedOffset }) => {
         const limit = requestedLimit ?? 25;
         const offset = requestedOffset ?? 0;
-        const rows = await listScheduledTasks(deps.db, grant.workspaceId, limit + 1, offset);
+        const viewer = await scheduledTaskViewerForGrant(deps.db, grant, deps.settings);
+        const rows = await listScheduledTasks(
+          deps.db,
+          grant.workspaceId,
+          limit + 1,
+          offset,
+          undefined,
+          viewer.subjectId,
+        );
         return json(
           boundScheduledTaskMcpPage({
             tasks: rows.slice(0, limit).map((task) => scheduledTaskForGrant(task, grant)),
@@ -1347,17 +1860,18 @@ export function buildOpenGeniMcpServer(
       "scheduled_tasks_get",
       {
         description:
-          "Get one scheduled task. The default is the same compact summary used by scheduled_tasks_list; pass includeEntity=true for a bounded projection with an 8 KiB prompt preview, bounded goal fields, resource/tool identity previews, and metadata keys without values.",
+          "Get one scheduled task. The default is the same compact summary used by scheduled_tasks_list; pass includeEntity=true for a bounded projection with an 8 KiB prompt preview, bounded goal fields, resource/tool identity previews, and metadata keys without values. For exact complete message text, pass promptOffset=0, then follow prompt.nextOffset with expectedExecutionDigest from the first page. This returns only the prompt page and preserves every character.",
         inputSchema: {
           id: z4.string().uuid(),
           includeEntity: z4.boolean().optional(),
+          promptOffset: z4.number().int().nonnegative().max(2_147_483_647).optional(),
+          expectedExecutionDigest: z4.string().min(1).max(128).optional(),
         },
       },
-      async ({ id, includeEntity }) => {
-        const task = scheduledTaskForGrant(
-          await requireScheduledTask(deps.db, grant.workspaceId, id),
-          grant,
-        );
+      async ({ id, includeEntity, promptOffset, expectedExecutionDigest }) => {
+        const task = scheduledTaskForGrant(await requireVisibleTask(id), grant);
+        if (promptOffset !== undefined)
+          return json(scheduledTaskPromptPage(task, promptOffset, expectedExecutionDigest));
         return json(
           includeEntity ? boundScheduledTaskDetailMcp(task) : scheduledTaskMcpSummary(task),
         );
@@ -1368,30 +1882,14 @@ export function buildOpenGeniMcpServer(
       "scheduled_tasks_create",
       {
         description:
-          "Create a scheduled task. Sessions generated for a task created from this session inherit this session's effective first-party tool selection and permission set; they never receive the deployment default catalog.",
-        inputSchema: {
-          name: z4.string(),
-          schedule: z4.unknown(),
-          runMode: z4.string().optional(),
-          targetSessionId: z4.string().uuid().nullable().optional(),
-          overlapPolicy: z4.string().optional(),
-          agentConfig: z4.unknown(),
-          status: z4.string().optional(),
-          // Explicit credential-free connection authority selections; declared
-          // so MCP validation doesn't strip them before the contract parse.
-          connectionAuthorities: z4.array(z4.unknown()).optional(),
-          variableSetId: z4.string().uuid().optional(),
-          // Deprecated alias of variableSetId; declared so MCP validation doesn't
-          // strip it before the contract parse maps it (rename back-compat).
-          environmentId: z4.string().uuid().optional(),
-          // Bind the task to a rig; declared so MCP validation doesn't strip it.
-          rigId: z4.string().uuid().nullable().optional(),
-          metadata: z4.record(z4.string(), z4.unknown()).optional(),
-        },
+          "Schedule a message in this chat by supplying name, schedule and prompt. Omitted destination uses the calling chat, with its model, tools, machine and attachments at run time. Choose reusable_session or new_session_per_run and agentConfig only when the user explicitly wants a separate agent; omit agentConfig.tools so each run gets the workspace's default connectors at that time, like a new chat, or list tools to give it exactly those. Each run uses the schedule owner’s current connected accounts; it never uses another chat owner’s credentials.",
+        inputSchema: contractToolInput(
+          scheduledTaskCreateToolProjection(),
+          scheduledTaskCreateToolValidation(sessionId),
+        ),
       },
       async (args) => {
-        const payload = CreateScheduledTaskRequest.parse(args);
-        requireVariableSetsUseForMcpAttachment(grant, payload.variableSetId);
+        const payload = resolveScheduledTaskCreateInput(args, sessionId);
         await requireLimit(deps, {
           accountId: grant.accountId,
           workspaceId: grant.workspaceId,
@@ -1434,34 +1932,23 @@ export function buildOpenGeniMcpServer(
     server.registerTool(
       "scheduled_tasks_update",
       {
-        description: "Update a scheduled task.",
-        inputSchema: {
-          id: z4.string().uuid(),
-          name: z4.string().optional(),
-          schedule: z4.unknown().optional(),
-          runMode: z4.string().optional(),
-          targetSessionId: z4.string().uuid().nullable().optional(),
-          overlapPolicy: z4.string().optional(),
-          agentConfig: z4.unknown().optional(),
-          status: z4.string().optional(),
-          // Omitted preserves the frozen selections, [] clears them, and an
-          // array replaces them; declared so MCP validation doesn't strip it.
-          connectionAuthorities: z4.array(z4.unknown()).optional(),
-          variableSetId: z4.string().uuid().nullable().optional(),
-          // Deprecated alias of variableSetId (rename back-compat); declared so MCP
-          // validation doesn't strip it before the contract parse maps it.
-          environmentId: z4.string().uuid().nullable().optional(),
-          // Bind the task to a rig; declared so MCP validation doesn't strip it.
-          rigId: z4.string().uuid().nullable().optional(),
-          metadata: z4.record(z4.string(), z4.unknown()).optional(),
-        },
+        description:
+          "Update a schedule without reconstructing its configuration: use prompt for message edits or targetSessionId to move it to an existing chat. Omitted fields are preserved. Send expectedExecutionDigest from get to reject stale edits. A move inherits the destination chat’s execution settings; if it reports an attached-access change, review it before retrying with adoptSessionSettings=true. For separate-agent model defaults use agentConfigPatch. agentConfig is full replacement; bounded get output is not replacement input. A schedule whose configuration.connectors is workspace_default keeps following the workspace's default connectors; its agentConfig.tools lists only connectors added on top.",
+        inputSchema: scheduledTaskUpdateToolInput(),
       },
       async ({ id, ...raw }) => {
-        const existing = await requireScheduledTask(deps.db, grant.workspaceId, id);
+        const existing = await requireVisibleTask(id);
         const previous = await captureScheduledTaskRestoreState(deps.db, existing);
         const payload = UpdateScheduledTaskRequest.parse(raw);
-        requireVariableSetsUseForMcpAttachment(grant, payload.variableSetId);
-        const update = await validatedScheduledTaskUpdate({
+        const patchWarnings = (task: ScheduledTask) =>
+          (payload.agentConfigPatch?.model !== undefined ||
+            payload.agentConfigPatch?.reasoningEffort !== undefined) &&
+          (task.runMode === "existing_session" || task.reusableSessionId)
+            ? [
+                "The task uses an existing session, whose model and reasoning are unchanged. Change that session separately if intended.",
+              ]
+            : [];
+        const updateOrError = await validatedScheduledTaskUpdate({
           settings: deps.settings,
           db: deps.db,
           objectStorage: deps.objectStorage,
@@ -1471,18 +1958,43 @@ export function buildOpenGeniMcpServer(
           toolsProvided: scheduledTaskToolsProvided(raw),
           sessionAuthorization: deps.sessionAuthorization,
           authorizationSurface: "first_party_mcp",
+        }).catch((error: unknown) => {
+          const conflict = scheduledTaskTargetAccessHttpError(error);
+          if (conflict) return conflict;
+          throw error;
         });
+        if (updateOrError instanceof ApiHttpError) {
+          return {
+            isError: true,
+            ...json({
+              error: {
+                code: updateOrError.code,
+                message: updateOrError.message,
+                details: updateOrError.details,
+              },
+            }),
+          };
+        }
+        const update = updateOrError;
         if (!scheduledTaskUpdateChangesState(existing, update)) {
-          return json(scheduledTaskReceipt("scheduled_tasks_update", existing, "unchanged", false));
+          return json(
+            scheduledTaskReceipt("scheduled_tasks_update", existing, "unchanged", false, {
+              warnings: patchWarnings(existing),
+            }),
+          );
         }
-        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, update);
+        const task = await updateScheduledTaskForApi(deps.db, grant, id, update);
         await syncUpdatedScheduledTask({
           db: deps.db,
           workflowClient: deps.workflowClient,
           previous,
           task,
         });
-        return json(scheduledTaskReceipt("scheduled_tasks_update", task, "updated", true));
+        return json(
+          scheduledTaskReceipt("scheduled_tasks_update", task, "updated", true, {
+            warnings: patchWarnings(task),
+          }),
+        );
       },
     );
 
@@ -1493,14 +2005,34 @@ export function buildOpenGeniMcpServer(
         inputSchema: { id: z4.string().uuid() },
       },
       async ({ id }) => {
-        const existing = await requireScheduledTask(deps.db, grant.workspaceId, id);
+        // Admins can pause any schedule, including someone else's Only me one,
+        // which they only ever see as a summary.
+        const viewer = await scheduledTaskViewerForGrant(deps.db, grant, deps.settings);
+        let pausable: Awaited<ReturnType<typeof requirePausableScheduledTask>>;
+        try {
+          pausable = await requirePausableScheduledTask(deps.db, grant, id, viewer);
+        } catch (error) {
+          if (error instanceof HTTPException && error.status === 404)
+            throw new Error(`Scheduled task not found: ${id}`, { cause: error });
+          throw error;
+        }
+        if (pausable.access === "summary") {
+          const changed = pausable.summary.status !== "paused";
+          if (changed) await pausePrivateScheduledTaskAsAdmin(deps.db, grant, id, viewer);
+          return json({ operation: "scheduled_tasks_pause", id, status: "paused", changed });
+        }
+        const existing = pausable.task;
         if (existing.status === "paused") {
           return json(scheduledTaskReceipt("scheduled_tasks_pause", existing, "unchanged", false));
         }
         const previous = await captureScheduledTaskRestoreState(deps.db, existing);
-        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, {
-          status: "paused",
-        });
+        const adminPause =
+          viewer.admin &&
+          (viewer.subjectId === null || existing.ownerSubjectId !== viewer.subjectId);
+        if (adminPause) await assertNotSiteClampedAgent(deps.db, grant, "schedules");
+        const task = adminPause
+          ? await pauseScheduledTaskAsAdmin(deps.db, grant.workspaceId, id)
+          : await updateScheduledTaskForApi(deps.db, grant, id, { status: "paused" });
         await syncUpdatedScheduledTask({
           db: deps.db,
           workflowClient: deps.workflowClient,
@@ -1518,7 +2050,7 @@ export function buildOpenGeniMcpServer(
         inputSchema: { id: z4.string().uuid() },
       },
       async ({ id }) => {
-        const existing = await requireScheduledTask(deps.db, grant.workspaceId, id);
+        const existing = await requireVisibleTask(id);
         if (existing.status === "active") {
           return json(scheduledTaskReceipt("scheduled_tasks_resume", existing, "unchanged", false));
         }
@@ -1533,7 +2065,7 @@ export function buildOpenGeniMcpServer(
           sessionAuthorization: deps.sessionAuthorization,
           authorizationSurface: "first_party_mcp",
         });
-        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, update);
+        const task = await updateScheduledTaskForApi(deps.db, grant, id, update);
         await syncUpdatedScheduledTask({
           db: deps.db,
           workflowClient: deps.workflowClient,
@@ -1555,7 +2087,7 @@ export function buildOpenGeniMcpServer(
         },
       },
       async ({ id, triggerId }) => {
-        const task = await requireScheduledTask(deps.db, grant.workspaceId, id);
+        const task = await requireVisibleTask(id);
         if (task.action.kind === "agent_turn") {
           const targetSession = await validateScheduledTaskTarget({
             db: deps.db,
@@ -1583,15 +2115,27 @@ export function buildOpenGeniMcpServer(
             grant,
             runMode: task.runMode,
             agentConfig: task.agentConfig,
+            audience: task.visibility === "private" ? "user_private" : "workspace_shared",
             requireOnline: true,
           });
-          await requireLimit(deps, {
-            accountId: grant.accountId,
-            workspaceId: grant.workspaceId,
-            action: "agent_run:create",
-            quantity: 1,
-            model: task.agentConfig.model ?? deps.settings.openaiModel,
+          const taskAuthoritySubjectId = await getScheduledTaskRevisionAuthoritySubject(deps.db, {
+            accountId: task.accountId,
+            workspaceId: task.workspaceId,
+            taskId: task.id,
+            taskAuthorityRevision: task.authorityRevision,
           });
+          await requireLimit(
+            { ...deps, settings: catalogSettings },
+            {
+              accountId: grant.accountId,
+              workspaceId: grant.workspaceId,
+              initiatingHumanSubjectId:
+                taskAuthoritySubjectId === task.ownerSubjectId ? taskAuthoritySubjectId : null,
+              action: "agent_run:create",
+              quantity: 1,
+              model: await resolveScheduledTaskPreflightModel(deps.db, catalogSettings, task),
+            },
+          );
         }
         const triggerToken = scheduledTaskTriggerToken(triggerId);
         const agentRunUsageIdempotencyKey =
@@ -1599,7 +2143,7 @@ export function buildOpenGeniMcpServer(
             ? manualScheduledTaskTriggerUsageKey(grant.workspaceId, task.id, triggerToken)
             : `knowledge-source-sync:manual:${grant.workspaceId}:${task.id}:${triggerToken}`;
         const triggerWorkflowId = manualScheduledTaskTriggerWorkflowId(task.id, triggerToken);
-        await deps.workflowClient.triggerScheduledTask({
+        await triggerScheduledTaskForGrant(deps.db, grant, deps.workflowClient, {
           task,
           agentRunUsageIdempotencyKey,
           triggerWorkflowId,
@@ -1653,10 +2197,18 @@ export function buildOpenGeniMcpServer(
         inputSchema: { id: z4.string().uuid() },
       },
       async ({ id }) => {
+        const target = await getScheduledTaskIncludingDeleted(deps.db, grant.workspaceId, id);
+        if (
+          target &&
+          scheduledTaskAccess(
+            await scheduledTaskViewerForGrant(deps.db, grant, deps.settings),
+            target,
+          ) !== "full"
+        )
+          throw new Error(`Scheduled task not found: ${id}`);
         const { task, changed } = await deleteScheduledTaskWithDurableCleanup(deps, {
-          workspaceId: grant.workspaceId,
+          grant,
           taskId: id,
-          subjectId: grant.subjectId,
         });
         return json(
           mcpMutationReceipt({
@@ -1680,12 +2232,14 @@ export function buildOpenGeniMcpServer(
           limit: z4.number().int().positive().optional(),
         },
       },
-      async ({ taskId, limit }) =>
-        json({
+      async ({ taskId, limit }) => {
+        await requireVisibleTask(taskId);
+        return json({
           runs: (await listScheduledTaskRuns(deps.db, grant.workspaceId, taskId, limit ?? 100)).map(
             (run) => scheduledTaskRunForGrant(run, grant),
           ),
-        }),
+        });
+      },
     );
   }
 
@@ -1705,7 +2259,7 @@ function registerSandboxFileArtifactTool(
     "sandbox_file_publish",
     {
       description:
-        "Publish one exact file from this session's /workspace into durable workspace storage. Use this before presenting a ZIP, CSV, JSON, Markdown, HTML, PDF, Office file, or other sandbox output as downloadable. Returns a permanent, authenticated artifact receipt; never invent or expose a sandbox: URL as the durable result.",
+        "Publish one exact file from this session's /workspace into durable workspace storage. Use this before presenting a video, ZIP, CSV, JSON, Markdown, HTML, PDF, Office file, or other sandbox output as downloadable. Present the returned artifact.artifactId as [Open file](artifact:<artifactId>), or ![Preview](artifact:<artifactId>) for inline image/video/audio/PDF previews. Replace <artifactId> with the exact returned ID and use a descriptive label. Never expose a sandbox: URL as the durable result. The artifactId is also the file's workspace File ID, so tools that take workspace file IDs, such as a browser upload action, accept it.",
       inputSchema: {
         path: z4.string().min(1).max(4_096),
       },
@@ -1738,14 +2292,29 @@ function registerSlackBotTools(
       sessionId,
       ...(connectionId ? { requestedConnectionId: connectionId } : {}),
     });
-    return createOpenGeniSlackBotClient(deps, resolved);
+    return createOpenGeniSlackBotClient(
+      {
+        ...deps,
+        authorizeProviderRequest: async () => {
+          if (sessionId !== null)
+            await authorizeFirstPartySession(
+              deps,
+              grant,
+              sessionId,
+              "session.first_party_mcp.call",
+            );
+          return true;
+        },
+      },
+      resolved,
+    );
   };
 
   server.registerTool(
     "slack_bot_list_channels",
     {
       description:
-        "List public and bot-visible private Slack channels through the workspace-shared OpenGeni bot. isMember identifies channels the bot may read/post in; the bot never joins channels automatically.",
+        "List public and bot-visible private Slack channels through the workspace-shared Opengeni bot. isMember identifies channels the bot may read/post in; the bot never joins channels automatically.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         cursor: z4.string().max(1024).optional(),
@@ -1763,62 +2332,14 @@ function registerSlackBotTools(
       ),
   );
 
-  server.registerTool(
-    "slack_bot_search",
-    {
-      description:
-        "Search public Slack channels workspace-wide as the workspace-shared OpenGeni bot: messages by default, plus files and channels via contentTypes. Public content only; private channels, DMs, and group DMs are searchable only through a member's personal Slack connection. Requires a bot install with the search scopes; older installs must be reinstalled by an admin. Continue with cursor for more results.",
-      inputSchema: {
-        connectionId: z4.string().uuid().optional(),
-        query: z4.string().min(1).max(500),
-        contentTypes: z4
-          .array(z4.enum(["messages", "files", "channels"]))
-          .min(1)
-          .max(3)
-          .optional(),
-        includeBots: z4.boolean().optional(),
-        before: z4.number().int().min(0).optional(),
-        after: z4.number().int().min(0).optional(),
-        sort: z4.enum(["score", "timestamp"]).optional(),
-        sortDir: z4.enum(["asc", "desc"]).optional(),
-        cursor: z4.string().max(1024).optional(),
-        limit: z4.number().int().min(1).max(20).optional(),
-      },
-    },
-    async ({
-      connectionId,
-      query,
-      contentTypes,
-      includeBots,
-      before,
-      after,
-      sort,
-      sortDir,
-      cursor,
-      limit,
-    }) =>
-      json(
-        await (
-          await clientFor(connectionId)
-        ).searchContext({
-          query,
-          ...(contentTypes ? { contentTypes } : {}),
-          ...(includeBots !== undefined ? { includeBots } : {}),
-          ...(before !== undefined ? { before } : {}),
-          ...(after !== undefined ? { after } : {}),
-          ...(sort ? { sort } : {}),
-          ...(sortDir ? { sortDir } : {}),
-          ...(cursor ? { cursor } : {}),
-          ...(limit !== undefined ? { limit } : {}),
-        }),
-      ),
-  );
+  // Real-time Search requires an approved app and a trusted Slack interaction
+  // action token. Generic agent calls cannot provide that interaction proof.
 
   server.registerTool(
     "slack_bot_channel_history",
     {
       description:
-        "Read Slack channel history as the workspace-shared OpenGeni bot. Public and private channels both require bot membership; invite the bot to private channels first.",
+        "Read Slack channel history as the workspace-shared Opengeni bot. Public and private channels both require bot membership; invite the bot to private channels first.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1842,7 +2363,7 @@ function registerSlackBotTools(
     "slack_bot_thread_replies",
     {
       description:
-        "Read a Slack thread as the workspace-shared OpenGeni bot. Pass the channel ID and the parent message timestamp returned by channel history. The result includes the parent followed by its replies.",
+        "Read a Slack thread as the workspace-shared Opengeni bot. Pass the channel ID and the parent message timestamp returned by channel history. The result includes the parent followed by its replies.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1867,7 +2388,7 @@ function registerSlackBotTools(
   server.registerTool(
     "slack_bot_list_users",
     {
-      description: "List Slack workspace users through the workspace-shared OpenGeni bot.",
+      description: "List Slack workspace users through the workspace-shared Opengeni bot.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         cursor: z4.string().max(1024).optional(),
@@ -1889,7 +2410,7 @@ function registerSlackBotTools(
     "slack_bot_list_files",
     {
       description:
-        "List Slack files and canvases shared with a channel where the workspace-shared OpenGeni bot is already a member.",
+        "List Slack files and canvases shared with a channel where the workspace-shared Opengeni bot is already a member.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1913,7 +2434,7 @@ function registerSlackBotTools(
     "slack_bot_file_info",
     {
       description:
-        "Read safe metadata for a Slack file or canvas shared with a channel where the workspace-shared OpenGeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the indirect share.",
+        "Read safe metadata for a Slack file or canvas shared with a channel where the workspace-shared Opengeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so Opengeni can verify the indirect share.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1937,7 +2458,7 @@ function registerSlackBotTools(
     "slack_bot_file_content",
     {
       description:
-        "Read a bounded page of UTF-8 text from a Slack file or canvas shared with a channel where the workspace-shared OpenGeni bot is already a member. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so OpenGeni can verify the channel-to-canvas-to-transcript chain. Slack may still restrict a huddle transcript body to participants; that returns huddle_transcript_requires_participant_access. Private Slack URLs and credentials are never returned. Continue with nextOffset when truncated is true.",
+        "Read a bounded page of text or view a PNG, JPEG, or WebP image from a Slack file shared with a channel where the workspace-shared Opengeni bot is already a member. Use the file ID from thread replies to view images in earlier thread messages. Images are returned as viewable content, only when directly shared to a non-shared channel, up to 640 KiB; offset must be 0. For an embedded huddle transcript, also pass the shared canvas file ID as parentFileId so Opengeni can verify the channel-to-canvas-to-transcript chain. Slack may still restrict a huddle transcript body to participants; that returns huddle_transcript_requires_participant_access. Private Slack URLs and credentials are never returned. Continue with nextOffset for truncated text.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
         channelId: z4.string().min(1).max(64),
@@ -1945,33 +2466,134 @@ function registerSlackBotTools(
         parentFileId: z4.string().min(1).max(64).optional(),
         offset: z4.number().int().min(0).max(4_000_000).optional(),
       },
+      outputSchema: {
+        kind: z4.enum(["text", "image"]),
+        fileId: z4.string(),
+        contentType: z4.string(),
+        content: z4.string().nullable(),
+        sizeBytes: z4.number().int().nullable(),
+        nextOffset: z4.number().int().nullable(),
+      },
     },
-    async ({ connectionId, channelId, fileId, parentFileId, offset }) =>
-      json(
-        await (
-          await clientFor(connectionId)
-        ).fileContent({
-          channelId,
+    async ({ connectionId, channelId, fileId, parentFileId, offset }) => {
+      const result = await (
+        await clientFor(connectionId)
+      ).fileContent({
+        channelId,
+        fileId,
+        ...(parentFileId ? { parentFileId } : {}),
+        ...(offset !== undefined ? { offset } : {}),
+      });
+      return slackBotFileContentResult(result);
+    },
+  );
+
+  server.registerTool(
+    "slack_bot_upload_file",
+    {
+      description:
+        "Upload one explicitly selected retained workspace file (including generated images) into this session's existing Slack task thread as the Opengeni bot. Use the file/artifact UUID returned by sandbox_file_publish or image generation. No channel or URL is accepted. Generate one operationId UUID per intended delivery and reuse the same operationId on every retry, including unknown outcomes; never start a replacement delivery to retry. Requires the bot's optional files:write scope: a Slack administrator must apply the bot manifest and reinstall an older bot, not connect a personal Slack account. Nonempty files up to 25 MiB; personal files stay in private task threads. Does not automatically upload files merely because they appear in a message.",
+      inputSchema: { fileId: z4.string().uuid(), operationId: z4.string().uuid() },
+    },
+    async ({ fileId, operationId }) => {
+      if (!sessionId) throw new Error("File upload requires an existing Slack task session");
+      return json(
+        await uploadSlackTaskFile(deps, {
+          grant,
+          sessionId,
           fileId,
-          ...(parentFileId ? { parentFileId } : {}),
-          ...(offset !== undefined ? { offset } : {}),
+          operationId,
+          authorize: async () => {
+            await authorizeFirstPartySession(
+              deps,
+              grant,
+              sessionId,
+              "session.first_party_mcp.call",
+            );
+          },
         }),
-      ),
+      );
+    },
   );
 
+  // Scheduled runs retain their person-chosen channel; ordinary chats supply
+  // an explicit destination. A server-owned prepared message id is the durable
+  // Slack delivery identity in both cases.
+  const authorizeBotPost = async () => {
+    if (sessionId === null) {
+      throw new Error("Bot posting requires a chat");
+    }
+    await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+  };
   server.registerTool(
-    "slack_bot_delete_message",
+    "slack_bot_prepare_message",
     {
       description:
-        "Delete a message authored by the workspace-shared OpenGeni bot. Pass the channel ID and exact message timestamp returned by a prior post or channel/thread read. Generate one operationId UUID per intended deletion and reuse it on every retry, including after an unknown outcome. Slack refuses deletion of messages not authored by this bot.",
+        "Prepare a message as the Opengeni bot, never as a personal Slack account. In an ordinary chat supply channelId and, if multiple bots are available, connectionId. Scheduled runs omit both and use only the channel chosen by a person in Post to Slack. Nothing is sent until slack_bot_send_prepared_message is called with the returned messageId. Reuse that messageId for retries. Bot membership and organization sharing are checked when sending.",
       inputSchema: {
         connectionId: z4.string().uuid().optional(),
-        operationId: z4.string().uuid(),
-        channelId: z4.string().min(1).max(64),
-        timestamp: z4.string().min(1).max(64),
+        channelId: z4
+          .string()
+          .regex(/^[CG][A-Z0-9]{2,63}$/)
+          .optional(),
+        text: z4.string().min(1).max(40_000),
+        threadTimestamp: z4
+          .string()
+          .regex(/^\d{1,20}\.\d{1,12}$/)
+          .optional(),
       },
     },
-    async ({ connectionId, operationId, channelId, timestamp }) =>
+    async ({ text, threadTimestamp, channelId, connectionId }) => {
+      await authorizeBotPost();
+      return json(
+        await prepareSlackBotPost({
+          db: deps.db,
+          grant,
+          sessionId,
+          text,
+          ...(channelId ? { channelId } : {}),
+          ...(connectionId ? { connectionId } : {}),
+          ...(threadTimestamp ? { threadTimestamp } : {}),
+        }),
+      );
+    },
+  );
+  server.registerTool(
+    "slack_bot_send_prepared_message",
+    {
+      description:
+        "Send a message prepared by slack_bot_prepare_message in this chat, exactly as saved, as the Opengeni bot. If a send is interrupted or its outcome is unclear, retry with the same messageId: Opengeni checks Slack and never posts the same message twice. Do not prepare a new message just to retry.",
+      inputSchema: { messageId: z4.string().uuid() },
+    },
+    async ({ messageId }) => {
+      await authorizeBotPost();
+      return json(
+        await sendSlackBotPost({
+          db: deps.db,
+          settings: deps.settings,
+          grant,
+          sessionId,
+          messageId,
+          ...(deps.slackFetch ? { slackFetch: deps.slackFetch } : {}),
+          authorizeProviderRequest: authorizeBotPost,
+        }),
+      );
+    },
+  );
+
+  server.registerTool(
+    "slack_bot_delete_message",
+    {
+      description:
+        "Delete a message authored by the workspace-shared Opengeni bot. Pass the channel ID and exact message timestamp returned by a prior post or channel/thread read. Generate one operationId UUID per intended deletion and reuse it on every retry, including after an unknown outcome. Slack refuses deletion of messages not authored by this bot.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        operationId: z4.string().uuid(),
+        channelId: z4.string().min(1).max(64),
+        timestamp: z4.string().min(1).max(64),
+      },
+    },
+    async ({ connectionId, operationId, channelId, timestamp }) =>
       json(
         await (await clientFor(connectionId)).deleteMessage({ operationId, channelId, timestamp }),
       ),
@@ -2225,122 +2847,6 @@ function registerFikenTools(
   );
 }
 
-function registerAtlassianTools(
-  server: McpServer,
-  deps: ApiRouteDeps,
-  grant: AccessGrant,
-  json: JsonResult,
-): void {
-  const connectionFor = async (connectionId?: string) => {
-    const authorized = await authorizedAtlassianConnectionsForGrant({
-      db: deps.db,
-      grant,
-    });
-    const candidates = authorized.filter(({ connection }) =>
-      connectionId ? connection.id === connectionId : true,
-    );
-    if (candidates.length === 0) {
-      throw new Error(
-        connectionId
-          ? "the requested Atlassian connection is unavailable for this turn"
-          : "no Atlassian connection is available for this turn",
-      );
-    }
-    if (!connectionId && candidates.length > 1) {
-      throw new Error(
-        "connectionId is required because multiple Atlassian connections are available",
-      );
-    }
-    const authority = candidates[0]!;
-    const metadata = AtlassianConnectionMetadata.safeParse(authority.connection.metadata);
-    if (!metadata.success) throw new Error("Atlassian connection metadata is invalid");
-    return {
-      connection: authority.connection,
-      metadata: metadata.data,
-      subjectId: authority.subjectId ?? grant.subjectId,
-    };
-  };
-
-  server.registerTool(
-    "atlassian_sources_list",
-    {
-      description:
-        "List the Jira projects and Confluence spaces available through the authorized Atlassian connection, including which sources are selected for OpenGeni. Use this before search when the site or boundary is unclear.",
-      inputSchema: { connectionId: z4.string().uuid().optional() },
-    },
-    async ({ connectionId }) => {
-      const authority = await connectionFor(connectionId);
-      const response = await browseAtlassianSources(deps, {
-        workspaceId: grant.workspaceId,
-        subjectId: authority.subjectId,
-        connectionId: authority.connection.id,
-      });
-      const selected = new Set(authority.metadata.selectedSources.map((source) => source.id));
-      return json({
-        connectionId: authority.connection.id,
-        account: authority.metadata.displayName,
-        items: response.items.map((item) => ({
-          ...item,
-          selected: selected.has(item.id),
-        })),
-      });
-    },
-  );
-
-  server.registerTool(
-    "atlassian_search",
-    {
-      description:
-        "Search Jira issues and Confluence pages live within the projects and spaces selected for OpenGeni. Results reflect current Atlassian data and permissions, independent of the knowledge sync index.",
-      inputSchema: {
-        connectionId: z4.string().uuid().optional(),
-        query: z4.string().min(1).max(500),
-        product: z4.enum(["jira", "confluence"]).optional(),
-        limit: z4.number().int().min(1).max(50).optional(),
-      },
-    },
-    async ({ connectionId, query, product, limit }) => {
-      const authority = await connectionFor(connectionId);
-      return json({
-        connectionId: authority.connection.id,
-        results: await searchAtlassianLive(deps, {
-          workspaceId: grant.workspaceId,
-          subjectId: authority.subjectId,
-          connectionId: authority.connection.id,
-          query,
-          ...(product ? { product } : {}),
-          limit: limit ?? 20,
-        }),
-      });
-    },
-  );
-
-  server.registerTool(
-    "atlassian_get",
-    {
-      description:
-        "Open one current Jira issue or Confluence page, including description or page content and comments. The item must belong to a project or space selected for OpenGeni.",
-      inputSchema: {
-        connectionId: z4.string().uuid().optional(),
-        kind: z4.enum(["jira_issue", "confluence_page"]),
-        id: z4.string().min(1).max(256),
-      },
-    },
-    async ({ connectionId, kind, id }) => {
-      const authority = await connectionFor(connectionId);
-      return json(
-        await getAtlassianLiveItem(deps, {
-          workspaceId: grant.workspaceId,
-          subjectId: authority.subjectId,
-          connectionId: authority.connection.id,
-          kind,
-          id,
-        }),
-      );
-    },
-  );
-}
-
 /** Only a prompt explicitly supplied through the human/API channel may redirect a user-paused goal. */
 export function isHumanDirectedTurn(turn: { source: string }): boolean {
   return turn.source === "user" || turn.source === "api";
@@ -2393,34 +2899,49 @@ function registerGoalTools(
   sessionId: string,
   json: (value: unknown) => { content: Array<{ type: "text"; text: string }> },
 ): void {
-  const boundedGoalToolString = (maxBytes: number, field: string) =>
+  const boundedGoalToolString = (maxBytes: number, field: string, purpose: string) =>
     z4
       .string()
       .min(1)
+      .max(maxBytes)
+      .describe(
+        `${purpose} At most ${maxBytes} UTF-8 bytes (ASCII characters count as one byte). Use normal spaces and sentences; summarize if needed, never squeeze words together. This is a ledger field, not the final answer.`,
+      )
       .refine((value) => sessionGoalUtf8Bytes(value) <= maxBytes, {
         message: `${field} exceeds ${maxBytes} UTF-8 bytes`,
       });
-  const goalText = boundedGoalToolString(SESSION_GOAL_TEXT_MAX_BYTES, "goal text");
+  const goalText = boundedGoalToolString(
+    SESSION_GOAL_TEXT_MAX_BYTES,
+    "goal text",
+    "The human-readable standing objective, not a progress report.",
+  );
   const successCriteriaSchema = boundedGoalToolString(
     SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
     "goal success criteria",
+    "Human-readable conditions that prove the full objective is achieved.",
+  );
+  const goalRationale = boundedGoalToolString(
+    SESSION_GOAL_RATIONALE_MAX_BYTES,
+    "goal rationale",
+    "A short human-readable explanation of the goal change or blocker and what must happen next.",
   );
-  const goalRationale = boundedGoalToolString(SESSION_GOAL_RATIONALE_MAX_BYTES, "goal rationale");
   const progressNoteSchema = boundedGoalToolString(
     SESSION_GOAL_PROGRESS_MAX_BYTES,
     "goal progress note",
+    "A short human-readable status of concrete progress toward the unchanged goal. Keep only useful milestones; do not pack a deliverable, command transcript, or continuation instructions here.",
   );
-  const inputWaitReasonSchema = boundedGoalToolString(2 * 1024, "session input wait reason").refine(
-    (value) => value.trim().length > 0,
-    {
-      message: "session input wait reason must not be blank",
-    },
-  );
+  const inputWaitReasonSchema = boundedGoalToolString(
+    2 * 1024,
+    "session input wait reason",
+    "One short human-readable sentence explaining the dependency being awaited.",
+  ).refine((value) => value.trim().length > 0, {
+    message: "session input wait reason must not be blank",
+  });
   server.registerTool(
     "goal_set",
     {
       description:
-        "Create a goal when this session has none, or replace a completed goal with a new one. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an active or paused goal, use goal_update with its objective revision, a change kind, and rationale.",
+        "Create a goal when this session has none, or replace a completed goal with a new one. text is the human-readable objective and successCriteria states its completion conditions; each allows 8192 UTF-8 bytes. Keep normal spaces; summarize, never compress words or put the deliverable in ledger text. Declare user-facing native document reports with reportRequirements before producing them. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an active or paused goal, use goal_update with its objective revision, a change kind, and rationale.",
       // `maxAutoContinuations` is deliberately not agent-facing: the ceiling is
       // API/scheduled-task pacing configuration, and an agent that set its own
       // cap used to silence its orchestration for hours. Continuation pacing is
@@ -2428,9 +2949,10 @@ function registerGoalTools(
       inputSchema: {
         text: goalText,
         successCriteria: successCriteriaSchema.optional(),
+        reportRequirements: SessionGoalReportRequirements.optional(),
       },
     },
-    async ({ text, successCriteria }) => {
+    async ({ text, successCriteria, reportRequirements }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
@@ -2444,15 +2966,24 @@ function registerGoalTools(
           ? (grant.metadata["turnId"] as string)
           : null;
       await assertGoalReactivationAllowed(deps, grant.workspaceId, sessionId, callerTurnId);
+      const context = exactAgentCommandContext(grant, sessionId);
       const { goal, replaced, events } = await upsertSessionGoalWithEvent(deps.db, {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
         sessionId,
         text,
         successCriteria: successCriteria ?? null,
+        ...(reportRequirements !== undefined ? { reportRequirements } : {}),
         maxAutoContinuations: null,
         createdBy: "agent",
         actor: "agent",
+        commandActor: {
+          type: "agent_attempt",
+          sessionId: context.callerSessionId,
+          turnId: context.callerTurnId,
+          attemptId: context.callerAttemptId,
+          executionGeneration: context.callerExecutionGeneration,
+        },
       });
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
@@ -2482,7 +3013,7 @@ function registerGoalTools(
     "goal_update",
     {
       description:
-        "Propose or apply a semantic goal revision under the session's mutation policy. Retain the standing goal unless explicit user direction or meaningful new evidence justifies the declared refinement, adaptation, or replacement. Every rewrite must use the exact expected objective revision and a concise rationale. Root constraints cannot be changed by an agent. A rewrite is not an execution-progress audit fact; use the optional goal_progress tool when such a fact should be recorded.",
+        "Maintain your operational goal as user direction or meaningful new evidence clarifies the intended outcome. text and successCriteria each allow 8192 UTF-8 bytes; rationale allows 2048 UTF-8 bytes for a short human-readable explanation. Use normal spaces and summarize instead of squeezing words. Changes apply directly unless the user explicitly configured review_changes; refinement, adaptation, and replacement are audit classifications, not approval gates under the default policy. Use the exact expected objective revision. Updating a goal grants no additional authority and cannot change root constraints. Progress notes belong in goal_progress (8192 UTF-8 bytes), not a semantic goal rewrite; deliver the answer in your final reply.",
       inputSchema: {
         text: goalText.optional(),
         successCriteria: successCriteriaSchema.nullable().optional(),
@@ -2540,13 +3071,14 @@ function registerGoalTools(
     "goal_progress",
     {
       description:
-        "Record concrete progress toward the unchanged active goal. This does not change goal text, success criteria, mutation policy, or objective revision. Do not use it merely to keep the continuation loop alive.",
+        "Record concrete progress toward the unchanged active goal. progressNote is a short human-readable status with useful milestones, at most 8192 UTF-8 bytes. Use normal spaces and sentences; summarize instead of compressing words. It is not the deliverable, a raw command transcript, or instructions for the next turn; the final answer still belongs in chat. Optionally append reportRequirements for secondary user-facing reports discovered during other work; existing requirement IDs and titles cannot be changed or removed. This does not change goal text, success criteria, mutation policy, or objective revision. Do not use it merely to keep the continuation loop alive.",
       inputSchema: {
         progressNote: progressNoteSchema,
         idempotencyKey: z4.string().uuid(),
+        reportRequirements: SessionGoalReportRequirements.optional(),
       },
     },
-    async ({ progressNote, idempotencyKey }) => {
+    async ({ progressNote, idempotencyKey, reportRequirements }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       const context = exactAgentCommandContext(grant, sessionId);
       const { goal, events, operationId, replay } = await recordSessionGoalProgressWithEvent(
@@ -2555,6 +3087,7 @@ function registerGoalTools(
         sessionId,
         {
           progressNote,
+          ...(reportRequirements !== undefined ? { reportRequirements } : {}),
           command: {
             accountId: grant.accountId,
             actor: {
@@ -2577,10 +3110,10 @@ function registerGoalTools(
     "wait_for_input",
     {
       description:
-        "End the current turn and wait out of turn for relevant session input. This is self-only and does not require a goal. After success, the production runtime ends the turn at the tool-batch boundary without another model step or final message. Use it for long or uncertain waits instead of sleeping or repeatedly calling session_wait/command_wait. timeoutSeconds is a relative safety-wake duration; OpenGeni persists the first absolute deadline for the turn, and repeated calls do not extend it. Timeout never cancels a background command. A human/API prompt, agent message or Steer, child terminal result, scheduled input, terminal background-command result, or the deadline wakes the session. Use goal_pause instead when the active goal itself should stop pending a human decision.",
+        "End the current turn and wait out of turn for relevant session input. This is self-only and does not require a goal. After success, the production runtime ends the turn at the tool-batch boundary without another model step or final message. Use it for long or uncertain waits, including right after spawning a child that needs minutes, instead of sleeping or repeatedly calling session_wait, session_get, or command_wait. No preliminary short wait or status recheck is required. timeoutSeconds is a relative safety-wake duration, not a blocking execution wait; choose it for the dependency or a meaningful user/task/Skill monitoring cadence, potentially hours or days within the schema limits. Do not schedule wakeups merely for unchanged reassurance unless an explicit update cadence requires it. Opengeni persists the first absolute deadline for the turn, and repeated calls do not extend it. After answering a question during a wait, preserve the existing deadline by passing the time remaining, not a fresh full timeout. If less than the schema minimum remains or the deadline has passed, a question-only human/API turn that consumed no immediate machine input may finish without replacing the retained wait; its deadline machinery remains authoritative. Do not send an invalid timeout or silently extend the deadline. Otherwise do not assume the old wait remains armed; register a valid wait if needed and make any unavoidable deadline adjustment explicit. Timeout never cancels a background command. A human/API prompt, agent message or Steer, child terminal result (it carries the child's final answer in payload.finalAnswer), scheduled input, terminal background-command result, or the deadline wakes the session. Use goal_pause instead when the active goal itself should stop pending a human decision. Pending Codemode calls require the same live attempt: observe them with command_wait/command_read rather than ending the turn.",
       inputSchema: {
         reason: inputWaitReasonSchema.describe(
-          "Shown directly to the user. Write one short, natural sentence explaining what you are waiting for, with normal spacing. Exclude internal IDs, cursors, commit hashes, paths, and continuation instructions. Example: Waiting for the build and database checks to finish.",
+          "Shown directly to the user; at most 2048 UTF-8 bytes. Write one short, natural sentence explaining what you are waiting for, with normal spacing. Exclude internal IDs, cursors, commit hashes, paths, and continuation instructions. Example: Waiting for the build and database checks to finish.",
         ),
         timeoutSeconds: z4
           .number()
@@ -2635,16 +3168,29 @@ function registerGoalTools(
     "goal_complete",
     {
       description:
-        "Mark the session goal as completed. Requires concrete evidence (what was done and how it satisfies the success criteria). Completion prevents further continuation turns.",
-      inputSchema: { evidence: z4.string().min(1) },
+        "Mark the session goal as completed with a short concrete proof for the goal ledger (evidence: at most 8192 characters). Evidence is not the deliverable and is not shown as your final chat reply; do not squeeze a report into it or remove spaces to fit. After this tool succeeds, reply to the user with the requested deliverable, or its summary and retained artifact link. Completion stops automatic goal continuations, not the current turn or its final reply. Every persisted report requirement must have a matching reportDeliveries entry containing a native document artifactId and its server-issued inspectionReceiptId from a post-edit body inspection. Missing, stale, inaccessible or summary-only proof fails; inspect again after an edit. Omit reportDeliveries only when no reports were declared.",
+      inputSchema: {
+        evidence: z4
+          .string()
+          .min(1)
+          .max(8192)
+          .describe(
+            "Short ledger proof, at most 8192 characters; not the final answer. Keep normal spaces. Deliver the answer in your final user-facing reply.",
+          ),
+        reportDeliveries: SessionGoalReportDeliveries.optional(),
+      },
     },
-    async ({ evidence }) => {
+    async ({ evidence, reportDeliveries }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
       if (!existing) {
         throw new Error("this session has no goal; use goal_set first");
       }
+      const context = exactAgentCommandContext(grant, sessionId);
+      const reportArtifactActor = editableArtifactActorForGrant(grant, "0000000000000001");
+      if (reportArtifactActor.kind !== "agent")
+        throw new Error("Goal completion requires exact agent authority");
       const { goal, events } = await setSessionGoalStatusWithEvent(
         deps.db,
         grant.workspaceId,
@@ -2652,6 +3198,15 @@ function registerGoalTools(
         {
           status: "completed",
           evidence,
+          ...(reportDeliveries !== undefined ? { reportDeliveries } : {}),
+          reportArtifactActor,
+          commandActor: {
+            type: "agent_attempt",
+            sessionId: context.callerSessionId,
+            turnId: context.callerTurnId,
+            attemptId: context.callerAttemptId,
+            executionGeneration: context.callerExecutionGeneration,
+          },
           event: { type: "goal.completed", evidence },
         },
       );
@@ -2659,8 +3214,8 @@ function registerGoalTools(
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
-      return json(
-        mcpMutationReceipt({
+      return json({
+        ...mcpMutationReceipt({
           operation: "goal_complete",
           committed: true,
           outcome: changed ? "updated" : "unchanged",
@@ -2675,7 +3230,15 @@ function registerGoalTools(
           idempotency: { status: "not_supported" },
           nextAction: { tool: "session_get", arguments: { sessionId } },
         }),
-      );
+        reportDeliveries: SessionGoalReportDeliveries.parse(
+          goal.metadata.reportDeliveriesV1 ?? [],
+        ).map((delivery) => ({
+          ...delivery,
+          artifactReference: `[Open report](/workspaces/${grant.workspaceId}/artifacts/editable/${delivery.artifactId})`,
+        })),
+        handoff:
+          "Now reply to the user with the requested deliverable, or its summary and retained artifact link. The evidence is only ledger proof; this receipt does not deliver your final answer.",
+      });
     },
   );
 
@@ -2683,7 +3246,7 @@ function registerGoalTools(
     "goal_pause",
     {
       description:
-        "Pause the session goal with a rationale (blocked, not productive, needs human input). No further continuation turns are synthesized until the goal is resumed or replaced.",
+        "Pause the session goal with an evidence-based rationale when no meaningful authorized progress remains. rationale is a short human-readable blocker explanation, at most 2048 UTF-8 bytes; keep normal spaces and summarize instead of compressing words. Investigate recoverable failures and try plausible safe alternatives that could materially help; no fixed turn or retry count is required, and a definitive missing permission or required human decision can justify pausing immediately. State the blocker and what must change to resume. Work already in flight or a meaningful timed recheck uses the available waiting mechanism instead. Tool approvals remain human-only. No further continuation turns are synthesized until the goal is resumed or replaced.",
       inputSchema: { rationale: goalRationale },
     },
     async ({ rationale }) => {
@@ -2736,7 +3299,7 @@ function registerGoalTools(
     "goal_resume",
     {
       description:
-        "Resume this session's paused goal regardless of who paused it or why. Already active is a successful no-op. Preserves the objective and resets continuation counters.",
+        "Resume this session's paused goal when the user asks you to continue (whoever paused it), or when the blocker you paused for has cleared. A user's question alone is not a reason to resume: answer it and leave the goal paused. Already active is a successful no-op. Preserves the objective and resets continuation counters.",
       inputSchema: {},
     },
     async () => {
@@ -2752,6 +3315,8 @@ function registerGoalTools(
         sessionId,
         {
           status: "active",
+          beforeResume: (tx, session, causalTurn) =>
+            assertGoalResumeAllowed({ ...deps, db: tx }, session, causalTurn),
           event: { type: "goal.resumed", actor: "agent" },
         },
       );
@@ -2830,9 +3395,22 @@ function registerWorkspaceArtifactTools(
       });
   const mutation = async (response: WorkspaceArtifactMutationResponse) =>
     await projectWorkspaceArtifactMutationProvenance(response, canReadProvenanceSession);
+  // A published Site follows its Site here exactly as through the API routes:
+  // the same hook resyncs the edge and scans a version that became current.
+  const siteMutation = async (response: WorkspaceArtifactMutationResponse, scan: boolean) =>
+    await mutation(await afterSiteArtifactMutation(deps, response, { scan }));
+  // An agent started from a Site page changes only the Sites it was started
+  // from and Sites its own session tree created (the HTTP routes check the same).
+  const otherSiteRefusal = async (artifactId: string) =>
+    (await siteAgentMayChangeArtifact(deps, grant, artifactId))
+      ? null
+      : siteAgentClampedToolResult(SITE_AGENT_OTHER_SITE_MESSAGE);
   const prepare = (
     html: string | undefined,
-    source?: { entrypoint: string; files: Array<{ path: string; content: string }> },
+    source?: {
+      entrypoint: string;
+      files: Array<{ path: string; content: string }>;
+    },
     requestedTools?: Array<{ serverId: string; toolName: string }>,
     uploadId?: string,
   ) => {
@@ -2895,9 +3473,10 @@ function registerWorkspaceArtifactTools(
     async ({ artifactId, versionId }) => {
       await authorize();
       if (!deps.objectStorage) throw new Error("Object storage is not configured");
+      const viewer = await siteViewerForGrant(deps.db, grant);
       const [rawDetail, ref] = await Promise.all([
-        getWorkspaceArtifact(deps.db, grant.workspaceId, artifactId),
-        getWorkspaceArtifactContentRef(deps.db, grant.workspaceId, artifactId, versionId),
+        getWorkspaceArtifact(deps.db, grant.workspaceId, viewer, artifactId),
+        getWorkspaceArtifactContentRef(deps.db, grant.workspaceId, viewer, artifactId, versionId),
       ]);
       const sourceAuthorizations = new Map<string, Promise<boolean>>();
       const canReadSourceSession = (sourceSessionId: string): Promise<boolean> => {
@@ -2924,7 +3503,7 @@ function registerWorkspaceArtifactTools(
     "artifacts_create",
     {
       description:
-        "Create and publish a generic workspace artifact from a complete HTML document. The exact HTML runs in an opaque-origin sandboxed iframe with JavaScript, external resources, forms, popups, and downloads enabled, but without parent-origin authority or top-level navigation.",
+        'Create and publish a Site from a complete HTML document. Its audience follows this chat unless you set visibility: in an Only me chat it is Only me (just the person you act for can see it; they can share it with the workspace from the Site page), otherwise everyone in the workspace can open it. Set visibility to "workspace" or "private" only when the person asks for that audience. The exact HTML runs in an opaque-origin sandboxed iframe with JavaScript, external resources, forms, popups, and downloads enabled, but without parent-origin authority or top-level navigation.',
       inputSchema: {
         title: z4.string().min(1).max(120),
         description: z4.string().max(2000).nullable().optional(),
@@ -2958,6 +3537,7 @@ function registerWorkspaceArtifactTools(
           )
           .max(WORKSPACE_ARTIFACT_REQUESTED_TOOLS_MAX)
           .optional(),
+        visibility: z4.enum(["private", "workspace"]).optional(),
         idempotencyKey: z4.string().min(1).max(200),
       },
     },
@@ -2968,10 +3548,19 @@ function registerWorkspaceArtifactTools(
       html,
       source,
       requestedTools,
+      visibility,
       idempotencyKey,
       uploadId,
     }) => {
       await authorize();
+      const audience = await resolveNewSiteAudience({
+        db: deps.db,
+        settings: deps.settings,
+        grant,
+        viewer: await siteViewerForGrant(deps.db, grant),
+        requested: visibility,
+        sourceSessionId: attempt().sessionId,
+      });
       const artifactId = crypto.randomUUID();
       const slugBase = slug ?? (normalizeWorkspaceArtifactSlug(title) || "artifact");
       const resolvedSlug = slug ?? `${slugBase.slice(0, 87)}-${artifactId.slice(0, 8)}`;
@@ -2983,6 +3572,7 @@ function registerWorkspaceArtifactTools(
             requestedSlug: slug ?? null,
             title,
             description: description ?? null,
+            ...audience,
             ...(await prepare(html, source, requestedTools, uploadId)),
             ...provenance(idempotencyKey, "artifacts_create"),
           }),
@@ -3041,16 +3631,28 @@ function registerWorkspaceArtifactTools(
       idempotencyKey,
     }) => {
       await authorize();
+      const refused = await otherSiteRefusal(artifactId);
+      if (refused) return refused;
+      const braked = await sitePlatformBrakeToolRefusal(() =>
+        requireSiteVersionPublishOpen(
+          deps,
+          { accountId: grant.accountId, workspaceId: grant.workspaceId },
+          artifactId,
+        ),
+      );
+      if (braked) return braked;
       return json(
-        await mutation(
+        await siteMutation(
           await publishWorkspaceArtifactVersion(deps.db, {
             artifactId,
+            viewer: await siteViewerForGrant(deps.db, grant),
             expectedCurrentVersionId,
             ...(title !== undefined ? { title } : {}),
             ...(description !== undefined ? { description } : {}),
             ...(await prepare(html, source, requestedTools, uploadId)),
             ...provenance(idempotencyKey, "artifacts_publish"),
           }),
+          true,
         ),
       );
     },
@@ -3071,15 +3673,19 @@ function registerWorkspaceArtifactTools(
     },
     async ({ artifactId, versionId, expectedCurrentVersionId, reason, idempotencyKey }) => {
       await authorize();
+      const refused = await otherSiteRefusal(artifactId);
+      if (refused) return refused;
       return json(
-        await mutation(
+        await siteMutation(
           await rollbackWorkspaceArtifact(deps.db, {
             artifactId,
+            viewer: await siteViewerForGrant(deps.db, grant),
             versionId,
             expectedCurrentVersionId,
             reason,
             ...provenance(idempotencyKey, "artifacts_rollback"),
           }),
+          true,
         ),
       );
     },
@@ -3099,15 +3705,19 @@ function registerWorkspaceArtifactTools(
     },
     async ({ artifactId, expectedCurrentVersionId, reason, idempotencyKey }) => {
       await authorize();
+      const refused = await otherSiteRefusal(artifactId);
+      if (refused) return refused;
       return json(
-        await mutation(
+        await siteMutation(
           await setWorkspaceArtifactStatus(deps.db, {
             artifactId,
+            viewer: await siteViewerForGrant(deps.db, grant),
             status: "archived",
             expectedCurrentVersionId,
             reason,
             ...provenance(idempotencyKey, "artifacts_archive"),
           }),
+          false,
         ),
       );
     },
@@ -3127,15 +3737,19 @@ function registerWorkspaceArtifactTools(
     },
     async ({ artifactId, expectedCurrentVersionId, reason, idempotencyKey }) => {
       await authorize();
+      const refused = await otherSiteRefusal(artifactId);
+      if (refused) return refused;
       return json(
-        await mutation(
+        await siteMutation(
           await setWorkspaceArtifactStatus(deps.db, {
             artifactId,
+            viewer: await siteViewerForGrant(deps.db, grant),
             status: "active",
             expectedCurrentVersionId,
             reason,
             ...provenance(idempotencyKey, "artifacts_restore"),
           }),
+          false,
         ),
       );
     },
@@ -3559,10 +4173,6 @@ function scheduledTaskUpdateChangesState(
   if (update.metadata !== undefined && stableJson(update.metadata) !== stableJson(task.metadata)) {
     return true;
   }
-  // Personal-connection delegations are recomputed with agentConfig and can
-  // change even when the visible config is byte-identical (for example after a
-  // connection rotation), so preserve that refresh as a real mutation.
-  if (update.personalConnectionDelegations !== undefined) return true;
   return false;
 }
 
@@ -3671,20 +4281,24 @@ function registerFleetTools(
     "sandbox_attach",
     {
       description:
-        'Attach this session to a sandbox for subsequent sandbox operations. The target must be owned and verified ready. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when attached back to home: OpenGeni checkpoints completed work and continues the same logical turn on home without another user message. A same-target attach is a repair request: it revalidates readiness and advances the route epoch rather than returning unchanged success. Recovery-in-progress/degraded/unrecoverable outcomes are typed. Use a sandboxes_list `id`, or "session"/"default" for home.',
+        'Attach this session to a sandbox for subsequent sandbox operations. The target must be owned and verified ready. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when attached back to home: Opengeni checkpoints completed work and continues the same logical turn on home without another user message. A same-target attach is a repair request: it revalidates readiness and advances the route epoch rather than returning unchanged success. Recovery-in-progress/degraded/unrecoverable outcomes are typed. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
-    async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
+    async ({ target }) =>
+      (await siteAgentComputeRefusal(deps, grant)) ??
+      json(await swapActiveSandbox(services, await fleetContext(), target)),
   );
 
   server.registerTool(
     "sandbox_swap",
     {
       description:
-        'Swap the active sandbox for this session mid-conversation. Validates ownership and verified readiness, then advances the route epoch. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when swapped back to home: OpenGeni checkpoints completed work and continues the same logical turn on home without another user message. Same-target swaps also revalidate and fence stale route caches. An operation that encountered provider disappearance is not replayed; retry only after a typed recovery-ready result. Use a sandboxes_list `id`, or "session"/"default" for home.',
+        'Swap the active sandbox for this session mid-conversation. Validates ownership and verified readiness, then advances the route epoch. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when swapped back to home: Opengeni checkpoints completed work and continues the same logical turn on home without another user message. Same-target swaps also revalidate and fence stale route caches. An operation that encountered provider disappearance is not replayed; retry only after a typed recovery-ready result. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
-    async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
+    async ({ target }) =>
+      (await siteAgentComputeRefusal(deps, grant)) ??
+      json(await swapActiveSandbox(services, await fleetContext(), target)),
   );
 
   server.registerTool(
@@ -3710,11 +4324,25 @@ function registerFleetTools(
       },
     },
     async ({ target, op }) => {
+      const refused = await siteAgentComputeRefusal(deps, grant);
+      if (refused) return refused;
       const typedOp = op as RunOnOp;
       const transientExecEnvironment = await oneOffCodemodeEnvironment(typedOp);
+      // W1 (DL-9): an exact agent attempt resolves `{{secret:…}}` references.
+      const claims = exactAgentAttemptClaims(grant);
+      const secretResolver =
+        claims && claims.sessionId === sessionId && typedOp.kind !== "read"
+          ? await createRunOnSecretResolver(
+              deps,
+              { accountId: grant.accountId, workspaceId: grant.workspaceId, ...claims },
+              (subjectId) =>
+                vaultProviderRegistryFor(deps, { workspaceId: grant.workspaceId, subjectId }),
+            )
+          : null;
       return json(
         await runOnSandbox(services, await fleetContext(), target, typedOp, {
           ...(transientExecEnvironment ? { transientExecEnvironment } : {}),
+          ...(secretResolver ? { secretResolver } : {}),
         }),
       );
     },
@@ -3724,27 +4352,67 @@ function registerFleetTools(
     "sandbox_provision",
     {
       description:
-        "Provision a new sandbox for the fleet. kind=selfhosted returns device-flow enrollment instructions to share with a HUMAN (install the agent + enroll their machine with loud whole-machine consent — the agent cannot self-consent). kind=modal creates a named Modal sandbox record, but it is NOT yet attachable as a swap target: routing a session onto a second Modal box is not supported yet, so sandbox_swap to its id is rejected. Use the session's own box (the default) or attach a Connected Machine instead.",
+        "Provision a new sandbox for the fleet. kind=selfhosted posts the Connected Machine card in this chat: the person copies a one-line connect command, runs it on their own computer, and picks Use in this chat; the card also offers the Opengeni Browser Chrome extension once the machine is connected. When you can already run commands on the target machine, install it yourself with connected_machine_enroll_token instead. kind=modal creates a named Modal sandbox record, but it is NOT yet attachable as a swap target: routing a session onto a second Modal box is not supported yet, so sandbox_swap to its id is rejected. Use the session's own box (the default) or attach a Connected Machine instead.",
       inputSchema: {
         kind: z4.enum(["selfhosted", "modal"]),
         name: z4.string().min(1).max(120).optional(),
       },
     },
-    async ({ kind, name }) =>
-      json(
+    async ({ kind, name }) => {
+      const refused = await siteAgentComputeRefusal(deps, grant);
+      if (refused) return refused;
+      if (kind === "selfhosted" && exactAgentAttemptClaims(grant)) {
+        // Same live-attempt authority the other fleet tools resolve, without
+        // requiring a session box: a chat with no sandbox can still connect one.
+        await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+        const item = nativeConnectionCapabilityRecommendations({ connectedMachines: true }).find(
+          (candidate) => candidate.id === CONNECTED_MACHINE_CAPABILITY_ID,
+        )!;
+        const setup = await capabilitySetupProjection(
+          deps,
+          grant.workspaceId,
+          item,
+          new Set(),
+          new Set(),
+          false,
+          new Set(),
+          new Set(),
+        );
+        if (setup.status === "unavailable") {
+          return json({ kind: "selfhosted", status: "unavailable", message: setup.detail });
+        }
+        const eventId = await appendCapabilityCardEvent(deps, grant, sessionId, {
+          item,
+          action: "connect",
+          rationale: "Connect your computer so this chat can run on it.",
+          toolName: "sandbox_provision",
+        });
+        return json({
+          kind: "selfhosted",
+          status: "card_posted",
+          eventId,
+          message: `${
+            setup.status === "ready"
+              ? `${setup.detail} The Connected Machine card lists them with Use in this chat and can connect another.`
+              : "The Connected Machine card was posted. The person copies its one-line connect command, runs it on their machine, and picks Use in this chat; nothing is connected yet."
+          } Check sandboxes_list after they confirm. Chrome needs the Opengeni Browser extension (${OPENGENI_BROWSER_EXTENSION_URL}) on the connected machine.`,
+        });
+      }
+      return json(
         await provisionSandbox(services, await fleetContext(), {
           kind,
           ...(name ? { name } : {}),
         }),
-      ),
+      );
+    },
   );
 }
 
-// Workspace-admin/operator surface for removing a connected machine. This is
+// Enrollment-management surface for creating tokens and removing machines. This is
 // deliberately separate from the session-scoped fleet tools: a worker can list,
 // attach, or run on a machine only with session authority, while removal requires
-// the explicit high-trust enrollments:manage permission and never accepts a
-// sandbox id. A Modal record therefore cannot be removed through this operation.
+// the explicit enrollments:manage permission. Removal accepts enrollment ids,
+// never sandbox ids; a Modal record cannot be removed through this operation.
 function registerConnectedMachineTools(
   server: McpServer,
   deps: ApiRouteDeps,
@@ -3752,11 +4420,119 @@ function registerConnectedMachineTools(
   sessionId: string | null,
   json: JsonResult,
 ): void {
+  server.registerTool(
+    "connected_machine_enroll_token",
+    {
+      description:
+        "Create a single-use Connected Machine enrollment token for this workspace (expires in one hour) using existing enrollments:manage authority. Returns the token, expiry and Unix/PowerShell install commands. Use it when you can run commands on the target machine yourself (run_on, SSH, a VM you control): run the matching command there, then verify the machine with sandboxes_list. One token connects one machine; mint another for each additional machine (the same machine may rerun its command). When the person must run it on their own computer, post the Connected Machine card instead (capability_authorization_request with api:connected-machine), which mints the command in their browser; do not paste a token into the chat. Screen control is optional and defaults off; to turn it on for a machine that is already connected, use connected_machine_enable_screen_control instead of reconnecting. The token grants whole-machine access on enrollment; do not put it in public code or unrelated logs. Existing machine connections are preserved. For Chrome, the person installs the Opengeni Browser extension (" +
+        OPENGENI_BROWSER_EXTENSION_URL +
+        ") after the machine is connected.",
+      inputSchema: { allowScreenControl: z4.boolean().optional() },
+    },
+    async ({ allowScreenControl }) => {
+      if (sessionId) {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      }
+      const refused = await siteAgentClampRefusal(deps, grant, "Connected Machines");
+      if (refused) return refused;
+      const minted = await mintEnrollToken(deps, {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        allowScreenControl: allowScreenControl ?? false,
+      });
+      if (!minted) throw new Error("enrollment credential plane is not configured");
+      const base = (deps.settings.publicBaseUrl ?? "https://app.opengeni.ai").replace(/\/+$/, "");
+      const unixQuote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+      const windowsQuote = (value: string) => `'${value.replaceAll("'", "''")}'`;
+      return json({
+        ...minted,
+        workspaceId: grant.workspaceId,
+        allowScreenControl: allowScreenControl ?? false,
+        installCommandUnix: `curl -fsSL ${unixQuote(`${base}/install.sh`)} | OPENGENI_API_URL=${unixQuote(base)} OPENGENI_ENROLL_TOKEN=${unixQuote(minted.token)} sh`,
+        installCommandWindows: `$env:OPENGENI_API_URL=${windowsQuote(base)}; $env:OPENGENI_ENROLL_TOKEN=${windowsQuote(minted.token)}; irm ${windowsQuote(`${base}/install.ps1`)} | iex`,
+      });
+    },
+  );
+  server.registerTool(
+    "connected_machine_enable_screen_control",
+    {
+      description:
+        "Turn screen control on for a machine that is already connected, in place, so agents can see and use its screen (computer and attached-Chrome tools). `target` is a sandboxes_list id or an enrollment id. Needs no human click, token, terminal or reconnect: Opengeni records the consent on that machine and its agent refreshes its own credentials over the live connection. status=active means it is on now. status=pending means it is allowed and turns on by itself: reason=offline when the machine next connects; reason=agent_update_required after its agent is updated (update it with the machine update action, POST /v1/workspaces/{workspaceId}/machines/{enrollmentId}/update); reason=renewal_failed: call again shortly; reason=reconnect_required: the machine's connection predates in-place changes, so rerun the connect command on it (connected_machine_enroll_token with allowScreenControl=true). On a Mac the OS must also allow Screen Recording, Accessibility and Input Monitoring for Opengeni: open each pane on the Mac with run_on exec `open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'` (Privacy_Accessibility, Privacy_ListenEvent; also the privacy-settings machine action) and ask the person to switch Opengeni on there, choosing Quit & Reopen if macOS asks; the machine list reports runtime.macPermissions. Chrome additionally needs the Opengeni Browser extension (" +
+        OPENGENI_BROWSER_EXTENSION_URL +
+        ") on that machine.",
+      inputSchema: { target: z4.string().min(1) },
+    },
+    async ({ target }) => {
+      if (sessionId) {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      }
+      const refused = await siteAgentClampRefusal(deps, grant, "Connected Machines");
+      if (refused) return refused;
+      // Personal machines belong to the person the attempt acts for.
+      const attempt = sessionId ? exactAgentAttemptClaims(grant) : null;
+      const resourceGrant =
+        sessionId && attempt
+          ? {
+              ...grant,
+              subjectId:
+                (await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId))
+                  .initiatingHumanSubjectId ?? grant.subjectId,
+            }
+          : grant;
+      const enrollments = await listEnrollments(deps.db, resourceGrant, { status: "active" });
+      let enrollment = enrollments.find((candidate) => candidate.id === target);
+      if (!enrollment) {
+        const sandbox = await getSandbox(deps.db, resourceGrant, target).catch(() => null);
+        enrollment = enrollments.find((candidate) => candidate.id === sandbox?.enrollmentId);
+      }
+      if (!enrollment) {
+        throw new Error("machine not found in this access scope; use a sandboxes_list id");
+      }
+      if (enrollment.scope === "organization" && !grant.permissions.includes("account:admin")) {
+        throw new Error("missing permission: account:admin");
+      }
+      if (enrollment.scope === "user" && sessionId && attempt) {
+        // The same per-attempt admission run_on requires for personal machines.
+        const admitted = await authorizePersonalMachineForAttempt(deps.db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          subjectId: resourceGrant.subjectId,
+          sessionId,
+          turnId: attempt.turnId,
+          attemptId: attempt.attemptId,
+          executionGeneration: attempt.executionGeneration,
+          enrollmentId: enrollment.id,
+          requireActiveSandbox: false,
+        }).catch(() => false);
+        if (!admitted) {
+          throw new Error("personal Connected Machine authority was not admitted for this attempt");
+        }
+      }
+      const result = await enableMachineScreenControl(
+        {
+          db: deps.db,
+          settings: deps.settings,
+          ...(deps.bus ? { bus: deps.bus } : {}),
+          observability: deps.observability,
+        },
+        {
+          enrollment,
+          access: enrollmentAccess(enrollment, resourceGrant),
+          actor: {
+            subjectId: grant.subjectId,
+            sessionId: sessionId ?? null,
+            attemptId: attempt?.attemptId ?? null,
+          },
+        },
+      );
+      return json({ ...result, machine: enrollment.id });
+    },
+  );
   server.registerTool(
     "connected_machine_remove",
     {
       description:
-        "Remove one enrolled self-hosted machine while it is offline. Access is revoked, future heartbeat/reconnect credentials are rejected, and session, route, lease, archive, and audit history is retained. Idle dependent sessions are detached atomically; machine-home sessions become compute-less (backend none) until another sandbox is selected. Active turns, live leases, and recovery work remain fail-closed blockers whose typed outcome explains what must settle before retrying. Pass the enrollmentId from the Machines surface, never a Modal sandbox id. Reconnecting later requires a fresh human-approved device-flow enrollment.",
+        "Remove one enrolled self-hosted machine while it is offline. Access is revoked, future heartbeat/reconnect credentials are rejected, and session, route, lease, archive, and audit history is retained. Sessions that point at the machine are detached atomically, including ones whose turn is queued, paused or recovering (their next attempt uses no machine); machine-home sessions become compute-less (backend none) until another sandbox is selected. Only a live machine lease or pending lease recovery blocks removal, with a typed outcome that explains what must settle before retrying. Pass the enrollmentId from the Machines surface, never a Modal sandbox id. Reconnecting later requires fresh enrollment through device approval or an authorized enrollment token.",
       inputSchema: {
         enrollmentId: z4.string().uuid(),
         expectedUpdatedAt: z4.string().datetime({ offset: true }).optional(),
@@ -3764,6 +4540,8 @@ function registerConnectedMachineTools(
       },
     },
     async ({ enrollmentId, expectedUpdatedAt, idempotencyKey }) => {
+      const refused = await siteAgentClampRefusal(deps, grant, "Connected Machines");
+      if (refused) return refused;
       const resourceGrant =
         sessionId && exactAgentAttemptClaims(grant)
           ? {
@@ -3843,7 +4621,7 @@ function registerRigTools(
     const rig = await requireRigForApi(deps.db, await resourceGrant(), rigId);
     if (rig.scope === "organization") {
       throw new Error(
-        "Organization rig mutation requires account-admin authority through the authenticated REST surface.",
+        "Organization sandbox environment mutation requires account-admin authority through the authenticated REST surface.",
       );
     }
     return rig;
@@ -3852,7 +4630,7 @@ function registerRigTools(
     server.registerTool(
       "rig_list",
       {
-        description: "List workspace rigs and their active versions.",
+        description: "List workspace sandbox environments and their active versions.",
         inputSchema: {},
       },
       async () => json({ rigs: await listRigs(deps.db, await resourceGrant()) }),
@@ -3862,7 +4640,7 @@ function registerRigTools(
       "rig_get",
       {
         description:
-          "Get one rig's bounded active definition plus compact historical version/change summaries. Historical setup scripts, checks, payloads, and verification logs are represented by counts/byte facts rather than copied into model context; use the access-controlled REST detail endpoints for exact retained definitions.",
+          "Get one sandbox environment's bounded active definition plus compact historical version/change summaries. Historical setup scripts, checks, payloads, and verification logs are represented by counts/byte facts rather than copied into model context; use the access-controlled REST detail endpoints for exact retained definitions.",
         inputSchema: {
           rigId: z4.string().uuid(),
           versionLimit: z4.number().int().positive().optional(),
@@ -3893,7 +4671,7 @@ function registerRigTools(
       "rig_propose_change",
       {
         description:
-          "Propose an additive rig setup command for clean verification. Use the exact command that already worked in this sandbox.",
+          "Propose an additive sandbox environment setup command for clean verification. Use the exact command that already worked in this sandbox.",
         inputSchema: {
           rigId: z4.string().uuid(),
           command: z4.string().min(1).max(8192),
@@ -3901,6 +4679,9 @@ function registerRigTools(
         },
       },
       async ({ rigId, command, note }) => {
+        // A Site-started agent does not change sandbox environments.
+        const refused = await siteAgentClampRefusal(deps, grant, "sandbox environments");
+        if (refused) return refused;
         const rig = await requireMutableRig(rigId);
         const originGrant = { ...(await resourceGrant()), workspaceId: rig.workspaceId };
         const change = await proposeRigChangeForApi(
@@ -3942,7 +4723,7 @@ function registerRigTools(
                 retryable: true,
               },
               warnings: [
-                "The rig change and verifying transition committed, but verification workflow start failed.",
+                "The sandbox environment change and verifying transition committed, but verification workflow start failed.",
               ],
               facts: { verificationAttempt: attempt },
               nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
@@ -3975,13 +4756,16 @@ function registerRigTools(
       "rig_verify",
       {
         description:
-          "Trigger rig verification. Pass changeId for a proposed change, or omit it to re-verify the active version's checks.",
+          "Trigger sandbox environment verification. Pass changeId for a proposed change, or omit it to re-verify the active version's checks.",
         inputSchema: {
           rigId: z4.string().uuid(),
           changeId: z4.string().uuid().optional(),
         },
       },
       async ({ rigId, changeId }) => {
+        // A Site-started agent does not change sandbox environments.
+        const refused = await siteAgentClampRefusal(deps, grant, "sandbox environments");
+        if (refused) return refused;
         const rig = await requireMutableRig(rigId);
         if (changeId) {
           const change = await requireRigChangeForApi(deps.db, rig.workspaceId, rig.id, changeId);
@@ -4045,7 +4829,7 @@ function registerRigTools(
           );
         }
         if (!rig.activeVersion) {
-          throw new Error("rig has no active version");
+          throw new Error("sandbox environment has no active version");
         }
         await deps.workflowClient.startRigVerification({
           workspaceId: rig.workspaceId,
@@ -4078,13 +4862,16 @@ function registerRigTools(
       "rig_promote",
       {
         description:
-          "Promote a verified definition_edit rig change to a new active immutable version. Requires rigs:manage.",
+          "Promote a verified definition_edit sandbox environment change to a new active immutable version. Requires rigs:manage.",
         inputSchema: {
           rigId: z4.string().uuid(),
           changeId: z4.string().uuid(),
         },
       },
       async ({ rigId, changeId }) => {
+        // A Site-started agent does not change sandbox environments.
+        const refused = await siteAgentClampRefusal(deps, grant, "sandbox environments");
+        if (refused) return refused;
         const rig = await requireMutableRig(rigId);
         const change = await requireRigChangeForApi(deps.db, rig.workspaceId, rig.id, changeId);
         const originGrant = { ...(await resourceGrant()), workspaceId: rig.workspaceId };
@@ -4163,42 +4950,236 @@ function registerWorkspaceOrchestrationTools(
   can: (permission: Permission) => boolean,
   callerSessionId: string | null,
   sessionCreateVisible: boolean,
+  childSelectableTools: readonly FirstPartyMcpToolName[],
   json: JsonResult,
 ): void {
-  if (can("sessions:read")) {
+  const acknowledgeReads = async (children: { sessionId: string; sequences: number[] }[]) => {
+    if (
+      !callerSessionId ||
+      !exactAgentAttemptClaims(grant) ||
+      !children.some((child) => child.sequences.length > 0)
+    )
+      return;
+    // Never use grant.subjectId, session creator, or the latest queue human.
+    // Reauthorize after the bounded read, including after a blocking wait.
+    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
+    if (!actor.initiatingHumanSubjectId) return;
+    await acknowledgeConsumedChildEvents(deps.db, {
+      workspaceId: grant.workspaceId,
+      sessionId: callerSessionId,
+      subjectId: actor.initiatingHumanSubjectId,
+      children,
+    });
+  };
+  // The caller's exact live attempt just returned a direct child's complete
+  // answer to its model. Record it on the reading turn: when that attempt
+  // completes its turn, a pending terminal result repeating only answers the
+  // model already holds is superseded instead of starting another inference.
+  // Only a direct model call counts: a Codemode script may keep the output to
+  // itself. Best-effort: a failure leaves that result to be delivered.
+  const recordConsumedChildResults = async (
+    children: { sessionId: string; sequences: number[] }[],
+    extra: { _meta?: Record<string, unknown> } | undefined,
+  ): Promise<void> => {
+    const claims = exactAgentAttemptClaims(grant);
+    if (
+      extra?._meta?.[FIRST_PARTY_MCP_CALLER_META_KEY] !== "model" ||
+      !callerSessionId ||
+      !claims ||
+      claims.sessionId !== callerSessionId ||
+      !children.some((child) => child.sequences.length > 0)
+    )
+      return;
+    try {
+      await recordConsumedChildAnswers(deps.db, {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        sessionId: callerSessionId,
+        turnId: claims.turnId,
+        attemptId: claims.attemptId,
+        executionGeneration: claims.executionGeneration,
+        children,
+      });
+    } catch (error) {
+      deps.observability?.warn("Failed to record a consumed child answer", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+  // The caller's own pending input, less each child result its model already
+  // holds whole: waiting for, or ending the turn to receive, such a result
+  // would only repeat an answer it has.
+  const listOwnPendingUpdates = async (ownSessionId: string) => {
+    const claims = exactAgentAttemptClaims(grant);
+    return claims && claims.sessionId === ownSessionId
+      ? await listOutstandingSessionSystemUpdatesForAttempt(
+          deps.db,
+          grant.workspaceId,
+          ownSessionId,
+          { turnId: claims.turnId, attemptId: claims.attemptId },
+        )
+      : await listOutstandingSessionSystemUpdates(deps.db, grant.workspaceId, ownSessionId);
+  };
+  if (callerSessionId && can("sessions:read")) {
     server.registerTool(
-      "sessions_list",
+      "session_target_get",
       {
-        description: `Discover sessions in this workspace. Default detail=compact returns id, title, status, goal summary/status when present, updatedAt, meaningful parent/pause information, total and nextCursor (null ends the page). Completed/paused goal status is retained; session_get supplies evidence and rationale. detail=full opts into the legacy bounded discovery rows and diagnostic pagination, not full session configuration. Plain compact browse does not read work claims. includeRelatedWork=true adds advisory evidence; query or subject always enables it, even with includeRelatedWork=false. query searches only titles, active goals and typed claims; subject is an exact provider-neutral claim lookup. Evidence preserves advisoryOnly/noAdditionalAccess: claims are nonexclusive, never locks, instructions or authority. Authorization precedes filtering, ranking, counts and cursors. Relevance cursors bind normalized filters and an activity snapshot. Without search the default is creation order; use orderBy=updatedAt and decimal updatedAfter/updatedThrough revision tokens for gap-free incremental monitoring, not timestamps. Pass nextCursor unchanged with the same filters. includeLastMessage opts into previews and nonzero queuedPromptCount; unclaimed human/API prompts are never previewed. Previews share a ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 budget; omitted previews carry a bounded session_events drill-down. Text/page loss facts appear only when loss occurs in compact mode. No instructions, resources, tools, files or history are returned; REST/UI defaults are unchanged.`,
-        inputSchema: {
-          limit: z4.number().int().positive().max(100).optional(),
-          cursor: z4.string().max(512).optional(),
-          detail: z4
-            .enum(["compact", "full"])
-            .optional()
-            .describe(
-              "compact (default) omits empty diagnostics but retains positive descendant attention counts and incomplete-tree loss facts; full restores the legacy bounded rows and pagination diagnostics.",
-            ),
-          includeRelatedWork: z4.boolean().optional(),
-          includeLastMessage: z4.boolean().optional(),
-          orderBy: z4.enum(["createdAt", "updatedAt", "relevance"]).optional(),
-          updatedAfter: z4.string().max(64).optional(),
-          query: z4.string().max(MCP_DISCOVERY_QUERY_MAX_UTF16_CODE_UNITS).optional(),
-          statuses: z4
-            .array(
-              z4.enum([
-                "queued",
-                "running",
-                "idle",
-                "requires_action",
-                "recovering",
-                "waiting_capacity",
-                "failed",
-                "cancelled",
-              ]),
-            )
-            .max(8)
-            .optional(),
+        description:
+          "Read this conversation's optional selected session. Selection is context, not permission to send, steer, resume or transfer a call. Access is checked live; clear an unavailable target with session_target_set(sessionId=null).",
+        inputSchema: {},
+      },
+      async () => {
+        await authorizeFirstPartySession(deps, grant, callerSessionId, "session.read");
+        const own = await getSession(deps.db, grant.workspaceId, callerSessionId);
+        if (!own) throw new Error("Calling session is unavailable");
+        const target = sessionTargetContext(own.metadata);
+        if (target.sessionId) {
+          try {
+            await authorizeFirstPartySession(deps, grant, target.sessionId, "session.read");
+          } catch (error) {
+            if (!(error instanceof SessionAuthorizationDeniedError)) throw error;
+            return json({
+              version: target.version,
+              sessionId: null,
+              unavailable: true,
+              selectionOnly: true,
+            });
+          }
+          const selected = await getSession(deps.db, grant.workspaceId, target.sessionId);
+          if (!selected) throw new Error("Selected session is unavailable");
+          return json({ ...target, title: selected.title, selectionOnly: true });
+        }
+        return json({ ...target, title: null, selectionOnly: true });
+      },
+    );
+    server.registerTool(
+      "session_message_status",
+      {
+        description:
+          "Follow the exact update ID returned by session_send_message or session_steer. Returns delivery state, consuming turn and an exact outcome read when present; acceptance or another turn finishing is not completion. Never resends. Use session_wait for changes, then read again. A paused pending target requires an explicitly authorized resume; do not silently steer it.",
+        inputSchema: { sessionId: z4.string().uuid(), updateId: z4.string().uuid() },
+      },
+      async ({ sessionId, updateId }) => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
+        const update = await getSessionSystemUpdateById(
+          deps.db,
+          grant.workspaceId,
+          sessionId,
+          updateId,
+        );
+        if (
+          !update ||
+          update.sourceId !== callerSessionId ||
+          !["agent_message", "agent_steer_instruction"].includes(update.kind)
+        )
+          throw new Error("Message receipt not found for this caller and target");
+        const turn = update.deliveredTurnId
+          ? await getSessionTurn(deps.db, grant.workspaceId, update.deliveredTurnId)
+          : null;
+        if (turn && turn.sessionId !== sessionId) throw new Error("Message receipt turn mismatch");
+        const outcome = turn
+          ? await getSessionMessageOutcomeEvent(
+              deps.db,
+              grant.workspaceId,
+              sessionId,
+              turn.id,
+              turn.executionGeneration,
+            )
+          : null;
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
+        return json({
+          sessionId,
+          updateId,
+          delivery: update.state,
+          turnId: turn?.id ?? null,
+          turnStatus: turn?.status ?? null,
+          outcome: outcome ? { type: outcome.type, sequence: outcome.sequence } : null,
+          nextAction: outcome
+            ? {
+                tool: "session_events",
+                arguments: {
+                  sessionId,
+                  ...(outcome.type === "turn.cancelled" || outcome.type === "turn.superseded"
+                    ? {
+                        view: "debug",
+                        includeTypes: [outcome.type],
+                        payloadMode: "full",
+                      }
+                    : { view: "results" }),
+                  after: outcome.sequence - 1,
+                  before: outcome.sequence + 1,
+                  limit: 1,
+                },
+              }
+            : { tool: "session_get", arguments: { sessionId } },
+        });
+      },
+    );
+    if (can("sessions:control"))
+      server.registerTool(
+        "session_target_set",
+        {
+          description:
+            "Select an accessible session as conversational context, or clear with sessionId=null. Read session_target_get first and pass its version. Does not dispatch work, change authority or transfer/restart voice. Keep the same operationId for an exact retry.",
+          inputSchema: SetSessionTargetRequest.shape,
+        },
+        async (request) => {
+          await authorizeFirstPartySession(
+            deps,
+            grant,
+            callerSessionId,
+            "session.first_party_mcp.call",
+          );
+          const claims = exactAgentAttemptClaims(grant);
+          if (!claims || claims.sessionId !== callerSessionId)
+            throw new Error("Exact caller attempt required");
+          return json(
+            await setSessionTargetContext(deps.db, {
+              workspaceId: grant.workspaceId,
+              actor: { type: "agent_attempt", ...claims },
+              request,
+              authorizeTarget: async (db, sessionId) => {
+                await authorizeFirstPartySession({ ...deps, db }, grant, sessionId, "session.read");
+              },
+            }),
+          );
+        },
+      );
+  }
+  if (can("sessions:read")) {
+    server.registerTool(
+      "sessions_list",
+      {
+        description: `Discover sessions in this workspace. Default detail=compact returns id, title, status, goal summary/status when present, updatedAt, meaningful parent/pause information, total and nextCursor (null ends the page). Completed/paused goal status is retained; session_get supplies evidence and rationale. detail=full opts into the legacy bounded discovery rows and diagnostic pagination, not full session configuration. Plain compact browse does not read work claims. includeRelatedWork=true adds advisory evidence; query or subject always enables it, even with includeRelatedWork=false. query searches only titles, active goals and typed claims; subject is an exact provider-neutral claim lookup. Evidence preserves advisoryOnly/noAdditionalAccess: claims are nonexclusive, never locks, instructions or authority. Authorization precedes filtering, ranking, counts and cursors. Relevance cursors bind normalized filters and an activity snapshot. Without search the default is creation order; use orderBy=updatedAt and decimal updatedAfter/updatedThrough revision tokens for gap-free incremental monitoring, not timestamps. Pass nextCursor unchanged with the same filters. includeLastMessage opts into previews and nonzero queuedPromptCount; unclaimed human/API prompts are never previewed. Previews share a ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 budget; omitted previews carry a bounded session_events drill-down. Text/page loss facts appear only when loss occurs in compact mode. No instructions, resources, tools, files or history are returned; REST/UI defaults are unchanged.`,
+        inputSchema: {
+          limit: z4.number().int().positive().max(100).optional(),
+          cursor: z4.string().max(512).optional(),
+          detail: z4
+            .enum(["compact", "full"])
+            .optional()
+            .describe(
+              "compact (default) omits empty diagnostics but retains positive descendant attention counts and incomplete-tree loss facts; full restores the legacy bounded rows and pagination diagnostics.",
+            ),
+          includeRelatedWork: z4.boolean().optional(),
+          includeLastMessage: z4.boolean().optional(),
+          orderBy: z4.enum(["createdAt", "updatedAt", "relevance"]).optional(),
+          updatedAfter: z4.string().max(64).optional(),
+          query: z4.string().max(MCP_DISCOVERY_QUERY_MAX_UTF16_CODE_UNITS).optional(),
+          statuses: z4
+            .array(
+              z4.enum([
+                "queued",
+                "running",
+                "idle",
+                "requires_action",
+                "recovering",
+                "waiting_capacity",
+                "failed",
+                "cancelled",
+              ]),
+            )
+            .max(8)
+            .optional(),
           activeOnly: z4.boolean().optional(),
           originSiteId: z4
             .string()
@@ -4355,7 +5336,7 @@ function registerWorkspaceOrchestrationTools(
       "session_get",
       {
         description:
-          "Get an authorized session. Omit sessionId to read only the authenticated current agent session (a child reads itself, never its parent or root); sessionless/operator callers must provide an explicit ID. Both forms retain live-attempt and target authorization checks. Default detail=compact returns status, goal (including completion evidence or pause rationale), latest recorded goal progress, meaningful pause/wait state, queue counts, active turn and snapshot lastSequence. Queued status and updatedAt are not proof of execution; inspect the active turn and durable results. Goal completion is not a terminal child result: join with session_wait waitFor=completion from the last consumed event cursor (0 if none), not this snapshot lastSequence, which may already include an unread completion. For an already-settled child, retrieve its result-bearing completion with session_events or join from the last consumed cursor. Use detail=full for the legacy bounded configuration including resources, persisted tool refs, effectiveToolPolicy and variableSet ids (never variable values). Full mode is configuration, not a substitute for compact goal/progress facts. Self reads inspect session state, not conversation history, which is supplied directly. Text loss is explicit; REST/UI defaults are unchanged.",
+          "Get an authorized session. Omit sessionId to read only the authenticated current agent session (a child reads itself, never its parent or root); sessionless/operator callers must provide an explicit ID. Both forms retain live-attempt and target authorization checks. Default detail=compact returns status, goal (including completion evidence or pause rationale), latest recorded goal progress, meaningful pause/wait state, queue counts, active turn and snapshot lastSequence. Queued status and updatedAt are not proof of execution; inspect the active turn and durable results. An unchanged snapshot is not new evidence of a child's progress: do not poll it between session_wait calls as a ritual. For a long or uncertain child wait, call wait_for_input instead; no preliminary snapshot or short wait is required. Its terminal result wakes you and carries its final answer (payload.finalAnswer). Meaningful user/task/Skill monitoring cadences remain supported. Goal completion is not a terminal child result: join with session_wait waitFor=completion from the last consumed event cursor (0 if none), not this snapshot lastSequence, which may already include an unread completion. For an already-settled child, retrieve its result-bearing completion with session_events or join from the last consumed cursor. Use detail=full for the legacy bounded configuration including resources, persisted tool refs, effectiveToolPolicy and variableSet ids (never variable values). Full mode is configuration, not a substitute for compact goal/progress facts. Self reads inspect session state, not conversation history, which is supplied directly. Text loss is explicit; REST/UI defaults are unchanged.",
         inputSchema: {
           sessionId: z4
             .string()
@@ -4403,7 +5384,15 @@ function registerWorkspaceOrchestrationTools(
         }
         return json(
           boundSessionDetailMcp(
-            await withMcpEffectivePolicy(deps, grant.workspaceId, grant.subjectId, projected),
+            await withMcpEffectivePolicy(
+              deps,
+              grant.workspaceId,
+              grant.subjectId,
+              // The Codex pointers by cutover disposition, as REST shows them.
+              (await loadCodexSessionPointerProjection(deps.db, grant.workspaceId, [projected]))(
+                projected,
+              ),
+            ),
           ),
         );
       },
@@ -4413,45 +5402,58 @@ function registerWorkspaceOrchestrationTools(
       "session_events",
       {
         description:
-          "Read session history. Default view=conversation returns roughly ten complete user/assistant messages, including completed commentary, in a 16 KiB envelope; no token deltas or execution records. Prefer fewer complete messages; a single oversized message has fragment offsets and a lossless nextCursor continuation over retained source text, including large legacy rows. Fragment unit is codepoint for plain text or utf16 for codec text; pass the opaque v2 cursor unchanged (v1 cursors must restart). Pass cursor=nextCursor with sessionId, omitting other selectors; it binds the view, detail and direction. after/nextAfter and before/nextBefore only change position, never view or detail; use nextCursor when present to avoid skipping a message fragment. view=results returns final turn answers and actionable outcomes without duplicate message-completion text. view=tools returns compact call/result identities; includeArguments/includeOutput opt into one text or JSON-encoded value, and callId selects an exact call (sparse scans can return an empty advancing page). sourceExact=false and sourceOmitted identify oversized structured values that were omitted, never partial JSON presented as complete; scalar text remains resumable. Conversation/results/tools omit never-claimed human/API prompts and stale duplicate events. view=debug exposes the existing authorized audit query with explicit type/class filters, mode=monitoring|forensic and payloadMode=none|summary|full; raw deltas and never-claimed prompts require mode=forensic. Explicit legacy audit selectors remain supported without view. latest is an exclusive semantic-class lookup; resultMode=compact requires latest. No read observes commands or changes append-only history. REST behavior is unchanged.",
+          "Read session history. Default view=conversation returns roughly ten complete user/assistant messages, including completed commentary, in a 16 KiB envelope; no token deltas or execution records. Prefer fewer complete messages; a single oversized message has fragment offsets and a lossless nextCursor continuation over retained source text, including large legacy rows. Fragment unit is codepoint for plain text or utf16 for codec text; pass the opaque v2 cursor unchanged (v1 cursors must restart). Pass cursor=nextCursor with sessionId, omitting other selectors; it preserves the view, detail, direction and page size. Copy nextCursor byte-for-byte, never retype or build one; when you cannot, repeat the call with before=nextBefore (or after=nextAfter) instead. limit is 1–50 for content views; larger values are rejected. after/nextAfter and before/nextBefore only change position, never view or detail; use nextCursor when present to avoid skipping a message fragment. view=results returns final turn answers and actionable outcomes without duplicate message-completion text. view=tools returns compact call/result identities; toolName finds exact named calls across retained history. includeArguments/includeOutput opt into one text or JSON-encoded value, and callId selects an exact call (sparse scans can return an empty advancing page). toolName with includeOutput=true returns each named call with its result, limit 1-3 (default 1, the newest unless direction=after). sourceExact=false and sourceOmitted identify oversized structured values that were omitted, never partial JSON presented as complete; scalar text remains resumable. Conversation/results/tools omit never-claimed human/API prompts and stale duplicate events. view=debug exposes the existing authorized audit query with explicit type/class filters, mode=monitoring|forensic and payloadMode=none|summary|full; raw deltas and never-claimed prompts require mode=forensic. Explicit legacy audit selectors remain supported without view. latest is an exclusive semantic-class lookup; resultMode=compact requires latest. No read observes commands or changes append-only history. REST behavior is unchanged.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           view: z4.enum(["conversation", "results", "tools", "debug"]).optional(),
           cursor: z4.string().max(4096).optional(),
           callId: z4.string().max(512).optional(),
+          toolName: z4
+            .string()
+            .min(1)
+            .max(256)
+            .optional()
+            .describe(
+              "Exact tool name; selects calls in view=tools. With includeOutput=true each call carries its result.",
+            ),
           includeArguments: z4.boolean().optional(),
           includeOutput: z4.boolean().optional(),
           after: z4.number().int().nonnegative().optional(),
           before: z4.number().int().positive().optional(),
-          limit: z4.number().int().positive().optional(),
+          limit: z4
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Page size, 1–50 for conversation/results/tools. Continuations preserve it."),
           direction: z4.enum(SessionEventReadDirection.options).optional(),
           mode: z4.enum(SessionEventReadMode.options).optional(),
           payloadMode: z4.enum(SessionEventPayloadMode.options).optional(),
           resultMode: z4.enum(SessionEventResultMode.options).optional(),
           includeTypes: z4
-            .array(
-              z4
-                .string()
-                .refine(
-                  (value) => SessionEventType.safeParse(value).success,
-                  "Unknown session event type",
-                ),
-            )
+            .array(z4.string())
             .max(100)
+            .superRefine((values, context) =>
+              addUnknownSessionEventTypeIssues(
+                values,
+                (value) => SessionEventType.safeParse(value).success,
+                (issue) => context.addIssue(issue),
+              ),
+            )
             .describe(
               "Debug audit event types, e.g. turn.completed, user.message, agent.message.completed, agent.toolCall.output. Validated against the canonical event-type registry.",
             )
             .optional(),
           excludeTypes: z4
-            .array(
-              z4
-                .string()
-                .refine(
-                  (value) => SessionEventType.safeParse(value).success,
-                  "Unknown session event type",
-                ),
-            )
+            .array(z4.string())
             .max(100)
+            .superRefine((values, context) =>
+              addUnknownSessionEventTypeIssues(
+                values,
+                (value) => SessionEventType.safeParse(value).success,
+                (issue) => context.addIssue(issue),
+              ),
+            )
             .describe(
               "Debug audit event types to exclude; validated against the canonical event-type registry.",
             )
@@ -4467,31 +5469,40 @@ function registerWorkspaceOrchestrationTools(
           latest: z4.enum(SessionEventLatestClass.options).optional(),
         },
       },
-      async ({
-        sessionId,
-        view,
-        cursor,
-        callId,
-        includeArguments,
-        includeOutput,
-        after,
-        before,
-        limit,
-        direction: requestedDirection,
-        mode: requestedMode,
-        payloadMode: requestedPayloadMode,
-        resultMode: requestedResultMode,
-        includeTypes: requestedIncludeTypes,
-        excludeTypes: requestedExcludeTypes,
-        includeClasses,
-        excludeClasses,
-        latest,
-      }) => {
+      async (
+        {
+          sessionId,
+          view,
+          cursor,
+          callId,
+          toolName,
+          includeArguments,
+          includeOutput,
+          after,
+          before,
+          limit,
+          direction: requestedDirection,
+          mode: requestedMode,
+          payloadMode: requestedPayloadMode,
+          resultMode: requestedResultMode,
+          includeTypes: requestedIncludeTypes,
+          excludeTypes: requestedExcludeTypes,
+          includeClasses,
+          excludeClasses,
+          latest,
+        },
+        extra,
+      ) => {
         await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
         // Keep the model schema compact without weakening either MCP validation
         // or direct adapter calls: the canonical registry owns accepted types.
-        const includeTypes = requestedIncludeTypes?.map((type) => SessionEventType.parse(type));
-        const excludeTypes = requestedExcludeTypes?.map((type) => SessionEventType.parse(type));
+        const canonicalType = (type: string) => {
+          const parsed = SessionEventType.safeParse(type);
+          if (!parsed.success) throw new Error(unknownSessionEventTypeMessage(type));
+          return parsed.data;
+        };
+        const includeTypes = requestedIncludeTypes?.map(canonicalType);
+        const excludeTypes = requestedExcludeTypes?.map(canonicalType);
         const latestClass =
           latest === undefined ? undefined : sessionEventLatestClassToSemanticClass(latest);
         if (requestedResultMode === "compact" && latestClass === undefined) {
@@ -4510,45 +5521,80 @@ function registerWorkspaceOrchestrationTools(
         ].some((value) => value !== undefined);
         if (((view !== undefined && view !== "debug") || cursor !== undefined) && auditRequested) {
           throw new Error(
-            "Audit selectors require view=debug and cannot change a conversation cursor",
+            sessionEventAuditSelectorMessage({
+              sessionId,
+              view,
+              cursor,
+              audit: {
+                mode: requestedMode,
+                payloadMode: requestedPayloadMode,
+                resultMode: requestedResultMode,
+                includeTypes,
+                excludeTypes,
+                includeClasses,
+                excludeClasses,
+                latest,
+              },
+              position: { after, before, direction: requestedDirection, limit },
+            }),
           );
         }
         if (view !== "debug" && !auditRequested) {
           const { readSessionEventView } = await import("./session-event-view");
           const { listSessionEventSlices } = await import("@opengeni/db/session-event-slices");
-          return json(
-            await readSessionEventView(
-              {
+          const page = await readSessionEventView(
+            {
+              sessionId,
+              view,
+              cursor,
+              callId,
+              toolName,
+              includeArguments,
+              includeOutput,
+              after,
+              before,
+              direction: requestedDirection,
+              limit,
+            },
+            (options) =>
+              listSessionEventSlices(
+                deps.db,
+                grant.workspaceId,
                 sessionId,
-                view,
-                cursor,
-                callId,
-                includeArguments,
-                includeOutput,
-                after,
-                before,
-                direction: requestedDirection,
-                limit,
-              },
-              (options) =>
-                listSessionEventSlices(
-                  deps.db,
-                  grant.workspaceId,
-                  sessionId,
-                  options,
-                  (legacyOptions) =>
-                    listSessionEventPage(deps.db, grant.workspaceId, sessionId, legacyOptions),
-                ),
-            ),
+                options,
+                (legacyOptions) =>
+                  listSessionEventPage(deps.db, grant.workspaceId, sessionId, legacyOptions),
+              ),
           );
+          const consumed = [{ sessionId, sequences: completeChildReadSequences(page) }];
+          await acknowledgeReads(consumed);
+          await recordConsumedChildResults(consumed, extra);
+          return json(page);
         }
         if (
           cursor !== undefined ||
           callId !== undefined ||
+          toolName !== undefined ||
           includeArguments !== undefined ||
           includeOutput !== undefined
         ) {
-          throw new Error("cursor/callId/includeArguments/includeOutput require a non-debug view");
+          throw new Error(
+            `cursor/callId/toolName/includeArguments/includeOutput require a non-debug view; view=debug pages with after/before. Use ${JSON.stringify(
+              callId === undefined &&
+                toolName === undefined &&
+                includeArguments === undefined &&
+                includeOutput === undefined
+                ? { sessionId, cursor: "<nextCursor, unchanged>" }
+                : {
+                    sessionId,
+                    view: "tools",
+                    ...(callId !== undefined ? { callId } : {}),
+                    ...(toolName !== undefined ? { toolName } : {}),
+                    ...(includeArguments !== undefined ? { includeArguments } : {}),
+                    ...(includeOutput !== undefined ? { includeOutput } : {}),
+                  },
+            )} instead.`,
+          );
         }
         if (
           latest &&
@@ -4584,40 +5630,62 @@ function registerWorkspaceOrchestrationTools(
         });
         if (requestedResultMode === "compact") {
           const event = dbPage.events[0];
-          return json(
-            event
-              ? boundSessionEventCompactResult(
-                  compactSessionEventResult(
-                    event,
-                    latestClass!,
-                    dbPage.coveredSequence ?? {
-                      first: event.sequence,
-                      last: event.sequence,
-                    },
-                  ),
-                )
-              : null,
-          );
+          const result = event
+            ? boundSessionEventCompactResult(
+                compactSessionEventResult(
+                  event,
+                  latestClass!,
+                  dbPage.coveredSequence ?? {
+                    first: event.sequence,
+                    last: event.sequence,
+                  },
+                ),
+              )
+            : null;
+          // The compact text of a turn that ended waiting for input is its
+          // empty output, never the reply its human's message received, so
+          // returning it is not proof of reading that reply.
+          if (
+            result &&
+            event &&
+            ["turn.completed", "agent.message.completed"].includes(result.type) &&
+            turnCompletedReply(event.payload) === null &&
+            !result.truncation.truncated &&
+            dbPage.fullPayloadsExact
+          ) {
+            const consumed = [{ sessionId, sequences: [result.sequence] }];
+            await acknowledgeReads(consumed);
+            await recordConsumedChildResults(consumed, extra);
+          }
+          return json(result);
         }
-        return json(
-          boundSessionEventMcpPage({
-            events: dbPage.events,
-            mode,
-            payloadMode,
-            direction,
-            sourceHasMore: dbPage.hasMore,
-            sourceTruncatedBy: dbPage.truncatedBy,
-            after: after ?? 0,
-            before: before ?? null,
-          }),
-        );
+        const page = boundSessionEventMcpPage({
+          events: dbPage.events,
+          mode,
+          payloadMode,
+          direction,
+          sourceHasMore: dbPage.hasMore,
+          sourceTruncatedBy: dbPage.truncatedBy,
+          after: after ?? 0,
+          before: before ?? null,
+        });
+        if (
+          payloadMode === "full" &&
+          dbPage.fullPayloadsExact &&
+          !page.truncation?.reasons.includes("model_payload")
+        ) {
+          const consumed = [{ sessionId, sequences: page.events.map((event) => event.sequence) }];
+          await acknowledgeReads(consumed);
+          await recordConsumedChildResults(consumed, extra);
+        }
+        return json(page);
       },
     );
 
     server.registerTool(
       "session_wait",
       {
-        description: `Wait once for durable session changes, your pending machine input, or maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}). Pass targets with sessionId and afterSequence: the last consumed cursor, or 0. Never substitute session_get.lastSequence, which may include an unread completion. waitFor=change returns on turn lifecycle, completed messages, terminal commands, blockers, goal facts, or session control. waitFor=completion joins a child result: only a result-bearing final turn or blocker qualifies, not commentary, goal.completed, background commands, maintenance turns, or continuation segments. Neither mode wakes on raw deltas or tool receipts. Each target contains up to ${SESSION_WAIT_EVENTS_PER_TARGET} bounded summaries, latestSequence (the next afterSequence), and hasMore. For omitted rows use session_events view=results after=latestSequence for final outcomes, or view=debug with explicit filters for diagnostics; the default conversation view does not contain execution records. Byte limits can leave events=[] with hasMore=true. ownPendingUpdates > 0 means input will arrive when your next turn is claimed: finish this turn, or use includeOwnPendingUpdates=false to keep waiting. timedOut=true means no matching change; liveFanout=false means the deadline re-check supplied durable truth without the live bus. Do not immediately repeat a timeout without new evidence. For long or uncertain waits call wait_for_input once and end the turn.`,
+        description: `Wait once for durable session changes, your pending machine input, or maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}). This is an optional in-turn execution wait, not a prerequisite for wait_for_input. Pass targets with sessionId and afterSequence: the last consumed cursor, or 0. Never substitute session_get.lastSequence, which may include an unread completion. waitFor=change returns on turn lifecycle, settled answers, terminal commands, blockers, goal facts, or session control. waitFor=completion joins a child result: only a result-bearing final turn or blocker qualifies, not commentary, goal.completed, background commands, maintenance turns, or continuation segments. Neither mode wakes on raw deltas, progress commentary, or tool receipts. Each target contains up to ${SESSION_WAIT_EVENTS_PER_TARGET} bounded summaries, latestSequence (the next afterSequence), and hasMore. For omitted rows use session_events view=results after=latestSequence for final outcomes, or view=debug with explicit filters for diagnostics; the default conversation view does not contain execution records. Byte limits can leave events=[] with hasMore=true. ownPendingUpdates > 0 means input will arrive when your next turn is claimed: finish this turn, or use includeOwnPendingUpdates=false to keep waiting. timedOut=true means no matching change; liveFanout=false means the deadline re-check supplied durable truth without the live bus. Do not immediately repeat a timeout without new evidence; an unchanged session_get snapshot between waits is not new evidence. For long or uncertain waits, including a child that needs minutes, call wait_for_input once and end the turn: the child's terminal result wakes you and carries its final answer (payload.finalAnswer). Use meaningful user/task/Skill monitoring cadences when needed; an out-of-turn wait may span hours or days within its own limits.`,
         inputSchema: {
           targets: z4
             .array(
@@ -4665,56 +5733,81 @@ function registerWorkspaceOrchestrationTools(
         // (tests) may pass no extra at all.
         const signal: AbortSignal | undefined = extra?.signal;
         const workspaceId = grant.workspaceId;
+        const incompleteWaitEvents = new Set<string>();
         // A NATS subscription is live fanout only; the durable session_events
         // read below is the authority. Bun.serve idleTimeout (255 s) and the
         // 60 s MCP client request timeout both exceed the 50 s cap.
-        return json(
-          await waitForSessionChanges({
-            targets,
-            ownSessionId,
-            maxWaitMs: (maxWaitSeconds ?? SESSION_WAIT_DEFAULT_SECONDS) * 1_000,
-            targetEventTypes,
-            targetEventMatches:
-              waitFor === "completion" ? sessionWaitCompletionEventMatches : undefined,
-            signal,
-            source: {
-              reauthorizeTargets: async (sessionIds) => {
-                for (const targetSessionId of sessionIds) {
-                  await authorizeFirstPartySession(
-                    deps,
-                    grant,
-                    targetSessionId,
-                    "session.events.read",
-                  );
-                }
-              },
-              readTargetEvents: async (target) => {
-                const page = await listSessionEventPage(deps.db, workspaceId, target.sessionId, {
-                  after: target.afterSequence,
-                  direction: "after",
-                  limit: SESSION_WAIT_EVENTS_PER_TARGET,
-                  payloadMode: "full",
-                  includeTypes: targetEventTypes,
-                  maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
-                });
-                return { events: page.events, hasMore: page.hasMore };
-              },
-              readOwnPendingUpdateKinds:
-                ownSessionId === null
-                  ? null
-                  : async () =>
-                      (
-                        await listOutstandingSessionSystemUpdates(
-                          deps.db,
-                          workspaceId,
-                          ownSessionId,
-                        )
-                      ).map((update) => update.kind),
-              subscribe: (targetSessionId, onEvents) =>
-                deps.bus.subscribe(workspaceId, targetSessionId, onEvents),
+        const result = await waitForSessionChanges({
+          targets,
+          ownSessionId,
+          maxWaitMs: (maxWaitSeconds ?? SESSION_WAIT_DEFAULT_SECONDS) * 1_000,
+          targetEventTypes,
+          targetEventMatches:
+            waitFor === "completion"
+              ? sessionWaitCompletionEventMatches
+              : sessionWaitChangeEventMatches,
+          signal,
+          source: {
+            reauthorizeTargets: async (sessionIds) => {
+              for (const targetSessionId of sessionIds) {
+                await authorizeFirstPartySession(
+                  deps,
+                  grant,
+                  targetSessionId,
+                  "session.events.read",
+                );
+              }
             },
-          }),
-        );
+            readTargetEvents: async (target) => {
+              const page = await listSessionEventPage(deps.db, workspaceId, target.sessionId, {
+                after: target.afterSequence,
+                direction: "after",
+                limit: SESSION_WAIT_EVENTS_PER_TARGET,
+                payloadMode: "full",
+                includeTypes: targetEventTypes,
+                // Progress notes must not fill the page ahead of the outcome.
+                excludeStreamedAssistantMessages: waitFor !== "completion",
+                maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
+              });
+              if (!page.fullPayloadsExact) {
+                for (const event of page.events) incompleteWaitEvents.add(event.id);
+              }
+              return { events: page.events, hasMore: page.hasMore };
+            },
+            readOwnPendingUpdateKinds:
+              ownSessionId === null
+                ? null
+                : async () =>
+                    (await listOwnPendingUpdates(ownSessionId)).map((update) => update.kind),
+            subscribe: (targetSessionId, onEvents) =>
+              deps.bus.subscribe(workspaceId, targetSessionId, onEvents),
+          },
+        });
+        if (!result.aborted && !result.truncated) {
+          const consumed = result.changed.map((target) => ({
+            sessionId: target.sessionId,
+            sequences: target.events
+              .filter((event) => event.contentComplete && !incompleteWaitEvents.has(event.id))
+              .map((event) => event.sequence),
+          }));
+          await acknowledgeReads(consumed);
+          await recordConsumedChildResults(consumed, extra);
+          if (result.ownPendingUpdates > 0 && ownSessionId !== null) {
+            // The returned answer may be the pending input this result
+            // counted; report what is still pending so the caller is not told
+            // to end its turn only to receive the answer it already has.
+            const pending = await listOwnPendingUpdates(ownSessionId);
+            if (pending.length !== result.ownPendingUpdates) {
+              return json(
+                withOwnPendingUpdateKinds(
+                  result,
+                  pending.map((update) => update.kind),
+                ),
+              );
+            }
+          }
+        }
+        return json(result);
       },
     );
 
@@ -4723,7 +5816,7 @@ function registerWorkspaceOrchestrationTools(
         server.registerTool(
           toolName,
           {
-            description: `${toolName === "command_read" ? "Read retained output immediately, or briefly wait" : "Briefly wait using the same read operation as command_read"} for one command owned by the current session, across sandbox and Connected Machine providers. Returns bounded stdout/stderr chunks, durable state and exitCode, nextCursor and hasMore, plus explicit retention limitations. Pass nextCursor to continue; output remains readable after the process exits. A terminal read observes completion and suppresses only its still-pending inbox notification; running reads and already claimed history are unchanged. waitSeconds is at most 50; command_wait defaults to 45, command_read to 0. For long waits use wait_for_input. Neither tool sends stdin or cancels the command.`,
+            description: `${toolName === "command_read" ? "Read retained output immediately, or briefly wait" : "Briefly wait using the same read operation as command_read"} for one command owned by the current session, across sandbox and Connected Machine providers. Returns bounded stdout/stderr chunks, durable state and exitCode, nextCursor and hasMore, plus explicit retention limitations. Pass nextCursor to continue; output remains readable after the process exits. A terminal read observes completion and suppresses only its still-pending inbox notification; running reads and already claimed history are unchanged. waitSeconds is at most 50; command_wait defaults to 45, command_read to 0. These execution-wait limits do not cap wait_for_input: use it for long out-of-turn waits, except pending Codemode calls require observation in the same live attempt. Neither tool sends stdin or cancels the command.`,
             inputSchema: {
               commandId: z4.string().uuid(),
               cursor: z4.string().max(128).optional(),
@@ -4770,131 +5863,15 @@ function registerWorkspaceOrchestrationTools(
   }
 
   if (can("sessions:create") && sessionCreateVisible) {
-    const sessionCreateInput = z4
-      .object({
-        initialMessage: z4.string().min(1),
-        projectId: z4
-          .string()
-          .uuid()
-          .nullable()
-          .optional()
-          .describe(
-            "Workspace project to file the new session into. Omit for existing default behavior; does not change runtime or visibility.",
-          ),
-        title: z4
-          .string()
-          .min(1)
-          .max(SESSION_TITLE_MAX_CHARACTERS)
-          .optional()
-          .describe(
-            "Concise semantic title for the child session. Omit only when the delegated goal or initial message already provides a suitable title; OpenGeni derives a sensitive-safe bounded fallback from that text.",
-          ),
-        instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
-        goal: GoalSpec.optional(),
-        resources: z4
-          .array(z4.unknown())
-          .optional()
-          .describe(
-            "Omit to inherit parent repositories only. Files are never inherited automatically; explicitly include file resources to attach them. An empty array inherits no resources.",
-          ),
-        tools: z4.array(z4.unknown()).optional(),
-        mcpServers: z4.array(z4.unknown()).optional(),
-        variableSetId: z4.string().uuid().optional(),
-        variableSetIds: z4.array(z4.string().uuid()).max(MAX_SELECTED_VARIABLE_SETS).optional(),
-        environmentId: z4.string().uuid().optional(),
-        rigId: z4.string().uuid().optional(),
-        model: z4
-          .string()
-          .min(1)
-          .optional()
-          .describe(
-            "Model for the worker. Omit to inherit the exact calling turn's model, including its Codex subscription billing path.",
-          ),
-        reasoningEffort: z4
-          .string()
-          .optional()
-          .describe("Omit to inherit the exact calling turn's reasoning effort."),
-        latencyMode: z4
-          .enum(["standard", "priority", "fast"])
-          .optional()
-          .describe("Omit to inherit the exact calling turn's latency mode."),
-        sandboxBackend: z4.string().optional(),
-        // Model-only structural coupling: workingDir cannot exist without a
-        // targetSandboxId because both live inside one optional object. The
-        // handler maps this back to the stable public REST/SDK request fields.
-        machineTarget: z4
-          .object({
-            targetSandboxId: z4.string().uuid(),
-            workingDir: z4.string().optional(),
-          })
-          .strict()
-          .optional(),
-        metadata: z4.record(z4.string(), z4.unknown()).optional(),
-        idempotencyKey: z4.string().min(1).max(200).optional(),
-        firstPartyMcpPermissions: z4
-          .array(z4.string())
-          .optional()
-          .describe(
-            "Optional first-party capability set for the child. Omit to inherit this session's effective permissions. An explicit set may only narrow capabilities held by this session. A goal-bearing child requires goals:manage in the resulting set; creation fails rather than adding it implicitly.",
-          ),
-        firstPartyMcpTools: z4
-          .array(z4.enum(FIRST_PARTY_MCP_TOOL_NAMES))
-          .optional()
-          .describe(
-            "Exact model-visible first-party tool selection for the child. Omit to inherit this session's effective selection. An explicit selection may only narrow that selection: every listed tool must already be available to this session, and a wider list is rejected. To create a non-delegating leaf, provide a selection that omits session_create. This does not grant permissions.",
-          ),
-        // The child's agent-access scope and end-user label are never model
-        // choices: it inherits this session's exactly. Only the Memory
-        // selector may be narrowed here (workspace > user > off).
-        memoryScope: z4
-          .enum(["workspace", "user", "off"])
-          .optional()
-          .describe(
-            "Optional Memory selector for the child. Omit to inherit this session's selector. An explicit value may only narrow it (workspace > user > off); off gives the child no Memory tools. Use task notes for task-local findings.",
-          ),
-        // Omission is the ordinary safe sharing path. Literal "shared" remains
-        // available to advanced REST/SDK callers but is intentionally absent
-        // from the model surface because it turns compatibility drift into a
-        // deterministic failure instead of the omission path's safe own-box fallback.
-        sandbox: z4
-          .union([z4.literal("new"), z4.object({ groupId: z4.string().uuid() })])
-          .optional(),
-      })
-      .superRefine((value, context) => {
-        if (!value.variableSetIds) return;
-        if (new Set(value.variableSetIds).size !== value.variableSetIds.length) {
-          context.addIssue({
-            code: z4.ZodIssueCode.custom,
-            path: ["variableSetIds"],
-            message: "variableSetIds must not contain duplicates",
-          });
-        }
-        const singular = value.variableSetId ?? value.environmentId;
-        if (singular === undefined) return;
-        const expected = value.variableSetIds[value.variableSetIds.length - 1];
-        if (singular !== expected) {
-          context.addIssue({
-            code: z4.ZodIssueCode.custom,
-            path: ["variableSetId"],
-            message: "variableSetId must match the last variableSetIds entry",
-          });
-        }
-      })
-      .strict();
     server.registerTool(
       "session_create",
       {
         description:
-          "Spawn a new agent session (a worker) only for a concrete, bounded subtask that can run independently and has a defined integration point in your current work. Do not delegate work you will also perform yourself; track the child and join its actual result before completing dependent work. Give the child a concise semantic title; if omitted, OpenGeni derives one from its delegated goal or initial message. The child inherits this session's visibility, agent-access scope and end-user label; a private session can only create a same-owner private child, and memoryScope may only narrow this session's selector. Give a goal-bearing child its delegated objective. Its goal.rootConstraints may be an exact applicable subset of this accepted turn's frozen root constraints; omit that field to inherit all of them. Omit sandbox for the safe default: compatible children share the creator's box, while a different Variable Set, Rig, or machineTarget gets its own box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget; a machineTarget is always an own-box create even when the parent is backend none. To create a non-delegating leaf, pass a narrowed firstPartyMcpTools list that omits session_create; do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
-        inputSchema: sessionCreateInput,
+          "Spawn a new agent session (a worker) only for a concrete, bounded subtask that can run independently and has a defined integration point in your current work. Delegation has setup and coordination overhead: by default, answer directly when the work takes only a few steps, and send a related follow-up to a worker you already spawned with session_send_message instead of spawning another. Explicit user requests and applicable Skill guidance for delegation, independent review, or fresh workers override that default within existing authority. After spawning work that needs minutes, once nothing else can advance, call wait_for_input and end the turn instead of alternating session_wait and session_get; no preliminary short wait or status recheck is required. The worker's terminal result wakes you and carries its final answer (payload.finalAnswer). Do not duplicate a child's implementation; independent review or comparison may intentionally examine the same subject with a distinct deliverable. Track the child and join its actual result before completing dependent work. Give the child a concise semantic title; if omitted, Opengeni derives one from its delegated goal or initial message. The child inherits this session's visibility, agent-access scope and end-user label; a private session can only create a same-owner private child, and memoryScope may only narrow this session's selector. Give a goal-bearing child its delegated objective. Its goal.rootConstraints may be an exact applicable subset of this accepted turn's frozen root constraints; omit that field to inherit all of them. Omit sandbox for the safe default: compatible children share the creator's box, while a different Sandbox Environment or machineTarget gets its own box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget; a machineTarget is always an own-box create even when the parent is backend none. Normally omit tools, mcpServers, and firstPartyMcpTools so the worker inherits this session's exact selections; specialize its task through initialMessage rather than a hand-written partial tool list. To create a worker that cannot start, message, or follow other sessions, use agent: { capabilities: { from: 'all', subagents: false } } and keep tool lists omitted; its final answer still reaches you automatically. Explicit tool arrays replace the inherited selection and are only for deliberate restrictions. Do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
+        inputSchema: sessionCreateToolInput(childSelectableTools),
       },
       async (args) => {
         try {
-          requireVariableSetsUseForMcpAttachments(grant, {
-            variableSetIds: args.variableSetIds,
-            variableSetId: args.variableSetId,
-            environmentId: args.environmentId,
-          });
           if (callerSessionId !== null) {
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
           }
@@ -4926,7 +5903,7 @@ function registerWorkspaceOrchestrationTools(
           );
           return json(sessionCreateMutationReceipt(result, Boolean(request.idempotencyKey)));
         } catch (error) {
-          return orchestrationFailureResult("session_create", error);
+          return orchestrationFailureResult("session_create", error, deps, grant);
         }
       },
     );
@@ -4937,14 +5914,14 @@ function registerWorkspaceOrchestrationTools(
       "session_send_message",
       {
         description:
-          "Acceptance is not execution. Keep resource.id: for agent messages, match that ID in payload.updateIds from session_events view=debug, includeTypes=[system.update.delivered], payloadMode=full; retain the event turnId and read its relevant result. An unrelated in-flight turn completing does not prove delivery. Do not resend an unconsumed message; inspect blockers. Worker messages are coalescible machine input, added to history when claimed. Sessionless operator calls append a human/API prompt and resource.id is its turn ID. Use your last consumed event sequence. Report stalled delivery if it cannot safely progress.",
+          "To continue related work, by default message a worker you already spawned instead of spawning a new one; it keeps its context. Acceptance is not execution. Keep resource.id: for agent messages, match that ID in payload.updateIds from session_events view=debug, includeTypes=[system.update.delivered], payloadMode=full; retain the event turnId and read its relevant result. An unrelated in-flight turn completing does not prove delivery. Explicit user requests and applicable Skill guidance for independent review or fresh workers override that default within existing authority. Do not resend an unconsumed message; inspect blockers. Worker messages are coalescible machine input, added to history when claimed. Sessionless operator calls append a human/API prompt and resource.id is its turn ID. Use your last consumed event sequence. Report stalled delivery if it cannot safely progress.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           text: z4.string().min(1),
           idempotencyKey: z4.string().uuid(),
           // Header-value rotation only. URL/name/tool settings are immutable
           // after create; core enforces mcp_servers:attach on this field.
-          mcpCredentialUpdates: z4.array(z4.unknown()).optional(),
+          mcpCredentialUpdates: z4.array(SessionMcpCredentialUpdateInput).optional(),
         },
       },
       async ({ sessionId: targetSessionId, text, idempotencyKey, mcpCredentialUpdates }) => {
@@ -5031,7 +6008,7 @@ function registerWorkspaceOrchestrationTools(
             }),
           );
         } catch (error) {
-          return orchestrationFailureResult("session_send_message", error);
+          return orchestrationFailureResult("session_send_message", error, deps, grant);
         }
       },
     );
@@ -5187,33 +6164,37 @@ function registerWorkspaceOrchestrationTools(
           },
         },
         async ({ sessionId, instruction, idempotencyKey }) => {
-          const result = await steerAgentSession(
-            deps,
-            exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
-            { targetSessionId: sessionId, instruction, idempotencyKey },
-          );
-          return json(
-            mcpMutationReceipt({
-              operation: "session_steer",
-              committed: true,
-              outcome: result.replay ? "replayed" : "updated",
-              changed: !result.replay,
-              resource: {
-                type: "session_system_update",
-                id: result.updateId,
-                state: result.effectiveState,
-              },
-              relatedResources: [{ type: "session", id: sessionId }],
-              timestamp: result.receipt.createdAt.toISOString(),
-              idempotency: { status: result.replay ? "replayed" : "applied" },
-              facts: {
-                interruptionCount: result.interruptionCount,
-                stoppingPreviousAttempt: result.interruptionCount > 0,
-              },
-              updateId: result.updateId,
-              nextAction: { tool: "session_get", arguments: { sessionId } },
-            }),
-          );
+          try {
+            const result = await steerAgentSession(
+              deps,
+              exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
+              { targetSessionId: sessionId, instruction, idempotencyKey },
+            );
+            return json(
+              mcpMutationReceipt({
+                operation: "session_steer",
+                committed: true,
+                outcome: result.replay ? "replayed" : "updated",
+                changed: !result.replay,
+                resource: {
+                  type: "session_system_update",
+                  id: result.updateId,
+                  state: result.effectiveState,
+                },
+                relatedResources: [{ type: "session", id: sessionId }],
+                timestamp: result.receipt.createdAt.toISOString(),
+                idempotency: { status: result.replay ? "replayed" : "applied" },
+                facts: {
+                  interruptionCount: result.interruptionCount,
+                  stoppingPreviousAttempt: result.interruptionCount > 0,
+                },
+                updateId: result.updateId,
+                nextAction: { tool: "session_get", arguments: { sessionId } },
+              }),
+            );
+          } catch (error) {
+            return orchestrationFailureResult("session_steer", error, deps, grant);
+          }
         },
       );
 
@@ -5225,22 +6206,47 @@ function registerWorkspaceOrchestrationTools(
           inputSchema: {
             sessionId: z4.string().uuid(),
             requestId: z4.string().uuid(),
-            response: z4.unknown(),
+            response: SubmitHumanInputResponseRequest,
             idempotencyKey: z4.string().uuid(),
           },
         },
         async ({ sessionId, requestId, response, idempotencyKey }) => {
           await authorizeFirstPartySession(deps, grant, sessionId, "session.human_input.write");
           const context = exactAgentCommandContext(grant, callerSessionId, "first_party_mcp");
-          const parsedResponse = SubmitHumanInputResponseRequest.parse(response);
+          // Secret questions take a {{secret:...}} reference in `values` or a
+          // generate spec in secretAnswers; a raw value is refused (AC-7).
+          const { response: parsedResponse, secretAnswers: rawSecretAnswers } = splitSecretAnswers(
+            SubmitHumanInputResponseRequest.parse(response),
+            undefined,
+          );
           let accepted: Awaited<ReturnType<typeof acceptSessionHumanInputResponse>>;
           try {
+            const secretAnswers = prepareSecretAnswers(deps.settings, rawSecretAnswers, "agent");
+            if (secretAnswers.some((answer) => answer.saveTo === "user")) {
+              throw new SecretAnswerRejectedError(
+                "An agent cannot save to Only me; use saveTo task or workspace.",
+              );
+            }
             accepted = await acceptSessionHumanInputResponse(deps.db, {
               accountId: grant.accountId,
               workspaceId: grant.workspaceId,
               sessionId,
               requestId,
               response: parsedResponse,
+              ...(secretAnswers.length
+                ? {
+                    secretAnswers,
+                    secretWriteContext: attemptSecretWriteContext({
+                      kind: "attempt",
+                      accountId: grant.accountId,
+                      workspaceId: grant.workspaceId,
+                      sessionId: context.callerSessionId,
+                      turnId: context.callerTurnId,
+                      attemptId: context.callerAttemptId,
+                      executionGeneration: context.callerExecutionGeneration,
+                    }),
+                  }
+                : {}),
               respondedBy: `agent_attempt:${context.callerAttemptId}`,
               respondedByKind: "agent_attempt",
               clientEventId: idempotencyKey,
@@ -5249,6 +6255,18 @@ function registerWorkspaceOrchestrationTools(
             if (error instanceof HumanInputResponseValidationError) {
               throw new Error(`human-input response rejected: ${error.message}`, { cause: error });
             }
+            if (error instanceof SecretAnswerRejectedError) {
+              throw new Error(`human-input response rejected: ${error.message}`, { cause: error });
+            }
+            const vaultError = isVaultError(error) ? error : vaultErrorFromDatabase(error);
+            if (vaultError) {
+              throw new Error(
+                `human-input response rejected: ${vaultError.code}: ${vaultError.message}`,
+                {
+                  cause: error,
+                },
+              );
+            }
             throw error;
           }
           if (accepted.action === "not_found") {
@@ -5318,6 +6336,45 @@ function registerWorkspaceOrchestrationTools(
         });
       },
     );
+
+    server.registerTool(
+      "session_set_model",
+      {
+        description:
+          "Set an existing session's model and reasoning defaults for future turns. Use a model from list_models and specify the intended reasoning effort. Does not send a message, resume a paused session, wake an idle session, change latency mode, or rewrite already accepted turns/scheduled occurrences. Older queued turns keep their settings but cannot undo this choice when they start. Reuse the exact idempotencyKey for retries; session_get detail=full reads current effective defaults. Requires sessions:control and ordinary target-session authorization.",
+        inputSchema: {
+          sessionId: z4.string().uuid(),
+          model: z4.string().min(1).max(512),
+          reasoningEffort: z4.enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"]),
+          idempotencyKey: z4.string().uuid(),
+        },
+      },
+      async ({ sessionId, ...request }) => {
+        const result = await setSessionModel(deps, grant, sessionId, request, "first_party_mcp");
+        return json(
+          mcpMutationReceipt({
+            operation: "session_set_model",
+            committed: true,
+            outcome: result.replay ? "replayed" : "updated",
+            changed: !result.replay,
+            resource: { type: "session", id: sessionId },
+            relatedResources: [
+              { type: "session_command_receipt", id: result.receiptId },
+              { type: "session_event", id: result.eventId },
+            ],
+            timestamp: result.timestamp,
+            idempotency: { status: result.replay ? "replayed" : "applied" },
+            facts: {
+              model: result.model,
+              reasoningEffort: result.reasoningEffort,
+              latencyMode: result.latencyMode,
+              effectiveFrom: result.effectiveFrom,
+            },
+            nextAction: { tool: "session_get", arguments: { sessionId, detail: "full" } },
+          }),
+        );
+      },
+    );
   }
 }
 
@@ -5356,340 +6413,93 @@ function registerProjectTools(
     );
   }
   if (can("sessions:create")) {
-    server.registerTool(
-      "project_create",
-      {
-        description:
-          "Create a workspace-shared sidebar group for related sessions. A project is organizational metadata, not a repository, working directory, or inherited agent configuration.",
-        inputSchema: { name: nameSchema, description: descriptionSchema.optional() },
-      },
-      async ({ name, description }) =>
-        json({
-          project: await createChannel(deps.db, {
-            accountId: grant.accountId,
-            workspaceId: grant.workspaceId,
-            name,
-            description: description ?? null,
-            createdBy: grant.subjectId,
-          }),
-        }),
-    );
-    server.registerTool(
-      "project_update",
-      {
-        description:
-          "Rename, describe or pin/unpin a workspace project. Pin state is shared by everyone in the workspace. Omitted fields stay unchanged; null clears the description.",
-        inputSchema: {
-          projectId: projectIdSchema,
-          name: nameSchema.optional(),
-          description: descriptionSchema.nullable().optional(),
-          pinned: z4.boolean().optional(),
-        },
-      },
-      async ({ projectId, ...update }) => {
-        const project = await updateChannel(deps.db, grant.workspaceId, projectId, update);
-        if (!project) throw new Error("Project not found");
-        return json({ project });
-      },
-    );
-    server.registerTool(
-      "project_reorder",
-      {
-        description:
-          "Replace the shared sidebar project order. Pass every current project ID exactly once, from project_list. Pinned projects still appear first. If projects changed, list again before retrying.",
-        inputSchema: { projectIds: z4.array(projectIdSchema).min(1).max(200) },
-      },
-      async ({ projectIds }) => {
-        const projects = await reorderChannels(deps.db, grant.workspaceId, projectIds);
-        if (!projects)
-          throw new Error("Projects changed or order is invalid; call project_list and retry");
-        return json({ projects });
-      },
-    );
-    server.registerTool(
-      "project_delete",
-      {
-        description:
-          "Delete a workspace-shared project. Its sessions are preserved and become unfiled; no running work is stopped.",
-        inputSchema: { projectId: projectIdSchema },
-      },
-      async ({ projectId }) => {
-        if (!(await deleteChannel(deps.db, grant.workspaceId, projectId)))
-          throw new Error("Project not found");
-        return json({ ok: true, projectId });
-      },
-    );
-  }
-  if (can("sessions:control")) {
-    server.registerTool(
-      "session_set_project",
-      {
-        description:
-          "File a session into a workspace project, or pass projectId=null to unfile it. Projects group root sessions in the user's sidebar. Filing changes organization only, not visibility, instructions, runtime, or history.",
-        inputSchema: { sessionId: z4.string().uuid(), projectId: projectIdSchema.nullable() },
-      },
-      async ({ sessionId, projectId }) => {
-        await authorizeFirstPartySession(deps, grant, sessionId, "session.control");
-        await requireSession(deps.db, grant.workspaceId, sessionId);
-        if (
-          !(await setSessionChannel(deps.db, {
-            workspaceId: grant.workspaceId,
-            sessionId,
-            channelId: projectId,
-          }))
-        )
-          throw new Error("Session not found");
-        return json({ ok: true, sessionId, projectId });
-      },
-    );
-  }
-}
-
-// Variable-set management for agents. Generic reads remain metadata-only.
-// Plaintext has one dedicated tool that additionally requires literal
-// secrets:read plus exact live attempt/session authorization.
-function registerVariableSetTools(
-  server: McpServer,
-  deps: ApiRouteDeps,
-  grant: AccessGrant,
-  can: (permission: Permission) => boolean,
-  sessionId: string | null,
-  json: JsonResult,
-): void {
-  const variableSetAccess = {
-    accountId: grant.accountId,
-    workspaceId: grant.workspaceId,
-    subjectId: grant.subjectId,
-  };
-  const registerListTool = (name: string, description: string): void => {
-    server.registerTool(
-      name,
-      {
-        description,
-        inputSchema: {},
-      },
-      async () => {
-        const variableSets = await listVariableSets(deps.db, variableSetAccess);
-        return json({ variableSets, environments: variableSets });
-      },
-    );
-  };
-  const setVariableHandler =
-    (operation: "variable_set_set_variable" | "environment_set_variable") =>
-    async ({
-      variableSetId,
-      variableSetName,
-      environmentId,
-      environmentName,
-      name,
-      value,
-    }: {
-      variableSetId?: string | undefined;
-      variableSetName?: string | undefined;
-      environmentId?: string | undefined;
-      environmentName?: string | undefined;
-      name: string;
-      value: string;
-    }) => {
-      const key = requireVariableSetEncryption(deps.settings);
-      const parsedName = VariableSetVariableName.safeParse(name);
-      if (!parsedName.success) {
-        throw new Error("variable set/environment variable names must match ^[A-Z][A-Z0-9_]*$");
-      }
-      assertAllowedVariableSetVariableName(parsedName.data);
-      const targetId = variableSetId ?? environmentId;
-      const targetName = variableSetName ?? environmentName;
-      if ((targetId === undefined) === (targetName === undefined)) {
-        throw new Error(
-          "provide exactly one of variableSetId or variableSetName; deprecated aliases must provide exactly one of environmentId or environmentName",
-        );
-      }
-      const trimmedVariableSetName = targetName?.trim();
-      if (targetName !== undefined && !trimmedVariableSetName) {
-        throw new Error("variable set name is required");
-      }
-      let created = false;
-      let variableSet =
-        targetId !== undefined
-          ? await getVariableSet(deps.db, variableSetAccess, targetId)
-          : await getVariableSetByName(deps.db, variableSetAccess, trimmedVariableSetName!);
-      if (!variableSet && targetId !== undefined) {
-        throw new Error("variable set/environment not found");
-      }
-      if (!variableSet) {
-        if (
-          (await countVariableSets(deps.db, variableSetAccess)) >= MAX_ENVIRONMENTS_PER_WORKSPACE
-        ) {
-          throw new Error(
-            `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
-          );
-        }
-        variableSet = await createVariableSet(deps.db, {
-          accountId: grant.accountId,
-          workspaceId: grant.workspaceId,
-          scope: "workspace",
-          subjectId: grant.subjectId,
-          name: trimmedVariableSetName!,
-        });
-        created = true;
-        await recordVariableSetAuditEvent(deps.db, {
-          grant,
-          action: "variable_set.created",
-          variableSetId: variableSet.id,
-        });
-      }
-      const exists = variableSet.variables.some((variable) => variable.name === parsedName.data);
-      if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
-        throw new Error(
-          `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables`,
-        );
-      }
-      const metadata = await setVariableSetVariable(deps.db, {
-        accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
-        subjectId: grant.subjectId,
-        variableSetId: variableSet.id,
-        name: parsedName.data,
-        valueEncrypted: encryptVariableSetValue(key, value),
-      });
-      await recordVariableSetAuditEvent(deps.db, {
-        grant,
-        action: "variable_set.variable.set",
-        variableSetId: variableSet.id,
-        variableName: parsedName.data,
-      });
-      return json(
-        mcpMutationReceipt({
-          operation,
-          committed: true,
-          outcome: exists ? "updated" : "created",
-          changed: true,
-          resource: {
-            type: "variable_set",
-            id: variableSet.id,
-            version: metadata.version,
-            state: "variable_written",
-          },
-          timestamp: metadata.updatedAt,
-          idempotency: { status: "not_supported" },
-          facts: {
-            variableCreated: !exists,
-            variableSetCreated: created,
-            deprecatedAlias: operation === "environment_set_variable",
-          },
-          nextAction: { tool: "variable_set_list", arguments: {} },
+    server.registerTool(
+      "project_create",
+      {
+        description:
+          "Create a workspace-shared sidebar group for related sessions. A project is organizational metadata, not a repository, working directory, or inherited agent configuration.",
+        inputSchema: { name: nameSchema, description: descriptionSchema.optional() },
+      },
+      async ({ name, description }) =>
+        json({
+          project: await createChannel(deps.db, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            name,
+            description: description ?? null,
+            createdBy: grant.subjectId,
+          }),
         }),
-      );
-    };
-  const registerSetTool = (
-    name: "variable_set_set_variable" | "environment_set_variable",
-    description: string,
-  ): void => {
+    );
     server.registerTool(
-      name,
+      "project_update",
       {
-        description,
+        description:
+          "Rename, describe or pin/unpin a workspace project. Pin state is shared by everyone in the workspace. Omitted fields stay unchanged; null clears the description.",
         inputSchema: {
-          variableSetId: z4.string().uuid().optional(),
-          variableSetName: z4.string().min(1).optional(),
-          environmentId: z4.string().uuid().optional(),
-          environmentName: z4.string().min(1).optional(),
-          name: z4.string().min(1),
-          value: z4.string().min(1).max(32768),
+          projectId: projectIdSchema,
+          name: nameSchema.optional(),
+          description: descriptionSchema.nullable().optional(),
+          pinned: z4.boolean().optional(),
         },
       },
-      setVariableHandler(name),
+      async ({ projectId, ...update }) => {
+        const project = await updateChannel(deps.db, grant.workspaceId, projectId, update);
+        if (!project) throw new Error("Project not found");
+        return json({ project });
+      },
     );
-  };
-  if (can("variable-sets:list") && can("secrets:list")) {
-    registerListTool(
-      "variable_set_list",
-      "List variable sets with variable names and metadata (versions, timestamps). Plaintext values are never returned by list operations.",
+    server.registerTool(
+      "project_reorder",
+      {
+        description:
+          "Replace the shared sidebar project order. Pass every current project ID exactly once, from project_list. Pinned projects still appear first. If projects changed, list again before retrying.",
+        inputSchema: { projectIds: z4.array(projectIdSchema).min(1).max(200) },
+      },
+      async ({ projectIds }) => {
+        const projects = await reorderChannels(deps.db, grant.workspaceId, projectIds);
+        if (!projects)
+          throw new Error("Projects changed or order is invalid; call project_list and retry");
+        return json({ projects });
+      },
     );
-    registerListTool(
-      "environment_list",
-      "(deprecated alias of variable_set_list) List variable sets with variable names and metadata (versions, timestamps). Plaintext values are never returned by list operations.",
+    server.registerTool(
+      "project_delete",
+      {
+        description:
+          "Delete a workspace-shared project. Its sessions are preserved and become unfiled; no running work is stopped.",
+        inputSchema: { projectId: projectIdSchema },
+      },
+      async ({ projectId }) => {
+        if (!(await deleteChannel(deps.db, grant.workspaceId, projectId)))
+          throw new Error("Project not found");
+        return json({ ok: true, projectId });
+      },
     );
   }
-
-  if (
-    sessionId !== null &&
-    can("variable-sets:read") &&
-    hasLiteralPermission(grant.permissions, "secrets:read")
-  ) {
+  if (can("sessions:control")) {
     server.registerTool(
-      "variable_set_get_variable",
+      "session_set_project",
       {
         description:
-          "Retrieve one exact plaintext variable value. This is a dedicated high-trust read: use it only when the current task requires the configured value. The access is audited against this exact live attempt.",
-        inputSchema: {
-          variableSetId: z4.string().uuid().optional(),
-          variableSetName: z4.string().min(1).max(120).optional(),
-          name: z4.string().min(1),
-        },
+          "File a session into a workspace project, or pass projectId=null to unfile it. Projects group root sessions in the user's sidebar. Filing changes organization only, not visibility, instructions, runtime, or history.",
+        inputSchema: { sessionId: z4.string().uuid(), projectId: projectIdSchema.nullable() },
       },
-      async ({ variableSetId, variableSetName, name }) => {
-        let target: { variableSetId: string } | { variableSetName: string };
-        if (variableSetId !== undefined) {
-          if (variableSetName !== undefined) {
-            throw new Error("provide exactly one of variableSetId or variableSetName");
-          }
-          target = { variableSetId };
-        } else {
-          if (variableSetName === undefined) {
-            throw new Error("provide exactly one of variableSetId or variableSetName");
-          }
-          target = { variableSetName };
-        }
+      async ({ sessionId, projectId }) => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.control");
+        await requireSession(deps.db, grant.workspaceId, sessionId);
         if (
-          ("variableSetId" in target && target.variableSetId.length === 0) ||
-          ("variableSetName" in target && target.variableSetName.trim().length === 0)
-        ) {
-          throw new Error("provide exactly one of variableSetId or variableSetName");
-        }
-        const parsedName = VariableSetVariableName.safeParse(name);
-        if (!parsedName.success) {
-          throw new Error("variable set variable names must match ^[A-Z][A-Z0-9_]*$");
-        }
-        assertAllowedVariableSetVariableName(parsedName.data);
-        const claims = exactAgentAttemptClaims(grant);
-        if (!claims || claims.sessionId !== sessionId) {
-          throw new Error("Exact signed secret-read attempt authority is required.");
-        }
-        await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
-        await authorizeFirstPartySession(deps, grant, sessionId, "session.secret.read");
-        const key = requireVariableSetEncryption(deps.settings);
-        const secret = await readVariableSetSecretAtomically(deps.db, {
-          accountId: grant.accountId,
-          workspaceId: grant.workspaceId,
-          subjectId: grant.subjectId,
-          ...target,
-          name: parsedName.data,
-          actor: {
-            kind: "agent_attempt",
-            sessionId: claims.sessionId,
-            turnId: claims.turnId,
-            attemptId: claims.attemptId,
-            executionGeneration: claims.executionGeneration,
-          },
-          decrypt: (valueEncrypted) => decryptVariableSetValue(key, valueEncrypted),
-        });
-        if (!secret) throw new Error("variable set variable not found");
-        return json(secret);
+          !(await setSessionChannel(deps.db, {
+            workspaceId: grant.workspaceId,
+            sessionId,
+            channelId: projectId,
+          }))
+        )
+          throw new Error("Session not found");
+        return json({ ok: true, sessionId, projectId });
       },
     );
   }
-
-  if (can("variable-sets:write") && can("secrets:write")) {
-    registerSetTool(
-      "variable_set_set_variable",
-      "Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to. Reading it requires the dedicated permissioned secret-read operation.",
-    );
-    registerSetTool(
-      "environment_set_variable",
-      "(deprecated alias of variable_set_set_variable) Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to. Reading it requires the dedicated permissioned secret-read operation.",
-    );
-  }
 }
 
 type CapabilitySetupProjection =
@@ -5708,6 +6518,8 @@ function registerCapabilityDiscoveryTools(
   sessionId: string,
   json: JsonResult,
 ): void {
+  const signedTools = grant.metadata?.["firstPartyMcpTools"];
+  const secretsSelected = Array.isArray(signedTools) && signedTools.includes("secret_search");
   const catalog = () =>
     buildCapabilityCatalog({
       db: deps.db,
@@ -5724,7 +6536,14 @@ function registerCapabilityDiscoveryTools(
   // This is a readiness projection, never credential resolution or a new grant.
   const setupProjections = async (items: CapabilityCatalogItem[]) => {
     const availableServerIds = new Set<string>();
-    if (items.some((item) => item.enabled && item.connectionRef?.subjectScope === "subject")) {
+    const availableFirstPartyTools = new Set<string>();
+    const acceptedServerIds = new Set<string>();
+    let accountSelectionKnown = false;
+    if (
+      items.some(
+        (item) => item.enabled && (item.connectionRef || item.surfaceType === "first_party_fiken"),
+      )
+    ) {
       const claims = exactAgentCommandContext(grant, sessionId);
       const attemptCatalog = await getAttemptToolCatalog(deps.db, {
         accountId: grant.accountId,
@@ -5736,12 +6555,35 @@ function registerCapabilityDiscoveryTools(
         attemptCatalog.turnId === claims.callerTurnId &&
         attemptCatalog.executionGeneration === claims.callerExecutionGeneration
       ) {
-        for (const entry of attemptCatalog.entries) availableServerIds.add(entry.identity.serverId);
+        for (const entry of attemptCatalog.entries) {
+          availableServerIds.add(entry.identity.serverId);
+          if (entry.identity.serverId === "opengeni")
+            availableFirstPartyTools.add(entry.identity.toolName);
+        }
+        const bindings = await getSessionTurnMcpAccountBindings(
+          deps.db,
+          grant.workspaceId,
+          sessionId,
+          claims.callerTurnId,
+        );
+        accountSelectionKnown = bindings !== null;
+        const readiness = capabilityAccountReadiness(availableServerIds, bindings);
+        for (const id of readiness.available) availableServerIds.add(id);
+        for (const id of readiness.accepted) acceptedServerIds.add(id);
       }
     }
     return await Promise.all(
       items.map((item) =>
-        capabilitySetupProjection(deps, grant.workspaceId, item, availableServerIds),
+        capabilitySetupProjection(
+          deps,
+          grant.workspaceId,
+          item,
+          availableServerIds,
+          acceptedServerIds,
+          accountSelectionKnown,
+          availableFirstPartyTools,
+          new Set((grant.metadata?.firstPartyMcpTools as string[] | undefined) ?? []),
+        ),
       ),
     );
   };
@@ -5750,7 +6592,7 @@ function registerCapabilityDiscoveryTools(
     "capability_catalog_search",
     {
       description:
-        "Search OpenGeni's reviewed workspace capability catalog when the user asks to add an integration or the task needs a capability that is not currently usable. Search by the outcome needed (for example `GitHub repositories`, `product analytics`, or `Slack notifications`), compare the returned candidates, and prefer a ready or verified exact match. This only reads secret-free metadata; it never installs, connects, or authorizes anything.",
+        "Find integrations in Opengeni's reviewed workspace catalog when the user asks to add one or needed access is missing. Search by integration name or task outcome; names are matched with typo tolerance, and a match with approximate: true matched only by a near spelling. Results describe setup status and provide setup.nextAction when human setup can be requested. Use available tools directly for ready candidates. When matches is empty, suggestions lists the closest catalog names: check whether one is what the user meant (or ask) before saying an integration does not exist. This reads metadata only and does not connect or authorize anything.",
       inputSchema: {
         query: z4.string().min(1).max(500),
         limit: z4.number().int().min(1).max(20).optional(),
@@ -5759,13 +6601,15 @@ function registerCapabilityDiscoveryTools(
     async ({ query, limit }) => {
       await authorize();
       const current = await catalog();
-      const ranked = searchCapabilityCatalogItems(
-        [...current.items, ...nativeConnectionCapabilityRecommendations()],
-        query,
-        limit ?? 8,
-      );
+      const candidates = [
+        ...current.items,
+        ...nativeConnectionCapabilityRecommendations({
+          connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+        }),
+      ];
+      const ranked = searchCapabilityCatalogItems(candidates, query, limit ?? 8);
       const setups = await setupProjections(ranked.map(({ item }) => item));
-      const matches = ranked.map(({ item, matchedOn }, index) => ({
+      const matches = ranked.map(({ item, matchedOn, approximate }, index) => ({
         capabilityId: item.id,
         name: item.name,
         description: item.description,
@@ -5777,12 +6621,40 @@ function registerCapabilityDiscoveryTools(
         authKind: item.authKind,
         tier: item.tier,
         matchedOn,
+        approximate,
         setup: {
           ...setups[index]!,
           requiredVariables: capabilityRequiredVariables(item),
+          nextAction:
+            setups[index]!.status === "authorization_required"
+              ? { toolName: "capability_authorization_request", capabilityId: item.id }
+              : null,
         },
       }));
-      return json({ query, matches });
+      // A miss must not read as "this integration does not exist" while the
+      // workspace catalog has entries: return the closest names, clearly
+      // labelled as suggestions rather than matches.
+      const suggestions =
+        matches.length === 0
+          ? suggestCapabilityCatalogItems(candidates, query, 5).map(({ item, similarity }) => ({
+              capabilityId: item.id,
+              name: item.name,
+              kind: item.kind,
+              source: item.source,
+              providerDomain: item.providerDomain,
+              similarity,
+            }))
+          : [];
+      return json({
+        query,
+        matches,
+        suggestions,
+        ...(suggestions.length > 0
+          ? {
+              note: "No catalog entry matched this query. suggestions are the closest names in this workspace catalog, not matches; check whether one is what the user meant before concluding the integration does not exist.",
+            }
+          : {}),
+      });
     },
   );
 
@@ -5790,7 +6662,10 @@ function registerCapabilityDiscoveryTools(
     "capability_authorization_request",
     {
       description:
-        "After capability_catalog_search and after explaining one chosen recommendation to the user, post exactly one in-session human authorization card for that catalog capability. This tool never grants access, enables a capability, reads a secret, or mints provider credentials; the authenticated user must click and confirm the provider/domain flow. Do not call it for a candidate reported ready or unavailable.",
+        "Show a Connect card in this chat for a suitable capability returned by capability_catalog_search with setup.nextAction. Supply its capability ID and a brief rationale explaining how it helps the task; no separate confirmation is needed before showing the card. Requesting setup needs no integration-management permission and grants no access. The authenticated human completes setup through the card; never ask them to paste credentials into chat. Do not request another card for the same pending setup, or for a candidate reported ready or unavailable. GitHub App (api:github-app) and Connected Machine (api:connected-machine) are exceptions: when already connected their card is still shown, listing repositories or machines the person can use in this chat. Use api:connected-machine when the person should connect their own computer: the card gives them a one-line connect command and the Opengeni Browser Chrome extension link; never paste an enroll token into the chat yourself." +
+        (secretsSelected
+          ? ' For a single password, API key or code for a service with no connector here, ask with a kind: "secret" question in request_human_input instead; you get a saved reference back.'
+          : ""),
       inputSchema: {
         capabilityId: z4.string().min(1).max(512),
         rationale: z4.string().min(1).max(2000),
@@ -5799,15 +6674,26 @@ function registerCapabilityDiscoveryTools(
     async ({ capabilityId, rationale }) => {
       await authorize();
       const current = await catalog();
-      const item = [...current.items, ...nativeConnectionCapabilityRecommendations()].find(
-        (candidate) => candidate.id === capabilityId,
-      );
+      const item = [
+        ...current.items,
+        ...nativeConnectionCapabilityRecommendations({
+          connectedMachines: deps.settings.sandboxSelfhostedEnabled,
+        }),
+      ].find((candidate) => candidate.id === capabilityId);
       if (!item || !capabilityCatalogItemIsTrustedForExposure(item)) {
         throw new Error("Unknown or untrusted capability; search the catalog again.");
       }
       const [setup] = await setupProjections([item]);
       if (!setup) throw new Error("Capability setup projection is unavailable.");
-      if (setup.status === "ready") {
+      // GitHub is the one capability whose card stays useful once connected:
+      // it lists the shared repositories with a "Use" action that attaches one
+      // to this chat, so a ready GitHub still gets its card.
+      const githubCardWhenReady = setup.status === "ready" && item.id === "api:github-app";
+      // The machine card likewise lists connected machines with "Use in this
+      // chat" and can connect another, so it is shown when machines exist too.
+      const machineCardWhenReady =
+        setup.status === "ready" && item.id === CONNECTED_MACHINE_CAPABILITY_ID;
+      if (setup.status === "ready" && !githubCardWhenReady && !machineCardWhenReady) {
         return json({
           capabilityId: item.id,
           status: "ready",
@@ -5821,22 +6707,147 @@ function registerCapabilityDiscoveryTools(
           message: setup.detail,
         });
       }
-      const claims = exactAgentCommandContext(grant, sessionId);
+      const eventId = await appendCapabilityCardEvent(deps, grant, sessionId, {
+        item,
+        action: setup.action ?? "connect",
+        rationale,
+      });
+      if (machineCardWhenReady) {
+        return json({
+          capabilityId: item.id,
+          status: "ready",
+          eventId,
+          message: `${setup.detail} The Connected Machine card is in this chat: the person can pick a machine with "Use in this chat" or connect another. Chrome needs the Opengeni Browser extension (${OPENGENI_BROWSER_EXTENSION_URL}) on a connected machine.`,
+        });
+      }
+      if (githubCardWhenReady) {
+        return json({
+          capabilityId: item.id,
+          status: "ready",
+          eventId,
+          message: `${setup.detail} The GitHub card is in this chat: the person picks a repository with its "Use" button, which attaches it to this chat.`,
+        });
+      }
+      return json({
+        capabilityId: item.id,
+        status: "authorization_requested",
+        action: setup.action,
+        eventId,
+        message:
+          item.id === CONNECTED_MACHINE_CAPABILITY_ID
+            ? "The Connected Machine card was posted. The person copies its connect command, runs it on their machine, and picks Use in this chat; nothing is connected yet. Do not paste an enroll token into the chat."
+            : "The recommendation was posted for human confirmation. No access has been granted yet.",
+      });
+    },
+  );
+
+  server.registerTool(
+    "custom_mcp_setup_request",
+    {
+      description:
+        "Prepare a remote HTTPS MCP connection when the person has the missing key. Search the catalog first and reuse available connections. Use only an endpoint supplied by the user or reliable documentation. For API-key or bearer auth, include explicit personal/workspace ownership and the complete non-secret mcpSetup (matching name and endpointUrl, fixed non-secret headers, secret references with any prefix/suffix, and labeled secret fields). The inline card asks only for those secret values; never put credentials in these tool arguments or chat. If you already have the key and delegated connections:read, connections:write and capabilities:manage, use environmentCodemodeClient().sessionRequest with the native /v1/workspaces/site-host/connect/attempts begin/advance lifecycle and the same mcpSetup; supply values only in that protected credential request, not a tool call. No human card is needed for that authorized path. Omit ownership/mcpSetup for a legacy server-review or OAuth setup. Posting this card does not contact or connect the server.",
+      inputSchema: {
+        name: z4.string().trim().min(1).max(256),
+        endpointUrl: z4
+          .string()
+          .url()
+          .max(2048)
+          .refine((url) => {
+            const parsed = new URL(url);
+            return (
+              parsed.protocol === "https:" &&
+              !parsed.username &&
+              !parsed.password &&
+              !parsed.hash &&
+              !parsed.search
+            );
+          }),
+        rationale: z4.string().trim().min(1).max(2000),
+        ownership: z4.enum(["personal", "workspace"]).optional(),
+        mcpSetup: z4
+          .object({
+            name: z4.string().trim().min(1).max(256),
+            endpointUrl: z4.string().url().max(2048),
+            headers: z4
+              .array(
+                z4.union([
+                  z4
+                    .object({
+                      name: z4.string().min(1).max(256),
+                      value: z4.string().min(1).max(16_384),
+                    })
+                    .strict(),
+                  z4
+                    .object({
+                      name: z4.string().min(1).max(256),
+                      secret: z4.string().min(1).max(64),
+                      prefix: z4.string().max(16_384).optional(),
+                      suffix: z4.string().max(16_384).optional(),
+                    })
+                    .strict(),
+                ]),
+              )
+              .min(1)
+              .max(32),
+            secretFields: z4
+              .array(
+                z4
+                  .object({
+                    id: z4.string().min(1).max(64),
+                    label: z4.string().min(1).max(256),
+                  })
+                  .strict(),
+              )
+              .max(32),
+          })
+          .strict()
+          .optional(),
+      },
+    },
+    async ({ name, endpointUrl, rationale, ownership, mcpSetup }) => {
+      await authorize();
       const payload = ToolAuthNeededPayload.parse({
-        serverId: item.runtime.mcpServerId ?? "opengeni",
-        toolName: "capability_authorization_request",
-        providerDomain: capabilityProviderDomain(item),
+        serverId: "opengeni",
+        toolName: "custom_mcp_setup_request",
+        providerDomain: new URL(endpointUrl).hostname,
         reason: "missing_connection",
-        capability: {
-          id: item.id,
-          name: item.name,
-          kind: item.kind,
-          source: item.source,
-          action: setup.action,
+        setupRequest: {
+          kind: "mcp",
+          name,
+          endpointUrl,
           rationale,
-          requiredVariables: capabilityRequiredVariables(item),
+          ...(ownership ? { ownership } : {}),
+          ...(mcpSetup ? { mcpSetup } : {}),
         },
       });
+      const current = await catalog();
+      const candidates = current.items.filter(
+        (item) => item.kind === "mcp" && item.endpointUrl === endpointUrl && !item.stale,
+      );
+      // Workspace is the default scope in public connection projections. Match
+      // scope before choosing a catalog entry; one endpoint can have both.
+      const existing = mcpSetup
+        ? candidates.find(
+            (item) =>
+              item.connectionRef &&
+              (item.connectionRef.subjectScope ?? "workspace") ===
+                (ownership === "personal" ? "subject" : "workspace"),
+          )
+        : candidates[0];
+      const setup =
+        existing?.enabled && mcpSetup ? (await setupProjections([existing]))[0] : undefined;
+      // A missing tool does not establish that the saved key is missing. Keep
+      // unknown discovery failures distinct from an actual connect request.
+      const reusablePrepared = setup && setup.status !== "authorization_required";
+      if (existing && (!mcpSetup || reusablePrepared)) {
+        return json({
+          status: "already_in_catalog",
+          capabilityId: existing.id,
+          ...(setup ? { setup } : {}),
+          message: "Use the catalog authorization flow for this server instead.",
+        });
+      }
+      const claims = exactAgentCommandContext(grant, sessionId);
       const appended = await appendAndPublishTurnEventsFenced(
         deps.db,
         deps.bus,
@@ -5848,17 +6859,14 @@ function registerCapabilityDiscoveryTools(
         [{ type: "tool.auth_needed", payload }],
       );
       if (!appended.accepted) {
-        throw new Error(
-          "The calling turn was replaced before the authorization request committed.",
-        );
+        throw new Error("The calling turn was replaced before the setup request committed.");
       }
       return json({
-        capabilityId: item.id,
-        status: "authorization_requested",
-        action: setup.action,
+        status: "setup_requested",
         eventId: appended.events[0]?.id ?? null,
-        message:
-          "The recommendation was posted for human confirmation. No access has been granted yet.",
+        message: mcpSetup
+          ? "The prepared connection card was posted. The person enters only the missing key in its protected fields. No server was added or contacted."
+          : "The human review card was posted. No server was added or contacted.",
       });
     },
   );
@@ -5869,7 +6877,87 @@ async function capabilitySetupProjection(
   workspaceId: string,
   item: CapabilityCatalogItem,
   availableServerIds: ReadonlySet<string>,
+  acceptedServerIds: ReadonlySet<string>,
+  accountSelectionKnown: boolean,
+  availableFirstPartyTools: ReadonlySet<string>,
+  selectedFirstPartyTools: ReadonlySet<string>,
 ): Promise<CapabilitySetupProjection> {
+  if (item.surfaceType === "first_party_onepassword") {
+    // 1Password is connected and its vaults linked in Settings > Secrets; the
+    // agent reaches linked vaults through secret references, not tools.
+    return item.enabled
+      ? {
+          status: "ready",
+          action: null,
+          detail:
+            "1Password is connected. Its linked vaults are available through secret references and the secrets tools.",
+        }
+      : {
+          status: "authorization_required",
+          action: "connect",
+          detail:
+            "Connect a 1Password service account and choose its vaults through the protected setup form.",
+        };
+  }
+  if (item.surfaceType === "first_party_fiken") {
+    if (!item.enabled || item.metadata.connectionStatus !== "active") {
+      return {
+        status: "authorization_required",
+        action: "connect",
+        detail:
+          item.metadata.connectionStatus === "needs_reauth"
+            ? "The workspace Fiken connection needs reconnection."
+            : "Connect Fiken through the protected setup form.",
+      };
+    }
+    const selected = FIRST_PARTY_MCP_TOOL_NAMES.filter(
+      (name) => name.startsWith("fiken_") && selectedFirstPartyTools.has(name),
+    );
+    if (selected.length === 0) {
+      return {
+        status: "authorization_required",
+        action: "enable",
+        detail:
+          "Fiken is connected, but its tools are not selected for this conversation. Ask the user to add its tools through the setup card, then send a new message.",
+      };
+    }
+    if (selected.some((name) => availableFirstPartyTools.has(name))) {
+      return {
+        status: "ready",
+        action: null,
+        detail: "Fiken is connected and has tools available in this turn.",
+      };
+    }
+    return {
+      status: "unavailable",
+      action: null,
+      detail:
+        "Fiken is connected, but its selected tools are unavailable in this execution. Check tool permissions and setup before retrying; reconnection is not required by this status.",
+    };
+  }
+  if (item.id === CONNECTED_MACHINE_CAPABILITY_ID) {
+    if (!deps.settings.sandboxSelfhostedEnabled) {
+      return {
+        status: "unavailable",
+        action: null,
+        detail: "Connected Machines are not enabled on this deployment.",
+      };
+    }
+    const enrolled = await listEnrollments(deps.db, workspaceId, { status: "active" });
+    if (enrolled.length > 0) {
+      return {
+        status: "ready",
+        action: null,
+        detail: "Machines are connected to this workspace; sandboxes_list shows which are online.",
+      };
+    }
+    return {
+      status: "authorization_required",
+      action: "connect",
+      detail:
+        "No machine is connected yet. The person copies a one-line connect command from the chat card and runs it on their machine.",
+    };
+  }
   if (item.id === "api:github-app" || item.surfaceType === "first_party_github") {
     const missing = githubAppMissingSettings(deps.settings);
     if (missing.length > 0) {
@@ -5909,7 +6997,7 @@ async function capabilitySetupProjection(
           detail: "A workspace admin must designate an authorized Codex Apps subscription.",
         };
   }
-  if (item.enabled && item.connectionRef?.subjectScope === "subject") {
+  if (item.enabled && item.connectionRef) {
     if (item.runtime.mcpServerId && availableServerIds.has(item.runtime.mcpServerId)) {
       return {
         status: "ready",
@@ -5917,11 +7005,22 @@ async function capabilitySetupProjection(
         detail: "This capability has tools available in this turn.",
       };
     }
+    if (
+      !accountSelectionKnown ||
+      (item.runtime.mcpServerId && acceptedServerIds.has(item.runtime.mcpServerId))
+    ) {
+      return {
+        status: "unavailable",
+        action: null,
+        detail:
+          "This integration's tools are unavailable in this execution. Check its connection or setup failure before requesting reconnection; missing tools alone do not establish an authorization failure.",
+      };
+    }
     return {
       status: "authorization_required",
       action: "connect",
       detail:
-        "This capability is enabled, but its personal account is not available in this turn. The account owner must review access using Use in this conversation, then send a new message. Shared conversations require acknowledgement that results are visible to workspace members.",
+        "This integration is enabled in the workspace, but no account was selected for this execution. Connect or select an account available to the sender, then send a new message.",
     };
   }
   if (item.enabled) {
@@ -5959,6 +7058,54 @@ async function capabilitySetupProjection(
   };
 }
 
+/**
+ * Post a capability Connect card in the calling turn. The card carries identity
+ * and rationale only; the authenticated person completes setup through it.
+ */
+async function appendCapabilityCardEvent(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+  input: {
+    item: CapabilityCatalogItem;
+    action: "connect" | "add_credentials" | "enable";
+    rationale: string;
+    toolName?: string;
+  },
+): Promise<string | null> {
+  const { item } = input;
+  const claims = exactAgentCommandContext(grant, sessionId);
+  const payload = ToolAuthNeededPayload.parse({
+    serverId: item.runtime.mcpServerId ?? "opengeni",
+    toolName: input.toolName ?? "capability_authorization_request",
+    providerDomain: capabilityProviderDomain(item),
+    reason: "missing_connection",
+    capability: {
+      id: item.id,
+      name: item.name,
+      kind: item.kind,
+      source: item.source,
+      action: input.action,
+      rationale: input.rationale,
+      requiredVariables: capabilityRequiredVariables(item),
+    },
+  });
+  const appended = await appendAndPublishTurnEventsFenced(
+    deps.db,
+    deps.bus,
+    grant.workspaceId,
+    sessionId,
+    claims.callerTurnId,
+    claims.callerExecutionGeneration,
+    claims.callerAttemptId,
+    [{ type: "tool.auth_needed", payload }],
+  );
+  if (!appended.accepted) {
+    throw new Error("The calling turn was replaced before the authorization request committed.");
+  }
+  return appended.events[0]?.id ?? null;
+}
+
 function capabilityRequiredVariables(item: CapabilityCatalogItem): string[] {
   const variableSet = item.metadata.variableSet;
   if (!variableSet || typeof variableSet !== "object" || Array.isArray(variableSet)) return [];
@@ -6047,44 +7194,6 @@ function registerGitHubConnectTool(
   );
 }
 
-// Defense-in-depth for invariant "agents cannot self-attach": the worker's
-// first-party delegated token must carry both exact attachment and use
-// permissions, so a token narrowed to only one cannot attach a variable set.
-// agents calling these MCP tools cannot attach a variable set.
-// Explicit detach (variableSetId: null) is also an attachment change and is
-// blocked the same way.
-function requireVariableSetsUseForMcpAttachment(
-  grant: AccessGrant,
-  variableSetId: string | null | undefined,
-): void {
-  if (variableSetId === undefined) return;
-  if (!hasPermission(grant.permissions, "variable-sets:attach")) {
-    throw new Error("missing permission: variable-sets:attach");
-  }
-  if (variableSetId !== null && !hasPermission(grant.permissions, "variable-sets:use")) {
-    throw new Error("missing permission: variable-sets:use");
-  }
-}
-
-function requireVariableSetsUseForMcpAttachments(
-  grant: AccessGrant,
-  selection: {
-    variableSetIds?: string[] | undefined;
-    variableSetId?: string | undefined;
-    environmentId?: string | undefined;
-  },
-): void {
-  const singular = selection.variableSetId ?? selection.environmentId;
-  const variableSetIds = selection.variableSetIds ?? (singular ? [singular] : undefined);
-  if (variableSetIds === undefined) return;
-  if (!hasPermission(grant.permissions, "variable-sets:attach")) {
-    throw new HTTPException(403, { message: "missing permission: variable-sets:attach" });
-  }
-  if (variableSetIds.length > 0 && !hasPermission(grant.permissions, "variable-sets:use")) {
-    throw new HTTPException(403, { message: "missing permission: variable-sets:use" });
-  }
-}
-
 /**
  * Project one allowlisted GitHub App repository into the resource an agent or
  * scheduled task attaches. Every listed repository is in the workspace
@@ -6095,25 +7204,7 @@ function requireVariableSetsUseForMcpAttachments(
 export function repositoryWithScheduledTaskResource(
   repository: GitHubRepository,
 ): GitHubRepository & { resource: ResourceRef } {
-  const uri = normalizedRepositoryUri(repository.cloneUrl);
-  return {
-    ...repository,
-    resource: {
-      kind: "repository",
-      uri,
-      ref: repository.defaultBranch,
-      provider: "github",
-      mountPath: defaultRepositoryMountPath(uri, "github"),
-      githubInstallationId: repository.installationId,
-      githubRepositoryId: repository.id,
-    },
-  };
-}
-
-function normalizedRepositoryUri(value: string): string {
-  const url = new URL(value);
-  const path = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
-  return `https://${url.host.toLowerCase()}/${path}.git`;
+  return { ...repository, resource: githubRepositoryResourceRef(repository) };
 }
 
 function boundedMcpLimit(limit: number | undefined): number {
@@ -6645,9 +7736,15 @@ async function withMcpEffectivePolicy(
   subjectId: string,
   session: Session,
 ): Promise<Session> {
-  const [workspaceServerIds, workspaceDefaultServerIds] = await Promise.all([
+  const [workspaceServerIds, workspaceDefaultServerIds, effectiveToolsContext] = await Promise.all([
     workspaceSessionToolPolicyServerIds(deps.db, workspaceId, deps.settings, subjectId),
     workspaceSessionToolPolicyDefaultServerIds(deps.db, workspaceId, deps.settings, subjectId),
+    workspaceSessionEffectiveToolsContext(deps, workspaceId, subjectId, [session]),
   ]);
-  return sessionWithEffectiveToolPolicy(session, workspaceServerIds, workspaceDefaultServerIds);
+  return sessionWithEffectiveToolPolicy(
+    session,
+    workspaceServerIds,
+    workspaceDefaultServerIds,
+    effectiveToolsContext,
+  );
 }