Provider Contract
Forge uses one provider model across all languages.
Why this matters
The value of Forge is portability. Developers should not need to learn a different runtime model for every vendor or language SDK.
That does not mean Forge pretends every provider is identical. It means Forge defines:
- one mandatory baseline
- one explicit advanced-capability model
- one fail-closed negotiation path
- one error model that can be reasoned about across languages
Baseline
Every approved coding provider in Forge core is expected to satisfy the same baseline contract:
- configuration and credential validation
- session lifecycle management
- task submission
- structured events
- cancellation and timeout handling
- normalized usage reporting
- normalized typed errors
- audit emission
- capability advertisement
- fail-closed unsupported-feature reporting
If a provider cannot meet that baseline, it should not ship as a core-supported coding provider.
Baseline semantics
| Contract area | What Forge guarantees |
|---|---|
| Configuration | The runtime can determine whether a provider is configured enough to begin negotiation |
| Session lifecycle | Open, execute, cancel, complete, and close are modeled explicitly |
| Event surface | Providers expose structured events or structured polling results |
| Usage | Usage data is normalized into a Forge-visible result surface |
| Errors | Failures map into stable Forge categories instead of vendor-only blobs |
| Capability advertisement | The runtime can inspect what a provider claims to support before execution |
Advanced capabilities
Beyond the baseline, Forge uses an explicit capability matrix for higher-order behavior such as:
- tool calls
- delegated agents
- terminal sessions
- structured patches
- attachments
- interrupts
- resume support
These capabilities are not implied by provider presence. They must be advertised, documented, and verified.
Negotiation
Forge does not guess. Before execution begins, the runtime verifies:
- provider availability
- requested model
- required capabilities
- active boundary-contract authority
- Aegis delegation requirements
- Arsenal scope eligibility
Unsupported requests fail closed before remote execution starts.
Negotiation flow
- resolve provider and model
- inspect advertised capabilities
- compare required capabilities to advertised capabilities
- verify boundary-contract authority
- verify delegation requirements for agentic behavior
- verify scoped capability eligibility
- either start the session or return a typed denial
Documentation rule
If this page or the capability matrix names a provider feature, that feature should be backed by executable coverage before it is described as shipped behavior.