fix: clarify GPT-5 tool use instructions to allow explanations with code changes

- Modified getSharedToolUseSection to accept modelId parameter
- Added GPT-5 specific instructions clarifying that explanations should accompany tool use
- Updated system.ts to pass modelId to getSharedToolUseSection
- Added comprehensive tests for GPT-5 prompt handling

Fixes #7264

src/core/prompts/sections/__tests__/tool-use.spec.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest"
+import { getSharedToolUseSection } from "../tool-use"
+
+describe("getSharedToolUseSection", () => {
+	it("should return standard tool use section for non-GPT-5 models", () => {
+		const result = getSharedToolUseSection("gpt-4")
+		expect(result).toContain("You have access to a set of tools")
+		expect(result).toContain("You can use one tool per message")
+		expect(result).not.toContain("IMPORTANT for GPT-5")
+		expect(result).not.toContain("explanatory text before or after the tool invocation")
+	})
+
+	it("should return standard tool use section when no model is provided", () => {
+		const result = getSharedToolUseSection()
+		expect(result).toContain("You have access to a set of tools")
+		expect(result).toContain("You can use one tool per message")
+		expect(result).not.toContain("IMPORTANT for GPT-5")
+		expect(result).not.toContain("explanatory text before or after the tool invocation")
+	})
+
+	it("should return GPT-5 specific tool use section for gpt-5 models", () => {
+		const result = getSharedToolUseSection("gpt-5-2025-08-07")
+		expect(result).toContain("You have access to a set of tools")
+		expect(result).toContain("You can use one tool per message")
+		expect(result).toContain("IMPORTANT for GPT-5")
+		expect(result).toContain("When using tools to make code changes, you should provide explanations")
+		expect(result).toContain("explanatory text before or after the tool invocation")
+		expect(result).toContain("describe what you're doing and why")
+	})
+
+	it("should return GPT-5 specific tool use section for gpt-5-mini models", () => {
+		const result = getSharedToolUseSection("gpt-5-mini-2025-08-07")
+		expect(result).toContain("IMPORTANT for GPT-5")
+		expect(result).toContain("When using tools to make code changes, you should provide explanations")
+	})
+
+	it("should return GPT-5 specific tool use section for gpt-5-nano models", () => {
+		const result = getSharedToolUseSection("gpt-5-nano-2025-08-07")
+		expect(result).toContain("IMPORTANT for GPT-5")
+		expect(result).toContain("When using tools to make code changes, you should provide explanations")
+	})
+
+	it("should return GPT-5 specific tool use section for gpt-5-chat-latest", () => {
+		const result = getSharedToolUseSection("gpt-5-chat-latest")
+		expect(result).toContain("IMPORTANT for GPT-5")
+		expect(result).toContain("When using tools to make code changes, you should provide explanations")
+	})
+
+	it("should handle case-insensitive GPT-5 model detection", () => {
+		const result1 = getSharedToolUseSection("GPT-5-2025-08-07")
+		expect(result1).toContain("IMPORTANT for GPT-5")
+
+		const result2 = getSharedToolUseSection("Gpt-5-Mini")
+		expect(result2).toContain("IMPORTANT for GPT-5")
+
+		const result3 = getSharedToolUseSection("openai/gpt5-turbo")
+		expect(result3).toContain("IMPORTANT for GPT-5")
+	})
+
+	it("should maintain consistent formatting structure", () => {
+		const standardResult = getSharedToolUseSection("gpt-4")
+		const gpt5Result = getSharedToolUseSection("gpt-5-2025-08-07")
+
+		// Both should have the same overall structure
+		expect(standardResult).toContain("====")
+		expect(standardResult).toContain("TOOL USE")
+		expect(standardResult).toContain("# Tool Use Formatting")
+		expect(standardResult).toContain("<actual_tool_name>")
+
+		expect(gpt5Result).toContain("====")
+		expect(gpt5Result).toContain("TOOL USE")
+		expect(gpt5Result).toContain("# Tool Use Formatting")
+		expect(gpt5Result).toContain("<actual_tool_name>")
+	})
+})

src/core/prompts/sections/tool-use.ts

@@ -1,9 +1,17 @@
-export function getSharedToolUseSection(): string {
+export function getSharedToolUseSection(modelId?: string): string {
+	// Check if this is a GPT-5 model
+	const isGpt5Model = modelId?.toLowerCase().includes("gpt-5") || modelId?.toLowerCase().includes("gpt5")
+
+	// Add GPT-5 specific clarification about explanations with tool use
+	const toolUseIntro = isGpt5Model
+		? `You have access to a set of tools that are executed upon the user's approval. You can use one tool per message, and will receive the result of that tool use in the user's response. **IMPORTANT for GPT-5**: When using tools to make code changes, you should provide explanations of your changes alongside the tool use in the same message. The "one tool per message" rule means you can only invoke one tool's XML tags per message, but you can and should include explanatory text before or after the tool invocation to describe what you're doing and why. You use tools step-by-step to accomplish a given task, with each tool use informed by the result of the previous tool use.`
+		: `You have access to a set of tools that are executed upon the user's approval. You can use one tool per message, and will receive the result of that tool use in the user's response. You use tools step-by-step to accomplish a given task, with each tool use informed by the result of the previous tool use.`
+
 	return `====
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. You can use one tool per message, and will receive the result of that tool use in the user's response. You use tools step-by-step to accomplish a given task, with each tool use informed by the result of the previous tool use.
+${toolUseIntro}
 
 # Tool Use Formatting
 

src/core/prompts/system.ts

@@ -92,7 +92,7 @@ async function generatePrompt(
 
 ${markdownFormattingSection()}
 
-${getSharedToolUseSection()}
+${getSharedToolUseSection(modelId)}
 
 ${getToolDescriptionsForMode(
 	mode,