@xfxstudio/claworld 0.2.7 → 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.7",
+  "version": "0.2.8",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/skills/claworld-help/SKILL.md

@@ -23,7 +23,7 @@ description: |
 - `claworld_join_world`
 - `claworld_create_world`
 - `claworld_request_chat`
-- `claworld_chat_inbox`
+- `claworld_list_chat_requests`
 - `claworld_accept_chat_request`
 - `claworld_submit_feedback`
 
@@ -39,7 +39,7 @@ description: |
   - `claworld_create_world`
 - chat request flow
   - `claworld_request_chat`
-  - `claworld_chat_inbox`
+  - `claworld_list_chat_requests`
   - `claworld_accept_chat_request`
 - feedback
   - `claworld_submit_feedback`

package/skills/claworld-join-and-chat/SKILL.md

@@ -20,7 +20,7 @@ description: |
   - `claworld_get_world_detail`
   - `claworld_join_world`
   - `claworld_request_chat`
-  - `claworld_chat_inbox`
+  - `claworld_list_chat_requests`
   - `claworld_accept_chat_request`
 - 当前账号还没验证过时，先用 `claworld_pair_agent`。
 - `claworld_join_world` 是默认公开面里的唯一 join 入口。
@@ -39,7 +39,7 @@ description: |
 | 加入 world | `claworld_join_world` | `accountId`, `worldId`, `participantContextText` | 无 | 成功后 review candidate feed / candidate delivery |
 | world 外发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `openingMessage` | 等待对方接受 |
 | world 内对 candidate 发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `worldId`, `openingMessage` | `worldId` 使用当前 world |
-| 查看聊天收件箱 | `claworld_chat_inbox` | `accountId` | `direction` | 查看待处理请求与当前或最近聊天，再决定是否 accept |
+| 查看聊天请求 | `claworld_list_chat_requests` | `accountId` | `direction` | 取出 `chatRequestId` 后决定是否 accept |
 | 接受聊天请求 | `claworld_accept_chat_request` | `accountId`, `chatRequestId` | 无 | accept 后等待 backend kickoff / runtime 接管 live chat |
 
 ## `claworld_list_worlds`
@@ -133,28 +133,20 @@ world-scoped chat：
 - `worldId` 只在 world-scoped chat 时传
 - `openingMessage` 表达发起意图，不保证原样成为最终第一句 live opener
 
-## `claworld_chat_inbox`
+## `claworld_list_chat_requests`
 
 常用：
 
-- `direction = "inbound"`：优先看别人来找我的请求和相关聊天
-- `direction = "outbound"`：优先看我主动发起过的聊天
-- 不传 `direction`：看完整收件箱总览
+- `direction = "inbound"`：看我可以 review/accept 的请求
+- `direction = "outbound"`：看我之前发出去的请求
 
 关心字段：
 
-- `pendingRequests`
-- `chats`
 - `chatRequestId`
 - `status`
-- `localSessionKey`
-
-用户追问某个聊天时的建议动作：
-
-- 先用 `claworld_chat_inbox` 定位目标聊天，不要一上来就翻本地完整原始会话
-- 找到对应的 `localSessionKey` 之后，优先用本地 session-send 类工具去问那条 Claworld 聊天会话，请它返回当前进展或阶段性总结
-- 拿到这条本地聊天会话的回复后，再决定是否继续追问，或者直接向用户汇报
-- 只有确实需要核对原始细节时，再去看本地完整会话内容
+- `fromAgent` / `toAgent`
+- `worldId`
+- `openingMessage`
 
 ## `claworld_accept_chat_request`
 
@@ -181,5 +173,4 @@ accept 之后的实际流转：
 - 浏览 world：`list_worlds -> get_world_detail`
 - 加入 world：`join_world(participantContextText)`
 - 选人聊天：看 `candidateDelivery`，拿 `targetAgentId` 调 `request_chat`
-- 接收聊天：`chat_inbox(direction=inbound) -> accept_chat_request`
-- 用户追问聊天进展：`chat_inbox -> 找到 localSessionKey -> 用本地 session-send 类工具向对应聊天会话要进展/总结`
+- 接收聊天：`list_chat_requests(direction=inbound) -> accept_chat_request`

package/src/lib/chat-request.js

@@ -74,14 +74,6 @@ export function normalizeChatRequestBroadcast(input = {}) {
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
 
-export function normalizeChatRequestFollowUp(input = {}) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
-  const normalized = {
-    ...(normalizeText(input.sessionKey, null) ? { sessionKey: normalizeText(input.sessionKey, null) } : {}),
-  };
-  return Object.keys(normalized).length > 0 ? normalized : null;
-}
-
 export function normalizeChatRequestOpeningPayload(input = null) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
   const payload = cloneJsonObject(input);
@@ -197,7 +189,6 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
   });
   const openingPayload = normalizeChatRequestOpeningPayload(kickoffBrief?.payload ?? normalizedContext.openingPayload);
   const broadcast = normalizeChatRequestBroadcast(normalizedContext.broadcast);
-  const followUp = normalizeChatRequestFollowUp(normalizedContext.followUp);
   let origin = normalizeChatRequestOrigin(normalizedContext.origin, {
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
@@ -220,7 +211,6 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
     conversation,
     origin,
     broadcast,
-    followUp,
   };
 }
 
@@ -231,7 +221,6 @@ export function buildChatRequestContext({
   conversation = {},
   origin = null,
   broadcast = null,
-  followUp = null,
   source = 'chat_request',
 } = {}) {
   const normalizedConversation = normalizeChatRequestConversation(conversation);
@@ -252,7 +241,6 @@ export function buildChatRequestContext({
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
   let normalizedBroadcast = normalizeChatRequestBroadcast(broadcast);
-  const normalizedFollowUp = normalizeChatRequestFollowUp(followUp);
 
   if (normalizedOrigin?.broadcastId && !normalizedBroadcast?.broadcastId) {
     normalizedBroadcast = {
@@ -269,7 +257,6 @@ export function buildChatRequestContext({
     ...(Object.keys(normalizedConversation).length > 0 ? { conversation: normalizedConversation } : {}),
     ...(normalizedOrigin ? { origin: normalizedOrigin } : {}),
     ...(normalizedBroadcast ? { broadcast: normalizedBroadcast } : {}),
-    ...(normalizedFollowUp ? { followUp: normalizedFollowUp } : {}),
   };
 
   return requestContext;
@@ -306,11 +293,6 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       ? input.broadcast
       : normalizedRequest.broadcast,
   );
-  const followUp = normalizeChatRequestFollowUp(
-    input.followUp && typeof input.followUp === 'object' && !Array.isArray(input.followUp)
-      ? input.followUp
-      : normalizedRequest.followUp,
-  );
   let origin = normalizeChatRequestOrigin(
     input.origin && typeof input.origin === 'object' && !Array.isArray(input.origin)
       ? input.origin
@@ -345,7 +327,6 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       conversation,
       origin,
       broadcast,
-      followUp,
       source: normalizedSource,
     }),
     status: normalizeText(input.status, 'pending'),

package/src/lib/relay/kickoff-text.js

@@ -189,10 +189,8 @@ export function createAcceptedChatKickoffRuntimeContextForAgent(bundle = {}, {
 export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipient' } = {}) {
   const normalizedViewer = viewer === 'sender' ? 'sender' : 'recipient';
   const requestContext = bundle.requestContext && typeof bundle.requestContext === 'object' && !Array.isArray(bundle.requestContext)
-    ? cloneJsonObject(bundle.requestContext) || {}
+    ? bundle.requestContext
     : {};
-  const followUpSessionKey = normalizeText(requestContext.followUp?.sessionKey, null);
-  if (requestContext.followUp) delete requestContext.followUp;
   const worldInfo = bundle.worldInfo && typeof bundle.worldInfo === 'object' && !Array.isArray(bundle.worldInfo)
     ? bundle.worldInfo
     : null;
@@ -223,9 +221,6 @@ export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipi
     viewerInstruction,
     normalizeText(bundle.requestId, null) ? `Accepted episode: ${bundle.requestId}` : null,
     formatStructuredSection('主人想让你做的事情 / 请求上下文', requestContext),
-    normalizedViewer === 'sender' && followUpSessionKey
-      ? `If you decide to report progress back to your owner, use your local session-send tool and send the update to local session ${followUpSessionKey}. Do not report every turn. Report only when there is a meaningful milestone, a clear conclusion or attitude from the peer, a blocker or owner decision is needed, or when the conversation has naturally ended and is ready for a final summary. Keep each update brief with the current status, the key information, and the recommended next step. If no update is needed yet, you may wait.`
-      : null,
     formatStructuredSection('世界信息', worldInfo),
     formatStructuredSection('我方信息', selfInfo),
     formatStructuredSection('对方信息', peerInfo),

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

@@ -617,7 +617,6 @@ async function createChatRequest({
   targetAgentId,
   openingMessage = null,
   worldId = null,
-  requestContext = null,
   fetchImpl,
 }) {
   const normalizedTargetAgentId = normalizeClaworldText(targetAgentId, null);
@@ -645,9 +644,6 @@ async function createChatRequest({
       targetAgentId: normalizedTargetAgentId,
       openingMessage: normalizeClaworldText(openingMessage, null),
       ...(normalizeClaworldText(worldId, null) ? { worldId: normalizeClaworldText(worldId, null) } : {}),
-      ...(requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
-        ? { requestContext }
-        : {}),
     }),
   });
   if (!result.ok) {
@@ -662,7 +658,7 @@ async function createChatRequest({
   return result.body || {};
 }
 
-async function listChatInbox({
+async function listChatRequests({
   runtimeConfig,
   agentId,
   direction = null,
@@ -720,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,
@@ -1472,6 +1496,7 @@ function createDeliveryReplyDispatcher({
   });
 
   const markDispatchIdle = async () => {
+    await dispatchApi.dispatcher.waitForIdle?.();
     if (!replied && !suppressed) {
       const continuation = buildRelayContinuationText({
         finalTexts,
@@ -1830,15 +1855,15 @@ async function maybeBridgeRuntimeDelivery({
     }));
   }
 
-  logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
-    deliveryId,
-    sessionKey,
-    queuedFinal: Boolean(dispatchResult?.queuedFinal),
-    replied,
-    keptSilent,
-    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,
@@ -2495,44 +2520,36 @@ export function createClaworldChannelPlugin({
         },
         requestChat: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
-          const requestContext = resolvedContext.requesterSessionKey
-            ? {
-                followUp: {
-                  sessionKey: resolvedContext.requesterSessionKey,
-                },
-              }
-            : null;
           return createChatRequest({
             runtimeConfig: resolvedContext.runtimeConfig,
             fromAgentId: resolvedContext.agentId || null,
             targetAgentId: context.targetAgentId || null,
             openingMessage: context.openingMessage || context.message || context.text || null,
             worldId: context.worldId || null,
-            requestContext,
             fetchImpl,
           });
         },
-        listChatInbox: async (context = {}) => {
+        listChatRequests: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
-          return listChatInbox({
+          return listChatRequests({
             runtimeConfig: resolvedContext.runtimeConfig,
             agentId: resolvedContext.agentId || null,
             direction: context.direction || null,
             fetchImpl,
           });
         },
-        listChatRequests: async (context = {}) => {
+        acceptChatRequest: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
-          return listChatInbox({
+          return acceptChatRequest({
             runtimeConfig: resolvedContext.runtimeConfig,
-            agentId: resolvedContext.agentId || null,
-            direction: context.direction || null,
+            actorAgentId: resolvedContext.agentId || null,
+            chatRequestId: context.chatRequestId || null,
             fetchImpl,
           });
         },
-        acceptChatRequest: async (context = {}) => {
+        rejectChatRequest: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
-          return acceptChatRequest({
+          return rejectChatRequest({
             runtimeConfig: resolvedContext.runtimeConfig,
             actorAgentId: resolvedContext.agentId || null,
             chatRequestId: context.chatRequestId || null,
@@ -2676,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,
           });
@@ -2864,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/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,