Summary

Add a Bcode abstraction layer for running existing AI coding agents behind the Bcode interface.

Users should be able to configure Bcode to delegate turns to tools like OpenCode, Claude Code, Pi, or other agentic coding CLIs while still interacting through the normal Bcode TUI/session experience. This should make Bcode easy to try with low commitment by reusing users' existing agent setup, auth, providers, MCP servers, tools, and workflows.

Motivation

Many users already have another coding agent configured extensively. Bcode should let those users adopt the Bcode interface and local client/server/session model without immediately migrating providers, credentials, tools, prompts, or agent-specific configuration.

The goal is for Bcode to become the stable user-facing shell while external agents can be selected as interchangeable execution backends.

Goals

• Provide a plugin/service-backed agent backend abstraction.
• Allow per-user and per-session backend selection.
• Support external agents such as:
  • OpenCode
  • Claude Code
  • Pi
  • future local/custom agent CLIs
• Keep the Bcode TUI, session history, status, cancellation, and permissions UX as the primary user interaction surface.
• Reuse existing external agent configuration where possible.
• Make backend capability differences explicit instead of pretending all agents support the same features.
• Preserve Bcode's plugin-first architecture.

Non-goals

• Do not replace the native Bcode agent/provider path.
• Do not hardcode support for one external agent directly into the host.
• Do not require users to migrate credentials or provider config into Bcode.
• Do not silently bypass Bcode permissions/security expectations.
• Do not require every backend to support every feature.

Proposed architecture

Introduce a versioned agent backend service interface, exposed through the plugin/service system.

Example conceptual interface:

• bcode.agent_backend.v1/discover
• bcode.agent_backend.v1/capabilities
• bcode.agent_backend.v1/start_session
• bcode.agent_backend.v1/resume_session
• bcode.agent_backend.v1/send_message
• bcode.agent_backend.v1/cancel_turn
• bcode.agent_backend.v1/shutdown_session

The Bcode server remains the owner of:

• Bcode session IDs
• append-only event history
• client fanout
• TUI-visible transcript
• selected backend metadata
• cancellation
• permission mediation where supported

Agent backend plugins own:

• locating/checking the external executable
• translating Bcode requests into backend-specific CLI/API calls
• mapping backend output into Bcode session events
• reporting backend capability limitations
• preserving backend-specific session references

Configuration

Support global and per-session backend selection.

Example shape, exact schema TBD:

[agent]
default_backend = "opencode"

[agent.backends.opencode]
enabled = true
command = "opencode"
profile = "default"

[agent.backends.claude_code]
enabled = true
command = "claude"

The TUI should eventually expose backend selection alongside model/session selection.

Capability model

Each backend should report capabilities such as:

• streaming assistant text
• structured tool events
• structured permission prompts
• cancellation
• resume existing backend session
• model selection
• working directory control
• slash command support
• file diff/change summaries
• headless mode vs PTY-only mode

If a backend only supports unstructured terminal output, Bcode should either:

1. run it in a degraded transcript/PTY mode with clear limitations, or
2. mark it unsupported until a structured integration is available.

MVP

Implement the abstraction plus one proof-of-concept adapter, preferably OpenCode.

MVP acceptance criteria:

• Bcode can list configured/discovered external agent backends.
• A session can be created using an external backend.
• Sending a user message through Bcode delegates the turn to the selected backend.
• Assistant output from the external backend appears in the Bcode transcript.
• Backend metadata is persisted with the Bcode session.
• Cancellation is supported where the backend allows it.
• Missing executable/config errors are surfaced clearly in the TUI/CLI.
• The adapter reports capabilities instead of assuming full feature parity.
• Tests use a fake agent backend binary/plugin so CI does not require OpenCode/Claude/Pi to be installed.

Security and UX requirements

• External backend usage must be explicit/configured.
• Bcode should clearly show which backend is active.
• Secrets from external agent config/stdout/stderr must not be logged into durable session history accidentally.
• Permission prompts should be mediated by Bcode where structured backend support exists.
• If permissions are handled by the external agent directly, Bcode should make that degraded behavior visible.
• Backend failures should not corrupt Bcode session history.

Likely dependencies

This builds on or relates to:

• Implement model provider abstraction #3
• Implement plugin service registry and invocation #5
• Implement append-only session event history #7
• Add model and session selection UI #10
• Implement permission checkpoint service #11
• Implement slash command plugin support #14

Follow-up issues

After the abstraction lands:

• Add OpenCode backend plugin
• Add Claude Code backend plugin
• Add Pi backend plugin
• Add backend capability/status UI
• Add structured permission bridge for supported backends
• Add backend session import/resume support