mobygate 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to mobygate are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version numbers are
 [Semantic Versioning](https://semver.org/).
 
+## [0.7.2] — 2026-04-25
+
+### Fixed
+
+- **"I can't use the tool 'grep' here because it isn't available" refusals**
+  in long-running tasks. Even with `allowedTools: ['mcp__mobygate__*']`
+  blocking everything except client-defined tools, the model retains
+  strong priors from training for Claude Code's built-ins (Bash, Grep,
+  Read, Edit, Glob, WebFetch, ToolSearch, etc.). When a task seemed to
+  call for one — e.g., "find all TODOs" → instinctive reach for Grep —
+  the model would attempt it, get blocked, refuse the task, and stop.
+  Instead of falling back to the available client tool (`searchFiles`,
+  `terminal`, etc.).
+
+  **Fix:** for any tool-enabled request, append a short system-prompt
+  block (~150 tokens) via the SDK's
+  `systemPrompt: { type: 'preset', preset: 'claude_code', append: ... }`
+  option. The append explicitly lists the available client tools and
+  states that Claude Code's built-ins are NOT in this environment.
+  Calibrated to be matter-of-fact ("here's the environment, work
+  within it") rather than over-restrictive — the model now uses
+  available tools or briefly says what's missing, instead of refusing
+  silently.
+
+  Applies to both `/v1/chat/completions` and `/v1/messages`.
+
+### Notes
+
+- New helper: `buildToolUsageGuidance(tools)` in `lib/tool-bridge.js`
+  produces the append text from the OpenAI-shape tool array. The
+  Anthropic surface translates its tool defs to OpenAI shape for the
+  bridge already, so the helper takes one input shape across both.
+- Per-request token overhead: ~150 tokens, only when `tools` is non-empty.
+  No effect on text-only chat or non-tool requests.
+
 ## [0.7.1] — 2026-04-24
 
 Fixes a meaningful token-burn issue for clients that don't pass session

package/lib/tool-bridge.js

@@ -218,6 +218,50 @@ export function hasToolUse(assistantMessage) {
 // Tool results (OpenAI tool messages → Anthropic tool_result content blocks)
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Strict-tool guidance (system-prompt append for tool-enabled requests)
+// ---------------------------------------------------------------------------
+// Even with native MCP registration + a tight `allowedTools` allowlist, the
+// model retains strong priors for Claude Code's built-in tools (Bash, Read,
+// Edit, Grep, Glob, WebFetch, ToolSearch, etc.) from training. When a task
+// seems to need one of those, the model reaches for it, gets blocked by
+// `allowedTools`, says "I can't use the tool 'grep' here because it isn't
+// available," and gives up — instead of falling back to the available
+// client-defined tools. We saw this in production OpenClaw use.
+//
+// The fix: append a short, explicit guidance block to Claude Code's system
+// prompt (via `systemPrompt: { type: 'preset', preset: 'claude_code', append: ... }`)
+// telling the model exactly which tools are available and that built-ins
+// are NOT in this environment. The positive list reinforces what the model
+// already sees via MCP registration; the negative list shuts down the
+// trained-in instinct to reach for built-ins.
+//
+// Calibration matters: too directive and the model becomes over-conservative
+// and refuses legitimate work. We aim for matter-of-fact "here's the
+// environment, work within it" rather than threatening prohibition.
+
+const KNOWN_BUILTINS = 'Bash, Read, Edit, Write, Grep, Glob, NotebookEdit, WebFetch, WebSearch, Task, ToolSearch';
+
+export function buildToolUsageGuidance(openaiTools) {
+  if (!Array.isArray(openaiTools) || openaiTools.length === 0) return null;
+  const names = [];
+  for (const t of openaiTools) {
+    if (t?.type !== 'function' || !t.function?.name) continue;
+    names.push(t.function.name);
+  }
+  if (names.length === 0) return null;
+
+  return [
+    'Tool environment: this session is running through a proxy that exposes only the client-defined tools listed below. Claude Code\'s default built-in tools',
+    `(${KNOWN_BUILTINS}, etc.) are NOT available in this environment and cannot be invoked — calls to them will fail.`,
+    '',
+    'Available tools:',
+    ...names.map((n) => `  - ${n}`),
+    '',
+    'If a task seems to require a built-in tool that isn\'t in this list, accomplish what you can with the available tools and briefly note what\'s missing — do not refuse silently or claim you have no tools.',
+  ].join('\n');
+}
+
 /**
  * Format OpenAI role:'tool' messages as a single user-readable text
  * block to splice into a resumed prompt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobygate",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "OpenAI-compatible local proxy for Claude Max. The Möbius-strip gateway: OpenAI shape in, Claude Max out.",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -55,6 +55,7 @@ import { loadSessions, saveSessions, flushSessionsNow } from './lib/session-stor
 import { LOGS_DIR } from './lib/config.js';
 import {
   buildClientToolsServer,
+  buildToolUsageGuidance,
   extractToolUses,
   hasToolUse,
   toolMessagesToText,
@@ -402,6 +403,12 @@ async function handleStreaming(req, res, body, requestId, sessionKey) {
   // Build the in-process MCP server exposing client tools to the SDK.
   // null when toolsEnabled is false (or all tools are malformed).
   const clientToolsServer = toolsEnabled ? buildClientToolsServer(body.tools) : null;
+  // System-prompt append: tells the model exactly which tools are
+  // available and that Claude Code's built-ins (Bash, Grep, Read, etc.)
+  // are NOT in this environment. Without this, the model trained-in
+  // priors lead it to call Grep/Bash, get blocked by allowedTools, and
+  // refuse the task instead of falling back to client tools. ~150 tokens.
+  const toolsGuidance = clientToolsServer ? buildToolUsageGuidance(body.tools) : null;
   if (images.length) console.log(`  [multimodal] ${images.length} image block(s)`);
   if (toolsEnabled) console.log(`  [tools] ${body.tools.length} client tool(s) registered as MCP`);
 
@@ -458,6 +465,7 @@ async function handleStreaming(req, res, body, requestId, sessionKey) {
           ? {
               mcpServers: { [MCP_SERVER_NAME]: clientToolsServer },
               allowedTools: [`${MCP_TOOL_PREFIX}*`],
+              systemPrompt: { type: 'preset', preset: 'claude_code', append: toolsGuidance },
             }
           : toolsEnabled
             // Tools were requested but none were valid — disable all tools.
@@ -620,6 +628,7 @@ async function handleNonStreaming(res, body, requestId, sessionKey) {
   const prompt = buildQueryPrompt(promptText, images);
   const model = resolveModel(body.model);
   const clientToolsServer = toolsEnabled ? buildClientToolsServer(body.tools) : null;
+  const toolsGuidance = clientToolsServer ? buildToolUsageGuidance(body.tools) : null;
   if (images.length) console.log(`  [multimodal] ${images.length} image block(s)`);
   if (toolsEnabled) console.log(`  [tools] ${body.tools.length} client tool(s) registered as MCP`);
 
@@ -656,6 +665,7 @@ async function handleNonStreaming(res, body, requestId, sessionKey) {
           ? {
               mcpServers: { [MCP_SERVER_NAME]: clientToolsServer },
               allowedTools: [`${MCP_TOOL_PREFIX}*`],
+              systemPrompt: { type: 'preset', preset: 'claude_code', append: toolsGuidance },
             }
           : toolsEnabled
             ? { allowedTools: [] }
@@ -806,6 +816,7 @@ async function handleAnthropicNonStreaming(res, body, requestId, sessionKey) {
       }))
     : null;
   const clientToolsServer = toolsForBridge ? buildClientToolsServer(toolsForBridge) : null;
+  const toolsGuidance = clientToolsServer ? buildToolUsageGuidance(toolsForBridge) : null;
 
   if (images.length) console.log(`  [multimodal] ${images.length} image block(s)`);
   if (toolsEnabled) console.log(`  [tools] ${body.tools.length} client tool(s) registered as MCP`);
@@ -844,6 +855,7 @@ async function handleAnthropicNonStreaming(res, body, requestId, sessionKey) {
           ? {
               mcpServers: { [MCP_SERVER_NAME]: clientToolsServer },
               allowedTools: [`${MCP_TOOL_PREFIX}*`],
+              systemPrompt: { type: 'preset', preset: 'claude_code', append: toolsGuidance },
             }
           : toolsEnabled
             ? { allowedTools: [] }
@@ -948,6 +960,7 @@ async function handleAnthropicStreaming(req, res, body, requestId, sessionKey) {
       }))
     : null;
   const clientToolsServer = toolsForBridge ? buildClientToolsServer(toolsForBridge) : null;
+  const toolsGuidance = clientToolsServer ? buildToolUsageGuidance(toolsForBridge) : null;
 
   if (images.length) console.log(`  [multimodal] ${images.length} image block(s)`);
   if (toolsEnabled) console.log(`  [tools] ${body.tools.length} client tool(s) registered as MCP`);
@@ -1004,6 +1017,7 @@ async function handleAnthropicStreaming(req, res, body, requestId, sessionKey) {
           ? {
               mcpServers: { [MCP_SERVER_NAME]: clientToolsServer },
               allowedTools: [`${MCP_TOOL_PREFIX}*`],
+              systemPrompt: { type: 'preset', preset: 'claude_code', append: toolsGuidance },
             }
           : toolsEnabled
             ? { allowedTools: [] }