[1126] feat: error-interception-middleware (2/3)

[myk1yt]

Stack Position

• Feature Branch: feat/error-interception-middleware
• Stage: 2/3
• Depends on: feat: error-interception-middleware (1/3) #23

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 interceptor, message transformer, structural validator, task-scoped occurrence/error state, and original error fallback using B01 contracts. Does not change presentAssistantMessage.ts.

Included Files

• src/core/tools/error-interception/ToolErrorInterceptor.ts
• src/core/tools/error-interception/StructuralValidator.ts
• src/core/tools/error-interception/TaskErrorState.ts
• src/core/tools/error-interception/MessageTransformer.ts
• Direct unit tests for the same module

Exclusion Scope

• src/core/assistant-message/presentAssistantMessage.ts and B03 integration test
• Duplicate changes to contracts/classifier already merged in B01
• All items in the common removal rules

Summary by CodeRabbit

• New Features

  • Added automatic classification of common tool errors with safe, actionable guidance.
  • Added validation for malformed working-directory values and nested tool inputs.
  • Added task-scoped error tracking, recovery escalation, and circuit breaking after repeated shell failures.
  • Preserved unsupported results and callbacks while transforming recognized failures into concise, size-limited messages.

• Bug Fixes

  • Prevented sensitive or unsafe values from appearing in model-facing error guidance.
  • Improved handling of invalid contexts, cyclic inputs, and oversized error details.

• Tests

  • Added comprehensive coverage for classification, validation, transformation, state tracking, and interception behavior.

---

Upstream PR: Zoo-Code-Org#1126