Make synchronous subagents opt-in via opencode.json

[mdev34-lab]

Problem

Subagents currently have synchronous/foreground execution behavior in places where background execution is the default path. This makes a single stuck subagent capable of blocking the parent agent indefinitely.

For AlphaCode, the safer architectural default is to run subagents through the background execution path and make synchronous execution an explicit configuration choice.

Proposal

Add an opencode.json configuration option that allows users to opt specific subagents into synchronous/foreground execution.

Conceptually:

{
  "agent": {
    "review": {
      "background": false
    }
  }
}

Use the repository's existing configuration conventions and schema rather than inventing a parallel mechanism. The exact shape should follow the current agent configuration model.

Desired semantics

• Background execution remains the default for subagents.
• Synchronous/foreground execution is opt-in.
• The configuration should be scoped to individual subagents/agents rather than being a global "disable background" switch.
• Existing subagent lifecycle, result propagation, cancellation, and permission behavior must remain correct in both modes.
• A synchronous subagent should still use the same finish termination contract as a background subagent.
• This should complement Add an explicit termination reason to the finish tool #172's explicit finish termination reasons, not replace them.

Motivation

A stuck subagent should not normally be able to block the entire parent agent. Making synchronous execution explicit forces callers to acknowledge that coupling when they need it.

This is particularly relevant to Review, where a model that repeatedly emits output without calling finish can otherwise hold the parent execution path indefinitely.

Requirements

• Inspect the existing OpenCode/AlphaCode agent configuration and background execution model before choosing the final schema.
• Add configuration schema/type support and runtime handling.
• Preserve backward compatibility for existing configuration files.
• Add focused tests covering:
  • default background behavior;
  • explicit synchronous opt-in;
  • independent configuration of different subagents;
  • equivalent result/finish handling in both modes;
  • invalid configuration handling according to existing config conventions.
• Update relevant documentation/config examples.
• Do not make Review-specific hardcoded behavior the configuration mechanism.
• Do not redesign the scheduler as part of this issue.

Related:

• Prevent Review subagent doomloops on repeated literal output #171 — Review literal-output stagnation recovery
• Add an explicit termination reason to the finish tool #172 — Add an explicit termination reason to the finish tool
• fix(runtime): prevent infinite turn loop when model fails to emit finish #140 — broader finish/liveness handling