Documentation needed for recent features: Report Failure Tool and Applied Rules optimization

[continue[bot]]

Summary

Two tier-2 features were recently merged that need documentation updates:

1. Report Failure Tool (PR #8694, merged Nov 14, 2025)
2. Remove Applied Rules from Chat History (PR #8594, merged Nov 7, 2025)

Feature 1: Report Failure Tool

What Changed

• Introduced a new built-in tool ReportFailure for CLI agents
• Allows agents to explicitly report unrecoverable failures with error messages
• Auto-reports failures on non-retryable errors or exhausted retries
• Posts FAILED status to agents/{id}/status endpoint
• Removed old status tool

Files Changed

• extensions/cli/src/tools/reportFailure.ts (new file)
• extensions/cli/src/tools/allBuiltIns.ts
• extensions/cli/src/commands/serve.ts
• extensions/cli/src/sentry.ts

Documentation Gaps

Currently, there is no documentation for:

• The ReportFailure tool in CLI/agents documentation
• List of built-in tools available in CLI headless mode
• Error handling and failure reporting in agent workflows
• How agents report status back to Mission Control

Suggested Documentation Locations

1. docs/cli/overview.mdx - Add section on built-in tools for CLI
2. docs/agents/overview.mdx - Add error handling and failure reporting section
3. docs/ide-extensions/agent/how-it-works.mdx - Update built-in tools list (if applicable to CLI)
4. Consider creating docs/cli/tools.mdx for comprehensive CLI tools reference

Feature 2: Remove Applied Rules from Chat History

What Changed

• Rules are no longer stored in full text in chat history
• Only rule metadata (RuleMetadata) is now persisted
• Reduces payload size and improves privacy
• Rules can be opened from metadata via source file or URL
• Analytics no longer includes full rule text

Files Changed

• core/index.d.ts - Type changes
• core/llm/rules/getSystemMessageWithRules.ts
• gui/src/components/mainInput/belowMainInput/RulesPeek.tsx
• gui/src/pages/config/sections/RulesSection.tsx
• packages/config-yaml/src/schemas/data/chatInteraction/index.ts

Documentation Gaps

The current rules documentation doesn't mention:

• How rules are stored/persisted in chat history
• Privacy implications of rule handling
• The optimization that rules are not duplicated in chat history
• How to access full rule content from the UI

Suggested Documentation Updates

1. docs/customization/rules.mdx - Add section on "How Rules Are Handled"
2. docs/customize/deep-dives/rules.mdx - Add technical details about rule metadata vs full text
3. Consider adding privacy/data handling information

Acceptance Criteria

• [ ] Document the ReportFailure tool in CLI documentation
• [ ] Create or update a comprehensive list of CLI built-in tools
• [ ] Document error handling and failure reporting for agents
• [ ] Update rules documentation to explain how rules are stored and accessed
• [ ] Add privacy/optimization notes about rule handling
• [ ] Ensure all documentation is consistent across IDE extensions, CLI, and agents
• [ ] Add examples of when/how agents report failures
• [ ] Consider adding troubleshooting section for agent failures

Related PRs

• #8694 - feat: report failure tool
• #8594 - feat: remove applied rules from chat history

Priority

High - These are tier-2 features that shipped without corresponding documentation. Users may not discover or understand these capabilities without proper documentation.

Notes

• The Report Failure tool is specifically for CLI/agent workflows
• The rules optimization is user-transparent but good to document for understanding system behavior
• Consider whether these features need announcement/changelog entries