feat(error-interception): user-friendly error UI with structured detail view

- Change MessageTransformer output from raw JSON to <error_details> block
- Add CATEGORY_TITLES mapping for all 11 error categories
- Add helper functions: getCategoryTitle, getErrorTitleFromGuided, formatErrorDetails
- Update all 6 cline.say('error') paths in presentAssistantMessage to use user-friendly titles
- Update ToolErrorInterceptor circuit breaker to use <error_details> format
- Update all test assertions from JSON.parse to string-content checks
- All 174 tests pass across 8 test files

Author: Zoo (VP)

docs/260726_0003_session_error-hiding-fix/074338_code-light-report.md

@@ -0,0 +1,45 @@
+# Code Light Task Report
+
+## Task Summary
+
+Rebuilt VSIX package and installed it after the AI guidance UI fix.
+
+## Actions Taken
+
+1. Ran `pnpm bundle --production` in `src/` — esbuild completed successfully (1932 files bundled).
+2. Ran `npx vsce package --no-dependencies --out ../bin` — packaged `zoo-code-3.72.0.vsix`.
+3. Installed via `code --install-extension bin\zoo-code-3.72.0.vsix --force` — extension successfully installed.
+
+## Result
+
+✅ **Success** — VSIX built and installed without errors.
+
+## VSIX Details
+
+- **Path**: `bin/zoo-code-3.72.0.vsix`
+- **Size**: 34,761,246 bytes (~33.15 MB)
+- **Version**: 3.72.0
+- **File count**: 1932 files
+
+## Build Output Highlights
+
+- 924 asset files (2.32 MB)
+- 175 dist files (97.69 MB uncompressed)
+- 801 webview-ui files (56.5 MB uncompressed)
+- 126 locale files
+- 36 tree-sitter language WASMs
+- 4 esbuild-wasm files
+- Note: `url.parse()` deprecation warning from Node.js v24 (non-blocking, cosmetic only)
+
+## Issues Discovered
+
+- Engine warning: wanted Node `20.20.2`, current `v24.16.0`. Build succeeds but is unsupported per `package.json` engine constraint.
+
+## Next Step Recommendations
+
+- Reload VS Code window to activate the newly installed extension.
+- Verify the AI guidance UI fix is visible and functional.
+
+## Affected File List
+
+- `bin/zoo-code-3.72.0.vsix` (generated artifact)

docs/260726_0003_session_error-hiding-fix/164100_code-report.md

@@ -0,0 +1,33 @@
+# Code Task Report
+
+## Task Summary
+
+Show AI guidance (WHAT/WHY/NEXT JSON) in Zoo Code UI alongside error messages for all 3 error interception paths in `presentAssistantMessage.ts`.
+
+## Actions Taken
+
+1. Read [`presentAssistantMessage.ts`](src/core/assistant-message/presentAssistantMessage.ts:559) to locate the 3 `cline.say("error", ...)` call sites.
+2. Applied surgical edits to all 3 error paths:
+    - **Line ~559 (Missing nativeArgs)**: Now appends `\n\n--- AI Guidance ---\n${guided}` when `guided` is truthy.
+    - **Line ~780 (Structural preflight)**: Same pattern, using `[${variant}]` prefix.
+    - **Line ~859 (Validation catch)**: Same pattern, using `Validation error:` prefix.
+3. Ran the test suite: `cd src; npx vitest run core/assistant-message/__tests__/presentAssistantMessage-error-interception.spec.ts` — all 19 tests passed.
+4. Verified no test assertions reference the exact error message format (no updates needed).
+5. Committed: `fix(error-interception): show AI guidance (WHAT/WHY/NEXT) to user in UI`.
+6. Pushed to `myk1yt/feature/combined-all-features`.
+
+## Result
+
+✅ Success. All 3 error paths now show both the error category message AND the structured AI guidance (WHAT/WHY/NEXT) to the user in the UI chat. When `guided` is undefined (no interceptor output), the original error message is shown unchanged.
+
+## Issues Discovered
+
+None.
+
+## Next Step Recommendations
+
+- Consider adding UI tests that assert the `--- AI Guidance ---` separator appears in the rendered error message when guidance is present.
+
+## Affected File List
+
+- `src/core/assistant-message/presentAssistantMessage.ts`

docs/260726_0003_session_error-hiding-fix/170650_code-report.md

@@ -0,0 +1,79 @@
+# Code Mode Task Report
+
+## Task Summary
+
+Make all error interception patterns user-friendly with clickable detail view. Changed the error output format from raw JSON to a structured `<error_details>` block, and added user-friendly titles for each error category displayed in the chat UI via `cline.say("error", ...)`.
+
+## Actions Taken
+
+### 1. MessageTransformer.ts — Core format change
+
+- Added `CATEGORY_TITLES` mapping: each `ErrorCategory` now has a concise, user-friendly title (e.g., `PARAM_TYPE_MISMATCH` → "Tool Call Format Error", `FILE_NOT_FOUND` → "File Not Found").
+- Added exported helpers: `getCategoryTitle()`, `extractCategoryFromGuided()`, `getErrorTitleFromGuided()`, `formatErrorDetails()`.
+- Replaced `serializePayload()` (JSON.stringify) with `formatPayloadAsDetails()` — produces a human-readable `<error_details>` block:
+    ```
+    <error_details>
+    Type: guided_tool_error
+    Category: PARAM_TYPE_MISMATCH
+    What: ...
+    Why: ...
+    Next:
+    1. ...
+    2. ...
+    Retryable: true
+    Pattern: EI/PARAM_TYPE_MISMATCH/002
+    Occurrence: 1
+    </error_details>
+    ```
+- Updated `fitPayloadWithinByteLimit()` → `fitDetailsWithinByteLimit()` with the same truncation strategy (reduce next items, then truncate why/what).
+
+### 2. ToolErrorInterceptor.ts — Circuit breaker format
+
+- Replaced `CIRCUIT_OPEN_MESSAGE` (plain object, JSON.stringify'd) with `CIRCUIT_OPEN_DETAILS` (pre-formatted `<error_details>` string via `formatErrorDetails()`).
+- Updated both circuit-open return paths to use `CIRCUIT_OPEN_DETAILS` directly.
+
+### 3. presentAssistantMessage.ts — User-friendly titles in UI
+
+- Added import of `getErrorTitleFromGuided` from error-interception module.
+- Updated all 6 `cline.say("error", ...)` paths to use the user-friendly title + `<error_details>` content:
+    1. Missing tool_use.id (INVALID_TOOL_PROTOCOL)
+    2. Missing nativeArgs / invalid JSON (PARAM_MISSING / INVALID_JSON_ARGUMENTS)
+    3. Structural preflight — CWD_OBJECT_MISUSE / NESTED_PARAM_OVERFLOW
+    4. Validation catch (type mismatch, mode restriction, etc.)
+    5. Custom tool arg validation failure
+    6. Unknown tool error
+
+### 4. index.ts — New exports
+
+- Exported `extractCategoryFromGuided`, `formatErrorDetails`, `getCategoryTitle`, `getErrorTitleFromGuided`.
+
+### 5. Test updates
+
+- **MessageTransformer.spec.ts**: Rewrote all assertions from `JSON.parse()` + field checks to string-content checks (`toContain`). Added new test suite for category title helpers.
+- **ToolErrorInterceptor.spec.ts**: Replaced all 13 `JSON.parse()` assertions with string-content checks.
+- **presentAssistantMessage-error-interception.spec.ts**: Updated CONTEXT_OVERFLOW test from JSON.parse to string checks. Updated CWD_OBJECT_MISUSE and NESTED_PARAM_OVERFLOW assertions to check for `PARAM_TYPE_MISMATCH` category + pattern ID instead of variant names.
+- **presentAssistantMessage-unknown-tool.spec.ts**: Updated `say("error")` assertion to check for guided title instead of raw i18n string.
+
+## Result
+
+✅ Success — All 174 tests pass across 8 test files (0 failures).
+
+## Issues Discovered
+
+None. The format change was clean and all existing test assertions were updated to match the new `<error_details>` format.
+
+## Next Step Recommendations
+
+- Consider adding integration tests that verify the `<error_details>` format is parseable by the AI model in actual conversation flows.
+- The `isErrorResult()` method in ToolErrorInterceptor already checks for `<error_details>` prefix (line 297), so the new format is compatible with the existing error detection logic.
+
+## Affected File List
+
+- `src/core/tools/error-interception/MessageTransformer.ts` (modified — core format change)
+- `src/core/tools/error-interception/ToolErrorInterceptor.ts` (modified — circuit breaker format)
+- `src/core/tools/error-interception/index.ts` (modified — new exports)
+- `src/core/assistant-message/presentAssistantMessage.ts` (modified — user-friendly titles in 6 error paths)
+- `src/core/tools/error-interception/__tests__/MessageTransformer.spec.ts` (modified — test assertions)
+- `src/core/tools/error-interception/__tests__/ToolErrorInterceptor.spec.ts` (modified — test assertions)
+- `src/core/assistant-message/__tests__/presentAssistantMessage-error-interception.spec.ts` (modified — test assertions)
+- `src/core/assistant-message/__tests__/presentAssistantMessage-unknown-tool.spec.ts` (modified — test assertion)

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

@@ -255,7 +255,8 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 			// User must see the error in the UI (design principle: both must happen).
 			const errorSayCalls = mockTask.say.mock.calls.filter((c: any[]) => c[0] === "error")
 			expect(errorSayCalls.length).toBe(1)
-			expect(errorSayCalls[0][1]).toContain("CWD_OBJECT_MISUSE")
+			expect(errorSayCalls[0][1]).toContain("PARAM_TYPE_MISMATCH")
+			expect(errorSayCalls[0][1]).toContain("EI/PARAM_TYPE_MISMATCH/002")
 		})
 
 		it("blocks tool_use with NESTED_PARAM_OVERFLOW and pushes guided tool_result", async () => {
@@ -293,7 +294,8 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 			// User must see the error in the UI (design principle: both must happen).
 			const errorSayCalls = mockTask.say.mock.calls.filter((c: any[]) => c[0] === "error")
 			expect(errorSayCalls.length).toBe(1)
-			expect(errorSayCalls[0][1]).toContain("NESTED_PARAM_OVERFLOW")
+			expect(errorSayCalls[0][1]).toContain("PARAM_TYPE_MISMATCH")
+			expect(errorSayCalls[0][1]).toContain("EI/PARAM_TYPE_MISMATCH/003")
 		})
 
 		it("escalates to STRUCTURAL_MISUSE_REPEAT on second identical misuse", async () => {
@@ -496,7 +498,7 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 			)
 		})
 	})
-	
+
 	describe("validation error classification (validateToolUse catch)", () => {
 		it("classifies 'not allowed in' as modeRestriction and pushes tool_result", async () => {
 			const { validateToolUse } = await import("../../tools/validateToolUse")
@@ -594,7 +596,7 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 			expect(errorSayCalls[0][1]).toContain("File restriction")
 		})
 	})
-	
+
 	describe("tool repetition detection", () => {
 		it("pushes guided error and asks user when repetition is detected", async () => {
 			const toolCallId = "call_repetition"
@@ -608,7 +610,7 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 					partial: false,
 				},
 			]
-	
+
 			// Mock repetition detector to block execution
 			mockTask.toolRepetitionDetector.check.mockReturnValue({
 				allowExecution: false,
@@ -617,22 +619,19 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 					messageDetail: "Tool {toolName} has been repeated too many times.",
 				},
 			})
-	
+
 			// Mock user response
 			mockTask.ask.mockResolvedValue({ response: "yesButtonClicked" })
-	
+
 			await presentAssistantMessage(mockTask)
-	
+
 			// Should have called ask for user confirmation
-			expect(mockTask.ask).toHaveBeenCalledWith(
-				"tool_repetition_limit",
-				expect.stringContaining("read_file"),
-			)
+			expect(mockTask.ask).toHaveBeenCalledWith("tool_repetition_limit", expect.stringContaining("read_file"))
 			// Should NOT have set didAlreadyUseTool (the tool was blocked)
 			expect(mockTask.didAlreadyUseTool).toBe(false)
 		})
 	})
-	
+
 	describe("unknown tool handling", () => {
 		it("pushes guided tool_result for unknown tool and does not set didAlreadyUseTool", async () => {
 			const toolCallId = "call_unknown_tool_handler"
@@ -646,9 +645,9 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 					partial: false,
 				},
 			]
-	
+
 			await presentAssistantMessage(mockTask)
-	
+
 			const toolResult = mockTask.userMessageContent.find(
 				(item: any) => item.type === "tool_result" && item.tool_use_id === toolCallId,
 			)
@@ -661,17 +660,17 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 			)
 			expect(mockTask.didAlreadyUseTool).toBe(false)
 		})
-	
+
 		describe("INVALID_JSON_ARGUMENTS - concatenated JSON tool call", () => {
 			it("produces guided tool_result with INVALID_JSON_ARGUMENTS when parse error is recorded", async () => {
 				const toolCallId = "call_concat_json_001"
-	
+
 				// Simulate NativeToolCallParser having recorded a JSON.parse
 				// failure for this tool call (e.g. concatenated JSON objects).
 				vi.mocked(NativeToolCallParser.consumeParseError).mockReturnValue(
 					"Unexpected non-whitespace character after JSON at position 42",
 				)
-	
+
 				mockTask.assistantMessageContent = [
 					{
 						type: "tool_use",
@@ -682,9 +681,9 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 						partial: false,
 					},
 				]
-	
+
 				await presentAssistantMessage(mockTask)
-	
+
 				const toolResult = mockTask.userMessageContent.find(
 					(item: any) => item.type === "tool_result" && item.tool_use_id === toolCallId,
 				)
@@ -704,13 +703,13 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 				// Should NOT have set didAlreadyUseTool
 				expect(mockTask.didAlreadyUseTool).toBe(false)
 			})
-	
+
 			it("falls back to PARAM_MISSING when no parse error is recorded", async () => {
 				const toolCallId = "call_missing_args_002"
-	
+
 				// No parse error recorded — simulate the original missing-args path
 				vi.mocked(NativeToolCallParser.consumeParseError).mockReturnValue(undefined)
-	
+
 				mockTask.assistantMessageContent = [
 					{
 						type: "tool_use",
@@ -720,9 +719,9 @@ describe("presentAssistantMessage - Error Interception Integration", () => {
 						partial: false,
 					},
 				]
-	
+
 				await presentAssistantMessage(mockTask)
-	
+
 				const toolResult = mockTask.userMessageContent.find(
 					(item: any) => item.type === "tool_result" && item.tool_use_id === toolCallId,
 				)
@@ -732,37 +731,35 @@ 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)
+
+					expect(message).toContain("<error_details>")
+					expect(message).toContain("</error_details>")
+					expect(message).toContain("Type: guided_runtime_error")
+					expect(message).toContain("Category: CONTEXT_OVERFLOW")
+					expect(message).toContain("Retryable: true")
+					expect(message).toContain("Pattern: EI/CONTEXT_OVERFLOW/001")
+					expect(message.toLowerCase()).toContain("context")
+					expect(message.toLowerCase()).toContain("exceeded")
+					expect(message).toContain("summary")
+					expect(message).toContain("Do not repeat")
 				})
 			})
 		})

src/core/assistant-message/__tests__/presentAssistantMessage-unknown-tool.spec.ts

@@ -106,8 +106,8 @@ describe("presentAssistantMessage - Unknown Tool Handling", () => {
 			expect.stringContaining("Unknown tool"),
 		)
 
-		// Verify error message was shown to user (uses i18n key)
-		expect(mockTask.say).toHaveBeenCalledWith("error", "unknownToolError")
+		// Verify error message was shown to user with guided details
+		expect(mockTask.say).toHaveBeenCalledWith("error", expect.stringContaining("Tool Call Format Error"))
 	})
 
 	it("should fail fast when tool_use is missing id (legacy/XML-style tool call)", async () => {
@@ -127,9 +127,7 @@ describe("presentAssistantMessage - Unknown Tool Handling", () => {
 		// Should not execute tool; should surface a clear error message.
 		const textBlocks = mockTask.userMessageContent.filter((item: any) => item.type === "text")
 		expect(textBlocks.length).toBeGreaterThan(0)
-		expect(textBlocks.some((b: any) => String(b.text).includes("guided_tool_error"))).toBe(
-			true,
-		)
+		expect(textBlocks.some((b: any) => String(b.text).includes("guided_tool_error"))).toBe(true)
 
 		// Verify consecutiveMistakeCount was incremented
 		expect(mockTask.consecutiveMistakeCount).toBe(1)