google-gemini / google-gemini/gemini-cli
Feature: Add structured error classification and recovery hints to tool error responses
- Dominant language
- TypeScript
- Stars
- 107k
- Forks
- 14.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 45
Description
### What would you like to be added?
Tool error responses sent to the model are currently unstructured strings (e.g., `{ "error": "File not found: /src/utils/halper.ts" }`), forcing the model to infer error category and recovery strategy from natural language. This leads to suboptimal recovery behavior — the model may retry fatally broken operations or give up on recoverable errors.
Add structured metadata fields to tool error `functionResponse.response`:
- `error_type` — the `ToolErrorType` enum value (e.g., `file_not_found`, `permission_denied`)
- `recoverable` — boolean indicating whether the error is recoverable
- `hint` — actionable recovery guidance specific to the error type
### Why is this needed?
The existing `ToolErrorType` enum and `isFatalToolError()` function already classify errors internally, but this classification is not surfaced to the model. By including structured metadata in error responses, the model can:
1. Distinguish recoverable errors (file not found → try glob) from fatal ones (no space left → stop writing)
2. Follow specific recovery guidance rather than guessing
3. Avoid retry loops on fatal errors
This is backward compatible — new fields only appear when `errorType` is defined.
### Additional context
All three `createErrorResponse` sites (ToolExecutor, CoreToolScheduler, Scheduler) should be updated for consistency.
Contributor guide
Assessment
This issue has not been assessed yet.