Fixes #4747: Add context overflow contingency for subtasks

[roomote]

Summary

This PR implements a context overflow contingency feature for subtasks to address issue #4747. The feature prevents subtasks from getting stuck when browser interactions or other tools return large amounts of content that cause context overflow.

Changes Made

Core Implementation

• Added contextOverflowContingency configuration to ModeConfig schema in packages/types/src/mode.ts

  • enabled: Boolean to enable/disable the feature
  • message: Default message when overflow is detected
  • toolSpecific: Tool-specific override messages

• Implemented context overflow detection in Task class in src/core/task/Task.ts

  • Added checkContextOverflowContingency() method to monitor token usage
  • Integrated checks into recursivelyMakeClineRequests() and attemptApiRequest()
  • Graceful exit with attempt_completion when overflow detected (90% threshold)
  • Tool detection for specific error messages

Testing & Documentation

• Comprehensive test suite in src/core/task/__tests__/ContextOverflowContingency.test.ts

  • Tests for subtask vs non-subtask behavior
  • Tests for enabled/disabled states
  • Tests for custom and tool-specific messages
  • All tests passing ✅

• Complete documentation in docs/context-overflow-contingency.md

  • Configuration examples
  • Use cases and benefits
  • Implementation details

How It Works

1. Monitoring: Checks context usage before API requests and during task execution
2. Threshold Detection: Triggers when context usage exceeds 90% of model's context window
3. Tool Detection: Identifies last tool used for specific error messages
4. Graceful Exit: Subtask exits with attempt_completion containing configured message
5. Parent Continuation: Parent task receives completion message and can continue

Example Configuration

customModes:
  - slug: "mcp-expert"
    name: "MCP Expert"
    roleDefinition: "You are an expert at handling browser interactions"
    groups: ["read", "edit", "browser", "command", "mcp"]
    contextOverflowContingency:
      enabled: true
      message: "Task failed because of a context overflow, possibly because webpage returned from the browser was too big"
      toolSpecific:
        browser_action: "Browser action returned too much content, causing context overflow"

Benefits

• ✅ Prevents hanging subtasks due to context overflow
• ✅ Maintains workflow continuity for parent tasks
• ✅ Provides clear, actionable error messages
• ✅ Supports tool-specific error handling
• ✅ Only affects subtasks (tasks with parent tasks)
• ✅ Fully configurable per mode

Testing

• All existing tests continue to pass
• New comprehensive test suite covers all scenarios
• TypeScript compilation successful across all packages

Fixes #4747

[ellipsis-dev]

⚠️ This PR is too big for Ellipsis, but support for larger PRs is coming soon. If you want us to prioritize this feature, let us know at [email protected]

---

Generated with ❤️ by ellipsis.dev

[daniel-lxs]

Closing for now, the proposal hasn't been reviewed yet.

I believe we can explore making subtasks fail if the context limit is reached.