clay-server 5.2.0-beta.1 → 5.2.0-beta.10

package/lib/sdk-bridge.js

@@ -1,12 +1,9 @@
-const crypto = require("crypto");
-var codexQuestionGuidance = require("./yoke/user-input-guidance").codexQuestionGuidance;
+var crypto = require("crypto");
 var fs = require("fs");
 var path = require("path");
 var execSync = require("child_process").execSync;
 var execFileSync = require("child_process").execFileSync;
 var usersModule = require("./users");
-var { getCodexConfig } = require("./codex-defaults");
-var { getKiroConfig } = require("./kiro-defaults");
 var { splitShellSegments, attachSkillDiscovery } = require("./sdk-skill-discovery");
 var skillDiscovery = require("./yoke/skill-discovery");
 var { isSafeBashSegment } = require("./safe-bash-commands");
@@ -19,7 +16,7 @@ var sessionTitlePolicy = require("./session-title-policy");
 var sessionTitleGenerator = require("./session-title-generator");
 var loopInterview = require("./project-loop-interview");
 
-var extractMcpDescriptors = require("./sdk-mcp-descriptors").extractMcpDescriptors;
+var extractMcpDescriptors = require("./yoke/sdk-mcp-descriptors").extractMcpDescriptors;
 
 // Call an MCP tool handler by server name and tool name.
 // Returns a promise that resolves with the tool result.
@@ -137,7 +134,7 @@ function createSDKBridge(opts) {
     }];
   }
 
-  function getCodexSessionMcpServer(session, queryGeneration) {
+  function getSessionMcpServer(session, queryGeneration) {
     if (!session || !Number.isInteger(queryGeneration)) return null;
     var bridgeArgs = [
       path.join(__dirname, "yoke", "mcp-bridge-server.js"),
@@ -165,25 +162,16 @@ function createSDKBridge(opts) {
     return _cachedFreshAuthState;
   }
 
-  function isAuthErrorMessage(errDetail) {
-    if (!errDetail) return false;
-    var errLower = String(errDetail).toLowerCase();
-    return errLower.indexOf("not logged in") !== -1
-      || errLower.indexOf("unauthenticated") !== -1
-      || errLower.indexOf("authentication") !== -1
-      || errLower.indexOf("sign in") !== -1
-      || errLower.indexOf("log in") !== -1
-      || errLower.indexOf("please login") !== -1;
-  }
+  var isAuthErrorMessage = require("./yoke/auth-events").isAuthenticationError;
 
   function getLoginCommand(vendor) {
     var info = yoke.getVendorInfo(vendor);
-    return (info && info.loginCommand) || "claude login";
+    return (info && info.loginCommand) || "";
   }
 
   function supportsOsUserIsolation(vendor) {
     var info = yoke.getVendorInfo(vendor);
-    return !info || info.osUserIsolation !== false;
+    return !!info && info.osUserIsolation === true;
   }
 
   function notifyAuthRequired(session, title, body, authLinuxUser, canAutoLogin, loginCommand) {
@@ -323,6 +311,7 @@ function createSDKBridge(opts) {
   }
 
   function stopIdleReaper() {
+    responseRecovery.dispose();
     if (_idleReaperTimer) {
       clearInterval(_idleReaperTimer);
       _idleReaperTimer = null;
@@ -389,6 +378,18 @@ function createSDKBridge(opts) {
   var sendAndRecord = msgProcessor.sendAndRecord;
   var sendToSession = msgProcessor.sendToSession;
 
+  var responseRecovery = require("./yoke/response-recovery").attachResponseRecovery(Object.assign({
+    getProvider: function(session) { var vendor = session.vendor || sm.defaultVendor || adapter && adapter.vendor; return adapters[vendor] || vendor || adapter; },
+    sessions: sm.sessions,
+    changed: onProcessingChanged,
+    record: sendAndRecord,
+    send: sendToSession,
+    broadcast: function() { if (sm.broadcastSessionList) sm.broadcastSessionList(); },
+    restart: function(session, payload, state) {
+      return startQuery(session, payload.text, payload.images, payload.linuxUser, payload.beforePush, null, state);
+    },
+  }, opts.responseRecovery || {}));
+
   // --- MCP elicitation ---
 
   function handleElicitation(session, request, opts) {
@@ -417,6 +418,7 @@ function createSDKBridge(opts) {
 
       if (pushModule) {
         pushModule.sendPush({
+          sessionId: session.localId,
           type: "elicitation",
           slug: slug,
           title: (request.serverName || "MCP Server") + " needs input",
@@ -467,6 +469,7 @@ function createSDKBridge(opts) {
 
       if (pushModule) {
         pushModule.sendPush({
+          sessionId: session.localId,
           type: "user_dialog",
           slug: slug,
           title: "Claude needs a decision",
@@ -489,44 +492,7 @@ function createSDKBridge(opts) {
   // Ensures the linux user's .claude project directory exists and is writable,
   // then pre-copies CLI session file if needed. Called before starting a query
   // so the worker can resume from the correct session file.
-  function ensureLinuxUserProjectDir(linuxUser, session) {
-    try {
-      var configMod = require("./config");
-      var osUsersMod = require("./os-users");
-      var originalHome = configMod.REAL_HOME || require("os").homedir();
-      var linuxUserHome = osUsersMod.getLinuxUserHome(linuxUser);
-      var uid = osUsersMod.getLinuxUserUid(linuxUser);
-      if (originalHome !== linuxUserHome && uid != null) {
-        var projectSlug = (cwd || "").replace(/\//g, "-");
-        var dstDir = path.join(linuxUserHome, ".claude", "projects", projectSlug);
-        // Create and chown the project directory once
-        if (!fs.existsSync(dstDir)) {
-          fs.mkdirSync(dstDir, { recursive: true });
-          try { execFileSync("chown", ["-R", String(uid), path.join(linuxUserHome, ".claude")]); } catch (e2) {}
-        } else {
-          try {
-            var dirStat = fs.statSync(dstDir);
-            if (dirStat.uid !== uid) {
-              execFileSync("chown", [String(uid), dstDir]);
-            }
-          } catch (e2) {}
-        }
-        // Pre-copy CLI session file so the worker can resume the conversation
-        if (session.cliSessionId) {
-          var sessionFileName = session.cliSessionId + ".jsonl";
-          var srcFile = path.join(originalHome, ".claude", "projects", projectSlug, sessionFileName);
-          var dstFile = path.join(dstDir, sessionFileName);
-          if (fs.existsSync(srcFile) && !fs.existsSync(dstFile)) {
-            fs.copyFileSync(srcFile, dstFile);
-            try { execFileSync("chown", [String(uid), dstFile]); } catch (e2) {}
-            console.log("[sdk-bridge] Pre-copied CLI session " + session.cliSessionId + " to " + linuxUser);
-          }
-        }
-      }
-    } catch (copyErr) {
-      console.log("[sdk-bridge] Dir setup / session pre-copy skipped:", copyErr.message);
-    }
-  }
+
 
   // --- SDK query lifecycle ---
 
@@ -745,6 +711,38 @@ function createSDKBridge(opts) {
     // Workspace inspection and proposal posting are session-bound. Keep this
     // list exact so a future execution/mutation tool cannot inherit approval.
     var safeWorkspaceTools = {
+      "mcp__clay-workspace__read_current_context": true,
+      "mcp__clay-workspace__read_selected_context": true,
+      "mcp__clay-workspace__open_context_conversation": true,
+      "mcp__clay-workspace__read_context_navigation_receipt": true,
+      "mcp__clay-workspace__read_owner_screen": true,
+      "mcp__clay-workspace__inspect_owner_screen_change": true,
+      "mcp__clay-workspace__control_owner_screen": true,
+      "mcp__clay-workspace__discover_product_controls": true,
+      "mcp__clay-workspace__list_owned_mates": true,
+      "mcp__clay-workspace__begin_schedule_control_interview": true,
+      "mcp__clay-workspace__read_schedule_controls": true,
+      "mcp__clay-workspace__inspect_schedule_change": true,
+      "mcp__clay-workspace__control_schedules": true,
+      "mcp__clay-workspace__read_mate_chat_control": true,
+      "mcp__clay-workspace__inspect_mate_chat_change": true,
+      "mcp__clay-workspace__control_mate_chat": true,
+      "mcp__clay-workspace__read_project_workspace": true,
+      "mcp__clay-workspace__read_workspace_receipt": true,
+      "mcp__clay-workspace__inspect_workspace_change": true,
+      "mcp__clay-workspace__control_project_workspace": true,
+      "mcp__clay-workspace__read_project_records": true,
+      "mcp__clay-workspace__inspect_project_record_change": true,
+      "mcp__clay-workspace__control_project_records": true,
+      "mcp__clay-workspace__read_mate_knowledge_control": true,
+      "mcp__clay-workspace__inspect_mate_knowledge_change": true,
+      "mcp__clay-workspace__control_mate_knowledge": true,
+      "mcp__clay-workspace__inspect_mate_control": true,
+      "mcp__clay-workspace__control_mate_lifecycle": true,
+      "mcp__clay-workspace__inspect_project_control": true,
+      "mcp__clay-workspace__control_project_lifecycle": true,
+      "mcp__clay-workspace__inspect_session_control": true,
+      "mcp__clay-workspace__control_project_session": true,
       "mcp__clay-workspace__list_projects": true,
       "mcp__clay-workspace__list_project_sessions": true,
       "mcp__clay-workspace__search_project_history": true,
@@ -902,6 +900,7 @@ function createSDKBridge(opts) {
 
       if (pushModule) {
         pushModule.sendPush({
+          sessionId: session.localId,
           type: "permission_request",
           slug: slug,
           requestId: requestId,
@@ -943,58 +942,13 @@ function createSDKBridge(opts) {
    * Only returns processes whose cwd matches our project directory.
    * Returns an array of { pid, command } for each conflicting process found.
    */
-  function findConflictingClaude() {
-    try {
-      var output = execFileSync("ps", ["ax", "-o", "pid,command"], { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
-      var lines = output.trim().split("\n");
-      var candidates = [];
-      for (var i = 1; i < lines.length; i++) { // skip header
-        var line = lines[i].trim();
-        var m = line.match(/^(\d+)\s+(.+)/);
-        if (!m) continue;
-        var pid = parseInt(m[1], 10);
-        var cmd = m[2];
-        // Skip our own process
-        if (pid === process.pid) continue;
-        // Skip node processes (our daemon, dev watchers, etc.)
-        if (/\bnode\b/.test(cmd.split(/\s/)[0])) continue;
-        // Match actual claude binary (e.g. /Users/x/.claude/local/claude, /usr/local/bin/claude)
-        if (/\/claude(\s|$)/.test(cmd) || /^claude(\s|$)/.test(cmd)) {
-          candidates.push({ pid: pid, command: cmd.substring(0, 200) });
-        }
-      }
-
-      // Filter to only processes whose cwd matches our project
-      var results = [];
-      for (var j = 0; j < candidates.length; j++) {
-        var c = candidates[j];
-        try {
-          // Use /proc/<pid>/cwd symlink (always available on Linux, no lsof dependency)
-          var procCwd = fs.readlinkSync("/proc/" + c.pid + "/cwd");
-          if (procCwd === cwd) {
-            results.push(c);
-          }
-        } catch (e) {
-          // /proc read failed — include as candidate anyway (conservative)
-          results.push(c);
-        }
-      }
-      return results;
-    } catch (e) {
-      return [];
-    }
+  function findConflictingProcesses(session, error) {
+    var service = require("./yoke/provider-contract").resolve(getAdapterForSession(session)).processControl;
+    return service && typeof service.shouldInspect === "function" && service.shouldInspect(error) && typeof service.findConflicts === "function" ? service.findConflicts(cwd) : [];
   }
-
-  /**
-   * Verify that a PID is actually a claude binary process (not arbitrary).
-   */
-  function isClaudeProcess(pid) {
-    try {
-      var output = execFileSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"] }).trim();
-      return /\/claude(\s|$)/.test(output) || /^claude(\s|$)/.test(output);
-    } catch (e) {
-      return false;
-    }
+  function isProviderProcess(pid, session) {
+    var service = require("./yoke/provider-contract").resolve(session ? getAdapterForSession(session) : adapter).processControl;
+    return !!(service && typeof service.verifyProcess === "function" && service.verifyProcess(pid));
   }
 
   function ownsQueryRuntime(session, queryInstance, queryGeneration) {
@@ -1006,6 +960,7 @@ function createSDKBridge(opts) {
   function recordRuntimeEffectivePermissionMode(session, queryInstance, queryGeneration, message) {
     if (!message || (message.yokeType !== "init" && message.yokeType !== "status") || !message.permissionMode) return false;
     if (!ownsQueryRuntime(session, queryInstance, queryGeneration)) return false;
+    session._permissionObservationRevision = Number(session._permissionObservationRevision || 0) + 1;
     session.effectivePermissionMode = message.permissionMode;
     session.permissionModeFallbackReason = null;
     sm.saveSessionFile(session);
@@ -1036,7 +991,8 @@ function createSDKBridge(opts) {
     return true;
   }
 
-  async function processQueryStream(session, codexCatalogCandidate) {
+  async function processQueryStream(session, catalogCandidate, queryContract) {
+    queryContract = queryContract || yoke.sessionTools.contract(getAdapterForSession(session));
     // Capture references at start so we only clean up OUR resources in finally,
     // not resources from a newer query that may have been created after an abort.
     var myQueryInstance = session.queryInstance;
@@ -1047,7 +1003,7 @@ function createSDKBridge(opts) {
     try {
       for await (var msg of myQueryInstance) {
         // An old iterator may drain after Stop or after a replacement query starts.
-        if (!ownsQueryRuntime(session, myQueryInstance, myQueryGeneration)) continue;
+        if (!ownsQueryRuntime(session, myQueryInstance, myQueryGeneration) || responseRecovery.stopping(session)) continue;
         if ((session.taskStopRequested || (myAbortController && myAbortController.signal.aborted))
             && msg && msg.yokeType !== "error" && msg.yokeType !== "interrupted") continue;
         if (msg && msg.yokeType !== "text_delta" && msg.yokeType !== "thinking_delta" && msg.yokeType !== "tool_input_delta") {
@@ -1091,6 +1047,7 @@ function createSDKBridge(opts) {
         if (continuationIdentity && !ownsQueryRuntime(session, myQueryInstance, myQueryGeneration)) {
           continue;
         }
+        responseRecovery.event(session, msg);
         processSDKMessage(session, msg);
         if (continuationIdentity) {
           settleContinuationStartup(session, myQueryInstance, myQueryGeneration, true, null);
@@ -1101,26 +1058,21 @@ function createSDKBridge(opts) {
         // permission state. Setter acknowledgement deliberately does not
         // change this field.
         recordRuntimeEffectivePermissionMode(session, myQueryInstance, myQueryGeneration, msg);
-        if (codexCatalogCandidate && msg && msg.yokeType === "session_started" && msg.sessionId
+        if (catalogCandidate && msg && msg.yokeType === "session_started" && msg.sessionId
             && session.queryInstance === myQueryInstance
-            && Number(session._sdkQueryGeneration || 0) === codexCatalogCandidate.generation
+            && Number(session._sdkQueryGeneration || 0) === catalogCandidate.generation
             && session.cliSessionId === msg.sessionId
             && (!sm.sessions || typeof sm.sessions.get !== "function" || sm.sessions.get(session.localId) === session)) {
-          if (codexCatalogCandidate.version) session.codexDynamicToolCatalogVersion = codexCatalogCandidate.version;
-          if (codexCatalogCandidate.userInputVersion) session.codexUserInputToolCatalogVersion = codexCatalogCandidate.userInputVersion;
-          if (codexCatalogCandidate.sharedBrowserVersion) session.codexSharedBrowserToolCatalogVersion = codexCatalogCandidate.sharedBrowserVersion;
-          if (codexCatalogCandidate.issuesVersion) session.codexIssuesToolCatalogVersion = codexCatalogCandidate.issuesVersion;
-          if (codexCatalogCandidate.youVersion) session.codexYouToolCatalogVersion = codexCatalogCandidate.youVersion;
-          if (codexCatalogCandidate.linearVersion) session.codexLinearToolCatalogVersion = codexCatalogCandidate.linearVersion;
+          queryContract.recordCatalog(session, catalogCandidate.versions);
           sm.saveSessionFile(session);
-          codexCatalogCandidate = null;
+          catalogCandidate = null;
         }
       }
       // (getContextUsage moved to processSDKMessage result handler -- fire-and-forget)
       // Stream ended normally after a task stop — no "result" message was sent,
       // so the session is still marked as processing. Send interrupted feedback.
       console.log("[sdk-bridge] processQueryStream ended: isProcessing=" + session.isProcessing + " taskStopRequested=" + session.taskStopRequested);
-      var stillOwnsRuntime = session.queryInstance === myQueryInstance;
+      var stillOwnsRuntime = session.queryInstance === myQueryInstance && !responseRecovery.stopping(session);
       settleContinuationStartup(session, myQueryInstance, myQueryGeneration, false, "The successor query ended before initialization.");
       if (session.isProcessing && session.taskStopRequested && stillOwnsRuntime) {
         session._lastTurnInterrupted = true;
@@ -1131,9 +1083,7 @@ function createSDKBridge(opts) {
         onProcessingChanged();
         send({ type: "status", processing: false });
         sendAndRecord(session, { type: "thinking_stop" });
-        var interruptMsg = (session.vendor && session.vendor !== "claude")
-          ? "\u25a0 Conversation interrupted - tell the model what to do differently."
-          : "Interrupted \u00b7 What should Claude do instead?";
+        var interruptMsg = (queryContract && queryContract.interruptionMessage) || "■ Conversation interrupted - tell the model what to do differently.";
         sendAndRecord(session, { type: "info", text: interruptMsg });
         sendAndRecord(session, { type: "done", code: 0 });
         sm.broadcastSessionList();
@@ -1158,7 +1108,7 @@ function createSDKBridge(opts) {
       }
     } catch (err) {
       settleContinuationStartup(session, myQueryInstance, myQueryGeneration, false, err.message || "The successor query failed before initialization.");
-      if (session.isProcessing && session.queryInstance === myQueryInstance) {
+      if (session.isProcessing && session.queryInstance === myQueryInstance && !responseRecovery.stopping(session)) {
         session.isProcessing = false;
         session._awaitingTurnResult = false;
         session._queuedTurnCount = 0;
@@ -1168,9 +1118,7 @@ function createSDKBridge(opts) {
           session._lastTurnInterrupted = true;
           if (!session.destroying) {
             sendAndRecord(session, { type: "thinking_stop" });
-            var interruptMsg2 = (session.vendor && session.vendor !== "claude")
-              ? "\u25a0 Conversation interrupted - tell the model what to do differently."
-              : "Interrupted \u00b7 What should Claude do instead?";
+            var interruptMsg2 = (queryContract && queryContract.interruptionMessage) || "■ Conversation interrupted - tell the model what to do differently.";
             sendAndRecord(session, { type: "info", text: interruptMsg2 });
             sendAndRecord(session, { type: "done", code: 0 });
           }
@@ -1186,21 +1134,17 @@ function createSDKBridge(opts) {
           console.error("[sdk-bridge] Query stream error for session " + session.localId + ":", errDetail);
           console.error("[sdk-bridge] Stack:", err.stack || "(no stack)");
 
-          // Check for conflicting Claude processes only on exit code 1
-          var isExitCode1 = err.exitCode === 1 || (err.message && err.message.indexOf("exited with code 1") !== -1);
-          var conflicts = isExitCode1 ? findConflictingClaude() : [];
+          var conflicts = findConflictingProcesses(session, err);
           if (conflicts.length > 0) {
-            console.error("[sdk-bridge] Found " + conflicts.length + " conflicting Claude process(es):", conflicts.map(function(c) { return "PID " + c.pid; }).join(", "));
+            console.error("[sdk-bridge] Found " + conflicts.length + " conflicting provider process(es):", conflicts.map(function(c) { return "PID " + c.pid; }).join(", "));
             sendAndRecord(session, {
               type: "process_conflict",
-              text: "Another Claude Code process is already running in this project.",
+              text: "Another provider process is already running in this project.",
               processes: conflicts,
             });
           } else {
             var errLower = errDetail.toLowerCase();
-            var isContextOverflow = errLower.indexOf("prompt is too long") !== -1
-              || errLower.indexOf("context_length") !== -1
-              || errLower.indexOf("maximum context length") !== -1;
+            var isContextOverflow = require("./yoke/errors").contextOverflow(errDetail);
             var isAuthError = isAuthErrorMessage(errDetail);
             if (isContextOverflow) {
               sendAndRecord(session, {
@@ -1247,7 +1191,7 @@ function createSDKBridge(opts) {
                 // chat message already sent above
               }
             } else {
-              sendAndRecord(session, { type: "error", text: "Claude process error: " + err.message });
+              sendAndRecord(session, { type: "error", text: "Provider process error: " + err.message });
             }
           }
           sendAndRecord(session, { type: "done", code: 1 });
@@ -1272,7 +1216,8 @@ function createSDKBridge(opts) {
       }
       if (session.messageQueue === myMessageQueue) session.messageQueue = null;
       if (session.abortController === myAbortController) session.abortController = null;
-      if (ownsRuntime) {
+      if (ownsRuntime && !responseRecovery.stopping(session)) {
+        responseRecovery.cancel(session);
         session.taskStopRequested = false;
         session.pendingPermissions = {};
         // Preserve only restored legacy MCP entries. Canonical Yoke requests
@@ -1321,7 +1266,7 @@ function createSDKBridge(opts) {
           }
         }
       }
-      if (!session.isProcessing && typeof opts.onSessionAvailable === "function") opts.onSessionAvailable(session);
+      if (!responseRecovery.stopping(session) && !session.isProcessing && typeof opts.onSessionAvailable === "function") opts.onSessionAvailable(session);
     }
   }
 
@@ -1329,20 +1274,16 @@ function createSDKBridge(opts) {
     if (session.queryInstance) return { query: session.queryInstance, isTemp: false, cleanup: function() {} };
 
     var handle;
+    var selectedAdapter = getAdapterForSession(session);
     try {
-      handle = await adapter.createQuery({
+      handle = await selectedAdapter.createQuery({
         cwd: cwd,
         resumeSessionId: session.cliSessionId,
         env: getRuntimeEnv(session),
-        adapterOptions: {
-          CLAUDE: {
-            settingSources: ["user", "project", "local"],
-            enableFileCheckpointing: true,
-          },
-        },
+        adapterOptions: require("./yoke/query-options").map(getAdapterForSession(session), { nativePermissionMode: "default" }),
       });
     } catch (e) {
-      sendAndRecord(session, { type: "error", text: "Failed to load Claude SDK: " + (e.message || e) });
+      sendAndRecord(session, { type: "error", text: "Failed to load provider session: " + (e.message || e) });
       throw e;
     }
 
@@ -1409,7 +1350,7 @@ function createSDKBridge(opts) {
       // abort the whole rewind instead of leaving local history trimmed
       // ahead of the real, un-rolled-back provider thread.
       if (!turnId) {
-        throw new Error("No turn id recorded for this turn; cannot roll back the Codex thread.");
+        throw new Error("No turn id recorded for this turn; cannot roll back the provider thread.");
       }
       await sessionAdapter.rollbackThread(session.cliSessionId, turnId, {
         linuxUser: getSessionLinuxUser(session) || undefined,
@@ -1425,6 +1366,8 @@ function createSDKBridge(opts) {
 
   async function forkSessionUnified(session, uuid) {
     var sessionAdapter = getAdapterForSession(session);
+    var localHistoryEndIndex = require("./session-fork-history").endIndex(session, uuid,
+      require("./yoke/provider-contract").resolve(sessionAdapter).forkHistoryBoundary);
     var result = await sessionAdapter.forkSession(session.cliSessionId, {
       upToMessageId: uuid,
       dir: cwd,
@@ -1433,8 +1376,10 @@ function createSDKBridge(opts) {
     if (!result || !result.sessionId) throw new Error("Fork returned no session id");
 
     // Adapters with rollbackThread (e.g. Codex) use local history copy
-    if (typeof sessionAdapter.rollbackThread === "function") {
-      return { sessionId: result.sessionId, useLocalHistory: true };
+    if (result.useLocalHistory === true || typeof sessionAdapter.rollbackThread === "function") {
+      var localFork = { sessionId: result.sessionId, useLocalHistory: true };
+      if (localHistoryEndIndex !== undefined) localFork.localHistoryEndIndex = localHistoryEndIndex;
+      return localFork;
     }
     // Claude: read history from CLI session files
     return { sessionId: result.sessionId, useLocalHistory: false };
@@ -1442,22 +1387,69 @@ function createSDKBridge(opts) {
 
   // Wrapper: marks the boot window so pushMessage can buffer instead of
   // dropping messages that arrive while createQuery is still awaiting.
-  async function startQuery(session, text, images, linuxUser, beforePush, onAccepted) {
+  async function startQuery(session, text, images, linuxUser, beforePush, onAccepted, retryState) {
+    if (opts.isLifecycleExecutionPaused && opts.isLifecycleExecutionPaused()) {
+      sendAndRecord(session, { type: "error", text: "Project execution is paused for lifecycle recovery. Reconcile the saved operation, or send a new owner message after restoring the registration." });
+      session.isProcessing = false; onProcessingChanged(); sendAndRecord(session, { type: "done", code: 1 }); return false;
+    }
+    if (session._responseRecoveryStopPending && !retryState) {
+      session.isProcessing = false;
+      onProcessingChanged();
+      sendAndRecord(session, { type: "error", text: "The previous Claude attempt has not confirmed stopped. Check the connection before sending this message again." });
+      sendAndRecord(session, { type: "done", code: 1 });
+      return false;
+    }
+    if (responseRecovery.stopping(session) && !retryState) return false;
     delete session._lastTurnInterrupted;
+    var payload = { text: text, images: images, linuxUser: linuxUser, beforePush: beforePush };
+    var recoveryState = responseRecovery.begin(session, payload, retryState);
+    if (recoveryState) recoveryState.handle = null;
+    var guardedPush = function() {
+      return !session.destroying && !session.taskStopRequested
+        && (!recoveryState || responseRecovery.valid(session, recoveryState) && !recoveryState.stopping)
+        && (typeof beforePush !== "function" || beforePush() === true);
+    };
+    guardedPush.exactProductDelivery = !!(beforePush && beforePush.exactProductDelivery);
     session._queryGeneration = (session._queryGeneration || 0) + 1;
     session._queryStarting = true;
+    var starting = startQueryInner(session, text, images, linuxUser, guardedPush, onAccepted, recoveryState);
+    if (recoveryState) recoveryState.starting = starting;
     try {
-      return await startQueryInner(session, text, images, linuxUser, beforePush, onAccepted);
+      var accepted = await starting;
+      if (accepted === false && (!recoveryState || !recoveryState.stopping)) {
+        responseRecovery.cancel(session);
+        session.isProcessing = false;
+        onProcessingChanged();
+      }
+      return accepted;
+    } catch (error) {
+      // Includes synchronous input queue failures, before stream consumption.
+      var failedHandle = session.queryInstance;
+      if (failedHandle) {
+        try { if (typeof failedHandle.abort === "function") failedHandle.abort(); } catch (e) {}
+        try { if (typeof failedHandle.close === "function") failedHandle.close(); } catch (e) {}
+      }
+      session.queryInstance = null;
+      session.abortController = null;
+      session.messageQueue = null;
+      session.isProcessing = false;
+      session._awaitingTurnResult = false;
+      session._queuedTurnCount = 0;
+      taskLifecycle.clearAll(session);
+      if (!recoveryState || !recoveryState.stopping) {
+        responseRecovery.cancel(session);
+        sendAndRecord(session, { type: "error", text: "The agent connection failed while delivering your message. Please retry or check the connection." });
+        sendAndRecord(session, { type: "done", code: 1 });
+        onProcessingChanged();
+        sm.broadcastSessionList();
+      }
+      return false;
     } finally {
       session._queryStarting = false;
-      if (!session.queryInstance && session.pendingPush && session.pendingPush.length) {
-        // The query never came up (auth/adapter failure already reported to
-        // the user). Drop the backlog rather than leaking it into a future
-        // unrelated query.
-        session.pendingPush = [];
-      }
-      if (!session.queryInstance && !session.isProcessing) session.taskStopRequested = false;
-      if (!session.isProcessing && typeof opts.onSessionAvailable === "function") opts.onSessionAvailable(session);
+      delete session._providerRecoveryWaiting;
+      if (!session.queryInstance && session.pendingPush && session.pendingPush.length) session.pendingPush = [];
+      if (!session.queryInstance && !session.isProcessing && !session._pendingMessageDrainPaused && !responseRecovery.stopping(session)) session.taskStopRequested = false;
+      if (!responseRecovery.stopping(session) && !session.isProcessing && typeof opts.onSessionAvailable === "function") opts.onSessionAvailable(session);
     }
   }
 
@@ -1501,7 +1493,7 @@ function createSDKBridge(opts) {
     };
   }
 
-  async function startQueryInner(session, text, images, linuxUser, beforePush, onAccepted) {
+  async function startQueryInner(session, text, images, linuxUser, beforePush, onAccepted, recoveryState) {
     var sessionRuntimeEnv = getRuntimeEnv(session);
     var resumedAtQueryStart = !!session.cliSessionId;
     async function ensureVendorReady(vendor) {
@@ -1653,7 +1645,8 @@ function createSDKBridge(opts) {
 
     // Ensure Linux user project directory exists (runs in parallel with worker boot)
     if (linuxUser) {
-      ensureLinuxUserProjectDir(linuxUser, session);
+      var preparation = require("./yoke/provider-contract").resolve(sessionAdapter).prepareIsolation;
+      if (typeof preparation === "function") preparation(linuxUser, session, cwd);
     }
 
     session.blocks = {};
@@ -1670,100 +1663,27 @@ function createSDKBridge(opts) {
       session.abortController = new AbortController();
     }
 
-    // Build Claude-specific adapter options
-    var claudeOpts = {
-      settingSources: ["user", "project", "local"],
-      includePartialMessages: true,
-      enableFileCheckpointing: true,
-      extraArgs: { "replay-user-messages": null },
-      promptSuggestions: true,
-      agentProgressSummaries: true,
-    };
-
-    // Per-loop settings override global defaults when present
     var ls = session.loopSettings || {};
-
-    if (sm.currentBetas && sm.currentBetas.length > 0) {
-      claudeOpts.betas = sm.currentBetas;
-    }
-    var thinkingMode = ls.thinking || sm.currentThinking;
-    if (thinkingMode === "disabled") {
-      claudeOpts.thinking = { type: "disabled" };
-    } else if (thinkingMode === "budget") {
-      var budgetTokens = ls.thinkingBudget || sm.currentThinkingBudget;
-      if (budgetTokens) claudeOpts.thinking = { type: "enabled", budgetTokens: budgetTokens };
-    } else {
-      // Adaptive (the default). Request summarized display explicitly:
-      // current models default thinking.display to "omitted", which streams
-      // thinking blocks whose text is an EMPTY string -- the UI's thinking
-      // section stays blank even though thinking happens and is billed.
-      // (SDK ThinkingAdaptive: { type: "adaptive", display?: "summarized" | "omitted" })
-      claudeOpts.thinking = { type: "adaptive", display: "summarized" };
-    }
-
-    if (ls.permissionMode) {
-      session._loopPermissionMode = ls.permissionMode;
-    }
-
-    // Pass through any extra SDK settings from LOOP.json
-    if (ls.disableAllHooks !== undefined) {
-      claudeOpts.settings = Object.assign({}, claudeOpts.settings || {}, { disableAllHooks: ls.disableAllHooks });
-    }
-
-    if (dangerouslySkipPermissions || (session.mode === "tui" && session.dangerouslySkipPermissions)) {
-      claudeOpts.allowDangerouslySkipPermissions = true;
-      claudeOpts.permissionMode = "bypassPermissions";
-    } else {
-      var globalMode = session.permissionMode || sm.currentPermissionMode || "default";
-      var effectiveDefault;
-      // GUI full access stays inside Clay's canUseTool callback. Passing the
-      // SDK bypass mode would require its process-level dangerous escape hatch
-      // and would skip Clay's permission policy entirely.
-      if (globalMode === "bypassPermissions") effectiveDefault = "default";
-      else if (session.acceptEditsAfterStart) effectiveDefault = "acceptEdits";
-      else effectiveDefault = globalMode;
-      var modeToApply = session._loopPermissionMode || effectiveDefault;
-      // Always set permissionMode explicitly, including "default". SDK
-      // 0.3.286+ leaves an omitted permissionMode to Claude Code itself,
-      // which can apply a settings defaultMode or start in auto mode on
-      // third-party providers / with telemetry off -- silently widening
-      // past Clay's Ask policy. Sending "default" keeps the SDK's own
-      // decision point at the same "default" behavior Clay has always run
-      // under: a tool the SDK's own allowed/denied rules or allowedTools
-      // list already settles is not re-asked, but anything left undecided
-      // still reaches Clay's canUseTool callback, as before.
-      claudeOpts.permissionMode = modeToApply || "default";
-    }
-    if (session.youCurator) {
-      claudeOpts.permissionMode = "default";
-      claudeOpts.allowDangerouslySkipPermissions = false;
-    }
-    // Clear one-shot acceptEditsAfterStart regardless of which branch ran above,
-    // so the flag does not linger into subsequent turns.
-    if (session.acceptEditsAfterStart) delete session.acceptEditsAfterStart;
-    if (session.cliSessionId && session.lastRewindUuid) {
-      claudeOpts.resumeSessionAt = session.lastRewindUuid;
-      delete session.lastRewindUuid;
-      sm.saveSessionFile(session);
-    }
-
-    // Pass linuxUser to adapter for worker-based queries
+    if (ls.permissionMode) session._loopPermissionMode = ls.permissionMode;
+    var permissionMode = session.permissionMode || sm.currentPermissionMode || "default";
+    var nativeMode = permissionMode === "bypassPermissions" ? "default" : session.acceptEditsAfterStart ? "acceptEdits" : permissionMode;
+    var isolationHome = null;
     if (linuxUser) {
-      claudeOpts.linuxUser = linuxUser;
-      claudeOpts.singleTurn = !!session.singleTurn;
-      try {
-        claudeOpts.originalHome = require("./os-users").resolveOsUserInfo(linuxUser).home;
-      } catch (e) {
-        claudeOpts.originalHome = null;
-      }
-      claudeOpts.projectPath = session.cwd || null;
-      claudeOpts._perfT0 = t0;
-      // Pass previous worker state for reuse
-      if (session._adapterWorkerState) {
-        claudeOpts._workerState = session._adapterWorkerState;
-        session._adapterWorkerState = null;
-      }
-    }
+      try { isolationHome = require("./os-users").resolveOsUserInfo(linuxUser).home; } catch (error) {}
+    }
+    var executionIntent = {
+      settings: sm, permissionMode: permissionMode, nativePermissionMode: session._loopPermissionMode || nativeMode,
+      nativeBypass: dangerouslySkipPermissions || session.mode === "tui" && session.dangerouslySkipPermissions,
+      readOnly: !!session.youCurator, betas: sm.currentBetas,
+      thinking: { mode: ls.thinking || sm.currentThinking, budget: ls.thinkingBudget || sm.currentThinkingBudget },
+      disableHooks: ls.disableAllHooks, resumeAt: session.cliSessionId && session.lastRewindUuid || undefined,
+      singleTurn: !!session.singleTurn, startedAt: t0,
+      isolation: { user: linuxUser, home: isolationHome, projectPath: session.cwd || null, workerState: session._adapterWorkerState },
+      sessionBridge: null,
+    };
+    if (session.acceptEditsAfterStart) delete session.acceptEditsAfterStart;
+    if (executionIntent.resumeAt) { delete session.lastRewindUuid; sm.saveSessionFile(session); }
+    if (linuxUser && session._adapterWorkerState) session._adapterWorkerState = null;
 
     // Pick a model from the session or its vendor-specific default, then
     // validate it against the session vendor's known model list.
@@ -1789,20 +1709,21 @@ function createSDKBridge(opts) {
       sm.saveSessionFile(session);
     }
 
-    var codexConfig = getCodexConfig(sm);
-    var kiroConfig = getKiroConfig(sm);
     session._sdkQueryGeneration = Number(session._sdkQueryGeneration || 0) + 1;
     // Individual feature modules own their transport capability checks. Do not
     // suppress unrelated session tools merely because one feature cannot be
     // delivered by this provider.
     var sessionToolDefs = getSessionToolDefs(session) || [];
     var queryGeneration = Number(session._sdkQueryGeneration || 0);
+    executionIntent.sessionBridge = getAcpMcpServers(session);
+    var queryContract = yoke.sessionTools.contract(sessionAdapter);
+    function needsCatalogRecovery(family, version) {
+      return yoke.sessionTools.needsRecovery(sessionAdapter, session, family, version);
+    }
     var hasYouCatalog = sessionToolDefs.some(function (tool) { return tool.name === "search_user_knowledge"; });
-    var recoverCodexYouTools = sessionAdapter.vendor === "codex" && !!session.cliSessionId
-      && hasYouCatalog && Number(session.codexYouToolCatalogVersion || 0) < 1;
+    var recoverYouTools = needsCatalogRecovery("knowledge", 1) && hasYouCatalog;
     var hasLinearCatalog = sessionToolDefs.some(function (tool) { return tool.name === "link_session_linear"; });
-    var recoverCodexLinearTools = sessionAdapter.vendor === "codex" && !!session.cliSessionId
-      && hasLinearCatalog && Number(session.codexLinearToolCatalogVersion || 0) < 1 && canUseSessionTools(session) === true;
+    var recoverLinearTools = needsCatalogRecovery("linear", 1) && hasLinearCatalog && canUseSessionTools(session) === true;
     var hasIssueCatalog = false;
     for (var issueToolIndex = 0; issueToolIndex < sessionToolDefs.length; issueToolIndex++) {
       if (sessionToolDefs[issueToolIndex].name === "create_issue") {
@@ -1811,24 +1732,23 @@ function createSDKBridge(opts) {
       }
     }
     var hasSharedBrowserCatalog = sessionToolDefs.some(function (definition) { return definition.name === "shared_browser"; });
-    var recoverCodexBrowserTools = sessionAdapter.vendor === "codex" && !!session.cliSessionId
-      && hasSharedBrowserCatalog && Number(session.codexSharedBrowserToolCatalogVersion || 0) < 5;
-    var recoverCodexIssueTools = sessionAdapter.vendor === "codex"
-      && !!session.cliSessionId
-      && hasIssueCatalog
-      && Number(session.codexIssuesToolCatalogVersion || 0) < 1;
+    var recoverBrowserTools = needsCatalogRecovery("browser", 6) && hasSharedBrowserCatalog;
+    var recoverIssueTools = needsCatalogRecovery("issues", 1) && hasIssueCatalog;
     function queryContextAvailable() {
+      if (queryRetired()) return false;
       if (Number(session._sdkQueryGeneration || 0) !== queryGeneration) return false;
       if (sm && sm.sessions && typeof sm.sessions.get === "function" && sm.sessions.get(session.localId) !== session) return false;
       return canUseSessionTools(session) === true;
     }
+    var hasMateScheduleTool = sessionToolDefs.some(function (tool) { return yoke.sessionTools.MATE_SCHEDULE_TOOLS.indexOf(tool.name) !== -1; });
+    var recoverMateSchedules = needsCatalogRecovery() && hasMateScheduleTool && queryContextAvailable();
     var hasScheduleTool = false;
     var hasScheduleInterviewTool = false;
     var scheduleInterviewActive = null;
     var scheduleQuestionLimit = null;
     for (var sessionToolIndex = 0; sessionToolIndex < sessionToolDefs.length; sessionToolIndex++) {
       if (yoke.sessionTools.SCHEDULE_TOOLS.indexOf(sessionToolDefs[sessionToolIndex].name) !== -1) hasScheduleTool = true;
-      if (sessionToolDefs[sessionToolIndex].name === "begin_scheduled_task_interview") {
+      if (["begin_scheduled_task_interview", "begin_mate_schedule_interview", "begin_schedule_control_interview"].indexOf(sessionToolDefs[sessionToolIndex].name) >= 0) {
         hasScheduleInterviewTool = true;
         scheduleInterviewActive = sessionToolDefs[sessionToolIndex].scheduleInterviewActive || null;
         scheduleQuestionLimit = sessionToolDefs[sessionToolIndex].structuredQuestionLimit || null;
@@ -1838,10 +1758,10 @@ function createSDKBridge(opts) {
     var activeLoopInterview = !isDriverOperatedSession(session) && !session.loopInterviewHandoff && !activeRun && !!loopInterview.activeInterviewId(session);
     var structuredInputSession = hasScheduleInterviewTool || activeLoopInterview || (!isDriverOperatedSession(session) && session.ralphCraftingMode === true && session.loop && session.loop.role === "crafting");
     var requestedUserInputMode = session.debateSetupMode || session.mateCreationMode ? "fallback" : "auto";
-    if (structuredInputSession || sessionAdapter.vendor === "codex") requestedUserInputMode = "fallback";
+    if (structuredInputSession) requestedUserInputMode = "fallback";
+    if (requestedUserInputMode === "auto" && queryContract.defaultUserInputMode) requestedUserInputMode = queryContract.defaultUserInputMode;
     var selectedUserInputMode = yoke.userInput.selectMode(sessionAdapter, requestedUserInputMode);
-    var recoverCodexQuestionTools = sessionAdapter.vendor === "codex" && !!session.cliSessionId
-      && Number(session.codexUserInputToolCatalogVersion || 0) < 1 && queryContextAvailable();
+    var recoverQuestionTools = needsCatalogRecovery("questions", 1) && queryContextAvailable();
     function structuredInputContextAvailable() {
       if (!queryContextAvailable()) return false;
       // A schedule-triggered fallback shares the schedule feature's live
@@ -1860,9 +1780,10 @@ function createSDKBridge(opts) {
       return "Ask exactly one question at a time, wait for the answer, then ask the next question.";
     }
     var sessionUserInputHandler = function(request, respond) {
-      if (!structuredInputContextAvailable()) {
+      if (queryRetired() || !structuredInputContextAvailable()) {
         return respond.cancel("This structured-input request belongs to an unavailable or older query.");
       }
+      responseRecovery.progress(session);
       var questionError = scheduleQuestionError(request);
       if (questionError) return respond.cancel(questionError);
       if (request.presentation === "elicitation" && request.diagnostics && request.diagnostics.elicitation) {
@@ -1882,21 +1803,33 @@ function createSDKBridge(opts) {
       return opts.onUserInputRequest(session, request, respond);
     };
     var localMcpServers = getMcpServers(session);
-    if (sessionAdapter.vendor === "claude" && hasScheduleTool && typeof sessionAdapter.createToolServer === "function") {
+    if (queryContract.toolTransport === "sdk-mcp" && (hasScheduleTool || hasMateScheduleTool)
+        && typeof sessionAdapter.createToolServer !== "function") {
+      throw new Error("The adapter cannot mount native schedule tools without createToolServer.");
+    }
+    if (queryContract.toolTransport === "sdk-mcp" && hasScheduleTool) {
       var scheduledTaskToolDefs = [];
       for (var scheduledToolIndex = 0; scheduledToolIndex < sessionToolDefs.length; scheduledToolIndex++) {
         if (yoke.sessionTools.SCHEDULE_TOOLS.indexOf(sessionToolDefs[scheduledToolIndex].name) !== -1) scheduledTaskToolDefs.push(sessionToolDefs[scheduledToolIndex]);
       }
       if (scheduledTaskToolDefs.length) {
         var scheduledTaskServer = sessionAdapter.createToolServer({ name: "clay-scheduled-tasks", version: "1.0.0", tools: scheduledTaskToolDefs });
-        if (scheduledTaskServer) {
-          localMcpServers = Object.assign({}, localMcpServers || {});
-          localMcpServers["clay-scheduled-tasks"] = scheduledTaskServer;
-        }
+        if (!scheduledTaskServer) throw new Error("The adapter could not mount scheduled-task tools.");
+        localMcpServers = Object.assign({}, localMcpServers || {});
+        localMcpServers["clay-scheduled-tasks"] = scheduledTaskServer;
       }
     }
+    if (queryContract.toolTransport === "sdk-mcp" && hasMateScheduleTool) {
+      localMcpServers = Object.assign({}, localMcpServers || {});
+      localMcpServers["clay-mate-schedules"] = sessionAdapter.createToolServer({ name: "clay-mate-schedules", version: "1.0.0",
+        tools: sessionToolDefs.filter(function (tool) { return yoke.sessionTools.MATE_SCHEDULE_TOOLS.indexOf(tool.name) !== -1; }) });
+      if (!localMcpServers["clay-mate-schedules"]) throw new Error("The adapter could not mount Mate schedule tools.");
+    }
     if (selectedUserInputMode === "fallback") {
       var userInputServer = yoke.userInput.createFallbackServer(sessionAdapter, sessionUserInputHandler, { force: true, maxQuestions: scheduleQuestionLimit });
+      if (queryContract.toolTransport === "sdk-mcp" && !userInputServer) {
+        throw new Error("The adapter could not mount structured-input tools.");
+      }
       if (userInputServer) {
         localMcpServers = Object.assign({}, localMcpServers || {});
         localMcpServers[userInputServer.name || "yoke-user-input"] = userInputServer;
@@ -1931,6 +1864,12 @@ function createSDKBridge(opts) {
       return snapshotDef;
     }
 
+    var externalQueryBridge = require('./mcp-query-bridge').createQueryBridge({ valid: queryContextAvailable,
+      getServers: function () { return getRemoteMcpServers ? getRemoteMcpServers(session) || {} : {}; } });
+    var externalToolDefs = queryContract.externalToolTransport === "dynamic" ? externalQueryBridge.dynamicDefs() : [];
+    if (externalToolDefs.length) { sessionToolDefs = sessionToolDefs.concat(externalToolDefs); queryToolSnapshots.set(session, { generation: queryGeneration, defs: sessionToolDefs.slice() }); }
+    var recoverExternalTools = needsCatalogRecovery() && (externalToolDefs.length > 0 || isMate);
+
     // Give fresh queries an immediate provisional label. The visible user
     // message in history wins over `text`, which may contain an internal
     // provider wrapper rather than what the person typed.
@@ -1945,6 +1884,10 @@ function createSDKBridge(opts) {
     }
 
     var modelSwitchGeneration = session._queryGeneration;
+    function queryRetired() {
+      return Number(session._sdkQueryGeneration || 0) !== queryGeneration || session.taskStopRequested
+        || session.destroying || responseRecovery.stopping(session) || (handle && session.queryInstance !== handle);
+    }
     var queryOpts = {
       onModelSwitch: function(change) {
         if (session._queryGeneration !== modelSwitchGeneration || session.taskStopRequested) return;
@@ -1959,7 +1902,7 @@ function createSDKBridge(opts) {
       clayBridgeToken: clayBridgeToken,
       linuxUser: linuxUser || undefined,
       env: sessionRuntimeEnv,
-      skillOptions: getSessionSkillOptions(session),
+      skillOptions: require("./session-skill-scope").bind(session, sm.sessions, getSessionSkillOptions(session), queryContextAvailable, usersModule.isMultiUser()),
       // appendSystemPrompt, NOT systemPrompt: a plain-string systemPrompt
       // REPLACES the entire Claude Code system prompt (sdk.d.ts:2096), which
       // would strip the driver session down to the two-sentence pair preset.
@@ -1967,7 +1910,7 @@ function createSDKBridge(opts) {
       // codex/kiro: prepend to the first message).
       appendSystemPrompt: [
         typeof opts.getSessionSystemPrompt === "function" ? opts.getSessionSystemPrompt(session) : "",
-        sessionAdapter.vendor === "codex" && queryContextAvailable() ? codexQuestionGuidance() : "",
+        typeof queryContract.questionGuidance === "function" && queryContextAvailable() ? queryContract.questionGuidance() : "",
       ].filter(Boolean).join("\n\n") || undefined,
       model: queryModel,
       // Effort is remembered per vendor and clamped to the session vendor's
@@ -1984,10 +1927,22 @@ function createSDKBridge(opts) {
       toolServers: mergedMcpServers,
       toolServerDescriptors: extractMcpDescriptors(mergedMcpServers) || undefined,
       dynamicTools: sessionToolDefs,
-      // Codex persists dynamic tools with a thread. A stale authorized Driver
+      // Conversation-scoped catalogs persist definitions. A stale authorized Driver
       // gets this exact-query bridge; its handlers still reauthorize live.
-      sessionMcpServer: (recoverCodexIssueTools || recoverCodexQuestionTools || recoverCodexBrowserTools || recoverCodexLinearTools || recoverCodexYouTools) ? getCodexSessionMcpServer(session, queryGeneration) : undefined,
+      sessionMcpServer: (recoverMateSchedules || recoverIssueTools || recoverQuestionTools || recoverBrowserTools || recoverLinearTools || recoverYouTools || recoverExternalTools) ? getSessionMcpServer(session, queryGeneration) : undefined,
+      onRecoveryAdmission: function(waiting) {
+        if (!queryContextAvailable()) return;
+        if (waiting) session._providerRecoveryWaiting = queryGeneration;
+        else delete session._providerRecoveryWaiting;
+      },
+      onRecoveryWaiting: function(waiting) {
+        if (!queryContextAvailable()) return;
+        sendAndRecord(session, { type: 'informational', level: 'info', content: waiting
+          ? 'Tool recovery is waiting for this conversation’s runtime to become safely available. Your message is retained; Stop cancels the wait.'
+          : 'Tool recovery is ready. Continuing your retained message.' });
+      },
       callDynamicTool: function (toolName, args) {
+        if (queryRetired() || !queryContextAvailable()) return Promise.reject(new Error("This session tool query is no longer available."));
         var toolDef = findSessionToolDef(toolName);
         if (toolDef && typeof toolDef.handler === "function") {
           return toolDef.handler(args || {});
@@ -1997,7 +1952,10 @@ function createSDKBridge(opts) {
       resumeSessionId: session.cliSessionId || undefined,
       abortController: linuxUser ? undefined : session.abortController,
       canUseTool: function(toolName, input, toolOpts) {
-        var nativeQuestionError = toolName === "AskUserQuestion" ? scheduleQuestionError(input) : null;
+        if (queryRetired()) return { behavior: "deny", message: "This attempt has stopped." };
+        responseRecovery.progress(session);
+        var questionInput = yoke.userInput.toolQuestions(sessionAdapter, toolName, input);
+        var nativeQuestionError = questionInput ? scheduleQuestionError(questionInput) : null;
         if (nativeQuestionError) return { behavior: "deny", message: nativeQuestionError };
         var permissionName = toolName;
         var permissionToolDef = findSessionToolDef(toolName);
@@ -2005,7 +1963,10 @@ function createSDKBridge(opts) {
         return handleCanUseTool(session, permissionName, input, toolOpts);
       },
       preToolUsePolicy: function(toolName, input) {
-        var nativeQuestionError = toolName === "AskUserQuestion" ? scheduleQuestionError(input) : null;
+        if (queryRetired()) return Promise.resolve({ behavior: "deny", message: "This attempt has stopped." });
+        responseRecovery.progress(session);
+        var questionInput = yoke.userInput.toolQuestions(sessionAdapter, toolName, input);
+        var nativeQuestionError = questionInput ? scheduleQuestionError(questionInput) : null;
         if (nativeQuestionError) return Promise.resolve({ behavior: "deny", message: nativeQuestionError });
         var permissionName = toolName;
         var permissionToolDef = findSessionToolDef(toolName);
@@ -2018,47 +1979,45 @@ function createSDKBridge(opts) {
       validateUserInputRequest: scheduleQuestionError,
       userInputMode: selectedUserInputMode,
       onElicitation: function(request, elicitOpts) {
+        if (queryRetired()) return Promise.resolve({ action: "cancel" });
+        responseRecovery.progress(session);
         return handleElicitation(session, request, elicitOpts);
       },
       onUserDialog: function(dialogRequest, dialogOpts) {
+        if (queryRetired()) return Promise.resolve({ behavior: "cancelled" });
+        responseRecovery.progress(session);
         return handleUserDialog(session, dialogRequest, dialogOpts);
       },
       callMcpTool: function(serverName, toolName, args) {
+        if (queryRetired()) return Promise.reject(new Error("This attempt has stopped."));
+        responseRecovery.progress(session);
         return callMcpToolHandler(mergedMcpServers, serverName, toolName, args);
       },
-      adapterOptions: {
-        CLAUDE: claudeOpts,
-        CODEX: {
-          // Always use "never" (auto-approve) because Clay handles tool
-          // permissions via its own UI (checkToolWhitelist + handleCanUseTool).
-          // Codex's native approval prompts are terminal-based and cannot be
-          // relayed through Clay's web UI, causing MCP tool calls to hang.
-          approvalPolicy: "never",
-          sandboxMode: session.youCurator ? "read-only" : codexConfig.sandbox,
-          webSearchMode: session.youCurator ? "disabled" : codexConfig.webSearch,
-        },
-        ACP: {
-          mcpServers: getAcpMcpServers(session),
-        },
-        ANTIGRAVITY: {
-          dangerouslySkipPermissions: dangerouslySkipPermissions
-            || session.permissionMode === "bypassPermissions",
-        },
-        KIRO: {
-          engine: kiroConfig.engine,
-          mode: kiroConfig.mode,
-          // ACP accepts additional stdio MCP servers per session. The bridge is
-          // bound to this Clay session so partner calls cannot leak across
-          // concurrent Kiro sessions or users.
-          mcpServers: getAcpMcpServers(session),
-        },
-      },
+      adapterOptions: require("./yoke/query-options").map(sessionAdapter, executionIntent),
     };
 
+    if (recoveryState) {
+      if (!recoveryState.context) recoveryState.context = { appendSystemPrompt: queryOpts.appendSystemPrompt, model: queryOpts.model, effort: queryOpts.effort };
+      Object.assign(queryOpts, recoveryState.context);
+    }
     var handle;
+    var startupHandle = session.queryInstance;
     console.log("[sdk-bridge] calling adapter.createQuery... vendor=" + sessionAdapter.vendor);
     try {
       handle = await sessionAdapter.createQuery(queryOpts);
+      // A guarded delivery must still own the exact startup after provider
+      // creation. Never replace a newer handle or publish to a deleted target.
+      if (beforePush && beforePush.exactProductDelivery) {
+        var startupCurrent = false;
+        try { startupCurrent = sm.sessions.get(session.localId) === session && session.queryInstance === startupHandle && Number(session._sdkQueryGeneration || 0) === queryGeneration && beforePush() === true; } catch (guardError) {}
+        if (!startupCurrent) {
+          try { if (handle.abort) handle.abort(); } catch (abortError) {}
+          try { if (handle.close) handle.close(); } catch (closeError) {}
+          if (session.queryInstance === startupHandle) session.isProcessing = false;
+          return false;
+        }
+      }
+      if (recoveryState) recoveryState.handle = handle;
       console.log("[sdk-bridge] createQuery returned handle, vendor=" + sessionAdapter.vendor);
       // SDK accepted the explicit title. Provisional labels remain eligible
       // for semantic generation after the first Home exchange (or the normal
@@ -2078,6 +2037,7 @@ function createSDKBridge(opts) {
       console.error("[sdk-bridge] Failed to create query for session " + session.localId + ":", e.message || e);
       console.error("[sdk-bridge] cliSessionId:", session.cliSessionId, "resume:", !!session.cliSessionId);
       console.error("[sdk-bridge] Stack:", e.stack || "(no stack)");
+      if (beforePush && beforePush.exactProductDelivery && (sm.sessions.get(session.localId) !== session || session.queryInstance !== startupHandle || Number(session._sdkQueryGeneration || 0) !== queryGeneration)) return false;
       session.isProcessing = false;
       session._awaitingTurnResult = false;
       session._queuedTurnCount = 0;
@@ -2112,11 +2072,9 @@ function createSDKBridge(opts) {
 
     // Store QueryHandle on session for iteration and control.
     session.queryInstance = handle;
-    // Capabilities come from the installed query handle, never a model-name
-    // table. `acceptEdits` and MCP overrides are Claude SDK semantics; a
-    // vendor may expose the generic setter without implementing either.
-    session.permissionCapabilities = require("./session-permission-mode").capabilities(session, sm.defaultVendor);
-    session.permissionCapabilities.mcpOverride = sessionAdapter.vendor === "claude" && typeof handle.setMcpPermissionModeOverride === "function";
+    // An installed setter and the adapter's explicit protocol contract are
+    // both required; generic handle stubs do not establish runtime support.
+    session.permissionCapabilities = require("./session-permission-mode").capabilities(session, sm.defaultVendor, sessionAdapter);
     session.effectivePermissionMode = null;
     sm.saveSessionFile(session);
     sendToSession(session, { type: "config_state", model: session.model || defaultModelForVendor(session.vendor || "claude"), vendor: session.vendor || "claude", sessionId: session.localId, mode: session.permissionMode || sm.currentPermissionMode || "default", effectivePermissionMode: null, permissionCapabilities: session.permissionCapabilities, mcpPermissionModeOverrides: session.mcpPermissionModeOverrides || {}, effort: session.effort || sm.currentEffort || "medium", betas: sm.currentBetas || [] });
@@ -2132,6 +2090,7 @@ function createSDKBridge(opts) {
     }
 
     if (typeof beforePush === "function" && beforePush() !== true) {
+      try { if (typeof handle.abort === "function") handle.abort(); } catch (e) {}
       try { handle.close(); } catch (e) {}
       if (session.queryInstance === handle) session.queryInstance = null;
       session.messageQueue = null;
@@ -2141,6 +2100,13 @@ function createSDKBridge(opts) {
       session._queuedTurnCount = 0;
       taskLifecycle.clearAll(session);
       onProcessingChanged();
+      if (recoveryState && !responseRecovery.stopping(session)) {
+        sendAndRecord(session, { type: "thinking_stop" });
+        sendAndRecord(session, { type: session.taskStopRequested ? "info" : "error", text: session.taskStopRequested
+          ? "Stopped before sending your message."
+          : "This request is no longer eligible for delivery. Please review it and send it again." });
+        sendAndRecord(session, { type: "done", code: session.taskStopRequested ? 0 : 1 });
+      }
       sm.broadcastSessionList();
       return false;
     }
@@ -2192,32 +2158,27 @@ function createSDKBridge(opts) {
     }
 
     session.lastActivityAt = Date.now();
-    var codexCatalogCandidate = null;
-    if (sessionAdapter.vendor === "codex" && !resumedAtQueryStart) {
+    var catalogCandidate = null;
+    if (queryContract.catalogLifetime === "conversation" && typeof queryContract.recordCatalog === "function" && !resumedAtQueryStart) {
       var requiredCatalogTools = { begin_scheduled_task_interview: false, propose_scheduled_task: false, list_scheduled_tasks: false, read_scheduled_task: false, update_scheduled_task: false, report_scheduled_task_outcome: false, ask_user_questions: false };
       for (var catalogToolIndex = 0; catalogToolIndex < sessionToolDefs.length; catalogToolIndex++) {
         if (Object.prototype.hasOwnProperty.call(requiredCatalogTools, sessionToolDefs[catalogToolIndex].name)) requiredCatalogTools[sessionToolDefs[catalogToolIndex].name] = true;
       }
       var completeInterviewCatalog = requiredCatalogTools.begin_scheduled_task_interview && requiredCatalogTools.propose_scheduled_task && requiredCatalogTools.list_scheduled_tasks && requiredCatalogTools.read_scheduled_task && requiredCatalogTools.update_scheduled_task && requiredCatalogTools.ask_user_questions;
       if (completeInterviewCatalog || requiredCatalogTools.report_scheduled_task_outcome) {
-        codexCatalogCandidate = { generation: queryGeneration, version: yoke.sessionTools.CODEX_CATALOG_VERSION };
+        catalogCandidate = { generation: queryGeneration, versions: { schedules: yoke.sessionTools.SCHEDULE_CATALOG_VERSION } };
       }
-      if (requiredCatalogTools.ask_user_questions) {
-        codexCatalogCandidate = Object.assign({}, codexCatalogCandidate || {}, { generation: queryGeneration, userInputVersion: 1 });
-      }
-      if (hasYouCatalog) codexCatalogCandidate = Object.assign({}, codexCatalogCandidate || {}, { generation: queryGeneration, youVersion: 1 });
-      if (hasLinearCatalog) codexCatalogCandidate = Object.assign({}, codexCatalogCandidate || {}, { generation: queryGeneration, linearVersion: 1 });
-      if (hasSharedBrowserCatalog) {
-        codexCatalogCandidate = Object.assign({}, codexCatalogCandidate || {}, { generation: queryGeneration, sharedBrowserVersion: 5 });
-      }
-      if (hasIssueCatalog) {
-        codexCatalogCandidate = Object.assign({}, codexCatalogCandidate || {}, {
-          generation: queryGeneration,
-          issuesVersion: 1,
-        });
+      function markCatalog(family, version) {
+        if (!catalogCandidate) catalogCandidate = { generation: queryGeneration, versions: {} };
+        catalogCandidate.versions[family] = version;
       }
+      if (requiredCatalogTools.ask_user_questions) markCatalog("questions", 1);
+      if (hasYouCatalog) markCatalog("knowledge", 1);
+      if (hasLinearCatalog) markCatalog("linear", 1);
+      if (hasSharedBrowserCatalog) markCatalog("browser", 6);
+      if (hasIssueCatalog) markCatalog("issues", 1);
     }
-    session.streamPromise = processQueryStream(session, codexCatalogCandidate).catch(function(err) {
+    session.streamPromise = processQueryStream(session, catalogCandidate, queryContract).catch(function(err) {
     });
     return true;
   }
@@ -2229,6 +2190,19 @@ function createSDKBridge(opts) {
   // dropped messages in both gap windows, which is what made a session show
   // the processing indicator without ever answering until a second send.
   function pushMessage(session, text, images, deliveryMeta) {
+    if (session._responseRecoveryStopPending && !responseRecovery.stopping(session)) return false;
+    function trackDelivery() {
+      responseRecovery.enqueue(session, {
+        text: text, images: images, linuxUser: session.lastLinuxUser || null,
+      });
+    }
+    if (responseRecovery.stopping(session)) {
+      // Keep admission serialized while the old execution is terminating.
+      session.pendingPush = session.pendingPush || [];
+      session.pendingPush.push(Object.assign({ text: text, images: images || null }, deliveryMeta || {}));
+      trackDelivery();
+      return true;
+    }
     session.lastActivityAt = Date.now();
     if (session._runtimeRefreshRequested && !session._queryStarting) {
       session._runtimeRefreshRequested = false;
@@ -2255,6 +2229,8 @@ function createSDKBridge(opts) {
         console.error("[sdk-bridge] QueryHandle rejected message for session " + session.localId + ":", e.message || e);
       }
       if (delivered) {
+        require('./sdk-foreground-admission').take(session);
+        trackDelivery();
         delete session._lastTurnInterrupted;
         if (session._awaitingTurnResult) {
           session._queuedTurnCount = (session._queuedTurnCount || 0) + 1;
@@ -2279,6 +2255,7 @@ function createSDKBridge(opts) {
     if (session._queryStarting) {
       session.pendingPush = session.pendingPush || [];
       session.pendingPush.push(Object.assign({ text: text, images: images || null }, deliveryMeta || {}));
+      trackDelivery();
       return true;
     }
     return false;
@@ -2359,65 +2336,8 @@ function createSDKBridge(opts) {
   // Detect which vendor binaries are installed for this user.
   // In multi-user mode, runs checks as the specific Linux user.
   function detectInstalledVendors(linuxUser) {
-    var execFileSync = require("child_process").execFileSync;
-    var fs = require("fs");
-    var result = [];
-
-    function tryLookup(name) {
-      try {
-        if (linuxUser) {
-          execFileSync("su", ["-", linuxUser, "-c", "which " + name], { timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-        } else {
-          if (process.platform === "win32") execFileSync("where", [name], { timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-          else execFileSync("which", [name], { timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-        }
-        return true;
-      } catch (e) {
-        return false;
-      }
-    }
-
-    // Claude: check if binary is in PATH
-    if (tryLookup(yoke.getVendorInfo("claude").binaryName)) result.push("claude");
-
-    // Codex: check bundled binary or PATH
-    var codexBin = null;
-    try {
-      codexBin = require("./yoke/codex-app-server").findCodexPath();
-    } catch (e) {}
-    if ((codexBin && fs.existsSync(codexBin)) || tryLookup(yoke.getVendorInfo("codex").binaryName)) result.push("codex");
-
-    var subprocessVendorKeys = ["antigravity", "opencode", "kimi", "grok", "copilot", "qwen", "junie"];
-    var acpProfiles = require("./yoke/acp-agent-profiles");
-    for (var subprocessVendorIndex = 0; subprocessVendorIndex < subprocessVendorKeys.length; subprocessVendorIndex++) {
-      var subprocessVendor = subprocessVendorKeys[subprocessVendorIndex];
-      var subprocessInfo = yoke.getVendorInfo(subprocessVendor);
-      if (!linuxUser || subprocessInfo.osUserIsolation) {
-        if (subprocessVendor === "antigravity") {
-          if (tryLookup(subprocessInfo.binaryName)) result.push(subprocessVendor);
-        } else {
-          var acpProfile = acpProfiles.getAcpAgentProfile(subprocessVendor);
-          if (acpProfiles.findAcpAgentPath(acpProfile)) result.push(subprocessVendor);
-        }
-      } else {
-        console.log("[sdk-bridge] " + subprocessInfo.displayName + " hidden for OS-isolated user " + linuxUser + ": per-user spawning is not implemented");
-      }
-    }
-
-    // Kiro has no per-user ACP spawn path yet. Do not advertise the daemon's
-    // binary to an OS-isolated user, even if that user also has Kiro installed.
-    var kiroInfo = yoke.getVendorInfo("kiro");
-    if (!linuxUser || kiroInfo.osUserIsolation) {
-      var kiroBin = null;
-      try {
-        kiroBin = require("./yoke/kiro-acp-server").findKiroPath();
-      } catch (e) {}
-      if ((kiroBin && fs.existsSync(kiroBin)) || tryLookup(kiroInfo.binaryName)) result.push("kiro");
-    } else {
-      console.log("[sdk-bridge] " + kiroInfo.displayName + " hidden for OS-isolated user " + linuxUser + ": per-user spawning is not implemented");
-    }
-
-    return result;
+    var installed = require("./yoke/discovery").installed({ user: linuxUser });
+    return Object.keys(installed).filter(function(vendor) { return installed[vendor]; });
   }
 
   function getAvailableVendors(linuxUser) {
@@ -2489,7 +2409,20 @@ function createSDKBridge(opts) {
     sendModelInfoForVendor(null, defaultVendor, defaultModelForVendor(defaultVendor));
   }
 
-  async function setModel(session, model) {
+  async function setModel(session, model, options) {
+    if (options && typeof options.revalidate === "function") {
+      var vendor = session.vendor || sm.defaultVendor || "claude";
+      return require("./session-config-transition").applySessionConfig({
+        sm: sm, session: session, revalidate: options.revalidate, method: "setModel", nativeValue: model, changes: { model: model },
+        publish: function () {
+          sm.defaultModelByVendor = sm.defaultModelByVendor || {};
+          sm.defaultModelByVendor[vendor] = model;
+          sm.broadcastSessionList();
+          sendModelInfoForVendor(session, vendor, model);
+          sendToSession(session, { type: "config_state", sessionId: session.localId, vendor: vendor, model: model, effort: session.effort || sm.currentEffort || "medium", mode: session.permissionMode || sm.currentPermissionMode || "default", betas: sm.currentBetas || [] });
+        },
+      });
+    }
     // Normalize to string id in case a { value, displayName } object slips in
     if (model && typeof model !== "string") {
       model = modelEntryValue(model);
@@ -2525,7 +2458,22 @@ function createSDKBridge(opts) {
     }
   }
 
-  async function setEffort(session, effort) {
+  async function setEffort(session, effort, options) {
+    if (options && typeof options.revalidate === "function") {
+      var vendor = session.vendor || sm.defaultVendor || "claude";
+      var value = yoke.clampEffort(vendor, effort);
+      if (!value || value !== effort) throw new Error("Unsupported reasoning effort.");
+      return require("./session-config-transition").applySessionConfig({
+        sm: sm, session: session, revalidate: options.revalidate, method: "setEffort", nativeValue: value, changes: { effort: value },
+        publish: function () {
+          sm.currentEffortByVendor = sm.currentEffortByVendor || {};
+          sm.currentEffortByVendor[vendor] = value;
+          sm.currentEffort = value;
+          sm.broadcastSessionList();
+          sendToSession(session, { type: "config_state", sessionId: session.localId, vendor: vendor, effort: value, model: session.model || "", mode: session.permissionMode || sm.currentPermissionMode || "default", betas: sm.currentBetas || [] });
+        },
+      });
+    }
     // Remember the pick per vendor (clamped) so vendor switches don't leak
     // unsupported levels across sessions; sm.currentEffort stays as the
     // display value for the session the user just configured.
@@ -2646,16 +2594,7 @@ function createSDKBridge(opts) {
             message: "Read-only access. You cannot make changes via @mention.",
           });
         },
-        adapterOptions: {
-          CLAUDE: {
-            settingSources: ["user"],
-            includePartialMessages: true,
-            // Explicit, not omitted: SDK 0.3.286+ leaves an omitted
-            // permissionMode to Claude Code's own default/auto behavior,
-            // which could bypass the deny-by-default canUseTool above.
-            permissionMode: "default",
-          },
-        },
+        adapterOptions: require("./yoke/query-options").map(mentionAdapter, { instructionSources: ["user"], readOnly: true }),
       });
     } catch (e) {
       opts.onError("Failed to create mention query: " + (e.message || e));
@@ -2794,12 +2733,14 @@ function createSDKBridge(opts) {
     startQuery: startQuery,
     startQueryWithAcceptance: startQueryWithAcceptance,
     pushMessage: pushMessage,
+    cancelResponseRecovery: responseRecovery.cancel,
     refreshSessionRuntime: refreshSessionRuntime,
     refreshEnvironmentRuntime: refreshEnvironmentRuntime,
     setModel: setModel,
     setEffort: setEffort,
     setPermissionMode: setPermissionMode,
-    isClaudeProcess: isClaudeProcess,
+    isProviderProcess: isProviderProcess,
+    isClaudeProcess: isProviderProcess, // Compatibility export; production uses the provider contract.
     permissionPushTitle: permissionPushTitle,
     permissionPushBody: permissionPushBody,
     warmup: warmup,