refactor: single source of truth for tool registration

Remove getAvailableTools() - a static duplicate of the dynamic tool
registration logic in getToolsForModel(). This eliminates divergence
between what tools are listed vs actually registered.

Changes:
- Delete getAvailableTools() from toolDefinitions.ts
- extractToolInstructions() now takes explicit toolNames[] instead of
  computing them from modelString
- aiService registers tools first, then extracts instructions only for
  registered tools (fixes instruction extraction for unavailable tools)
- Tokenizer no longer filters by model-specific availability (tools in
  messages were always available when called)
- Add tests for extractToolInstructions() with new signature

The tool registration logic (provider-specific web_search, conditional
bash_background_*) remains in getToolsForModel() where it always was.

Author: ethanndickson

src/common/utils/tools/toolDefinitions.ts

@@ -322,45 +322,3 @@ export function getToolSchemas(): Record<string, ToolSchema> {
     ])
   );
 }
-
-/**
- * Get which tools are available for a given model
- * @param modelString The model string (e.g., "anthropic:claude-opus-4-1")
- * @returns Array of tool names available for the model
- */
-export function getAvailableTools(modelString: string): string[] {
-  const [provider] = modelString.split(":");
-
-  // Base tools available for all models
-  const baseTools = [
-    "bash",
-    "bash_background_read",
-    "bash_background_list",
-    "bash_background_terminate",
-    "file_read",
-    "file_edit_replace_string",
-    // "file_edit_replace_lines", // DISABLED: causes models to break repo state
-    "file_edit_insert",
-    "propose_plan",
-    "todo_write",
-    "todo_read",
-    "status_set",
-    "web_fetch",
-  ];
-
-  // Add provider-specific tools
-  switch (provider) {
-    case "anthropic":
-      return [...baseTools, "web_search"];
-    case "openai":
-      // Only some OpenAI models support web search
-      if (modelString.includes("gpt-4") || modelString.includes("gpt-5")) {
-        return [...baseTools, "web_search"];
-      }
-      return baseTools;
-    case "google":
-      return [...baseTools, "google_search"];
-    default:
-      return baseTools;
-  }
-}

src/common/utils/tools/tools.ts

@@ -52,7 +52,7 @@ export type ToolFactory = (config: ToolConfiguration) => Tool;
  * @param additionalInstructions Additional instructions to append to the description
  * @returns The same tool instance with the augmented description
  */
-function augmentToolDescription(baseTool: Tool, additionalInstructions: string): Tool {
+export function augmentToolDescription(baseTool: Tool, additionalInstructions: string): Tool {
   // Access the tool as a record to get its properties
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const baseToolRecord = baseTool as any as Record<string, unknown>;

src/node/services/aiService.ts

@@ -16,7 +16,7 @@ import type { Config, ProviderConfig } from "@/node/config";
 import { StreamManager } from "./streamManager";
 import type { InitStateManager } from "./initStateManager";
 import type { SendMessageError } from "@/common/types/errors";
-import { getToolsForModel } from "@/common/utils/tools/tools";
+import { getToolsForModel, augmentToolDescription } from "@/common/utils/tools/tools";
 import { createRuntime } from "@/node/runtime/runtimeFactory";
 import { secretsToRecord } from "@/common/types/secrets";
 import type { MuxProviderOptions } from "@/common/types/providerOptions";
@@ -752,15 +752,8 @@ export class AIService extends EventEmitter {
       const streamToken = this.streamManager.generateStreamToken();
       const runtimeTempDir = await this.streamManager.createTempDirForStream(streamToken, runtime);
 
-      // Extract tool-specific instructions from AGENTS.md files
-      const toolInstructions = await readToolInstructions(
-        metadata,
-        runtime,
-        workspacePath,
-        modelString
-      );
-
       // Get model-specific tools with workspace path (correct for local or remote)
+      // Tools are registered first based on runtime capabilities
       const allTools = await getToolsForModel(
         modelString,
         {
@@ -772,10 +765,28 @@ export class AIService extends EventEmitter {
           workspaceId,
         },
         workspaceId,
-        this.initStateManager,
-        toolInstructions
+        this.initStateManager
       );
 
+      // Extract tool-specific instructions only for registered tools
+      // This ensures we don't extract instructions for tools that aren't available
+      // (e.g., background tools in SSH workspaces or CLI paths without a manager)
+      const registeredToolNames = Object.keys(allTools);
+      const toolInstructions = await readToolInstructions(
+        metadata,
+        runtime,
+        workspacePath,
+        registeredToolNames
+      );
+
+      // Apply tool instructions to registered tools
+      for (const [toolName, instructions] of Object.entries(toolInstructions)) {
+        const tool = allTools[toolName];
+        if (tool) {
+          augmentToolDescription(tool, instructions);
+        }
+      }
+
       // Apply tool policy to filter tools (if policy provided)
       const tools = applyToolPolicy(allTools, toolPolicy);
 

src/node/services/systemMessage.test.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs/promises";
 import * as os from "os";
 import * as path from "path";
-import { buildSystemMessage } from "./systemMessage";
+import { buildSystemMessage, extractToolInstructions } from "./systemMessage";
 import type { WorkspaceMetadata } from "@/common/types/workspace";
 import { DEFAULT_RUNTIME_CONFIG } from "@/common/constants/workspace";
 
@@ -436,3 +436,57 @@ Answer in two sentences max.
     }
   });
 });
+
+describe("extractToolInstructions", () => {
+  test("extracts instructions only for specified tools", () => {
+    const globalInstructions = `
+# Tool: bash
+Custom bash instructions here.
+
+# Tool: file_read
+Custom file_read instructions here.
+
+# Tool: nonexistent_tool
+This should not be extracted.
+`;
+    const result = extractToolInstructions(globalInstructions, null, ["bash", "file_read"]);
+
+    expect(Object.keys(result).sort()).toEqual(["bash", "file_read"]);
+    expect(result.bash).toContain("Custom bash instructions");
+    expect(result.file_read).toContain("Custom file_read instructions");
+    expect(result.nonexistent_tool).toBeUndefined();
+  });
+
+  test("prefers context instructions over global", () => {
+    const globalInstructions = "# Tool: bash\nGlobal bash instructions";
+    const contextInstructions = "# Tool: bash\nContext bash instructions";
+
+    const result = extractToolInstructions(globalInstructions, contextInstructions, ["bash"]);
+
+    expect(result.bash).toContain("Context bash instructions");
+    expect(result.bash).not.toContain("Global bash instructions");
+  });
+
+  test("falls back to global when context lacks tool section", () => {
+    const globalInstructions = "# Tool: bash\nGlobal bash instructions";
+    const contextInstructions = "# Tool: file_read\nContext file_read instructions";
+
+    const result = extractToolInstructions(globalInstructions, contextInstructions, [
+      "bash",
+      "file_read",
+    ]);
+
+    expect(result.bash).toContain("Global bash instructions");
+    expect(result.file_read).toContain("Context file_read instructions");
+  });
+
+  test("returns empty object when no matching tools", () => {
+    const result = extractToolInstructions("# Tool: bash\nstuff", null, ["web_search"]);
+    expect(result).toEqual({});
+  });
+
+  test("returns empty object for empty tool list", () => {
+    const result = extractToolInstructions("# Tool: bash\nstuff", null, []);
+    expect(result).toEqual({});
+  });
+});

src/node/services/systemMessage.ts

@@ -11,7 +11,6 @@ import {
 } from "@/node/utils/main/markdown";
 import type { Runtime } from "@/node/runtime/Runtime";
 import { getMuxHome } from "@/common/constants/paths";
-import { getAvailableTools } from "@/common/utils/tools/toolDefinitions";
 
 // NOTE: keep this in sync with the docs/models.md file
 
@@ -85,18 +84,17 @@ function getSystemDirectory(): string {
  *
  * @param globalInstructions Global instructions from ~/.mux/AGENTS.md
  * @param contextInstructions Context instructions from workspace/project AGENTS.md
- * @param modelString Active model identifier to determine available tools
+ * @param toolNames List of registered tool names to extract instructions for
  * @returns Map of tool names to their additional instructions
  */
 export function extractToolInstructions(
   globalInstructions: string | null,
   contextInstructions: string | null,
-  modelString: string
+  toolNames: string[]
 ): Record<string, string> {
-  const availableTools = getAvailableTools(modelString);
   const toolInstructions: Record<string, string> = {};
 
-  for (const toolName of availableTools) {
+  for (const toolName of toolNames) {
     // Try context instructions first, then global
     const content =
       (contextInstructions && extractToolSection(contextInstructions, toolName)) ??
@@ -118,22 +116,22 @@ export function extractToolInstructions(
  * @param metadata - Workspace metadata (contains projectPath)
  * @param runtime - Runtime for reading workspace files (supports SSH)
  * @param workspacePath - Workspace directory path
- * @param modelString - Active model identifier to determine available tools
+ * @param toolNames - List of registered tool names to extract instructions for
  * @returns Map of tool names to their additional instructions
  */
 export async function readToolInstructions(
   metadata: WorkspaceMetadata,
   runtime: Runtime,
   workspacePath: string,
-  modelString: string
+  toolNames: string[]
 ): Promise<Record<string, string>> {
   const [globalInstructions, contextInstructions] = await readInstructionSources(
     metadata,
     runtime,
     workspacePath
   );
 
-  return extractToolInstructions(globalInstructions, contextInstructions, modelString);
+  return extractToolInstructions(globalInstructions, contextInstructions, toolNames);
 }
 
 /**

src/node/utils/main/tokenizer.ts

@@ -1,7 +1,7 @@
 import assert from "@/common/utils/assert";
 import CRC32 from "crc-32";
 import { LRUCache } from "lru-cache";
-import { getAvailableTools, getToolSchemas } from "@/common/utils/tools/toolDefinitions";
+import { getToolSchemas } from "@/common/utils/tools/toolDefinitions";
 import type { CountTokensInput } from "./tokenizer.worker";
 import { models, type ModelName } from "ai-tokenizer";
 import { run } from "./workerPool";
@@ -178,14 +178,10 @@ export async function getToolDefinitionTokens(
   modelString: string
 ): Promise<number> {
   try {
-    const availableTools = getAvailableTools(modelString);
-    if (!availableTools.includes(toolName)) {
-      return 0;
-    }
-
     const toolSchemas = getToolSchemas();
     const toolSchema = toolSchemas[toolName];
     if (!toolSchema) {
+      // Provider-native tools (web_search, google_search) have no schema in TOOL_DEFINITIONS
       return 40;
     }