clay-server 4.0.0-beta.13 → 4.0.0-beta.15

package/lib/server-home-chat.js

@@ -10,6 +10,7 @@ var attachHomeDebates = require("./server-home-debates").attachHomeDebates, atta
 var homeChatEvents = require("./server-home-chat-events");
 var homeCapsuleCreation = require("./server-home-capsule-creation");
 var sessionTitlePolicy = require("./session-title-policy");
+var sessionProvenance = require("./session-provenance");
 var historyToHomeChat = homeChatEvents.historyToHomeChat;
 var transformEvent = homeChatEvents.transformEvent;
 function attachHomeChat(deps) {
@@ -83,8 +84,14 @@ function attachHomeChat(deps) {
     var sessionManager = found.ctx.getSessionManager();
     if (!sessionManager) return [];
     var result = [];
+    var visibleSessions = [];
     sessionManager.sessions.forEach(function (session) {
       if (!ownsSession(session, userId)) return;
+      visibleSessions.push(session);
+    });
+    var hierarchy = sessionProvenance.hierarchyFor(visibleSessions);
+    for (var vi = 0; vi < visibleSessions.length; vi++) {
+      var session = visibleSessions[vi];
       if (sessionTitlePolicy.repairLegacySearchTitle(session)
           && typeof sessionManager.saveSessionFile === "function") {
         sessionManager.saveSessionFile(session);
@@ -102,12 +109,16 @@ function attachHomeChat(deps) {
         createdAt: createdAt,
         lastActivity: lastActivity,
         isProcessing: !!session.isProcessing,
+        sessionRole: hierarchy[session.localId].role,
+        parentSessionId: hierarchy[session.localId].parentSessionId == null ? null : sessionReference(sessionManager.sessions.get(hierarchy[session.localId].parentSessionId)),
+        parentAvailable: hierarchy[session.localId].parentAvailable,
+        workerGeneration: hierarchy[session.localId].generation,
       });
       if (session.debateSetupMode === true) result[result.length - 1].debatePlanning = true;
       if (session.homeDebatePhase) result[result.length - 1].debatePhase = session.homeDebatePhase;
       if (session.mateCreationMode === true) result[result.length - 1].mateCreation = true;
       if (session.homeMateCreationPhase) result[result.length - 1].mateCreationPhase = session.homeMateCreationPhase;
-    });
+    }
     result.sort(function (a, b) { return b.lastActivity - a.lastActivity; });
     return result;
   }

package/lib/server-tools.js

@@ -2,11 +2,15 @@ var toolsRegistry = require("./tools-registry");
 var toolStorage = require("./tool-storage");
 var crypto = require("crypto");
 var toolLlm = require("./tool-llm");
+var capsuleFloor = require("./capsule-display-floor");
+var capsuleServerRuntimes = require("./capsule-server-runtimes");
+var capsuleFrameServer = require("./capsule-frame-server");
 
 function attachTools(deps) {
   var users = deps.users;
   var projects = deps.projects;
-  var serverLogic = Object.create(null);
+  var serverRuntimes = deps.serverRuntimes || capsuleServerRuntimes;
+  var frameServer = deps.frameServer || capsuleFrameServer.createCapsuleFrameServer({ tlsOptions: deps.tlsOptions || null });
   var controlTimeoutMs = deps.controlTimeoutMs || 15000;
   var llmControlTimeoutMs = deps.llmControlTimeoutMs || 90000;
   var pendingControl = Object.create(null);
@@ -137,20 +141,47 @@ function attachTools(deps) {
     });
   }
 
+  // One act pipeline for server-runtime Capsules. The human's button click and
+  // the Mate's clay_tool_act call both arrive here, so the same Logic enforces
+  // the same rules for both and neither gets a private path. The seat is set
+  // from the server-resolved actor, never from caller-supplied text.
+  //
+  // The caller gets state and nothing else: a Mate never sees Display. Every
+  // successful act additionally pushes its causal {seq, actor, action,
+  // previous, next} event to the user's own connected clients, so a watching
+  // Display re-renders on any Logic change no matter who caused it.
+  async function controlServerCapsule(userId, installed, actor, callerId, kind, payload) {
+    var runtime = serverRuntimes.createRuntime(installed.manifest.id, contextFor(userId));
+    if (!runtime) throw new Error("No trusted server runtime is registered for this capsule.");
+    var context = { userId: userId, actor: actor, callerId: callerId };
+    if (kind === "snapshot") return runtime.snapshot(context);
+    if (kind === "act") {
+      var result = await runtime.act(context, payload.actionId, payload.args || {});
+      if (result && result.event) {
+        broadcastToUser(userId, { type: "tool_server_event", toolId: installed.manifest.id, event: result.event });
+        return result.state;
+      }
+      return result;
+    }
+    if (kind === "set" && runtime.set) return runtime.set(context, payload.controlId, payload.value);
+    throw new Error("The server-runtime capsule does not support '" + kind + "'.");
+  }
+
   function controlForMate(userId, mateId, toolId, kind, payload) {
     payload = payload || {};
     var ctx = contextFor(userId);
     toolsRegistry.listTools(ctx);
     var installed = toolsRegistry.getTool(ctx, toolId);
     if (!installed) return Promise.reject(new Error("Tool is not installed."));
+    // Skills are gated by Display: the Mate loses a Capsule at the same moment
+    // the human loses the declarative floor it is operated through.
+    if (!capsuleFloor.hasUsableFloor(installed.manifest, installed.uiTree)) {
+      return Promise.reject(new Error("This Capsule has no usable human Display, so it is unavailable to Mates."));
+    }
     if (installed.manifest.runtime === "server") {
-      var adapter = serverLogic[toolId];
-      if (!adapter) return Promise.reject(new Error("No trusted server runtime is registered for this capsule."));
-      var context = { userId: userId, callerId: mateId };
-      if (kind === "snapshot") return Promise.resolve(adapter.snapshot(context));
-      if (kind === "act") return Promise.resolve(adapter.act(context, payload.actionId, payload.args || {}));
-      if (kind === "set" && adapter.set) return Promise.resolve(adapter.set(context, payload.controlId, payload.value));
-      return Promise.reject(new Error("The server-runtime capsule does not support '" + kind + "'."));
+      return Promise.resolve().then(function () {
+        return controlServerCapsule(userId, installed, "mate", mateId, kind, payload);
+      });
     }
     var permissions = installed.manifest.permissions || [];
     var timeoutMs = kind === "act" && permissions.indexOf("llm") !== -1 ? llmControlTimeoutMs : controlTimeoutMs;
@@ -262,8 +293,18 @@ function attachTools(deps) {
     return { removed: true, toolId: toolId };
   }
 
+  // The human half of the shared server-Capsule pipeline. Same Logic, same
+  // rules, no AI in the path.
+  function controlForUser(userId, toolId, kind, payload) {
+    var ctx = contextFor(userId);
+    var installed = toolsRegistry.getTool(ctx, toolId);
+    if (!installed) throw new Error("Tool is not installed.");
+    if (installed.manifest.runtime !== "server") throw new Error("This Capsule does not run on the server.");
+    return controlServerCapsule(userId, installed, "human", "user", kind, payload || {});
+  }
+
   function handleMessage(ws, msg) {
-    var messageTypes = ["tools_list", "tool_get", "tool_install", "tool_remove", "tool_storage_op", "tool_llm_op", "tool_llm_config_get", "tool_control_response", "tool_source_get", "tool_mate_access_set"];
+    var messageTypes = ["tools_list", "tool_get", "tool_install", "tool_remove", "tool_storage_op", "tool_llm_op", "tool_llm_config_get", "tool_control_response", "tool_source_get", "tool_mate_access_set", "tool_server_control", "tool_frame_url"];
     if (!msg || messageTypes.indexOf(msg.type) === -1) return false;
     var userId;
     if (users.isMultiUser()) {
@@ -312,6 +353,52 @@ function attachTools(deps) {
       });
       return true;
     }
+    if (msg.type === "tool_frame_url") {
+      // The rich element renders on a separate anonymous origin, so the frame
+      // URL is minted here, on the authenticated socket, as a short-lived
+      // one-time token bound to this user's tools root. The rich element is
+      // additive only: it exists solely when the floor already validated at
+      // registration, and losing it never costs the human the floor.
+      Promise.resolve().then(function () {
+        var ctx = contextFor(userId);
+        var installed = toolsRegistry.getTool(ctx, msg.toolId);
+        if (!installed) throw new Error("Tool is not installed.");
+        if (!installed.hasRichDisplay) throw new Error("This Capsule ships no rich Display element.");
+        return frameServer.issueFrameUrl(ctx, msg.toolId);
+      }).then(function (frame) {
+        send(ws, { type: "tool_frame_url_state", toolId: msg.toolId, requestId: msg.requestId || null, ok: true, frame: frame });
+      }).catch(function (error) {
+        send(ws, {
+          type: "tool_frame_url_state",
+          toolId: msg.toolId,
+          requestId: msg.requestId || null,
+          ok: false,
+          error: error && error.message ? error.message : "The rich Display is unavailable.",
+        });
+      });
+      return true;
+    }
+    if (msg.type === "tool_server_control") {
+      Promise.resolve().then(function () {
+        return controlForUser(userId, msg.toolId, msg.kind, {
+          actionId: msg.actionId,
+          args: msg.args || {},
+          controlId: msg.controlId,
+          value: msg.value,
+        });
+      }).then(function (state) {
+        send(ws, { type: "tool_server_state", toolId: msg.toolId, requestId: msg.requestId || null, ok: true, state: state });
+      }).catch(function (error) {
+        send(ws, {
+          type: "tool_server_state",
+          toolId: msg.toolId,
+          requestId: msg.requestId || null,
+          ok: false,
+          error: error && error.message ? error.message : "The Capsule action failed.",
+        });
+      });
+      return true;
+    }
     if (msg.type === "tool_install") {
       run(ws, msg, function () {
         installForMate(userId, {
@@ -366,6 +453,7 @@ function attachTools(deps) {
     handleMessage: handleMessage,
     installedManifests: installedManifests,
     controlForMate: controlForMate,
+    controlForUser: controlForUser,
     installForMate: installForMate,
     sourceForMate: sourceForMate,
     updateForMate: updateForMate,

package/lib/server.js

@@ -1428,6 +1428,9 @@ function createServer(opts) {
   var toolsHandler = serverTools.attachTools({
     users: users,
     projects: projects,
+    // The rich-Display frame listener must speak the same scheme as the app,
+    // or the sandboxed frame would be blocked as mixed content under TLS.
+    tlsOptions: tlsOptions,
   });
 
   // --- Mate handler ---

package/lib/session-driver-eligibility.js

@@ -1,183 +1,38 @@
-// Driver eligibility: which models may hold the Driver role of a visible
-// Driver/Split Worker pair and receive the autonomous lifecycle tools.
+// Driver capability for a visible Driver/Split Worker pair.
 //
-// There is no canonical tier helper in the repo to reuse. Claude models are
-// enumerated by the SDK at runtime, so there is no static list; Codex ships a
-// fixed catalog in yoke/adapters/codex.js. What both have in common is a tier
-// token in the model id and in its display name, which the existing
-// project-worker-proposal.js already keys on ("fable"). This module makes that
-// same idea explicit, ordered, and vendor-scoped.
-//
-// Ranks are per vendor family and are only ever compared within a family; no
-// cross-vendor ranking is implied or invented.
-//
-//   claude family   haiku 1  <  sonnet 2  <  opus 3  <  fable 4
-//                   real ids: claude-haiku-4-5-20251001, claude-sonnet-5,
-//                             claude-opus-5, claude-fable-5
-//                   Driver threshold: fable
-//
-//   codex family    gpt-5.2 1 < gpt-5.5 2 < luna 3 < sol 4 < terra 5
-//                   real ids: the CODEX_MODELS catalog, strongest first
-//                   Driver threshold: sol
-//
-// Matching is by token, not by exact id, so a later release in the same family
-// (claude-fable-6, gpt-5.7-terra) stays eligible without a code change. A
-// model in a known family whose tier token is unrecognized is NOT eligible:
-// unknown capability fails closed rather than inheriting the threshold.
-//
-// Any other vendor is not eligible for the Driver role at all, because no
-// equivalent tier metadata exists to compare against. Those vendors remain
-// perfectly usable as Workers.
-
-var models = require("./project-models");
-
-var FAMILIES = {
-  claude: {
-    label: "Claude",
-    threshold: 4,
-    thresholdName: "Fable",
-    // Longest/most specific tokens first so "haiku" cannot shadow a future
-    // compound name. Each entry is a token searched in id and display name.
-    tiers: [
-      { token: "fable", rank: 4, name: "Fable" },
-      { token: "opus", rank: 3, name: "Opus" },
-      { token: "sonnet", rank: 2, name: "Sonnet" },
-      { token: "haiku", rank: 1, name: "Haiku" },
-    ],
-  },
-  codex: {
-    label: "OpenAI",
-    threshold: 4,
-    thresholdName: "Sol",
-    tiers: [
-      { token: "terra", rank: 5, name: "Terra" },
-      { token: "sol", rank: 4, name: "Sol" },
-      { token: "luna", rank: 3, name: "Luna" },
-      { token: "gpt-5.5", rank: 2, name: "GPT-5.5" },
-      { token: "gpt-5.2", rank: 1, name: "GPT-5.2" },
-    ],
-  },
-};
-
-function familyFor(vendor) {
-  var key = String(vendor || "").toLowerCase();
-  return Object.prototype.hasOwnProperty.call(FAMILIES, key) ? FAMILIES[key] : null;
-}
-
-// Every string the catalog knows this model by. The catalog entry is found with
-// the repo's own matcher so an alias ("fable"), an id, or a resolvedModel all
-// resolve to the same entry, and the display name participates in tier
-// detection exactly as project-worker-proposal.js already relies on.
-function searchTextFor(vendor, model, modelsByVendor) {
-  var parts = [String(model || "")];
-  var catalog = (modelsByVendor && modelsByVendor[vendor]) || [];
-  for (var i = 0; i < catalog.length; i++) {
-    if (!models.modelEntryMatches(catalog[i], model)) continue;
-    var entry = catalog[i];
-    if (typeof entry === "string") {
-      parts.push(entry);
-    } else {
-      parts.push(entry.value || "");
-      parts.push(entry.id || "");
-      parts.push(entry.resolvedModel || "");
-      parts.push(entry.displayName || "");
-      parts.push(entry.name || "");
-    }
-    break;
-  }
-  return parts.join(" ").toLowerCase();
-}
-
-// Resolve the tier of one model inside its vendor family. Returns null when
-// the vendor has no tier metadata or the tier token is unrecognized.
-function resolveTier(vendor, model, modelsByVendor) {
-  var family = familyFor(vendor);
-  if (!family || !model) return null;
-  var text = searchTextFor(vendor, model, modelsByVendor);
-  for (var i = 0; i < family.tiers.length; i++) {
-    if (text.indexOf(family.tiers[i].token) !== -1) {
-      return {
-        vendor: String(vendor).toLowerCase(),
-        family: family.label,
-        rank: family.tiers[i].rank,
-        name: family.tiers[i].name,
-        threshold: family.threshold,
-        thresholdName: family.thresholdName,
-      };
-    }
-  }
-  return null;
-}
-
-// The hard invariant. Returns { ok, tier, error } and never throws. `error` is
-// a complete English sentence suitable for returning to a tool caller.
-function evaluateDriverModel(vendor, model, modelsByVendor) {
-  var family = familyFor(vendor);
-  if (!family) {
-    return {
-      ok: false,
-      tier: null,
-      error: "The Driver role requires a Claude model of Fable tier or higher, or an OpenAI model of " +
-        "Sol tier or higher. Vendor \"" + String(vendor || "unknown") + "\" has no comparable tier " +
-        "metadata, so it cannot take the Driver role. It can still be used for the Split Worker.",
-    };
+// Model and vendor choice belongs to the user. A session does not need to
+// clear a model-tier threshold to coordinate a Split Worker; runtime catalog
+// validation belongs to session-pair-factory.js and applies equally to every
+// requested role. The only session-level exclusion here is structural: an
+// embedded terminal has no project chat surface on which to host the Driver
+// controls or the paired pane.
+
+var sessionProvenance = require("./session-provenance");
+
+function evaluateDriverSession(session) {
+  if (!session) {
+    return { ok: false, error: "No session was bound to this request." };
   }
-  if (!model) {
-    return {
-      ok: false,
-      tier: null,
-      error: "This session has no resolved model yet, so its " + family.label +
-        " tier cannot be confirmed. The Driver role requires " + family.thresholdName +
-        " tier or higher.",
-    };
-  }
-  var tier = resolveTier(vendor, model, modelsByVendor);
-  if (!tier) {
-    return {
-      ok: false,
-      tier: null,
-      error: "Model \"" + model + "\" is not a recognized " + family.label +
-        " tier, so it cannot take the Driver role. The Driver role requires " +
-        family.thresholdName + " tier or higher.",
-    };
-  }
-  if (tier.rank < tier.threshold) {
+  if (session.mode === "tui") {
     return {
       ok: false,
-      tier: tier,
-      error: "The Driver role requires a " + family.label + " model of " + family.thresholdName +
-        " tier or higher. This session is " + tier.name + " tier.",
+      error: "An embedded terminal session cannot take the Driver role.",
     };
   }
-  return { ok: true, tier: tier, error: null };
-}
-
-// The session-level form. Resolves the session's effective model the same way
-// the rest of the server does: the session's own model, else the vendor
-// default. Identity is read from the session object, never from a caller.
-function evaluateDriverSession(session, sm) {
-  if (!session) return { ok: false, tier: null, error: "No session was bound to this request." };
-  if (session.mode === "tui") {
+  if (sessionProvenance.isWorker(session)) {
     return {
       ok: false,
-      tier: null,
-      error: "An embedded terminal session cannot take the Driver role.",
+      error: "A Split Worker session cannot take the Driver role.",
     };
   }
-  var vendor = session.vendor || "claude";
-  var fallback = (sm && sm.defaultModelByVendor && sm.defaultModelByVendor[vendor]) || "";
-  var model = session.model || fallback;
-  return evaluateDriverModel(vendor, model, sm && sm.modelsByVendor);
+  return { ok: true, error: null };
 }
 
-function isEligibleDriverSession(session, sm) {
-  return evaluateDriverSession(session, sm).ok;
+function isEligibleDriverSession(session) {
+  return evaluateDriverSession(session).ok;
 }
 
 module.exports = {
-  FAMILIES: FAMILIES,
-  evaluateDriverModel: evaluateDriverModel,
   evaluateDriverSession: evaluateDriverSession,
   isEligibleDriverSession: isEligibleDriverSession,
-  resolveTier: resolveTier,
 };

package/lib/session-pair-factory.js

@@ -2,9 +2,9 @@
 //
 // Extracted from project-session-pair.js, which operates a pair once it
 // exists; this module is only about how one comes into being. Both the
-// explicit "Add Split Worker" flow and the Driver-initiated
-// send_to_partner-creates-a-pair flow land here, so vendor validation, owner
-// derivation and the group record are written in exactly one place.
+// explicit "Add Split Worker", accepted proposal, and transactional replacement
+// flows land here, so vendor validation, owner derivation and the group record
+// are written in exactly one place.
 //
 // Ownership always comes from the connection or the Driver session, never from
 // the incoming message.
@@ -22,11 +22,10 @@
 //
 // Two ordering rules matter and are load-bearing:
 //
-//   1. Nothing is created until everything is validated. Driver eligibility and
+//   1. Nothing is created until everything is validated. Driver capability and
 //      both runtime requests are settled first, so a rejected request leaves no
-//      orphan session behind. For a newly requested Driver the tier is checked
-//      against the model that session would actually resolve to, before either
-//      session exists.
+//      orphan session behind. Any installed, available model may be the Driver;
+//      model choice is the user's rather than a server-side tier policy.
 //   2. `preflightRuntime` is side-effect free, so a caller that is about to
 //      destroy something (replacement dissolving a live pair) can validate the
 //      replacement first and abort while the old pair is still intact.
@@ -34,6 +33,7 @@
 var driverEligibility = require("./session-driver-eligibility");
 var models = require("./project-models");
 var yoke = require("./yoke");
+var sessionProvenance = require("./session-provenance");
 
 function attachPairFactory(ctx) {
   var sm = ctx.sm;
@@ -87,8 +87,8 @@ function attachPairFactory(ctx) {
     };
   }
 
-  // The vendor a Driver-initiated Worker gets when none is named: prefer a
-  // different engine from the Driver's own, so the pair does not double up.
+  // The default Worker vendor for an accepted proposal or replacement prefers
+  // a different engine from the Driver's own, so the pair does not double up.
   function defaultWorkerVendorFor(driver) {
     var installed = sm.installedVendors || [];
     if (installed.length === 0) throw new Error("no coding agent is installed for a Split Worker session");
@@ -140,14 +140,6 @@ function attachPairFactory(ctx) {
       groupName = undefined; // auto name from member titles
     } else {
       driverRuntime = preflightRuntime(driverSpec, "claude");
-      // The tier is judged on the model this session would really resolve to:
-      // the explicit request if there is one, else that vendor's default.
-      var effectiveDriverModel = driverRuntime.model ||
-        (sm.defaultModelByVendor && sm.defaultModelByVendor[driverRuntime.vendor]) || "";
-      var newVerdict = driverEligibility.evaluateDriverModel(
-        driverRuntime.vendor, effectiveDriverModel, sm.modelsByVendor
-      );
-      if (!newVerdict.ok) throw new Error(newVerdict.error);
       groupName = "Agent pair";
     }
 
@@ -176,18 +168,29 @@ function attachPairFactory(ctx) {
     worker.title = "Split Worker · " + ((yoke.getVendorInfo(workerRuntime.vendor) || {}).displayName || workerRuntime.vendor);
     if (workerRuntime.explicitEffort) worker.loopSettings = { effort: workerRuntime.effort };
 
-    var result = store.create(ws, {
-      members: [driver.localId, worker.localId],
-      pair: { driverId: driver.localId, workerId: worker.localId },
-      name: groupName,
-    });
-    if (!result.ok) {
-      // The group is the last step, so a failure here would otherwise strand
-      // the sessions this call just made. Only sessions created by this call
-      // are removed; an existing Driver is never touched.
+    var result;
+    try {
+      // Creation provenance is durable and independent from the active split
+      // group. Persist both ends before the group's broadcast so the Worker
+      // never flashes as unrelated and survives a restart with its parentage.
+      sessionProvenance.markWorker(driver, worker, sm.sessions);
+      if (typeof sm.saveSessionFile === "function") {
+        sm.saveSessionFile(driver);
+        sm.saveSessionFile(worker);
+      }
+
+      result = store.create(ws, {
+        members: [driver.localId, worker.localId],
+        pair: { driverId: driver.localId, workerId: worker.localId },
+        name: groupName,
+      });
+      if (!result.ok) throw new Error(result.error);
+    } catch (e) {
+      // Any failure after session creation must remove exactly the sessions
+      // made by this call. An existing Driver is never removed.
       removeCreated(worker);
       removeCreated(createdDriver);
-      throw new Error(result.error);
+      throw e;
     }
     sm.broadcastSessionList();
     return { driver: driver, worker: worker, group: result.group };
@@ -202,7 +205,7 @@ function attachPairFactory(ctx) {
   }
 
   function createWorkerForDriver(driver, args) {
-    // Validates the Driver's eligibility and the whole Worker runtime before
+    // Validates the Driver's capability and the whole Worker runtime before
     // any session is made, so a rejection creates nothing.
     var runtime = preflightWorkerForDriver(driver, args);
     var ws = {

package/lib/session-pair-mcp-server.js

@@ -9,14 +9,11 @@ function getToolDefs(handlers, options) {
   var defs = [
     {
       name: "send_to_partner",
-      description: "Delegate one concrete task to the visible Split Worker. If this session has no pair yet, Clay creates a real Split Worker session and opens it visibly in the right pane before starting the task — no approval step and no suggestion card. A completed turn does not end the Split Worker session: reuse the same Split Worker for follow-up implementation and corrections instead of taking over its work. Detached completions are pushed back automatically. A delegated turn cannot delegate back, so keep orchestration one hop deep.",
+      description: "Delegate one concrete follow-up task to the existing visible Split Worker. This tool is exposed only after the user has configured and accepted an exact pair. A completed turn does not end the Split Worker session: reuse the same Split Worker for follow-up implementation and corrections instead of taking over its work. Detached completions are pushed back automatically. A delegated turn cannot delegate back, so keep orchestration one hop deep.",
       inputSchema: buildShape({
         message: { type: "string", description: "The complete task or question for the partner." },
         wait: { type: "boolean", description: "Wait for the partner's turn to finish. Defaults to true." },
         timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
-        workerVendor: { type: "string", description: "Optional Split Worker vendor to use only when creating a new pair. Defaults to a suitable installed vendor." },
-        workerModel: { type: "string", description: "Optional Split Worker model to use only when creating a new pair." },
-        workerEffort: { type: "string", description: "Optional Split Worker reasoning effort to use only when creating a new pair." },
         operationId: { type: "string", description: "Optional stable id for this delegation. Reusing it within the same human turn returns the original operation instead of sending twice." },
       }, ["message"]),
       handler: function (args) { return handlers.send(args || {}); },
@@ -52,21 +49,20 @@ function getToolDefs(handlers, options) {
     },
     {
       name: "replace_partner",
-      description: "Replace your Split Worker with a fresh, compact one in a single operation: the old pair is dissolved, a new Worker session is created and opened visibly, and an optional task is delivered to it. The previous Worker's conversation is preserved and stays browsable. Use this when the current Worker is context-bloated, stale, or working on something unrelated to the next task. Refuses while the Worker is mid-turn unless you pass interrupt true.",
+      description: "Propose replacing the current Split Worker with a fresh runtime. This non-mutating call shows a user-controlled vendor, model, and effort card. Only acceptance performs the transactional replacement and delegates the supplied task once; decline keeps the existing pair and resumes the Driver. The previous Worker's conversation remains browsable. An active Worker requires interrupt true.",
       inputSchema: buildShape({
         interrupt: { type: "boolean", description: "Stop the Worker first if it is mid-turn or holding a delegated task. Required to replace an active Worker." },
-        message: { type: "string", description: "Optional task to deliver to the new Worker immediately after it is created." },
-        wait: { type: "boolean", description: "When a message is given, wait for that turn to finish. Defaults to true." },
-        timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
+        message: { type: "string", description: "Task to deliver exactly once after the user accepts the replacement." },
         workerVendor: { type: "string", description: "Optional vendor for the new Worker. Must be installed and available." },
         workerModel: { type: "string", description: "Optional model for the new Worker. Must be offered by that vendor." },
         workerEffort: { type: "string", description: "Optional reasoning effort for the new Worker." },
+        recommendationRationale: { type: "string", description: "Concise Driver-authored explanation of why the recommended replacement vendor, model, and effort fit the next task." },
         evaluation: {
           type: "object",
           description: "Optional bounded assessment of the Worker being replaced, recorded against that exact generation.",
         },
         operationId: { type: "string", description: "Optional stable id for this replacement. Reusing it within the same human turn returns the original operation instead of replacing twice." },
-      }),
+      }, ["message", "recommendationRationale"]),
       handler: function (args) { return handlers.replace(args || {}); },
     },
     {

package/lib/session-pair-prompts.js

@@ -1,10 +1,7 @@
 // Driver-facing system prompt text for the visible Driver/Split Worker pair.
 //
 // Pure data, extracted from project-session-pair.js so that module stays under
-// the size limit and so the guidance can be reviewed as prose. There is no
-// proposal or approval language here by design: a qualified Driver manages its
-// Worker on its own authority, so telling the model to suggest or ask would
-// contradict the tools it actually has.
+// the size limit and so the guidance can be reviewed as prose.
 
 var DRIVER = [
   "You are the Driver of a visible Driver/Split Worker pair, and you manage that Split Worker yourself.",
@@ -17,18 +14,22 @@ var DRIVER = [
   "working on something unrelated, replace it instead of carrying that cost forward. Call partner_status to",
   "decide: it reports context tokens used and the ratio of its window, current activity, vendor/model/effort,",
   "history size and idle time, whether replacing is safe right now, and the results you recorded for earlier",
-  "Worker generations. It returns no transcript, so it is cheap to consult.",
+  "Worker generations. It returns no transcript, so it is cheap to consult. Never tell the user that you will",
+  "reuse the current Worker before checking partner_status. If you previously expected reuse but the status leads",
+  "you to replace it, explicitly say that the decision changed and give the reason.",
   "",
-  "Act on your own authority. You create, reuse, interrupt, replace, and close the Split Worker without asking",
-  "the user and without posting any suggestion or approval card. send_to_partner creates and opens a visible",
-  "Split Worker when none exists. replace_partner dissolves the current pair and opens a fresh compact Worker in",
-  "one step, optionally delivering the next task with it; the replaced Worker keeps its conversation, so nothing",
-  "is lost. Replacing an actively running Worker requires interrupt true, which stops it first. A human Stop",
+  "Use send_to_partner seamlessly for follow-up work in the existing pair. Runtime creation and replacement are",
+  "recorded through a configuration card before anything mutates. replace_partner always posts that card. When",
+  "this Driver is in full-access mode, Clay may auto-accept your exact server-validated recommendation; otherwise",
+  "the selected vendor, model, and effort remain pending until the user explicitly accepts them.",
+  "The replaced Worker keeps its conversation, so nothing is lost. Replacing an actively running Worker requires",
+  "interrupt true, which stops it first only after acceptance. A human Stop",
   "is authoritative: do not retry, send more work, or replace the Worker in the same turn. Clay blocks those",
   "actions until the human sends a new Driver message. Use close_partner when they ask to close the pane.",
   "",
-  "Choose the Worker vendor, model, and effort for the task from what is actually installed and offered; an",
-  "unavailable choice is refused rather than silently substituted. After a Worker generation finishes or is",
+  "Recommend a Worker vendor, model, and effort from what is actually installed and offered, and include a concise",
+  "rationale explaining why all three fit the task. The card remains visible as an audit trail even when full access",
+  "auto-accepts it; an unavailable choice is never auto-accepted. After a Worker generation finishes or is",
   "replaced, call record_partner_evaluation with succeeded, partial, failed, or abandoned and a short reason.",
   "Clay stores that against that exact generation alongside what it measured itself, and partner_status hands it",
   "back, so your next model choice can use observed results instead of guesswork. This is your own record for",
@@ -51,9 +52,8 @@ var UNPAIRED = [
   "Split Worker and its partner tools. Internal Sub-agents are a distinct execution mechanism, not a lexical",
   "category; use them only when the user clearly intends internal or background parallel delegation rather than a",
   "visible paired session. When ambiguity would materially change where work runs, ask a concise clarification",
-  "instead of guessing. When a task is implementation-heavy, call send_to_partner directly: Clay creates the",
-  "paired Split Worker session and opens it in the right pane automatically before delivering the task. Do not",
-  "ask the user for permission to start one, do not ask them to enable split mode, and do not use a background",
+  "instead of guessing. When a task is implementation-heavy, call propose_worker with an exact runtime recommendation",
+  "and concise rationale. Clay records and shows the card before the visible pair is accepted or auto-accepted. Do not use a background",
   "Sub-agent as a substitute for a visible Split Worker.",
 ].join(" ").replace(/ {2,}/g, " ");