@xfxstudio/claworld 0.2.6 → 0.2.8

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/src/openclaw/installer/core.js

@@ -316,6 +316,20 @@ export function parseJsonDocument(text, fallback = null) {
   return fallback;
 }
 
+function parseCommandJsonOutput(result = {}, fallback = null) {
+  const stdout = String(result?.stdout || '').trim();
+  const stderr = String(result?.stderr || '').trim();
+  const combined = [stdout, stderr].filter(Boolean).join('\n');
+  const reversed = [stderr, stdout].filter(Boolean).join('\n');
+  return (
+    parseJsonDocument(stdout, null)
+    || parseJsonDocument(stderr, null)
+    || parseJsonDocument(combined, null)
+    || parseJsonDocument(reversed, null)
+    || fallback
+  );
+}
+
 function parseLegacyChannelTokenStatus(tokenValue = '') {
   const normalized = normalizeText(tokenValue, '').toLowerCase();
   if (!normalized || normalized === 'missing' || normalized === 'none' || normalized === 'unset') {
@@ -1089,7 +1103,7 @@ export async function readGatewayStatus({
     env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
     dryRun,
   });
-  const payload = parseJsonDocument(`${result.stdout || ''}\n${result.stderr || ''}`, null);
+  const payload = parseCommandJsonOutput(result, null);
   if (!payload) {
     throw createInstallerError(
       'invalid_gateway_status',
@@ -1118,7 +1132,7 @@ export async function readChannelStatus({
     dryRun,
   });
   const output = `${result.stdout || ''}\n${result.stderr || ''}`;
-  const payload = parseJsonDocument(output, null) || parseLegacyChannelStatus(output);
+  const payload = parseCommandJsonOutput(result, null) || parseLegacyChannelStatus(output);
   if (!payload) {
     throw createInstallerError(
       'invalid_channel_status',

package/src/openclaw/installer/doctor.js

@@ -6,8 +6,11 @@ import {
   DEFAULT_CLAWORLD_AGENT_ID,
   DEFAULT_CLAWORLD_SERVER_URL,
   expandUserPath,
+  getEffectiveAgentSandboxMode,
+  MIN_MANAGED_SESSION_VISIBILITY,
   normalizeText,
   resolveClaworldManagedRuntimeOptions,
+  sandboxModeNeedsSessionToolsVisibility,
 } from '../plugin/managed-config.js';
 import {
   CLAWORLD_DOCTOR_COMMAND,
@@ -87,6 +90,18 @@ function findChannelAccount(channelStatus, accountId) {
   return entries.find((entry) => entry?.accountId === accountId) || null;
 }
 
+const SESSION_VISIBILITY_RANK = Object.freeze({
+  self: 0,
+  tree: 1,
+  agent: 2,
+  all: 3,
+});
+
+function resolveConfiguredSessionVisibility(config = {}) {
+  const visibility = normalizeText(config?.tools?.sessions?.visibility, null);
+  return Object.prototype.hasOwnProperty.call(SESSION_VISIBILITY_RANK, visibility) ? visibility : null;
+}
+
 function normalizeGatewayBaseUrl(gatewayStatus) {
   const probeUrl = normalizeText(gatewayStatus?.gateway?.probeUrl, null);
   if (probeUrl) {
@@ -455,6 +470,54 @@ export async function runClaworldDoctor({
     details: { issues: configuredAccount.issues },
   }));
 
+  const configuredSessionVisibility = resolveConfiguredSessionVisibility(config);
+  const sessionVisibilityHealthy = (
+    configuredSessionVisibility != null
+    && SESSION_VISIBILITY_RANK[configuredSessionVisibility] >= SESSION_VISIBILITY_RANK[MIN_MANAGED_SESSION_VISIBILITY]
+  );
+  checks.push(createCheck({
+    id: 'session-tools-visibility',
+    category: 'Managed config',
+    label: 'Session tool visibility',
+    status: sessionVisibilityHealthy ? 'pass' : 'warn',
+    summary: sessionVisibilityHealthy
+      ? `tools.sessions.visibility is \`${configuredSessionVisibility}\`, which satisfies the managed same-agent minimum \`${MIN_MANAGED_SESSION_VISIBILITY}\`.`
+      : `tools.sessions.visibility is \`${configuredSessionVisibility || 'missing'}\`, but the managed same-agent follow-up path needs at least \`${MIN_MANAGED_SESSION_VISIBILITY}\`.`,
+    action: sessionVisibilityHealthy
+      ? null
+      : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to raise session visibility for managed same-agent follow-up routing.`,
+    details: {
+      actualVisibility: configuredSessionVisibility,
+      minimumVisibility: MIN_MANAGED_SESSION_VISIBILITY,
+    },
+  }));
+
+  const effectiveSandboxMode = getEffectiveAgentSandboxMode(config, resolvedAgentId);
+  if (sandboxModeNeedsSessionToolsVisibility(effectiveSandboxMode)) {
+    const sandboxSessionToolsVisibility = normalizeText(
+      config?.agents?.defaults?.sandbox?.sessionToolsVisibility,
+      null,
+    );
+    const sandboxVisibilityHealthy = sandboxSessionToolsVisibility === 'all';
+    checks.push(createCheck({
+      id: 'sandbox-session-tools-visibility',
+      category: 'Managed config',
+      label: 'Sandbox session tool visibility',
+      status: sandboxVisibilityHealthy ? 'pass' : 'warn',
+      summary: sandboxVisibilityHealthy
+        ? `Effective sandbox mode is \`${effectiveSandboxMode}\` and agents.defaults.sandbox.sessionToolsVisibility is correctly set to \`all\`.`
+        : `Effective sandbox mode is \`${effectiveSandboxMode}\`, so agents.defaults.sandbox.sessionToolsVisibility should be \`all\` (currently \`${sandboxSessionToolsVisibility || 'missing'}\`).`,
+      action: sandboxVisibilityHealthy
+        ? null
+        : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` to widen sandbox session-tool visibility for managed follow-up routing.`,
+      details: {
+        effectiveSandboxMode,
+        sessionToolsVisibility: sandboxSessionToolsVisibility,
+        requiredSessionToolsVisibility: 'all',
+      },
+    }));
+  }
+
   checks.push(createCheck({
     id: 'app-token',
     category: 'Credentials and runtime',

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -10,6 +10,7 @@ import {
   defaultClaworldAccountId,
   inspectClaworldChannelAccount,
   listClaworldAccountIds,
+  projectClaworldStatusAccount,
   resolveClaworldChannelAccount,
   resolveClaworldRuntimeConfig,
   validateClaworldChannelConfig,
@@ -61,6 +62,11 @@ function normalizeRelayHttpBaseUrl(serverUrl) {
   return parsed.toString().replace(/\/$/, '');
 }
 
+function normalizePluginOptionalText(value) {
+  const normalized = String(value ?? '').trim();
+  return normalized || null;
+}
+
 function inferRelayDomain(runtimeConfig = {}) {
   const defaultToAddress = String(runtimeConfig.relay?.defaultToAddress || '').trim();
   const atIndex = defaultToAddress.indexOf('@');
@@ -710,6 +716,34 @@ async function acceptChatRequest({
   return result.body || {};
 }
 
+async function rejectChatRequest({
+  runtimeConfig,
+  actorAgentId,
+  chatRequestId,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/chat-requests/${encodeURIComponent(chatRequestId)}/reject`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({ actorAgentId }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'chat_request_reject_failed',
+      publicMessage: 'failed to reject chat request',
+      context: { actorAgentId, chatRequestId },
+    });
+  }
+  return result.body || {};
+}
+
 async function syncChatRequestApprovalPolicy({
   runtimeConfig,
   fetchImpl,
@@ -1301,7 +1335,12 @@ function createDeliveryReplyDispatcher({
     : undefined;
 
   let replied = false;
+  let keptSilent = false;
   let suppressed = false;
+  let replyTransport = null;
+  let replyFallbackUsed = false;
+  let keptSilentTransport = null;
+  let keptSilentFallbackUsed = false;
   const finalTexts = [];
   const blockTexts = [];
   let partialContinuationText = '';
@@ -1383,16 +1422,52 @@ function createDeliveryReplyDispatcher({
       suppressed = true;
       return false;
     }
-    relayClient.sendReply({
-      deliveryId,
-      sessionKey,
-      replyText: normalized,
-      source: 'openclaw-autochain',
-    });
+    if (typeof relayClient.sendReplyAndWaitForAck === 'function') {
+      const replyResult = await relayClient.sendReplyAndWaitForAck({
+        deliveryId,
+        sessionKey,
+        replyText: normalized,
+        source: 'openclaw-autochain',
+      });
+      replyTransport = replyResult?.transport || 'websocket';
+      replyFallbackUsed = replyResult?.fallbackUsed === true;
+    } else {
+      relayClient.sendReply({
+        deliveryId,
+        sessionKey,
+        replyText: normalized,
+        source: 'openclaw-autochain',
+      });
+      replyTransport = 'websocket-fire-and-forget';
+      replyFallbackUsed = false;
+    }
     replied = true;
     return true;
   };
 
+  const flushKeptSilent = async (reason = null) => {
+    if (replied || keptSilent || suppressed) return false;
+    if (allowReply === false) {
+      suppressed = true;
+      return false;
+    }
+    if (typeof relayClient.sendKeepSilentAndWaitForAck === 'function') {
+      const silentResult = await relayClient.sendKeepSilentAndWaitForAck({
+        deliveryId,
+        sessionKey,
+        reason: normalizePluginOptionalText(reason) || 'no_renderable_reply',
+        source: 'openclaw-autochain',
+      });
+      keptSilentTransport = silentResult?.transport || 'websocket';
+      keptSilentFallbackUsed = silentResult?.fallbackUsed === true;
+    } else {
+      keptSilentTransport = 'unsupported';
+      keptSilentFallbackUsed = false;
+    }
+    keptSilent = true;
+    return true;
+  };
+
   const dispatchApi = runtime.channel.reply.createReplyDispatcherWithTyping({
     responsePrefix: prefixContext.responsePrefix,
     responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
@@ -1421,6 +1496,7 @@ function createDeliveryReplyDispatcher({
   });
 
   const markDispatchIdle = async () => {
+    await dispatchApi.dispatcher.waitForIdle?.();
     if (!replied && !suppressed) {
       const continuation = buildRelayContinuationText({
         finalTexts,
@@ -1435,6 +1511,8 @@ function createDeliveryReplyDispatcher({
         : null;
       if (continuation.text) {
         await flushReply(continuation.text);
+      } else {
+        await flushKeptSilent(continuation.source);
       }
     }
     await dispatchApi.markDispatchIdle?.();
@@ -1472,6 +1550,7 @@ function createDeliveryReplyDispatcher({
     },
     markDispatchIdle,
     didReply: () => replied,
+    didKeepSilent: () => keptSilent,
     getRuntimeOutputSummary: () => ({
       counts: { ...runtimeOutputSummary.counts },
       previews: {
@@ -1484,6 +1563,10 @@ function createDeliveryReplyDispatcher({
       },
       relayContinuationSource: runtimeOutputSummary.relayContinuationSource,
       relayContinuationPreview: runtimeOutputSummary.relayContinuationPreview,
+      replyTransport,
+      replyFallbackUsed,
+      keptSilentTransport,
+      keptSilentFallbackUsed,
     }),
   };
 }
@@ -1500,7 +1583,14 @@ async function runDeliveryReplyDispatch({
   runtimeAccountId,
   inboundCtx,
 } = {}) {
-  const { dispatcher, replyOptions, markDispatchIdle, didReply, getRuntimeOutputSummary } = createDeliveryReplyDispatcher({
+  const {
+    dispatcher,
+    replyOptions,
+    markDispatchIdle,
+    didReply,
+    didKeepSilent,
+    getRuntimeOutputSummary,
+  } = createDeliveryReplyDispatcher({
     runtime,
     currentCfg,
     relayClient,
@@ -1523,6 +1613,7 @@ async function runDeliveryReplyDispatch({
   return {
     dispatchResult,
     replied: didReply(),
+    keptSilent: didKeepSilent(),
     runtimeOutputSummary: getRuntimeOutputSummary(),
   };
 }
@@ -1704,6 +1795,7 @@ async function maybeBridgeRuntimeDelivery({
   let {
     dispatchResult,
     replied,
+    keptSilent,
     runtimeOutputSummary,
   } = await runDeliveryReplyDispatch({
     runtime,
@@ -1747,6 +1839,7 @@ async function maybeBridgeRuntimeDelivery({
     ({
       dispatchResult,
       replied,
+      keptSilent,
       runtimeOutputSummary,
     } = await runDeliveryReplyDispatch({
       runtime,
@@ -1762,19 +1855,21 @@ async function maybeBridgeRuntimeDelivery({
     }));
   }
 
-  logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
-    deliveryId,
-    sessionKey,
-    queuedFinal: Boolean(dispatchResult?.queuedFinal),
-    replied,
-    routeStatus: routed?.status || null,
-    runtimeOutputSummary,
-  });
+    logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
+      deliveryId,
+      sessionKey,
+      queuedFinal: Boolean(dispatchResult?.queuedFinal),
+      replied,
+      keptSilent,
+      routeStatus: routed?.status || null,
+      runtimeOutputSummary,
+    });
 
   return {
     skipped: false,
     ok: true,
     replied,
+    keptSilent,
     queuedFinal: Boolean(dispatchResult?.queuedFinal),
     sessionKey,
     routeStatus: routed?.status || null,
@@ -1794,6 +1889,69 @@ export function createClaworldChannelPlugin({
   const relayClients = new Map();
   const lifecycles = new Map();
   const accountRuntimeContexts = new Map();
+  const accountBindingStates = new Map();
+
+  function resolveAccountBindingKey(runtimeConfig = {}, fallbackAccountId = 'default') {
+    return String(runtimeConfig?.accountId || fallbackAccountId || 'default');
+  }
+
+  function mergeBoundRuntimeConfig(currentRuntimeConfig = {}, boundRuntimeConfig = {}) {
+    return applyRuntimeIdentity({
+      ...currentRuntimeConfig,
+      ...boundRuntimeConfig,
+      relay: {
+        ...(currentRuntimeConfig?.relay && typeof currentRuntimeConfig.relay === 'object' ? currentRuntimeConfig.relay : {}),
+        ...(boundRuntimeConfig?.relay && typeof boundRuntimeConfig.relay === 'object' ? boundRuntimeConfig.relay : {}),
+      },
+    });
+  }
+
+  async function ensureAccountRelayBinding({ runtimeConfig, accountId = null }) {
+    const normalizedRuntimeConfig = applyRuntimeIdentity(runtimeConfig);
+    const accountKey = resolveAccountBindingKey(normalizedRuntimeConfig, accountId || null);
+    const cachedState = accountBindingStates.get(accountKey) || null;
+    const cachedBinding = cachedState?.binding || null;
+
+    if (
+      cachedBinding
+      && cachedBinding.runtimeConfig?.serverUrl
+      && cachedBinding.runtimeConfig.serverUrl === normalizedRuntimeConfig.serverUrl
+    ) {
+      return {
+        ...cachedBinding,
+        runtimeConfig: mergeBoundRuntimeConfig(normalizedRuntimeConfig, cachedBinding.runtimeConfig),
+        bindingSource: cachedBinding.bindingSource === 'configured_app_token'
+          ? 'configured_app_token'
+          : 'binding_cache',
+      };
+    }
+
+    if (cachedState?.promise) {
+      return cachedState.promise;
+    }
+
+    const promise = ensureRelayBinding({
+      runtimeConfig: normalizedRuntimeConfig,
+      fetchImpl,
+      logger,
+    }).then((binding) => {
+      const resolvedBinding = {
+        ...binding,
+        runtimeConfig: mergeBoundRuntimeConfig(normalizedRuntimeConfig, binding.runtimeConfig),
+      };
+      accountBindingStates.set(accountKey, { binding: resolvedBinding });
+      return resolvedBinding;
+    }).catch((error) => {
+      const latest = accountBindingStates.get(accountKey) || null;
+      if (latest?.promise === promise) {
+        accountBindingStates.delete(accountKey);
+      }
+      throw error;
+    });
+
+    accountBindingStates.set(accountKey, { promise });
+    return promise;
+  }
 
   async function persistRuntimeAppToken({ runtime, accountId, appToken }) {
     if (!runtime?.config?.loadConfig || !runtime?.config?.writeConfigFile) {
@@ -1847,7 +2005,7 @@ export function createClaworldChannelPlugin({
         bindingSource: 'runtime_context',
       };
     }
-    const binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
+    const binding = await ensureAccountRelayBinding({ runtimeConfig, accountId });
     runtimeConfig = binding.runtimeConfig;
     return {
       ...context,
@@ -1896,7 +2054,7 @@ export function createClaworldChannelPlugin({
 
         let binding;
         try {
-          binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
+          binding = await ensureAccountRelayBinding({ runtimeConfig, accountId: runtimeAccountId });
         } catch (error) {
           const normalized = normalizeRuntimeBoundaryError(error, {
             code: 'claworld_relay_binding_failed',
@@ -2059,6 +2217,7 @@ export function createClaworldChannelPlugin({
           relayClients.delete(accountKey);
         }
         accountRuntimeContexts.delete(accountKey);
+        accountBindingStates.delete(accountKey);
       },
     });
 
@@ -2200,7 +2359,8 @@ export function createClaworldChannelPlugin({
       validate: validateClaworldChannelConfig,
       listAccountIds: (cfg) => listClaworldAccountIds(cfg),
       defaultAccountId: (cfg) => defaultClaworldAccountId(cfg),
-      inspectAccount: (cfg, accountId) => inspectClaworldChannelAccount(cfg, accountId),
+      inspectAccount: (cfg, accountId) =>
+        projectClaworldStatusAccount(inspectClaworldChannelAccount(cfg, accountId)),
       resolveAccount: (cfg, accountId) => resolveClaworldChannelAccount(cfg, accountId),
       resolveRuntimeConfig: (cfg, accountId) => resolveClaworldRuntimeConfig(cfg, accountId),
       isConfigured: (account, cfg) => {
@@ -2387,6 +2547,15 @@ export function createClaworldChannelPlugin({
             fetchImpl,
           });
         },
+        rejectChatRequest: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return rejectChatRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            actorAgentId: resolvedContext.agentId || null,
+            chatRequestId: context.chatRequestId || null,
+            fetchImpl,
+          });
+        },
       },
       postSetup: {
         fetchWorldDirectory: async (context = {}) => {
@@ -2524,6 +2693,7 @@ export function createClaworldChannelPlugin({
             mode: context.mode || 'get',
             changes: context.changes || null,
             enabled: Object.prototype.hasOwnProperty.call(context, 'enabled') ? context.enabled : null,
+            status: context.status || null,
             fetchImpl,
             logger,
           });
@@ -2712,6 +2882,7 @@ export function createClaworldChannelPlugin({
               mode: context.mode || 'get',
               changes: context.changes || null,
               enabled: Object.prototype.hasOwnProperty.call(context, 'enabled') ? context.enabled : null,
+              status: context.status || null,
               fetchImpl,
               logger,
             });

package/src/openclaw/plugin/config-schema.js

@@ -417,6 +417,14 @@ export function inspectClaworldChannelAccount(config = {}, accountId = null) {
   };
 }
 
+export function projectClaworldStatusAccount(inspection = {}) {
+  // Keep the steady-state credential nested under relay/runtimeConfig so
+  // generic OpenClaw status does not misclassify Claworld as a bot+app token
+  // channel.
+  const { appToken: _appToken, ...statusAccount } = inspection || {};
+  return statusAccount;
+}
+
 export function resolveClaworldRuntimeConfig(config = {}, accountId = null) {
   const result = validateClaworldChannelConfig(config, accountId);
   if (!result.ok) {
@@ -435,11 +443,8 @@ export function resolveClaworldRuntimeConfig(config = {}, accountId = null) {
 export function resolveClaworldChannelAccount(config = {}, accountId = null) {
   const runtimeConfig = resolveClaworldRuntimeConfig(config, accountId);
   const inspection = inspectClaworldChannelAccount(config, accountId);
-  // Keep the steady-state credential nested under relay/runtimeConfig so generic
-  // OpenClaw status does not misclassify Claworld as a bot+app token channel.
-  const { appToken: _appToken, ...statusAccount } = inspection;
   return {
-    ...statusAccount,
+    ...projectClaworldStatusAccount(inspection),
     runtimeReady: true,
     resolvedFrom: accountId ? 'requested_account' : 'default_account',
     runtimeConfig,

package/src/openclaw/plugin/managed-config.js

@@ -23,6 +23,8 @@ export const DEFAULT_CLAWORLD_APPROVAL_MODE = DEFAULT_CHAT_REQUEST_APPROVAL_POLI
 export const DEFAULT_CLAWORLD_SESSION_TARGET = 'mainagent';
 export const DEFAULT_CLAWORLD_FALLBACK_TARGET = 'mainagent';
 export const CLAWORLD_PLUGIN_TOOL_ALLOW_ENTRY = 'claworld';
+export const MIN_MANAGED_SESSION_VISIBILITY = 'agent';
+export const REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY = 'all';
 
 export const TOOL_PROFILES = CLAWORLD_TOOL_PROFILES;
 
@@ -128,6 +130,109 @@ function findManagedAccountEntry(config = {}, accountId) {
   return {};
 }
 
+const SESSION_VISIBILITY_RANK = Object.freeze({
+  self: 0,
+  tree: 1,
+  agent: 2,
+  all: 3,
+});
+
+const SANDBOX_SESSION_TOOLS_VISIBILITY_RANK = Object.freeze({
+  spawned: 0,
+  all: 1,
+});
+
+function normalizeSessionVisibility(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return Object.prototype.hasOwnProperty.call(SESSION_VISIBILITY_RANK, normalized)
+    ? normalized
+    : fallback;
+}
+
+function normalizeSandboxSessionToolsVisibility(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return Object.prototype.hasOwnProperty.call(SANDBOX_SESSION_TOOLS_VISIBILITY_RANK, normalized)
+    ? normalized
+    : fallback;
+}
+
+function compareRankedSetting(value, target, rankMap) {
+  const nextValue = normalizeText(value, null);
+  const nextTarget = normalizeText(target, null);
+  const valueRank = Object.prototype.hasOwnProperty.call(rankMap, nextValue) ? rankMap[nextValue] : null;
+  const targetRank = Object.prototype.hasOwnProperty.call(rankMap, nextTarget) ? rankMap[nextTarget] : null;
+  if (valueRank == null && targetRank == null) return 0;
+  if (valueRank == null) return -1;
+  if (targetRank == null) return 1;
+  return valueRank - targetRank;
+}
+
+export function getEffectiveAgentSandboxMode(config = {}, agentId = DEFAULT_CLAWORLD_AGENT_ID) {
+  const normalizedAgentId = normalizeText(agentId, DEFAULT_CLAWORLD_AGENT_ID);
+  const agentEntry = findAgentEntry(config, normalizedAgentId);
+  const agentSandboxMode = normalizeText(agentEntry?.sandbox?.mode, null);
+  if (agentSandboxMode) return agentSandboxMode;
+  return normalizeText(config?.agents?.defaults?.sandbox?.mode, 'off');
+}
+
+export function sandboxModeNeedsSessionToolsVisibility(mode) {
+  return mode === 'all' || mode === 'non-main';
+}
+
+function ensureManagedSessionRoutingVisibility(config = {}, {
+  agentId = DEFAULT_CLAWORLD_AGENT_ID,
+  summary = [],
+} = {}) {
+  config.tools = ensureObject(config.tools);
+  const existingSessionTools = ensureObject(config.tools.sessions);
+  const existingVisibility = normalizeSessionVisibility(existingSessionTools.visibility, null);
+  if (compareRankedSetting(existingVisibility, MIN_MANAGED_SESSION_VISIBILITY, SESSION_VISIBILITY_RANK) < 0) {
+    config.tools.sessions = {
+      ...existingSessionTools,
+      visibility: MIN_MANAGED_SESSION_VISIBILITY,
+    };
+    summary.push(
+      existingVisibility
+        ? `tools.sessions.visibility raised from ${existingVisibility} to ${MIN_MANAGED_SESSION_VISIBILITY}`
+        : `tools.sessions.visibility set to ${MIN_MANAGED_SESSION_VISIBILITY}`,
+    );
+  } else if (Object.keys(existingSessionTools).length > 0) {
+    config.tools.sessions = existingSessionTools;
+  }
+
+  const effectiveSandboxMode = getEffectiveAgentSandboxMode(config, agentId);
+  if (!sandboxModeNeedsSessionToolsVisibility(effectiveSandboxMode)) {
+    return;
+  }
+
+  config.agents = ensureObject(config.agents);
+  config.agents.defaults = ensureObject(config.agents.defaults);
+  const existingSandbox = ensureObject(config.agents.defaults.sandbox);
+  const existingSessionToolsVisibility = normalizeSandboxSessionToolsVisibility(
+    existingSandbox.sessionToolsVisibility,
+    null,
+  );
+  if (
+    compareRankedSetting(
+      existingSessionToolsVisibility,
+      REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY,
+      SANDBOX_SESSION_TOOLS_VISIBILITY_RANK,
+    ) < 0
+  ) {
+    config.agents.defaults.sandbox = {
+      ...existingSandbox,
+      sessionToolsVisibility: REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY,
+    };
+    summary.push(
+      existingSessionToolsVisibility
+        ? `agents.defaults.sandbox.sessionToolsVisibility raised from ${existingSessionToolsVisibility} to ${REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY}`
+        : `agents.defaults.sandbox.sessionToolsVisibility set to ${REQUIRED_SANDBOX_SESSION_TOOLS_VISIBILITY}`,
+    );
+  } else if (Object.keys(existingSandbox).length > 0) {
+    config.agents.defaults.sandbox = existingSandbox;
+  }
+}
+
 function inferExistingAgentId(config = {}, accountId = DEFAULT_CLAWORLD_ACCOUNT_ID) {
   const bindings = Array.isArray(config?.bindings) ? config.bindings : [];
   const bindingMatch = bindings
@@ -716,6 +821,11 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
       : `reconciled claworld binding for ${options.accountId}`,
   );
 
+  ensureManagedSessionRoutingVisibility(config, {
+    agentId: options.agentId,
+    summary,
+  });
+
   return {
     config,
     summary,