Runner adapter contract
What you'll find here
The runner-agnostic contract between Craik core and concrete agent environments. Adapters receive Craik state and return normalized Craik state without leaking provider-specific details into core contracts.
Adapters translate, they don't grant authority.
Side effects still require explicit capability grants. Adapter metadata describes what a runner can do; policy decides what it may do.
Contracts
craik.runner_metadatafixture / prompt-handoff / live) · capability names · structured adapter metadata.craik.runner_adapter_requestcraik.runner_adapter_resultcompleted / blocked / failed / partial) · summary · structured outputs · receipt ids · optional handoff id · memory proposal ids · artifacts · diagnostics · runner metadata.craik.runner_step_requestplan / act / observe / evaluate / continue / stop) · runner metadata · policy envelope id · optional intent lock id · capability grant ids · expected output schemas · input prompt · bounded context · redaction requirement.craik.runner_step_resultcraik.runner_capability_matrixCapability support levels
unsupportedprompt-handoffsupportedSide-effect capabilities default to grant_required: true. Read-only
context and structured-result capabilities may be marked grant-free
when the runner profile can consume them without widening authority.
Adapter interface
Python adapters implement the RunnerAdapter protocol.
from craik.runtime.runners import RunnerAdapter
def run_task(adapter: RunnerAdapter, request):
return adapter.run(request)
Validate · preserve · normalize.
Adapters validate the request they receive, preserve runner metadata,
and return a craik.runner_adapter_result payload.
Fixture adapters can use FixtureRunnerAdapter for
deterministic contract tests without live runner credentials.
Shipped preview adapters
Codex
Codex-compatible prompt handoff and deterministic fixture runs.
Claude
Claude-compatible prompt handoff and deterministic fixture runs.
Gemini
Gemini-compatible read/review-oriented prompt handoff and deterministic fixture runs.
Capability matrix
craik runners matrix
craik runners matrix --runner codex
The v0.1.0 runner profiles are conservative.
codexclaudegeminifixtureFuture prompt compilation and policy decisions consume
craik.runner_capability_matrix rather than inferring authority from
a runner name or free-form metadata. The
prompt compiler uses these matrices to include
runner-specific capability notes and policy boundaries in
deterministic prompts.
Boundaries
Craik core owns
- Task requests
- Case files
- Policy envelopes
- Capability grants
- Receipts
- Handoffs
- Memory proposals
- Contract validation
Adapters own
- Runner invocation or prompt handoff
- Runner-specific session details
- Runner-specific diagnostics
- Mapping runner output back into Craik contracts
Runner-specific details stay inside the metadata, outputs, or
diagnostics fields unless they become stable cross-runner contract
fields. Adapter-produced receipts and handoff inputs include the
stable runner metadata snapshot.
Provider-backed MVP runner
The MVP provider-backed runner is implemented in
craik.runtime.provider_runner. It uses the normal case-file and
prompt compiler flow, then runs deterministic provider-normalized
steps through the governed loop.
Provider-backed runs must persist:
Compiled prompt
Task run
Normalized run outputs
Per executed step.
Provider receipts
Per model step.
Side-effect / denial receipts
Emitted by the loop.
Handoff
For completion · block · failure · interruption.
OpenAI and Anthropic parity is covered by deterministic tests for
provider_openai and provider_anthropic. The MVP runner path
does not perform live API calls by default.
Additional live runner adapters are post-MVP.
Preview adapters may remain useful for prompt handoff, local fixtures, and contract validation, but they should not be documented as operational live execution paths until they meet the same certification, budget, retry, redaction, receipt, and side-effect requirements as the MVP OpenAI and Anthropic provider paths. See Post-MVP Scope.