🤖 Include tool names in mode switch sentinel (#250)

## Summary

When mode switches mid-conversation, the AI now receives information
about which tools are available in the new mode. This helps models make
better decisions about how to proceed after a mode transition.

## Changes

**Extended mode transition sentinel to include tool availability:**
- Added optional `toolNames` parameter to `injectModeTransition()`
- Reorganized `aiService.ts` to determine tools before message
transformations
- Mode transition messages now include tool names when available

**Example transition message:**
```
[Mode switched from plan to exec. Follow exec mode instructions. Available tools: file_read, bash, propose_plan, web_search.]
```

**Benefits:**
- Models understand what tools are newly available/unavailable after
mode switch
- Handles model-specific tools (e.g., `web_search` only for some models)
- Respects tool policy filters automatically
- Backward compatible (tools parameter is optional)

## Testing

Added comprehensive test coverage:
- Mode switch with tools - verifies tool names appear in sentinel
- Mode switch without tools parameter - ensures backward compatibility
- Mode switch with empty tool list - graceful handling
- Existing mode transition tests still pass

All 489 tests pass including new test cases.

_Generated with `cmux`_

Author: ammar-agent

src/services/aiService.ts

@@ -1,5 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
+import * as os from "os";
 import { EventEmitter } from "events";
 import { convertToModelMessages, wrapLanguageModel, type LanguageModel } from "ai";
 import { applyToolOutputRedaction } from "@/utils/messages/applyToolOutputRedaction";
@@ -436,6 +437,15 @@ export class AIService extends EventEmitter {
       // Extract provider name from modelString (e.g., "anthropic:claude-opus-4-1" -> "anthropic")
       const [providerName] = modelString.split(":");
 
+      // Get tool names early for mode transition sentinel (stub config, no workspace context needed)
+      const earlyAllTools = await getToolsForModel(modelString, {
+        cwd: process.cwd(),
+        tempDir: os.tmpdir(),
+        secrets: {},
+      });
+      const earlyTools = applyToolPolicy(earlyAllTools, toolPolicy);
+      const toolNamesForSentinel = Object.keys(earlyTools);
+
       // Filter out assistant messages with only reasoning (no text/tools)
       const filteredMessages = filterEmptyAssistantMessages(messages);
       log.debug(`Filtered ${messages.length - filteredMessages.length} empty assistant messages`);
@@ -452,7 +462,12 @@ export class AIService extends EventEmitter {
       const messagesWithSentinel = addInterruptedSentinel(filteredMessages);
 
       // Inject mode transition context if mode changed from last assistant message
-      const messagesWithModeContext = injectModeTransition(messagesWithSentinel, mode);
+      // Include tool names so model knows what tools are available in the new mode
+      const messagesWithModeContext = injectModeTransition(
+        messagesWithSentinel,
+        mode,
+        toolNamesForSentinel
+      );
 
       // Apply centralized tool-output redaction BEFORE converting to provider ModelMessages
       // This keeps the persisted/UI history intact while trimming heavy fields for the request

src/utils/messages/modelMessageTransform.test.ts

@@ -847,4 +847,105 @@ describe("injectModeTransition", () => {
     expect(result.length).toBe(1);
     expect(result).toEqual(messages);
   });
+
+  it("should include tool names in transition message when provided", () => {
+    const messages: CmuxMessage[] = [
+      {
+        id: "user-1",
+        role: "user",
+        parts: [{ type: "text", text: "Let's plan a feature" }],
+        metadata: { timestamp: 1000 },
+      },
+      {
+        id: "assistant-1",
+        role: "assistant",
+        parts: [{ type: "text", text: "Here's the plan..." }],
+        metadata: { timestamp: 2000, mode: "plan" },
+      },
+      {
+        id: "user-2",
+        role: "user",
+        parts: [{ type: "text", text: "Now execute it" }],
+        metadata: { timestamp: 3000 },
+      },
+    ];
+
+    const toolNames = ["file_read", "bash", "file_edit_replace_string", "web_search"];
+    const result = injectModeTransition(messages, "exec", toolNames);
+
+    // Should have 4 messages: user, assistant, mode-transition, user
+    expect(result.length).toBe(4);
+
+    // Third message should be mode transition with tool names
+    expect(result[2].role).toBe("user");
+    expect(result[2].metadata?.synthetic).toBe(true);
+    expect(result[2].parts[0]).toMatchObject({
+      type: "text",
+      text: "[Mode switched from plan to exec. Follow exec mode instructions. Available tools: file_read, bash, file_edit_replace_string, web_search.]",
+    });
+  });
+
+  it("should handle mode transition without tools parameter (backward compatibility)", () => {
+    const messages: CmuxMessage[] = [
+      {
+        id: "user-1",
+        role: "user",
+        parts: [{ type: "text", text: "Let's plan" }],
+        metadata: { timestamp: 1000 },
+      },
+      {
+        id: "assistant-1",
+        role: "assistant",
+        parts: [{ type: "text", text: "Planning..." }],
+        metadata: { timestamp: 2000, mode: "plan" },
+      },
+      {
+        id: "user-2",
+        role: "user",
+        parts: [{ type: "text", text: "Execute" }],
+        metadata: { timestamp: 3000 },
+      },
+    ];
+
+    const result = injectModeTransition(messages, "exec");
+
+    // Should have 4 messages with transition, but no tool info
+    expect(result.length).toBe(4);
+    expect(result[2].parts[0]).toMatchObject({
+      type: "text",
+      text: "[Mode switched from plan to exec. Follow exec mode instructions.]",
+    });
+  });
+
+  it("should handle mode transition with empty tool list", () => {
+    const messages: CmuxMessage[] = [
+      {
+        id: "user-1",
+        role: "user",
+        parts: [{ type: "text", text: "Let's plan" }],
+        metadata: { timestamp: 1000 },
+      },
+      {
+        id: "assistant-1",
+        role: "assistant",
+        parts: [{ type: "text", text: "Planning..." }],
+        metadata: { timestamp: 2000, mode: "plan" },
+      },
+      {
+        id: "user-2",
+        role: "user",
+        parts: [{ type: "text", text: "Execute" }],
+        metadata: { timestamp: 3000 },
+      },
+    ];
+
+    const result = injectModeTransition(messages, "exec", []);
+
+    // Should have 4 messages with transition, but no tool info (empty array handled gracefully)
+    expect(result.length).toBe(4);
+    expect(result[2].parts[0]).toMatchObject({
+      type: "text",
+      text: "[Mode switched from plan to exec. Follow exec mode instructions.]",
+    });
+  });
 });

src/utils/messages/modelMessageTransform.ts

@@ -113,9 +113,14 @@ export function addInterruptedSentinel(messages: CmuxMessage[]): CmuxMessage[] {
  *
  * @param messages The conversation history
  * @param currentMode The mode for the upcoming assistant response (e.g., "plan", "exec")
+ * @param toolNames Optional list of available tool names to include in transition message
  * @returns Messages with mode transition context injected if needed
  */
-export function injectModeTransition(messages: CmuxMessage[], currentMode?: string): CmuxMessage[] {
+export function injectModeTransition(
+  messages: CmuxMessage[],
+  currentMode?: string,
+  toolNames?: string[]
+): CmuxMessage[] {
   // No mode specified, nothing to do
   if (!currentMode) {
     return messages;
@@ -160,13 +165,22 @@ export function injectModeTransition(messages: CmuxMessage[], currentMode?: stri
   }
 
   // Inject mode transition message right before the last user message
+  let transitionText = `[Mode switched from ${lastMode} to ${currentMode}. Follow ${currentMode} mode instructions.`;
+
+  // Append tool availability if provided
+  if (toolNames && toolNames.length > 0) {
+    transitionText += ` Available tools: ${toolNames.join(", ")}.]`;
+  } else {
+    transitionText += "]";
+  }
+
   const transitionMessage: CmuxMessage = {
     id: `mode-transition-${Date.now()}`,
     role: "user",
     parts: [
       {
         type: "text",
-        text: `[Mode switched from ${lastMode} to ${currentMode}. Follow ${currentMode} mode instructions.]`,
+        text: transitionText,
       },
     ],
     metadata: {