[FEATURE]: Capability-based external CLI agent adapter and conformance tests

[areshand]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Add an opt-in, process-based external-agent adapter to the current
anomalyco/opencode ecosystem, subject to maintainer confirmation of the proper
extension point. This request is for anomalyco/opencode, not the archived
opencode-ai/opencode repository.

The proposed adapter would invoke a noninteractive external CLI process through
a small versioned contract. It would exchange a structured start request and
JSONL lifecycle/result events, while the host owns workspace policy, environment
allowlisting, timeout, cancellation, process cleanup, and artifact collection.
Concrete Codex/Claude command mappings would remain outside the core contract.

Existing subagent issues cover related delegation and native-agent behavior,
but the upstream audit found no exact duplicate for an external CLI process
contract plus evidence gate. This enhancement should reuse established
subagent/session concepts where they fit. It differs by focusing on process
interoperability, host-enforced permissions, lifecycle cancellation, and
normalized evidence rather than introducing another native subagent design.

Minimal scope:

• Capability manifest plus structured start request.
• A small event set: ready, progress, tool observation, validation, finding,
  artifact, result, and error.
• Stable terminal reason codes and fail-closed handling of missing/malformed
  results.
• Offline conformance fixtures for lifecycle, cancellation, policy, and
  redaction behavior.
• Separate records for requested capabilities and effective runtime policy.

Non-goals:

• No bundled vendor CLI, model, or credentials.
• No attempt to normalize every native tool call.
• No claim that the process protocol itself provides sandboxing.
• No default provider or UI changes.
• No benchmark score reporting.

Questions to settle before code:

1. Should this target a provider/plugin API, ACP-compatible boundary, SDK
   package, standalone bridge, or another extension point?
2. Is there an existing event envelope and artifact abstraction to reuse?
3. Which runtime API should own process-tree cancellation and effective policy
   evidence?
4. Should discovery use configuration, executable manifests, or package
   registration?
5. Would a protocol/conformance-only first PR be useful without a vendor adapter?

Acceptance criteria for a first PR:

• Feature is inert unless explicitly configured.
• A fake adapter completes a request with ordered structured events and an
  artifact digest.
• Timeout, cancellation, malformed JSON, nonzero exit, and zero exit without a
  result have distinct tested outcomes.
• Process-tree cleanup, canonical path checks, output limits, and log redaction
  are covered offline.
• Requested capabilities are never presented as proof of effective permissions.
• Protocol versioning and unknown-event behavior are documented.

The preferred rollout is a protocol/conformance-only first PR. A concrete CLI
adapter would follow only after the extension boundary is accepted. A separate
integration package is an acceptable outcome if maintainers do not want the
process contract in core.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• This issue does not use one of the three required issue templates (Bug Report, Feature Request, or Question).
• If this is a feature request, the title must start with [FEATURE]: and the issue must use the Feature Request template, including a verification checkbox and description.
• If this is a question or design discussion, please use the Question template.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thank you for updating the issue! It now meets the contributing guidelines. We appreciate the detailed and well-structured feature request.

[EZotoff]

Thanks for writing this RFC. We implemented the core dispatch idea locally against OpenCode v1.17.9: an explicitly configured agent can route task(subagent_type=...) to an external CLI instead of creating an LLM child session.

The patch is intentionally small and touches three files. The config schema and runtime Agent.Info each gain command?: string and external?: boolean, and the task tool gains the dispatch branch. When agent.external && agent.command, it runs Bun.spawn(["sh", "-c", command]), pipes the task prompt through stdin, collects the process result, and bypasses the child-session pipeline entirely. This keeps the feature inert unless both fields are configured.

A few implementation details were easy to get wrong:

• The prompt needs to go through stdin, not a positional argument. With CLIs that accept variadic options such as --allowedTools, a trailing prompt can be consumed as another option value.
• Session flags need to be conditional: use --session-id for a new external session and --resume for continuation, never both.
• Interactive tools such as AskUserQuestion do not work under noninteractive -p execution, so they need to be explicitly disabled. We use the subscription auth path and do not inject credentials into the adapter.

Our source patch has been reviewed and its dispatch path verified at code level, but we have not deployed the binary. The build is currently blocked by a pre-existing Bun v1.3.14 Effect schema regression, unrelated to these changes.

Would a PR using this schema-based, opt-in approach be welcome, perhaps as a smaller precursor to the full protocol and conformance layer proposed here? For the dispatch result, is there an existing event-envelope and artifact format you would prefer us to target rather than returning a task result directly?

Happy to contribute a PR aligned with the extension boundary and result contract you prefer.