SFF-063: Provider-neutral tool orchestration bridge

[jmrpineda]

Reported by: Codex
Requested by: jmr.pineda
Priority: P1
Affected surfaces: OpenAI-compatible execution provider, native CLI runners, provider abstraction layer, phase orchestration, execution receipts, Central gateway integration
Constraints: The harness must remain the source of truth for tool policy and evidence; do not couple the product exclusively to one provider's native tool-calling API; preserve non-tool execution paths where no tools are needed; do not assume Central is the only possible gateway implementation even if it is the primary commercial one.

Summary

SpecForge should add a provider-neutral tool orchestration bridge so model-backed phases can use governed execution tools whether the underlying provider offers native tool calling, partial support, or only plain text generation, while also supporting explicit routing to OSS-local handlers or to a compatible gateway such as SpecForge Central.

Problem / opportunity

The current OpenAI-compatible path is centered on plain /chat/completions message exchange, and native runner paths also assume prompt-in and content-out execution. That is enough for prompt-only phases but not for governed execution tools. If SpecForge ties orchestration directly to one provider API, tool support becomes fragmented and provider-specific. If it ties routing directly to a proprietary Central implementation, the OSS architecture starts to look artificially closed. A harness-level orchestration bridge keeps the product portable while still allowing SpecForge Central to be the managed commercial gateway for shared and organization-grade capabilities.

Requested behavior

Introduce a tool orchestration layer inside SpecForge that can mediate tool requests, tool results, and iteration between the model and the runtime. Providers with native tool-calling support can map into that layer; providers without it can still participate through a harness-managed loop. The orchestration layer must also support routing to local handlers or to a compatible gateway, with Central as the primary commercial implementation rather than the only conceivable implementation.

Scope

• In scope: Harness-level orchestration loop; provider adapter contract for tool-capable and non-tool-capable transports; normalized tool request and tool result messages; fallback loop for providers that do not support native tools; routing to local handlers and gateway handlers; receipt integration.
• Out of scope: Replacing every provider transport at once; adding speculative multi-agent orchestration unrelated to tool use; forcing tools into phases that do not need them.

Acceptance criteria

1. SpecForge defines a provider-neutral orchestration contract for governed execution tools.
2. At least one provider path can execute a tool-enabled phase through the new orchestration layer.
3. Providers without native tool APIs can still participate through a harness-controlled fallback loop.
4. Tool-enabled and prompt-only executions both produce normalized execution metadata and receipts, including whether a tool was resolved locally or through a gateway.

Notes

• This is the key feature that prevents tool support from becoming an openai-compatible implementation detail instead of a SpecForge runtime capability.
• The first implementation can target one provider path while preserving an abstraction that keeps Codex, Claude, Copilot, and OpenAI-compatible transports aligned.
• Product packaging guidance is captured in doc/execution-tool-packaging.md.