feat: add support for external cli in bg agents

[antoniomdk]

Summary

• Add extensible external CLI framework for background agent execution
• Implement Cursor as the first provider, allowing users to leverage existing Cursor subscriptions
• Enable opt-in configuration to route background tasks through external CLI tools instead of OpenCode's native agent system

Changes

New Feature: External CLI Backend

• Users can now configure external CLI tools to handle background agent tasks
• Cursor provider implemented with full support for model selection and workspace configuration
• Extensible provider interface allows future CLI integrations (e.g., aider, codex)

Configuration

{
  external_cli: {
    enabled: true,
    provider: cursor,
    models: {
      explore: gpt-5.1-codex-mini,
      librarian: gpt-5.2
    },
    default_model: gpt-5.1-codex,
    timeout: 300000
  }
}

New Files

• src/features/external-cli/ - External CLI framework
  • types.ts - Provider interface and config types
  • executor.ts - Provider management and execution
  • providers/cursor.ts - Cursor CLI provider implementation
  • providers/index.ts - Provider factory

Modified Files

• src/config/schema.ts - Added ExternalCliConfigSchema with provider selection
• src/features/background-agent/manager.ts - Route to external CLI when enabled
• src/features/background-agent/types.ts - Added external-cli backend type
• src/tools/background-task/tools.ts - Display external-cli backend in task status
• src/index.ts - Wire up external CLI config to BackgroundManager
• README.md - Documentation for external CLI configuration

Adding New Providers

The system is designed for extensibility:

1. Add provider name to ExternalCliProviderSchema in schema.ts
2. Create provider class implementing ExternalCliProviderInterface
3. Register in providers/index.ts

##Testing

• Added unit tests for provider factory and type contracts
• All 630 tests passing

---

Summary by cubic

Adds an external CLI backend for background agents with a Cursor provider, letting users run tasks through Cursor instead of OpenCode. Opt-in via config; tasks and results clearly label the backend.

• New Features

  • External CLI framework with an extensible provider interface.
  • Cursor provider with model selection, workspace, and timeout; executes via cursor-agent with JSON output.
  • BackgroundManager routes to external CLI when enabled; tasks include backend = "external-cli" or "opencode".
  • Task status/result formatting shows external-cli outputs.
  • Config/schema updates (Zod + JSON schema) and provider factory.
  • Unit tests for provider factory, types, and manager; existing tests remain passing.

• Migration

  • Enable in config: external_cli.enabled=true, provider="cursor", default_model, optional models/workspace/timeout.
  • Requirements: Cursor installed and authenticated; verify with cursor-agent -p --model <model> --output-format json "test".
  • No changes needed when disabled (default).

^{Written for commit d83e221. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[antoniomdk]

I have read the CLA Document and I hereby sign the CLA

[code-yeongyu]

Thank you for your contribution to external CLI support!

After careful review, I'm closing this PR due to the following reasons:

1. Significant Architecture Drift
This PR is based on v2.13.x, but the dev branch is now at v3.2.1. The background-agent system has undergone major refactoring including:

• Unified Claude Tasks system (PR Implement unified Claude Tasks system with single multi-action tool #1356)
• Sisyphus and Hephaestus agents
• Category-based delegation
• Unstable-agent-babysitter system
• New BackgroundTask interface without the backend field

2. Conflicts Require Substantial Rebase
The PR has merge conflicts because the background-agent manager and types have evolved substantially. Resolving these would require rewriting most of the implementation to align with current architecture.

3. Feature Implementation Gap
The external CLI approach would need to integrate with the current agent orchestration strategy, which differs significantly from the v2.13.x architecture.

Recommendations
If you'd like to pursue external CLI support:

1. Please rebase your work against the latest dev branch
2. Consider integrating with the new category-based delegation system
3. Align with the current BackgroundTask interface
4. Test against the latest agent orchestration patterns

The concept of external CLI backends is still valuable for users with existing Cursor subscriptions. Feel free to open a new PR with an updated implementation!

Best regards,