mixdog 0.9.9 → 0.9.11

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -7,6 +7,7 @@ import {
     parseMarkdownFrontmatter,
     readMarkdownDocument,
 } from '../../../shared/markdown-frontmatter.mjs';
+import { loadConfig, normalizeSkillsConfig } from '../config.mjs';
 
 // --- mixdog asset roots (standalone CLI owns its own paths; never .claude) ---
 // Project-local:  <cwd>/.mixdog/<kind>
@@ -123,6 +124,37 @@ export function collectSkills(cwd) {
     }
     return skills;
 }
+
+function normalizeSkillNameKey(name) {
+    return String(name || '').trim().toLowerCase();
+}
+
+export function getDisabledSkillNameSet(config = null) {
+    const cfg = config || loadConfig({ secrets: false });
+    const keys = normalizeSkillsConfig(cfg.skills).disabled
+        .map((n) => normalizeSkillNameKey(n))
+        .filter(Boolean);
+    return new Set(keys);
+}
+
+export function isSkillDisabled(name, config = null) {
+    const n = normalizeSkillNameKey(name);
+    if (!n) return false;
+    return getDisabledSkillNameSet(config).has(n);
+}
+
+export function filterSkillsExcludingDisabled(skills, config = null) {
+    const disabled = getDisabledSkillNameSet(config);
+    if (!disabled.size) return Array.isArray(skills) ? skills : [];
+    return (Array.isArray(skills) ? skills : []).filter((s) => {
+        const key = normalizeSkillNameKey(s?.name);
+        return key && !disabled.has(key);
+    });
+}
+
+export function collectPromptSkillsCached(cwd, config = null) {
+    return filterSkillsExcludingDisabled(collectSkillsCached(cwd), config);
+}
 // --- Skill cache (mtime-based, keyed by cwd) ---
 const _skillsCache = new Map();
 const _mtimeCache = new Map();
@@ -267,6 +299,130 @@ export function buildSkillManifest(skills, { limit = 80 } = {}) {
     return lines.join('\n');
 }
 
+const DEFERRED_TOOLS_BLOCK_RE = /(\n\n---\n*)?<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>\s*/gi;
+const MCP_INSTRUCTIONS_BLOCK_RE = /(\n\n---\n*)?<mcp-instructions>[\s\S]*?<\/mcp-instructions>\s*/gi;
+const DEFERRED_TOOL_NAME_SAFE_RE = /^[A-Za-z0-9_.:-]+$/;
+const MCP_SERVER_NAME_SAFE_RE = /^[A-Za-z0-9_.:-]+$/;
+const MCP_INSTRUCTION_MAX_CHARS = 600;
+
+function sanitizeDeferredToolManifestName(name) {
+    const text = String(name || '').trim();
+    if (!text || text.includes('<') || text.includes('>')) return '';
+    if (!DEFERRED_TOOL_NAME_SAFE_RE.test(text)) return '';
+    return text;
+}
+
+export function bp1HasDeferredToolManifestBlock(text) {
+    const raw = String(text || '');
+    return /<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>/i.test(raw)
+        || /<mcp-instructions>[\s\S]*?<\/mcp-instructions>/i.test(raw);
+}
+
+/**
+ * Names-only manifest for tools in the deferred pool (catalog minus active wire tools).
+ * Empty pool → '' (caller omits the block).
+ */
+export function buildDeferredToolManifest(names) {
+    const list = [...new Set((Array.isArray(names) ? names : [])
+        .map((name) => sanitizeDeferredToolManifestName(name))
+        .filter(Boolean))]
+        .sort((a, b) => a.localeCompare(b));
+    if (!list.length) return '';
+    return ['<available-deferred-tools>', ...list, '</available-deferred-tools>'].join('\n');
+}
+
+function sanitizeMcpManifestServerName(name) {
+    const text = String(name || '').trim();
+    if (!text || text.includes('<') || text.includes('>')) return '';
+    if (!MCP_SERVER_NAME_SAFE_RE.test(text)) return '';
+    return text;
+}
+
+function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
+    const stripped = String(text || '').replace(/[<>]/g, '').trim();
+    if (!stripped) return '';
+    const cap = Math.max(1, Number(max) || MCP_INSTRUCTION_MAX_CHARS);
+    return stripped.length > cap ? `${stripped.slice(0, Math.max(1, cap - 3))}...` : stripped;
+}
+
+/**
+ * Per-server MCP initialize instructions for deferred-pool tools only.
+ * Empty when no instructions or no matching deferred MCP tools → omit block.
+ */
+export function buildMcpInstructionsManifest(mcpServerInstructions, poolNames) {
+    const map = mcpServerInstructions && typeof mcpServerInstructions === 'object'
+        ? mcpServerInstructions
+        : {};
+    const pool = [...new Set((Array.isArray(poolNames) ? poolNames : [])
+        .map((name) => sanitizeDeferredToolManifestName(name))
+        .filter(Boolean))];
+    const toolsByServer = new Map();
+    for (const name of pool) {
+        const match = name.match(/^mcp__(.+?)__(.+)$/);
+        if (!match) continue;
+        const server = match[1];
+        if (!toolsByServer.has(server)) toolsByServer.set(server, []);
+        toolsByServer.get(server).push(name);
+    }
+    const servers = [...toolsByServer.keys()]
+        .filter((server) => sanitizeMcpManifestServerName(server)
+            && sanitizeMcpInstructionText(map[server])
+            && toolsByServer.get(server).length)
+        .sort((a, b) => a.localeCompare(b));
+    if (!servers.length) return '';
+    const lines = ['<mcp-instructions>'];
+    for (const server of servers) {
+        const safeServer = sanitizeMcpManifestServerName(server);
+        const body = sanitizeMcpInstructionText(map[server]);
+        const tools = [...toolsByServer.get(server)].sort((a, b) => a.localeCompare(b));
+        lines.push(`## ${safeServer}`, body, ...tools.map((tool) => `- ${tool}`));
+    }
+    lines.push('</mcp-instructions>');
+    return lines.join('\n');
+}
+
+export function stripDeferredToolManifestBlock(text) {
+    return String(text || '')
+        .replace(DEFERRED_TOOLS_BLOCK_RE, '')
+        .replace(MCP_INSTRUCTIONS_BLOCK_RE, '')
+        .replace(/\n\n---\n*$/,'')
+        .trimEnd();
+}
+
+/** Inject names-only deferred pool into BP1 once at session start; never rewrite BP1 after. */
+export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
+    if (!session || !Array.isArray(session.messages) || session.deferredToolBp1Applied) return false;
+    const pool = Array.isArray(poolNames) ? poolNames : [];
+    const parts = [];
+    const deferredManifest = buildDeferredToolManifest(pool);
+    if (deferredManifest) parts.push(deferredManifest);
+    const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool);
+    if (mcpManifest) parts.push(mcpManifest);
+    const manifest = parts.join('\n\n');
+    let idx = -1;
+    for (let i = 0; i < session.messages.length; i++) {
+        if (session.messages[i]?.role === 'system') {
+            idx = i;
+            break;
+        }
+    }
+    if (idx === -1) return false;
+    const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
+    if (bp1HasDeferredToolManifestBlock(raw)) {
+        session.deferredToolBp1Applied = true;
+        return true;
+    }
+    if (manifest) {
+        const base = stripDeferredToolManifestBlock(raw);
+        session.messages[idx].content = base
+            ? `${base}\n\n---\n\n${manifest}`
+            : manifest;
+    }
+    session.deferredToolBp1Applied = true;
+    session.updatedAt = Date.now();
+    return true;
+}
+
 /**
  * Build the fixed skill loader meta-tool.
  * A tiny stable schema keeps provider cache keys steady; concrete skill
@@ -558,6 +714,10 @@ export function composeSystemPrompt(opts) {
     if (!_skip.skills && opts.skillManifest && typeof opts.skillManifest === 'string' && opts.skillManifest.trim()) {
         baseParts.push(opts.skillManifest.trim());
     }
+    // deferredToolManifest: optional BP1 slice; production path is applyInitialDeferredToolManifestToBp1 once after applyDeferredToolSurface.
+    if (opts.deferredToolManifest && typeof opts.deferredToolManifest === 'string' && opts.deferredToolManifest.trim()) {
+        baseParts.push(opts.deferredToolManifest.trim());
+    }
     const baseRules = baseParts.join('\n\n---\n\n');
 
     // ── BP2: role/system layer ─────────────────────────────────────────

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -147,6 +147,16 @@ export function getMcpServerStatus() {
         })(),
     }));
 }
+
+/** Snapshot of MCP initialize `instructions` per connected server (handshake time). */
+export function getMcpServerInstructionsMap() {
+    const out = {};
+    for (const server of servers.values()) {
+        const text = typeof server.instructions === 'string' ? server.instructions.trim() : '';
+        if (text) out[server.name] = text;
+    }
+    return out;
+}
 /**
  * Execute an MCP tool call.
  * Name format: `mcp__{serverName}__{toolName}`
@@ -290,6 +300,16 @@ function capMcpOutput(content) {
 export function isMcpTool(name) {
     return name.startsWith('mcp__');
 }
+/** True when the prefixed name exists on a connected MCP server. */
+export function isRegisteredMcpTool(name) {
+    if (!isMcpTool(name)) return false;
+    const match = name.match(/^mcp__(.+?)__(.+)$/);
+    if (!match) return false;
+    const [, serverName] = match;
+    const server = servers.get(serverName);
+    if (!server || !Array.isArray(server.tools)) return false;
+    return server.tools.some((t) => t?.name === name);
+}
 /**
  * Check whether the inputSchema for an MCP tool declares the given top-level
  * property. Used to decide if the orchestrator should auto-inject context
@@ -416,6 +436,10 @@ async function connectServer(name, cfg) {
         throw new Error(`Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`);
     }
     await client.connect(transport);
+    const instructionsRaw = typeof client.getInstructions === 'function'
+        ? client.getInstructions()
+        : undefined;
+    const instructions = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
     const toolsResult = await client.listTools();
     if (!toolsResult || !Array.isArray(toolsResult.tools)) {
         throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
@@ -427,7 +451,7 @@ async function connectServer(name, cfg) {
         ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
     }));
     const toolNames = tools.map(t => t.name);
-    servers.set(name, { name, client, transport, tools, cfg });
+    servers.set(name, { name, client, transport, tools, cfg, instructions });
     _invalidateMcpToolFieldMemo();
     mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
 }

package/src/runtime/agent/orchestrator/providers/gemini-stream.mjs

@@ -425,6 +425,7 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
     try {
         armFirstByteTimer();
         resetIdleTimer();
+        var collectedChunks = [];
         while (true) {
             if (idleTimedOut) {
                 throw geminiTimeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
@@ -463,6 +464,7 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
                 clearFirstByteTimer();
             }
             resetIdleTimer();
+            if (step.value) collectedChunks.push(step.value);
             try { onStreamDelta?.(); } catch {}
             if (onTextDelta || textLeakGuard) {
                 const t = geminiChunkText(step.value);
@@ -488,17 +490,30 @@ export async function consumeGeminiSdkStream(streamResult, { signal, onStreamDel
         try { textLeakGuard?.finalize(); } catch {}
     }
 
-    let response;
-    try {
-        response = await streamResult.response;
-    } catch (err) {
-        if (signal?.aborted) {
-            const reason = signal.reason;
-            throw reason instanceof Error ? reason : new Error(`${label} aborted`);
+    // Aggregate the raw wire chunks locally instead of awaiting the SDK's
+    // streamResult.response: @google/generative-ai 0.24.1 aggregateResponses()
+    // predates Gemini 3 thinking and silently drops part.thoughtSignature.
+    // Losing the signature breaks the mandatory echo-back on the next turn
+    // (400 "Function call is missing a thought_signature in functionCall
+    // parts"). aggregateGeminiStreamChunks() preserves it (see part copy
+    // above). Fall back to the SDK aggregate only if we somehow collected no
+    // usable chunks.
+    let raw;
+    if (collectedChunks.length > 0) {
+        raw = aggregateGeminiStreamChunks(collectedChunks);
+    } else {
+        let response;
+        try {
+            response = await streamResult.response;
+        } catch (err) {
+            if (signal?.aborted) {
+                const reason = signal.reason;
+                throw reason instanceof Error ? reason : new Error(`${label} aborted`);
+            }
+            throw err;
         }
-        throw err;
+        raw = response?.candidates ? response : (response?.response || response);
     }
-    const raw = response?.candidates ? response : (response?.response || response);
     const finishReason = raw?.candidates?.[0]?.finishReason || null;
     assertGeminiStreamCompleted({ sawStreamChunk, finishReason, label });
     return raw;

package/src/runtime/agent/orchestrator/providers/gemini.mjs

@@ -174,12 +174,29 @@ export class GeminiProvider {
     // a few iterations.
     async _ensureGeminiCache({ apiKey, model, systemInstruction, geminiTools, contents, opts }) {
         if (Array.isArray(opts?.nativeTools) && opts.nativeTools.length) return null;
+        // Kill-switch: MIXDOG_GEMINI_EXPLICIT_CACHE=0 skips cachedContents
+        // entirely and relies on Gemini's implicit prefix caching (2.5+/3.x
+        // default, same 90% discount, no storage fee). A/B probe knob.
+        const explicitMode = String(process.env.MIXDOG_GEMINI_EXPLICIT_CACHE || '').trim().toLowerCase();
+        if (['0', 'false', 'off', 'no'].includes(explicitMode)) return null;
         const state = opts.providerState?.gemini || null;
         const now = Date.now();
         const currentIter = Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : 1;
         const refreshEveryN = Number(process.env.MIXDOG_GEMINI_CACHE_REFRESH_EVERY) > 0
             ? Number(process.env.MIXDOG_GEMINI_CACHE_REFRESH_EVERY)
             : 4;
+        // Cache TTL (storage is billed per token-hour, so shorter is cheaper).
+        // Default 5m: agent tool loops re-request within seconds, and the
+        // refresh-every-4-iterations rebuild re-arms the TTL well before
+        // expiry. Long-idle sessions just pay one cold rebuild on resume.
+        const ttlSeconds = Number(process.env.MIXDOG_GEMINI_CACHE_TTL_SECONDS) > 0
+            ? Number(process.env.MIXDOG_GEMINI_CACHE_TTL_SECONDS)
+            : 300;
+        // Reuse guard: require some remaining TTL headroom so we never attach
+        // a cache that expires mid-request. Scale with TTL (25%, clamped to
+        // 10s..6m) — the old fixed 6-minute floor silently disabled reuse for
+        // any TTL <= 6m, forcing a full-price rebuild every turn.
+        const reuseHeadroomMs = Math.min(6 * 60 * 1000, Math.max(10 * 1000, ttlSeconds * 250));
         const cacheLiveMs = state?.cacheExpiresAt ? state.cacheExpiresAt - now : 0;
         const itersSinceCreate = state?.cacheCreatedAtIter != null
             ? currentIter - state.cacheCreatedAtIter
@@ -203,7 +220,7 @@ export class GeminiProvider {
             && !!state?.cachePrefixHash
             && state.cachePrefixHash === currentStatePrefixHash;
         const canAttachState = !!state?.cacheName && cacheLiveMs > 0 && modelMatches && prefixMatches;
-        const canReuseState = canAttachState && cacheLiveMs > 6 * 60 * 1000 && itersSinceCreate < refreshEveryN;
+        const canReuseState = canAttachState && cacheLiveMs > reuseHeadroomMs && itersSinceCreate < refreshEveryN;
         try {
             appendAgentTrace({
                 sessionId: opts.sessionId || opts.session?.id || null,
@@ -253,7 +270,6 @@ export class GeminiProvider {
             } catch {}
             return canAttachState ? state.cacheName : null;
         }
-        const ttlSeconds = 3600;
         const cachePrefixContentCount = _geminiCachePrefixCount(contents);
         const cachePrefixHash = _geminiCachePrefixHash({
             model,

package/src/runtime/agent/orchestrator/providers/openai-compat-xai.mjs

@@ -66,11 +66,30 @@ export function xaiResponsesCacheRouting(opts, params, rawTools, model) {
     const providerKey = resolveProviderCacheKey(opts, 'xai');
     const prefixSeed = xaiPrefixSeed({ opts, params, rawTools, model });
     const prefixHash = traceHash(prefixSeed);
+    // Optional lane sharding (OpenAI prompt-caching guidance: keep each
+    // prefix+prompt_cache_key combo under ~15 RPM). When lane shards are
+    // enabled (MIXDOG_XAI_RESPONSES_CACHE_LANE_SHARDS=N or lane auto), mix the
+    // assigned slot into the routing seed so sessions spread across N server
+    // cache keys instead of overflowing one. Slot is derived from a hash of
+    // the session id (NOT in-process round-robin: headless workers run one
+    // session per process, where round-robin degenerates to slot 0 for
+    // everyone). Default stays a single shared key (lane disabled) —
+    // identical seed/key to before.
+    const lane = xaiResponsesPromptCacheLane(opts, null, { prefixHash, ownerSessionHash: sessionId ? traceHash(sessionId) : null });
+    const laneEnabled = lane?.enabled === true;
+    const laneShards = Number.isFinite(Number(lane?.shards)) && Number(lane.shards) > 0 ? Number(lane.shards) : 0;
+    const explicitSlot = Number(opts?.promptCacheLaneSlot ?? opts?.xaiCacheLaneSlot);
+    const laneSlot = Number.isFinite(explicitSlot) && explicitSlot >= 0
+        ? (laneShards > 0 ? Math.floor(explicitSlot) % laneShards : Math.floor(explicitSlot))
+        : (laneShards > 0
+            ? createHash('sha256').update(sessionId || String(process.pid)).digest().readUInt32BE(0) % laneShards
+            : Number.isFinite(Number(lane?.slot)) ? Number(lane.slot) : 0);
     const routingSeed = stableTraceStringify({
         scope: 'xai-responses-prefix-v1',
         providerKey: String(providerKey),
         model: model || null,
         prefixHash,
+        ...(laneEnabled ? { laneSlot } : {}),
     });
     return {
         key: deterministicUuidFromKey(routingSeed),
@@ -78,6 +97,10 @@ export function xaiResponsesCacheRouting(opts, params, rawTools, model) {
         seedHash: traceHash(routingSeed),
         prefixHash,
         ownerSessionHash: sessionId ? traceHash(sessionId) : null,
+        ...(laneEnabled ? {
+            laneIndex: laneSlot,
+            activeLanes: Number.isFinite(Number(lane?.shards)) && Number(lane.shards) > 0 ? Number(lane.shards) : null,
+        } : {}),
     };
 }
 

package/src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs

@@ -254,6 +254,15 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts } = {}) {
         turn_id: turnId,
         window_id: windowId,
         request_kind: requestKind,
+        // Richer codex turn-metadata fields (responses_metadata.rs:264-280:
+        // thread_source "user" per protocol.rs:2751-2765, sandbox label).
+        // A/B 2026-07-04 (rvA/rvB interleaved, 24 sessions/arm): no effect
+        // (it2 full 3 vs 2, miss 2 vs 3 — noise). Default OFF; keep the knob
+        // for future probes if the backend starts gating on payload richness.
+        ...(process.env.MIXDOG_OAI_TURN_METADATA_RICH === '1' ? {
+            thread_source: 'user',
+            sandbox: 'read-only',
+        } : {}),
         turn_started_at_unix_ms: startedAt,
     };
     const metadata = {

package/src/runtime/agent/orchestrator/session/loop/deferred-call-through.mjs

@@ -0,0 +1,79 @@
+// Deferred catalog call-through: inactive catalog tool_use → discovery bookkeeping
+// then normal executeTool routing (runtime errors only; no pre-dispatch schema).
+import { clean } from '../../../../../session-runtime/session-text.mjs';
+import { isReadonlySelectable, selectDeferredTools } from '../../../../../session-runtime/tool-catalog.mjs';
+
+/** Skill-list plumbing only; mutation/MCP/builtins must use the catalog+mode gate. */
+const INACTIVE_INFRA_BYPASS = new Set(['skills_list', 'skill_view']);
+
+function isActiveSessionTool(session, name) {
+    const key = clean(name);
+    if (!key || !Array.isArray(session?.tools)) return false;
+    return session.tools.some((tool) => clean(tool?.name) === key);
+}
+
+function lookupDeferredCatalogTool(session, name) {
+    const catalog = Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : [];
+    const key = clean(name);
+    if (!key) return null;
+    for (const tool of catalog) {
+        const n = clean(tool?.name);
+        if (n === key || n.toLowerCase() === key.toLowerCase()) return tool;
+    }
+    return null;
+}
+
+export function isOnDeferredToolSurface(session, name) {
+    if (!session) return false;
+    return isActiveSessionTool(session, name) || lookupDeferredCatalogTool(session, name) !== null;
+}
+
+export function toolExecutesWhenInactive(name) {
+    return INACTIVE_INFRA_BYPASS.has(name);
+}
+
+function resolveDeferredSelectMode(session) {
+    const spec = session?.toolSpec;
+    if (spec == null || spec === '') return null;
+    if (spec === 'readonly') return 'readonly';
+    if (spec === 'full' || spec === 'mcp') return 'full';
+    if (Array.isArray(spec)) {
+        if (!spec.length) return null;
+        if (spec.includes('full')) return 'full';
+        if (spec.includes('tools:readonly')) return 'readonly';
+        return 'full';
+    }
+    return null;
+}
+
+function denyDeferredCallThrough(message) {
+    return { deny: message };
+}
+
+/**
+ * Inactive deferred catalog hits: readonly/mode gate + promoteToActive, or deny.
+ * Returns null when not applicable (not in catalog, already active, infra allowlist).
+ */
+export function prepareDeferredToolCallThrough(sessionRef, name, _args) {
+    if (!sessionRef) return null;
+    const tool = lookupDeferredCatalogTool(sessionRef, name);
+    if (!tool) return null;
+    if (isActiveSessionTool(sessionRef, name)) return null;
+    if (toolExecutesWhenInactive(name)) return null;
+
+    const toolLabel = clean(tool.name) || clean(name) || 'tool';
+    const resolvedMode = resolveDeferredSelectMode(sessionRef);
+    if (resolvedMode === null) {
+        if (!isReadonlySelectable(tool)) {
+            return denyDeferredCallThrough(
+                `Error: tool "${toolLabel}" is deferred and cannot be auto-loaded without a resolved tool mode; use tool_search or load it explicitly.`,
+            );
+        }
+    } else if (resolvedMode === 'readonly' && !isReadonlySelectable(tool)) {
+        return denyDeferredCallThrough(`Error: tool "${toolLabel}" is not available in readonly mode`);
+    }
+
+    const selectMode = resolvedMode === null ? 'readonly' : resolvedMode;
+    selectDeferredTools(sessionRef, [toolLabel], selectMode, { promoteToActive: true });
+    return null;
+}

package/src/runtime/agent/orchestrator/session/loop/tool-exec.mjs

@@ -3,7 +3,7 @@
 // shell/apply_patch/builtin/external-adapter) through before/after hooks and the
 // scoped-cache outcome bookkeeping. No behavior change: bodies are verbatim from
 // loop.mjs, re-exported via the facade so existing importers keep working.
-import { executeMcpTool, isMcpTool, mcpToolHasField } from '../../mcp/client.mjs';
+import { executeMcpTool, isMcpTool, isRegisteredMcpTool, mcpToolHasField } from '../../mcp/client.mjs';
 import { executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool, isExternalAdapterTool } from '../../tools/builtin.mjs';
 import { executeBashSessionTool } from '../../tools/bash-session.mjs';
 import { executePatchTool } from '../../tools/patch.mjs';
@@ -21,6 +21,7 @@ import {
     buildAgentBashSessionArgs,
     resolvePreToolAskApproval,
 } from './tool-helpers.mjs';
+import { isOnDeferredToolSurface, prepareDeferredToolCallThrough } from './deferred-call-through.mjs';
 
 let codeGraphRuntimePromise = null;
 async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
@@ -125,6 +126,8 @@ export async function executeTool(name, args, cwd, callerSessionId, sessionRef,
     const afterToolHook = typeof executeOpts.afterToolHook === 'function'
         ? executeOpts.afterToolHook
         : sessionRef?.afterToolHook;
+    const deferredPrep = prepareDeferredToolCallThrough(sessionRef, name, args);
+    if (deferredPrep?.deny) return deferredPrep.deny;
     const __result = await (async () => {
     if (name === 'Skill') {
         return viewSkill(cwd, args?.name);
@@ -136,6 +139,9 @@ export async function executeTool(name, args, cwd, callerSessionId, sessionRef,
         return viewSkill(cwd, args?.name);
     }
     if (isMcpTool(name)) {
+        if (!isOnDeferredToolSurface(sessionRef, name) && !isRegisteredMcpTool(name)) {
+            return formatUnknownBuiltinToolMessage(name, args, 'tool');
+        }
         // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
         // (bash / grep / read / list / glob etc.) but the worker session's
         // cwd was previously dropped here. Inject cwd only when the tool's

package/src/runtime/agent/orchestrator/session/loop/tool-helpers.mjs

@@ -4,7 +4,13 @@
 import { isMcpTool } from '../../mcp/client.mjs';
 import { isBuiltinTool } from '../../tools/builtin.mjs';
 import { isInternalTool } from '../../internal-tools.mjs';
-import { collectSkillsCached, loadSkillResource, buildSkillToolEnvelope } from '../../context/collect.mjs';
+import {
+    collectSkillsCached,
+    loadSkillResource,
+    buildSkillToolEnvelope,
+    filterSkillsExcludingDisabled,
+    isSkillDisabled,
+} from '../../context/collect.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 
 // Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
@@ -37,12 +43,13 @@ export function getToolKind(name) {
     return 'builtin';
 }
 export function buildSkillsListResponse(cwd) {
-    const skills = collectSkillsCached(cwd);
+    const skills = filterSkillsExcludingDisabled(collectSkillsCached(cwd));
     const entries = skills.map(s => ({ name: s.name, description: s.description || '' }));
     return JSON.stringify({ skills: entries });
 }
 export function viewSkill(cwd, name) {
     if (!name) return 'Error: skill name is required';
+    if (isSkillDisabled(name)) return `Error: skill "${name}" is disabled`;
     const res = loadSkillResource(name, cwd);
     if (!res) return `Error: skill "${name}" not found`;
     // Return the general tool envelope: the model-visible tool_result is the

package/src/runtime/agent/orchestrator/session/manager.mjs

@@ -13,7 +13,7 @@ import {
 } from './compact.mjs';
 import { estimateMessagesTokens, estimateTranscriptContextUsage } from './context-utils.mjs';
 import { executeInternalTool } from '../internal-tools.mjs';
-import { collectSkillsCached, buildSkillManifest, composeSystemPrompt } from '../context/collect.mjs';
+import { collectPromptSkillsCached, buildSkillManifest, composeSystemPrompt } from '../context/collect.mjs';
 import { saveSession, saveSessionAsync, loadSession, listStoredSessionSummaries, sweepStaleSessions, markSessionClosed, bumpSessionGeneration, setLiveSession } from './store.mjs';
 import { clearReadDedupSession, tryPrefetchCached, setPrefetchCached } from './read-dedup.mjs';
 import { clearOffloadSession } from './tool-result-offload.mjs';
@@ -636,7 +636,7 @@ export function createSession(opts) {
     // maintenance roles are deliberately narrowed away from the Skill tool.
     // Do not leak a Skill manifest into those hidden prompts when no Skill()
     // loader is available.
-    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectSkillsCached(opts.cwd);
+    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectPromptSkillsCached(opts.cwd);
 
     // BP1 is shared tool policy (+ compact skill manifest in compose). BP2 is
     // role/system rules. User-defined schedules/webhooks ride as normal user
@@ -1785,7 +1785,7 @@ export async function resumeSession(sessionId, preset) {
     // createSession so resume and spawn produce identical BP_1 shapes.
     const oldTools = session.tools || [];
     const ownerIsAgent = isAgentOwner(session);
-    const skills = ownerIsAgent ? [] : collectSkillsCached(session.cwd);
+    const skills = ownerIsAgent ? [] : collectPromptSkillsCached(session.cwd);
     let toolSpec = ownerIsAgent ? 'full' : (preset || session.preset || 'full');
     if (session.profileId && _agentRuntimeApi?.getProfile) {
         try {

package/src/runtime/agent/orchestrator/tools/builtin/arg-guard.mjs

@@ -9,7 +9,7 @@
 // callers may pass either spelling (e.g. `glob` alias for grep, or
 // `file_path` alias for read.path).
 
-import { coerceShapeFlex, hasGlobMagic } from './path-utils.mjs';
+import { coerceReadFamilyPathArg, coerceShapeFlex, hasGlobMagic } from './path-utils.mjs';
 
 const MAX_INT = 100000;
 // Explicit grep context should be large enough to frame a function/block without
@@ -368,11 +368,11 @@ function guardRead(a) {
         return 'Error: read requires "path" (or alias file_path).';
     }
     // Some providers/models send a batched path array as a JSON string despite
-    // the schema. The executor already accepts that shape via coerceShapeFlex(),
-    // but validation runs first; apply the same lossless shape coercion here so
-    // valid batched reads do not waste a retry turn.
+    // the schema (or path:"[]" meaning cwd). The executor coerces via
+    // coerceReadFamilyPathArg(); mirror that here so validation does not reject
+    // shapes the executor would absorb.
     if (hasOwn(a, 'path')) {
-        a.path = coerceShapeFlex(a.path);
+        a.path = coerceReadFamilyPathArg(a.path);
     }
     // path can be string | string[] | object[]; file_path is string
     if (hasOwn(a, 'path')) {

package/src/runtime/agent/orchestrator/tools/builtin/external-tool-adapters.mjs

@@ -12,7 +12,7 @@
 // adapter expects — the caller (builtin.mjs default: case) falls back to
 // the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
 import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
-import { dirname, sep } from 'node:path';
+import { dirname } from 'node:path';
 import { atomicWrite } from './atomic-write.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
 import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
@@ -102,25 +102,6 @@ function guardRealTarget(fullPath) {
     return null;
 }
 
-// Write containment — mirrors apply_patch's realBase check: the REAL resolved
-// target (symlinks flattened, create-mode suffix re-attached lexically) must
-// stay inside the REAL workDir. A lexically-inside path whose ancestor
-// symlink/junction lands outside the project must not be writable through
-// this adapter surface (apply_patch refuses the same shape).
-function guardBaseContainment(fullPath, workDir) {
-    let realBase;
-    try { realBase = realpathSync(workDir); } catch { return null; }
-    const nearest = realpathNearestExisting(fullPath);
-    if (!nearest) return null;
-    const realResolved = nearest.real + fullPath.slice(nearest.probe.length);
-    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
-    const baseWithSep = realBase.endsWith(sep) ? realBase : realBase + sep;
-    if (fold(realResolved) !== fold(realBase) && !fold(realResolved).startsWith(fold(baseWithSep))) {
-        return `Error: cannot write outside the working directory: ${normalizeOutputPath(realResolved)} escapes ${normalizeOutputPath(realBase)}`;
-    }
-    return null;
-}
-
 async function resolveTargetPath(args, workDir) {
     const raw = args?.path ?? args?.file_path;
     if (typeof raw !== 'string' || raw.length === 0) return null;
@@ -138,8 +119,6 @@ async function resolveTargetPath(args, workDir) {
     catch (e) { return { error: `Error: ${e?.message || e}` }; }
     const realGuardErr = guardRealTarget(full);
     if (realGuardErr) return { error: realGuardErr };
-    const containErr = guardBaseContainment(full, workDir);
-    if (containErr) return { error: containErr };
     return { full };
 }