[1121] feat: error-interception-middleware (1/3)

[myk1yt]

Stack Position

• Feature Branch: feat/error-interception-middleware
• Stage: 1/3
• Depends on: None

Description

Full Feature Description

• Feature Branch: feat/error-interception-middleware
• Feature Name: Error Interception Middleware
• Purpose: Resolves the problem where errors occurring at tool, parser, validation, and provider boundaries are delivered only as unstructured strings, causing the model to repeat the same incorrect call or leaving users unable to determine the cause and recovery method. Classifies errors into stable categories, retry policies, and occurrence-aware recovery dispositions without losing the original error, converting them into structured recovery guidance.
• Full Change Description: B01 defines the classification category, signal, result, pattern priority, and guidance payload contracts. B02 adds the interception runtime that validates and transforms classifier results and manages task-scoped occurrence/error state. B03 connects this runtime to assistant-message presentation exactly once, showing recoverable messages to both the user and the model.
• Impact Scope: Affects all of src/core/tools/error-interception and the final integration point presentAssistantMessage.ts. Maintained as an internal middleware boundary without changing public provider/tool contracts.
• Errors and Edge Cases: Unknown errors are treated as UNCLASSIFIED while preserving the original text and cause. On transformation or structural validation failure, falls back to the original error. If presentation itself fails, interception is not recursively invoked. Repeated occurrences of the same fingerprint escalate to correct_once, change_strategy, await_user, etc. based on occurrence count, without producing duplicate messages. Metadata does not include sensitive values such as commands, absolute paths, or raw arguments.
• Testing Method: Run B01's category precedence, known/unknown classification, and redaction tests, B02's transformation/validation/state reset/recursion tests, and B03's one-time integration and legacy behavior regression tests. Manually trigger known tool errors and unclassified errors respectively, verifying that structured guidance is shown only once and that original technical information and the normal task error path are preserved.

Why Split Into 17 PRs

Instead of submitting this feature as a single unified PR, it was split into individual PRs because as code size grows, safely reviewing a PR becomes very difficult. The feature was broken into mutually exclusive individual PRs so that each can be reviewed independently.

What This PR Specifically Changes

Adds classification category, signal/stage/source, retry/recovery contracts, pattern priority, known/unknown classifier, and redaction-safe facts. Does not change task execution or assistant presentation.

Included Files

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

Exclusion Scope

• Task execution changes
• Assistant-message rendering changes
• B02 runtime and B03 integration files
• All items in the common removal rules

Summary by CodeRabbit

• New Features
  • Added structured detection and classification for common tool and workflow errors.
  • Provides clearer error categories, severity levels, retry guidance, and recovery recommendations.
  • Recognizes missing tools or parameters, invalid data, file and shell failures, protocol errors, and context limits.
  • Sanitizes error details and guidance to reduce unsafe or misleading content.
  • Supports consistent handling of individual errors and structured tool results, with a reliable fallback for unclassified issues.

---

Upstream PR: Zoo-Code-Org#1121