feat(error-interception): improve AI guidance quality for 4 patterns

Author: Zoo (VP)

src/core/assistant-message/__tests__/presentAssistantMessage-error-interception.spec.ts

@@ -3,6 +3,7 @@
 import { describe, it, expect, beforeEach, vi } from "vitest"
 import { presentAssistantMessage } from "../presentAssistantMessage"
 import { getTaskErrorState } from "../../tools/error-interception"
+import { ToolErrorInterceptor } from "../../tools/error-interception/ToolErrorInterceptor"
 import { NativeToolCallParser } from "../NativeToolCallParser"
 
 // Mock heavy dependencies that are not relevant to error interception paths.
@@ -667,8 +668,9 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 				expect(String(toolResult.content)).toContain("INVALID_JSON_ARGUMENTS")
 				// The guidance should mention concatenation
 				expect(String(toolResult.content)).toContain("concatenated")
-				// Should mention one tool call per file
-				expect(String(toolResult.content)).toContain("one tool call per file")
+				// Should mention sequential (one at a time) calls, not parallel
+				expect(String(toolResult.content)).toContain("ONE AT A TIME")
+				expect(String(toolResult.content)).toContain("never in parallel")
 				// Should NOT contain the generic PARAM_MISSING message
 				expect(String(toolResult.content)).not.toContain("PARAM_MISSING")
 				// consecutiveMistakeCount should increment
@@ -704,6 +706,39 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 				expect(String(toolResult.content)).toContain("PARAM_MISSING")
 				expect(String(toolResult.content)).not.toContain("INVALID_JSON_ARGUMENTS")
 			})
+		
+			describe("CONTEXT_OVERFLOW guidance", () => {
+				it("produces guided_runtime_error payload with correct guidance for context overflow", () => {
+					// Directly test the interceptor's transformError path for a
+					// context overflow signal, simulating an API request that was
+					// rejected due to context window limits.
+					const interceptor = new ToolErrorInterceptor()
+					const task = {}
+		
+					const signal = {
+						source: "api_request" as const,
+						stage: "api" as const,
+						taskId: "ei-task-id",
+						metadata: { contextWindowExceeded: true },
+					}
+		
+					const message = interceptor.transformError(task, signal)
+					expect(message).toBeDefined()
+		
+					const parsed = JSON.parse(message!)
+					expect(parsed.version).toBe(1)
+					expect(parsed.status).toBe("error")
+					expect(parsed.type).toBe("guided_runtime_error")
+					expect(parsed.category).toBe("CONTEXT_OVERFLOW")
+					expect(parsed.retryable).toBe(true)
+					expect(parsed.pattern_id).toBe("EI/CONTEXT_OVERFLOW/001")
+					expect(parsed.what).toContain("context")
+					expect(parsed.what).toContain("exceeded")
+					expect(parsed.next.length).toBeGreaterThan(0)
+					expect(parsed.next.some((n: string) => n.includes("summary"))).toBe(true)
+					expect(parsed.next.some((n: string) => n.includes("Do not repeat"))).toBe(true)
+				})
+			})
 		})
 	})
 })

src/core/tools/error-interception/ErrorClassifier.ts

@@ -17,6 +17,7 @@ const SAFE_FACT_KEYS = new Set<string>([
 	"invalidProtocol",
 	"missingNativeArgs",
 	"missingParameter",
+	"parameterName",
 	"pathEmpty",
 	"repetitionCount",
 	"retryDisposition",
@@ -61,6 +62,59 @@ function hasToolContext(signal: InterceptionSignal): boolean {
 	return signal.toolName !== undefined || signal.toolCallId !== undefined
 }
 
+/**
+ * Extract a parameter name from an error message or result text.
+ *
+ * Common patterns from tool execution errors:
+ * - "Required parameter 'path' is missing"
+ * - "The 'path' parameter must be a string"
+ * - "Missing required parameter: command"
+ * - "parameter 'path' is required"
+ */
+function extractParameterName(signal: InterceptionSignal): string | undefined {
+	// Check metadata first (explicitly provided by the caller).
+	const metaName = signal.metadata["parameterName"]
+	if (typeof metaName === "string" && metaName.length > 0) return metaName
+
+	// Try to extract from error.message.
+	if (signal.error !== null && typeof signal.error === "object") {
+		const message = (signal.error as { message?: unknown }).message
+		if (typeof message === "string") {
+			const name = tryExtractParamNameFromText(message)
+			if (name) return name
+		}
+	}
+
+	// Try to extract from result.text.
+	if (typeof signal.result === "object" && signal.result !== null) {
+		const text = (signal.result as { text?: unknown }).text
+		if (typeof text === "string") {
+			const name = tryExtractParamNameFromText(text)
+			if (name) return name
+		}
+	}
+
+	return undefined
+}
+
+function tryExtractParamNameFromText(text: string): string | undefined {
+	// Pattern: "parameter 'name'" or "parameter \"name\"" or "parameter: name"
+	const paramQuoteMatch = text.match(/parameter\s*['"']([^'"']+)['"']/i)
+	if (paramQuoteMatch) return paramQuoteMatch[1]
+
+	// Pattern: "Required parameter 'name'" — already covered above, but also
+	// try "Missing required parameter: name" (colon-separated, no quotes).
+	const colonMatch = text.match(/(?:missing|required)\s+parameter\s*[:\s]+(\w+)/i)
+	if (colonMatch) return colonMatch[1]
+
+	// Pattern: "The 'name' parameter must be..." — extract the quoted name
+	// before the word "parameter".
+	const theParamMatch = text.match(/the\s+['"']([^'"']+)['"']\s+parameter/i)
+	if (theParamMatch) return theParamMatch[1]
+
+	return undefined
+}
+
 function isEligible(pattern: ErrorPattern, signal: InterceptionSignal): boolean {
 	if (pattern.category === "UNCLASSIFIED") return false
 	return !pattern.requiresToolContext || hasToolContext(signal)
@@ -90,6 +144,22 @@ function sanitizeFacts(signal: InterceptionSignal, pattern: ErrorPattern): Reado
 	facts.category = pattern.category
 	facts.errorSource = signal.source
 
+	// Inject extracted parameter name for PARAM_MISSING and generic
+	// PARAM_TYPE_MISMATCH patterns so the transformer can include it in
+	// guidance messages. Skip the CWD_OBJECT_MISUSE and NESTED_PARAM_OVERFLOW
+	// variants — they have their own specific guidance.
+	if (
+		pattern.category === "PARAM_MISSING" ||
+		(pattern.category === "PARAM_TYPE_MISMATCH" && pattern.id === "EI/PARAM_TYPE_MISMATCH/001")
+	) {
+		if (facts.parameterName === undefined) {
+			const paramName = extractParameterName(signal)
+			if (paramName !== undefined) {
+				facts.parameterName = paramName
+			}
+		}
+	}
+
 	return Object.freeze(facts)
 }
 

src/core/tools/error-interception/MessageTransformer.ts

@@ -50,17 +50,40 @@ function resolveTemplate(patternId: string) {
 }
 
 function buildPayload(classification: ErrorClassification, occurrence: number): GuidancePayload {
-	const { category, patternId, retryPolicy } = classification
+	const { category, patternId, retryPolicy, facts } = classification
 	const template = resolveTemplate(patternId)
 
+	let what = template.what
+	let next = template.next
+
+	// Inject extracted parameter name into guidance for PARAM_MISSING and
+	// generic PARAM_TYPE_MISMATCH patterns.
+	const paramName = facts["parameterName"]
+	if (typeof paramName === "string" && paramName.length > 0) {
+		if (category === "PARAM_MISSING") {
+			what = `Required parameter '${paramName}' is missing.`
+			next = [
+				`Provide a valid value for '${paramName}' in a single corrected native tool call.`,
+				"Retry only once with the complete parameter set.",
+			]
+		} else if (category === "PARAM_TYPE_MISMATCH" && patternId === "EI/PARAM_TYPE_MISMATCH/001") {
+			what = `Parameter '${paramName}' has a type that does not match the tool schema.`
+			next = [
+				`Re-read the tool schema for the '${paramName}' parameter.`,
+				"Correct only the reported field type and keep the rest unchanged.",
+				"Submit one corrected native tool call; do not repeat blindly.",
+			]
+		}
+	}
+
 	return {
 		version: GUIDANCE_VERSION,
 		status: "error",
 		type: payloadType(classification.facts["errorSource"] as ErrorSource | undefined),
 		category,
-		what: template.what,
+		what,
 		why: template.why,
-		next: clampNextItems(template.next),
+		next: clampNextItems(next),
 		retryable: isRetryable(retryPolicy, category),
 		occurrence: Math.max(1, occurrence),
 		pattern_id: patternId,

src/core/tools/error-interception/__tests__/ErrorClassifier.spec.ts

@@ -378,6 +378,79 @@ describe("classifyError", () => {
 		})
 	})
 
+	describe("parameter name extraction", () => {
+		it("extracts parameter name from error message for PARAM_MISSING", () => {
+			const signal = baseSignal({
+				source: "validation",
+				stage: "preflight",
+				error: { message: "Required parameter 'path' is missing" },
+				metadata: { missingParameter: true },
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_MISSING")
+			expect(result.facts.parameterName).toBe("path")
+		})
+
+		it("extracts parameter name from result text for PARAM_MISSING", () => {
+			const signal = baseSignal({
+				source: "tool_result",
+				stage: "result",
+				result: { status: "missing-parameter", text: "Missing required parameter: command" },
+				metadata: {},
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_MISSING")
+			expect(result.facts.parameterName).toBe("command")
+		})
+
+		it("extracts parameter name from 'The [name] parameter' pattern for PARAM_TYPE_MISMATCH", () => {
+			const signal = baseSignal({
+				source: "tool_result",
+				stage: "result",
+				error: { code: -32602, message: "The 'path' parameter must be a string" },
+				metadata: {},
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_TYPE_MISMATCH")
+			expect(result.facts.parameterName).toBe("path")
+		})
+
+		it("uses parameterName from metadata when provided", () => {
+			const signal = baseSignal({
+				source: "validation",
+				stage: "preflight",
+				metadata: { missingParameter: true, parameterName: "command" },
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_MISSING")
+			expect(result.facts.parameterName).toBe("command")
+		})
+
+		it("does not set parameterName when no name is extractable", () => {
+			const signal = baseSignal({
+				source: "validation",
+				stage: "preflight",
+				metadata: { missingParameter: true },
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_MISSING")
+			expect(result.facts.parameterName).toBeUndefined()
+		})
+
+		it("does not inject parameterName for CWD_OBJECT_MISUSE variant", () => {
+			const signal = baseSignal({
+				source: "validation",
+				stage: "preflight",
+				error: { message: "cwd must be a string" },
+				metadata: { variant: "CWD_OBJECT_MISUSE" },
+			})
+			const result = classifyError(signal)
+			expect(result.category).toBe("PARAM_TYPE_MISMATCH")
+			expect(result.patternId).toBe("EI/PARAM_TYPE_MISMATCH/002")
+			expect(result.facts.parameterName).toBeUndefined()
+		})
+	})
+
 	describe("classifyToolResult", () => {
 		it("classifies a structured tool result by status", () => {
 			const result = classifyToolResult({ status: "missing-parameter" }, "task-456", "call-1")

src/core/tools/error-interception/__tests__/MessageTransformer.spec.ts

@@ -182,6 +182,90 @@ describe("transformErrorToMessage", () => {
 	})
 })
 
+describe("parameter name injection in guidance", () => {
+	it("injects parameter name into PARAM_MISSING guidance when parameterName fact is present", () => {
+		const classification = {
+			category: "PARAM_MISSING" as const,
+			patternId: "EI/PARAM_MISSING/001",
+			confidence: "exact" as const,
+			retryPolicy: "correct-and-retry" as const,
+			facts: { errorSource: "tool_result", parameterName: "path" },
+		}
+		const message = transformErrorToMessage(classification)
+		const parsed = JSON.parse(message)
+
+		expect(parsed.category).toBe("PARAM_MISSING")
+		expect(parsed.what).toContain("'path'")
+		expect(parsed.what).toContain("missing")
+		expect(parsed.next[0]).toContain("'path'")
+	})
+
+	it("injects parameter name into PARAM_TYPE_MISMATCH guidance when parameterName fact is present", () => {
+		const classification = {
+			category: "PARAM_TYPE_MISMATCH" as const,
+			patternId: "EI/PARAM_TYPE_MISMATCH/001",
+			confidence: "exact" as const,
+			retryPolicy: "correct-and-retry" as const,
+			facts: { errorSource: "tool_result", parameterName: "command" },
+		}
+		const message = transformErrorToMessage(classification)
+		const parsed = JSON.parse(message)
+
+		expect(parsed.category).toBe("PARAM_TYPE_MISMATCH")
+		expect(parsed.what).toContain("'command'")
+		expect(parsed.what).toContain("type")
+		expect(parsed.next[0]).toContain("'command'")
+	})
+
+	it("falls back to generic guidance when parameterName is absent", () => {
+		const classification = {
+			category: "PARAM_MISSING" as const,
+			patternId: "EI/PARAM_MISSING/001",
+			confidence: "exact" as const,
+			retryPolicy: "correct-and-retry" as const,
+			facts: { errorSource: "tool_result" },
+		}
+		const message = transformErrorToMessage(classification)
+		const parsed = JSON.parse(message)
+
+		expect(parsed.category).toBe("PARAM_MISSING")
+		expect(parsed.what).not.toContain("'")
+		expect(parsed.what).toContain("required parameter")
+	})
+
+	it("does not inject parameter name for CWD_OBJECT_MISUSE variant", () => {
+		const classification = {
+			category: "PARAM_TYPE_MISMATCH" as const,
+			patternId: "EI/PARAM_TYPE_MISMATCH/002",
+			confidence: "exact" as const,
+			retryPolicy: "correct-and-retry" as const,
+			facts: { errorSource: "tool_result", parameterName: "cwd" },
+		}
+		const message = transformErrorToMessage(classification)
+		const parsed = JSON.parse(message)
+
+		// CWD_OBJECT_MISUSE has its own specific guidance; parameterName
+		// should NOT override it.
+		expect(parsed.what).toContain("parallel tool call")
+		expect(parsed.what).not.toContain("'cwd'")
+	})
+
+	it("end-to-end: classifies and transforms PARAM_MISSING with parameter name from error message", () => {
+		const signal = baseSignal({
+			source: "validation",
+			stage: "preflight",
+			error: { message: "Required parameter 'path' is missing" },
+			metadata: { missingParameter: true },
+		})
+		const classification = classifyError(signal)
+		const message = transformErrorToMessage(classification)
+		const parsed = JSON.parse(message)
+
+		expect(parsed.category).toBe("PARAM_MISSING")
+		expect(parsed.what).toContain("'path'")
+	})
+})
+
 describe("encode helpers", () => {
 	it("encodeUtf8Bytes returns the same length as getPayloadByteLength", () => {
 		const text = '{"what":"test"}'

src/core/tools/error-interception/errorPatterns.ts

@@ -292,8 +292,8 @@ export const ERROR_PATTERNS: readonly ErrorPattern[] = [
 			what: "The requested MCP tool or server is not registered or is unavailable.",
 			why: "The tool name may belong to a different MCP namespace, or the server/tool is disabled.",
 			next: [
-				"Select the tool from the returned available server/tool list.",
-				"Do not guess names or invent namespaces.",
+				"Check the available MCP tools by examining the tool definitions provided in the system prompt or by using the list_mcp_tools command.",
+				"Select a tool from the available server/tool list; do not guess names or invent namespaces.",
 				"If no replacement exists, inform the user and stop retrying.",
 			],
 		},
@@ -368,7 +368,8 @@ export const ERROR_PATTERNS: readonly ErrorPattern[] = [
 			what: "Tool call arguments could not be parsed as JSON.",
 			why: "You concatenated multiple JSON objects into a single arguments string. Each tool call must contain exactly one valid JSON object.",
 			next: [
-				"Issue one tool call per file. Use parallel tool calls if you need multiple files simultaneously.",
+				"Make tool calls ONE AT A TIME, never in parallel.",
+				"Each tool call must contain exactly one valid JSON object as arguments.",
 			],
 		},
 	},