feat: generalize host routing and add OpenCode as a routable execution host

[pacphi]

Summary

Generalize agentic-kit's current Claude+Codex dual execution substrate into capability-driven multi-host routing, then add OpenCode as the first third routable execution host.

This is the immediate follow-on to:

• feat: add capability-driven integration adapters #74, which introduced capability-driven host/provider/projection/observability registries and lifecycle contracts; and
• feat: OpenCode as a managed non-routable host adapter (ADR-0017) #67, which should land OpenCode as a fully managed and observable non-routable host.

Do not implement this work by merely changing OpenCode's canRouteActivities flag. That flag is a safety gate. It may become true only after a real execution adapter and generalized orchestrator can launch, supervise, interpret, cancel, and verify OpenCode workers.

Problem

The routing policy is increasingly capability-driven, but execution is still coupled to @claude-flow/codex and the vocabulary/assumptions of exactly two worker platforms:

• ak dual run delegates to claude-flow-codex;
• workers execute through claude -p or codex exec;
• templates and escalation ladders assume Claude/Codex platform identifiers;
• configuration and documentation define dual as the Claude+Codex collaboration substrate;
• there is no OpenCode worker launcher, structured-result interpreter, cancellation contract, or readiness probe.

OpenCode now exposes credible automation surfaces:

• opencode run for non-interactive execution;
• --model, --agent, --format json, --dir, and --auto;
• attachment to a persistent opencode serve process;
• a headless HTTP/OpenAPI server; and
• ACP over stdin/stdout.

The remaining limitation is therefore agentic-kit's orchestration integration, not a categorical inability of OpenCode to execute headlessly.

Goals

1. Define one host-worker execution contract independent of Claude, Codex, and OpenCode.
2. Adapt existing Claude and Codex execution without regressing ak dual.
3. Implement and prove an OpenCode worker adapter.
4. Allow per-activity routes and ordered escalation ladders to target any capability-qualified routable host.
5. Preserve host/provider/provenance separation introduced by ADR-0016.
6. Generalize user-facing vocabulary and configuration without silently changing existing dual behavior.
7. Keep automatic route seeding cost-safe.
8. Produce sufficient independent evidence for qe-court to render a cross-vendor verdict.

Non-goals

• Do not fold this into feat: OpenCode as a managed non-routable host adapter (ADR-0017) #67.
• Do not treat OpenCode as an AQE inference-provider type.
• Do not infer an execution provider solely from the OpenCode host.
• Do not add a dashboard control plane.
• Do not promise OpenCode subscription, quota, or cost semantics that cannot be observed.
• Do not remove the existing ak dual compatibility surface without a documented migration and deprecation decision.
• Do not make canRouteActivities: true precede a verified execution adapter.

Proposed architecture

1. Host-worker adapter contract

Introduce a contract conceptually covering:

detect/readiness
  → prepare
  → launch
  → stream/observe
  → interpret result
  → cancel/timeout
  → cleanup

The exact names may follow existing lifecycle vocabulary, but execution and configuration lifecycle must remain distinct concerns.

Each adapter must define:

• executable/readiness detection;
• command/API construction;
• working-directory and environment handling;
• model and agent normalization;
• structured event/output parsing;
• success/failure/cancellation interpretation;
• timeout and signal behavior;
• permission/sandbox policy;
• authentication/provider readiness facts;
• transcript/evidence correlation;
• cleanup and orphan prevention.

Initial adapters:

Host	Execution surface
Claude Code	claude -p
Codex CLI	codex exec
OpenCode	initially evaluate opencode run --format json --auto; compare against ACP/server attachment before fixing the contract

The OpenCode transport choice must be recorded in an ADR with observed tradeoffs. Prefer the smallest reliable surface that supports deterministic completion, cancellation, structured evidence, and repo mutation.

2. Generalized orchestrator

Separate pipeline orchestration from claude-flow-codex platform assumptions:

• materialize workers from the canonical per-activity policy;
• resolve a host-worker adapter by registry capability;
• honor dependency ordering and bounded concurrency;
• share only explicitly supported coordination state;
• propagate cancellation and timeout;
• collect normalized worker results;
• apply ordered escalation consistently across hosts;
• prevent unsupported hosts from entering a runnable plan.

Determine whether to:

1. extend/replace the upstream adapter;
2. add an agentic-kit-owned thin generalized adapter; or
3. introduce a versioned adapter interface with claude-flow-codex retained as the Claude/Codex implementation.

The decision must be grounded in upstream capabilities and recorded before implementation is locked in.

3. Vocabulary and CLI compatibility

dual currently means Claude+Codex. Adding a third routable peer must not silently redefine it.

Design and document one of:

• a new generalized command such as ak run / ak swarm run while retaining ak dual as a compatibility projection; or
• a versioned generalization with an explicit migration/deprecation path.

Requirements:

• existing Claude/Codex route configuration remains readable;
• existing ak dual invocations retain behavior during the compatibility window;
• templates become host-neutral activity pipelines;
• ak host pick --route validates against canRouteActivities;
• primary-host semantics are explicitly revisited rather than automatically extended;
• help, README, provider/host docs, upgrading docs, dashboard labels, and ADR vocabulary agree.

4. Routing and model normalization

OpenCode model identifiers use provider/model. The canonical policy must keep these axes distinct:

activity → execution host + optional host model selector
host execution → observed/configured inference provider + exact model + provenance

Define:

• accepted OpenCode model selector syntax;
• whether the policy stores an opaque host-native selector or normalized fields;
• validation without turning curated catalogs into hard allowlists;
• migration of existing Claude/Codex route entries;
• behavior when a configured OpenCode provider/model is unavailable.

5. Permission and unattended-execution safety

Ground and test OpenCode's non-interactive permission semantics:

• explicit policy for --auto;
• behavior for operations explicitly denied by configuration;
• protection against an unattended permission prompt/hang;
• external-directory and secret-file behavior;
• timeout if structured progress stops;
• no implicit weakening of user-owned OpenCode permission rules.

Document which policy is owned by agentic-kit and which remains user-owned.

6. Cost safety and provider provenance

OpenCode can route inference through multiple providers. Therefore:

• enabling OpenCode routing must not silently introduce a metered path;
• automatic seed defaults may target OpenCode only when billing/provenance is sufficiently grounded and allowed by the existing cost-safety rules;
• an unknown OpenCode inference provider remains unknown, not inferred from model naming or host identity;
• escalation must disclose when it can cross billing classes;
• qe-court vendor diversity must use established inference-vendor evidence, not merely three different host CLIs.

7. Observability and normalized results

Define a normalized worker result that can represent:

• host;
• activity/role;
• configured model selector;
• observed provider/model and provenance;
• session/correlation ID;
• timestamps/duration;
• status and exit category;
• structured failure reason;
• transcript/event references where supported;
• cost/usage only when grounded.

OpenCode JSON/ACP/server events must be tested against recorded fixtures with secrets removed.

Implementation slices

1. Specification/ADR
   • choose orchestration ownership and command vocabulary;
   • define execution-adapter and normalized-result contracts;
   • define migration/compatibility and cost-safety decisions.
2. Contract and Claude/Codex parity
   • implement adapters around current execution;
   • prove no behavioral regression in existing templates, escalation, timeout, and dry-run.
3. OpenCode proof harness
   • capture sanitized structured fixtures;
   • prove readiness, repo mutation, result parsing, timeout, cancellation, denied operations, and cleanup.
4. OpenCode adapter
   • implement against the selected transport;
   • retain canRouteActivities: false until adapter conformance and integration tests pass.
5. Generalized routing/CLI
   • enable OpenCode route selection;
   • migrate/project existing policy;
   • preserve ak dual compatibility.
6. Observability/dashboard/docs
   • expose honest normalized facts;
   • update canonical docs and upgrading guidance.
7. Verification
   • full repository gates;
   • live smoke tests for all three hosts where credentials are available;
   • ruflo swarm review;
   • qe-court cross-vendor verdict.

Required tests

Adapter conformance

• every routable host implements the complete execution contract;
• non-routable hosts cannot materialize runnable workers;
• readiness failure occurs before partial orchestration starts;
• timeout/cancellation always terminates or reports any surviving child;
• cleanup is idempotent.

Claude/Codex regression

• current templates materialize the same effective host assignments;
• sequential/parallel behavior remains bounded;
• escalation produces the same next rung;
• dry-run remains side-effect free;
• auth/model errors remain distinguishable from routing errors.

OpenCode integration

• non-interactive edit succeeds in a sandbox repository;
• structured output produces a normalized successful result;
• configured model/agent/directory reach the invocation correctly;
• an explicit permission denial fails deterministically;
• no permission prompt can hang CI indefinitely;
• timeout and cancellation stop the worker;
• malformed/truncated structured events fail honestly;
• absent CLI, missing auth, unavailable model, and non-zero exit are distinct;
• user-owned OpenCode configuration is not weakened or overwritten;
• concurrent workers use isolated sessions/workspaces as designed.

Routing/migration

• legacy Claude/Codex policy migrates without semantic change;
• OpenCode is rejected before its adapter capability is enabled;
• after enablement, explicit OpenCode activity routes materialize correctly;
• automatic seeds never introduce an ungrounded metered OpenCode path;
• escalation may include OpenCode only when explicitly configured or safely seeded;
• primary-host behavior follows the ADR;
• disabling a routing host reconciles routes, downstream projections, and bridges consistently with x provider pick: excluding a routing host (codex) leaves seeded routes, agentOverrides, and MCP bridges live — one disable semantics for all hosts #73.

Evidence and qe-court

• host diversity is not mistaken for inference-vendor diversity;
• unknown provider/model remains unknown;
• correlated OpenCode events establish host/session provenance;
• qe-court receives at least two independently evidenced vendors for a diversity-backed verdict.

Acceptance criteria

• feat: OpenCode as a managed non-routable host adapter (ADR-0017) #67 is merged first as the managed, observable, non-routable OpenCode baseline.
• An accepted ADR defines generalized orchestration, CLI vocabulary, migration, and OpenCode transport.
• Claude, Codex, and OpenCode satisfy one tested host-worker execution contract.
• Existing ak dual workflows remain compatible or have an explicit, tested migration path.
• OpenCode becomes canRouteActivities: true only in the same change that makes its runnable contract real.
• An explicit activity can route to OpenCode and complete a sandboxed repository mutation.
• Timeout, cancellation, permissions, authentication, and malformed-output behavior are deterministic.
• Ordered cross-host escalation is tested.
• Automatic routing cannot silently introduce an unknown metered provider.
• Host/provider/model provenance remains normalized and evidence-backed.
• pnpm run check passes.
• pnpm run test:surface passes.
• Relevant live smoke tests pass on the exact final head.
• A ruflo swarm reviews architecture, implementation, testing, security, docs, and migration.
• qe-court convenes on the exact final head and returns a passing cross-vendor verdict, or all blocking findings are remediated and the court is reconvened.

Dependencies and ordering

1. Merge feat: OpenCode as a managed non-routable host adapter (ADR-0017) #67 after it is rebased onto the feat: add capability-driven integration adapters #74 architecture and passes its own qe-court review.
2. Reconcile or incorporate x provider pick: excluding a routing host (codex) leaves seeded routes, agentOverrides, and MCP bridges live — one disable semantics for all hosts #73's disable semantics so generalized routing cannot leave stale routes/bridges.
3. Start this issue from the clean post-feat: OpenCode as a managed non-routable host adapter (ADR-0017) #67 main.

This issue should be the source of truth for the immediate follow-on activity. Keep #67 focused on complete managed-host integration and honest non-routability.

Managed OpenCode CLI parity

OpenCode must retain the same managed-CLI lifecycle as Claude and Codex while routing is generalized:

• an enabled but absent OpenCode CLI is installed as opencode-ai by ak host pick, setup, or sync;
• npm-managed versions participate in the shared version-drift/update path;
• external/brew/mise/native installs are detected but never shadowed or overwritten;
• ak host, setup, sync, status, and teardown converge or remove only agentic-kit-owned OpenCode integration artifacts;
• installation success alone is not execution readiness: wiring follows post-install detection, and routing remains disabled until the worker adapter contract is proven.

Required parity coverage: enabled-absent install, declined/failed install, npm version drift, external-install preservation, post-install wiring, status visibility, and marker-precise teardown.

Live baseline recorded 2026-07-29: opencode-ai 1.18.9 was installed through npm, enabled with ak host pick --host claude,codex,opencode --yes, and status reports the CLI, managed MCP wiring, converted agents, and npm ownership as healthy.

[pacphi]

Implementation checkpoint: #67 is merged and #76 has begun from clean main. The first compatibility-preserving slice adds a proposed ADR-0018, a host-worker execution contract/result schema, and a host-neutral plan projection while retaining ak dual’s existing Claude/Codex adapter shape unchanged. Transport decision is provisional pending proof: use short-lived loopback opencode serve HTTP/OpenAPI for supervised workers; keep opencode run --format json for fixtures/smoke, and do not use ACP as the worker transport. OpenCode remains non-routable until adapter conformance and live/sandbox evidence exist. Local pnpm run check passes. #73 is explicitly sequenced as the fast follow after #76 merge per the current plan.

[pacphi]

Scope refinement — managed OpenCode interaction now has an explicit side-effect boundary:

• execution uses an owned, loopback-only opencode serve process with ephemeral HTTP Basic-auth credentials;
• it opens an isolated session, starts observing global SSE events before submitting the async prompt, aborts on permission requests, and disposes the owned server during cleanup;
• the worker instruction is a versioned package template sent only with the invocation. It is not deployed as an OpenCode agent/command/configuration, because agent-level permissions can override a user's global policy;
• no --auto, permission mutation, or silent approval path is permitted.

This is a tested implementation foundation, not the capability flip: OpenCode remains non-routable until the generalized runner, live sandbox mutation, timeout/cancel, malformed-event, and final-head evidence are complete. pnpm run check passes on this slice.

[pacphi]

Closure punch list

The implementation slices have largely landed through #67, #77, #79, #80, #81, #82, and #84. Before closing this issue, complete and link evidence for the following remaining acceptance criteria:

• Generalized escalation: bring ordered, bounded cross-host escalation into the canonical ak run path (or explicitly retire it with an approved migration decision). It must be tested with an OpenCode-qualified route; keeping escalation only in deprecated ak dual does not satisfy this issue.
• Final-head validation: run and record pnpm run check and pnpm run test:surface on the exact candidate final main head.
• Live three-host smoke: where credentials are available, record a final-head smoke for Claude, Codex, and OpenCode. The OpenCode proof must cover a sandboxed repository mutation plus successful normalized terminal evidence; identify any host that cannot be exercised and why.
• Ruflo review: run the required swarm review against the exact final head, covering architecture, implementation, tests, security, documentation, and migration; remediate or explicitly disposition findings.
• qe-court verdict: convene qe-court on that same final head and attach the passing cross-vendor verdict. It must rely on independently evidenced inference vendors, not merely distinct CLIs. If the court finds blocking issues, remediate and reconvene.
• Acceptance evidence: update this issue checklist to link the final tests, smoke evidence, swarm report, and qe-court verdict, then verify no acceptance item remains open.

Current status: OpenCode is explicitly activity-routable via canonical ak run; it is not an AQE provider, primary host, or vendor-diversity shortcut. ak dual is now a deprecated compatibility wrapper, with its remaining escalation behavior intentionally tracked above and separately by the GA cleanup program in #83.

[robertlee-ioactive]

Final-head validation (punch-list item 2) — run against the exact current main head 6347d1a ("deprecate: make ak run the canonical executor (#84)"), fresh clone:

$ pnpm run check       → exit 0
    typecheck + eslint + markdownlint + build: clean
    kit tests: 1047/1047 pass
    cjs suites: 222/222 pass (43+10+7+31+7+63+33+28)

$ pnpm run test:surface → exit 0
    25/25 pass

Both gates green on the candidate final head. (Contributor machine: macOS arm64, Node 22, pnpm 11.17.)

[robertelee78]

Live three-host smoke (punch-list item 3) — ak run feature end-to-end per host on current main (6347d1a), each in a fresh sandboxed git repo, tiny bounded task (create hello.mjs), JSON results captured. Machine: macOS arm64; claude (subscription), codex (ChatGPT login), opencode 1.18.8 (kimi-k3).

Host	Workers	Mutation	Normalized evidence	Notes
claude	4/4 success (30–76s each)	hello.mjs, tests/	status/exitCategory per worker	required workspace-trust preset for the sandbox repo (see posture notes)
codex	4/4 success (21–45s each)	hello.mjs, hello.test.mjs, package.json	status/exitCategory per worker	gpt-5.3-codex rejected by this ChatGPT account → used account default gpt-5.6-sol
opencode	4/4 success (35–82s each)	hello.mjs, tests/	plus observed model kimi-k3, provider opencode	only after fixing two adapter bugs — PR #85

OpenCode could not be exercised on shipped main — two adapter bugs, both reproduced and fixed in PR #85:

1. POST /session/:id/prompt_async 400s on every configured-model worker: the adapter posts model as a bare string; serve expects {providerID, modelID} or null. Serve's own error: "Expected object | null, got \"opencode/kimi-k3\" at [\"model\"]". Verified the object shape returns 204.
2. Process crash after the verdict: when the prompt post throws, launch() stops the owned server but leaves the terminal SSE promise unconsumed — its socket-close rejection kills node as an unhandled rejection (TypeError: terminated, UND_ERR_SOCKET) after the run verdict printed.

Permission postures (the "why" behind each host's smoke preset — no global config was permanently changed):

• claude: --print denies writes non-interactively by default; repo-level permissions.allow is additionally gated by workspace trust. Smoke preset: hasTrustDialogAccepted for the sandbox path in ~/.claude.json (restored afterwards). Without it the workers "succeed" textually with zero side effects — worth noting for the GA story: ak run against claude today cannot mutate in a default posture.
• codex: exec is read-only in untrusted projects regardless of sandbox_mode in config.toml; only -c overrides or per-project trust_level = "trusted" enable workspace-write. Gotcha worth documenting: the trust check keys on the realpath of the cwd the adapter passes (/private/tmp/… on macOS), so a preset for the logical /tmp/… spelling silently misses.
• opencode: serve surfaces permission prompts as SSE events and the adapter aborts honestly (permission_required — good); repo-scoped {"permission":{"edit":"allow","bash":"allow"}} in the sandbox repo is the cleanest preset of the three (nothing outside the repo).

Net: claude + codex legs pass on shipped main; the opencode leg passes with PR #85 applied (evidence above). All sandbox repos + user configs restored; total smoke cost bounded to a few small tasks on subscriptions/local models.

[robertelee78]

qe-court record — delivery: final head 6347d1a (#76 body, #67–#84)

Convened per ADR-124 (orchestration form — no monolithic binary yet). Panel from .claude/skills/qe-court/config.json on the reviewed tree; two independently evidenced inference vendors (not merely distinct CLIs): Anthropic via claude subscription (hostAuthState: oauth) and OpenAI via codex ChatGPT login (~/.codex/auth.json). Jury provider (claude-code) ∉ {writer/defense (codex)} — writer≠juror holds.

Role	Provider	Lens
Defense	codex (OpenAI)	case-for-ship, evidence only
Prosecutor A	claude-code (Anthropic)	brutal-honesty probe set
Prosecutor B	codex (OpenAI)	cross-vendor GPT probe set
Blind refuter	claude-code	kill round, default-refuted-if-uncertain
Jury	claude-code (Anthropic)	two-gate, three-valued verdict

Verdict: REMAND (confidence: high) — no fatal charges surviving; 9 major + 1 minor with bounded conditions

Charges: 12 filed, 2 killed in the blind round

Killed:

• A1 (subprocess inverted-orphan): the specific false-orphaned propagation does not occur through runner.mjs:51 (adjacent real signal-discard noted, uncharged).
• B2 (opencode wire-shape model post + unconsumed SSE rejection → process crash): reproduced on the delivery head and remediated by PR fix(execution): opencode serve protocol — object-shaped model post + settled terminal stream #85 (9faf506 — serveModelFor + settled terminal consumer, with regression tests). Killed because the fix exists with proof, not because the delivery lacked the bug — the smoke hit it live.

Surviving (prosecutor → severity):

• B3 — dependency DAG discards dependency outputs (charged fatal; jury re-weighed to major: shared cwd is a plausible-but-undocumented continuity channel; gap narrows to the security template chain + outputs that never touch disk)
• B1 — host-only --route override inherits the previous host's default model (resolveRoutes: model: p.model ?? def.model) — major, reproduced (--route implementation:claude → coder claude gpt-5.4)
• B4 — timeoutMs covers only observe; readiness/prepare/launch (esp. opencode /session POST) unbounded — major
• B5 — subprocess terminate() treats kill('SIGTERM')==true as terminated (no close wait, no bounded SIGKILL) — major
• B6 — provider: host, providerProvenance: 'configured' fabricated from the CLI id — major (contradicts ADR-0018's own invariant)
• B7 — --escalate silently accepted and dropped in ak run (strict:false), while the deprecation nudge says "use ak run" — major (overlaps punch-list item 1)
• B8 — --json output contaminated by trailing ✓ run complete / fail status line (jq breaks) — major, reproduced
• A2 — validateWorkerResult applied on success path only, not the timedOut branch — major
• A3 — validateRegistries (the canDriveSession→canBePrimary/canRouteActivities invariant) never runs at HOST_MAP construction — major
• A4 — opencode port reserve-probe-release TOCTOU under maxConcurrent=4 — minor

Jury rationale (abridged)

"…B3's factual claims hold, but architect/coder/tester/reviewer share one cwd, so the working tree is a plausible continuity channel; the gap narrows to the security chain and disk-avoidant outputs, degrading to redundant re-derivation rather than silently wrong results. Nine confirmed majors remain; B1 and B8 are live-breaking but each independently bounded. The defense's own concession — a real three-host smoke found every configured-model OpenCode worker failing at this commit, fixed only in follow-up 9faf506 — corroborates REMAND over SHIP without escalating to BLOCK."

Conditions to lift the verdict (jury's minimal bounded set)

1. B1: don't carry a different host's default model across a host-only override.
2. B8: gate the human status line behind !flags.json in run.mjs.
3. B7: implement --escalate in ak run, or reject/warn rather than silently drop. (= punch-list item 1's surface)
4. B6: stop fabricating provider/providerProvenance from the host id; default unknown until grounded.
5. A2: validate interpret() results on the timeout path too.
6. B4/B5: bound readiness/prepare/launch with timeoutMs; terminate() waits for close with a bounded SIGKILL.
7. B3: thread worker output into dependent prompts, or document the shared-cwd contract per template.
8. A3 (lower): enforce the capability invariant at HOST_MAP construction.

Court artifacts (charges, kill-round reasoning, full jury rationale, defense case) retained; sign-off by the human judge is the remaining protocol step.

[robertelee78]

Bounded remediation of the qe-court conditions is up as PR #86 (B1 host-only model inheritance, B8 --json purity, B6 provider-provenance honesty, A2 timeout-path schema validation, A3 construction-time registry invariants). Architectural conditions (B3 dependency-output threading, B4/B5 runner lifecycle bounds, B7 generalized escalation) dispositioned to your in-flight work rather than a community rewrite.