Agent Harness Plugins SDK

An agent harness acts as the low-level executor for a single prepared turn of an OpenClaw agent. It is neither a model provider, a channel, nor a tool registry. For the user-facing conceptual overview, refer to Agent runtimes.

This surface is intended only for bundled or trusted native plugins. The contract remains experimental, since the parameter types deliberately mirror the current embedded runner.

When to use a harness

Register an agent harness when a model family ships its own native session runtime and the standard OpenClaw provider transport does not fit:

a native coding-agent server that manages threads and compaction
a local CLI or daemon that needs to stream native plan/reasoning/tool events
a model runtime that requires its own resume id alongside the OpenClaw session transcript

Do not register a harness merely to introduce a new LLM API. For ordinary HTTP or WebSocket model APIs, construct a provider plugin.

What core still owns

Before a harness gets selected, OpenClaw has already determined:

provider and model
runtime auth state, unless the harness declares ownership of auth bootstrap
thinking level and context budget
the OpenClaw transcript/session file
workspace, sandbox, and tool policy
channel reply callbacks and streaming callbacks
model fallback and live model switching policy

A harness executes a prepared attempt; it does not choose providers, take over channel delivery, or switch models on its own.

Native tool-policy enforcement

Set conversationToolPolicySupport: "exact" only when runAttempt enforces every explicit OpenClaw tool-policy layer across native and built-in tools, OpenClaw tools, requester and configured MCP servers, apps, delegation, and resumed threads. Core passes params.pluginHarnessToolPolicyRestricted as the prepared decision that the native surface must be isolated. Default tool-profile narrowing does not set this flag.

Harnesses with an independently managed native surface can also declare conversationToolPolicySafeDenyTools using canonical OpenClaw tool names. Core preserves the native surface only when every expanded deny is a known core tool in that audited safe list. Finite allowlists, undeclared or unknown tool names, wildcards, and groups containing any undeclared name remain native-surface restrictions. Omit the list to retain the conservative behavior where every explicit restriction isolates the native surface. Because omissions fail closed, new tools cannot silently relax the policy boundary.

Omit the declaration when any native capability can bypass those layers. OpenClaw then visibly rejects explicitly restricted turns before invoking the harness. The operator can switch the session to the embedded runtime or upgrade the harness. Channel /btw side questions with a restrictive direct policy are rejected by core and are not covered by this declaration.

Harness-owned auth bootstrap

By default, core resolves provider credentials before calling a harness. A trusted harness that can authenticate through its own native runtime may set authBootstrap: "harness" on its static AgentHarness registration. Core then skips its generic provider credential bootstrap and missing-credential failure for every attempt claimed by that harness.

Core still forwards a compatible, explicitly selected or ordered OpenClaw auth profile and its scoped store when one exists. The harness must resolve that profile or its native credentials before issuing model requests, keep secrets scoped to the attempt, and surface actionable authentication failures. Do not set this capability on a harness that only sometimes owns authentication.

Verified setup runtime artifacts

A local harness that can supply inference for first-run setup must attest the implementation that completed the probe. When params.captureRuntimeArtifact is true, return an opaque result.runtimeArtifact with a stable id and content fingerprint. Register a matching runtimeArtifact.validate(...) capability that rechecks that binding without loading a different harness or scanning unrelated plugins.

Verified OpenClaw continuations also pass params.expectedRuntimeArtifact. The harness must compare it with the exact native process it acquired and fail before starting or resuming a native thread if they differ. Ordinary agent turns omit both fields, so content hashing stays out of the normal request hot path. Remote/WebSocket harnesses need a server attestation contract before they can participate; a version string alone is not an artifact identity.

The prepared attempt also includes params.runtimePlan, an OpenClaw-owned policy bundle for runtime decisions that must stay shared across OpenClaw and native harnesses:

runtimePlan.tools.normalize(...) and runtimePlan.tools.logDiagnostics(...) for provider-aware tool schema policy
runtimePlan.transcript.resolvePolicy(...) for transcript sanitization and tool-call repair policy
runtimePlan.delivery.isSilentPayload(...) for shared NO_REPLY and media delivery suppression
runtimePlan.outcome.classifyRunResult(...) for model fallback classification
runtimePlan.observability for resolved provider/model/harness metadata

Harnesses may use the plan for decisions that need to match OpenClaw behavior, but treat it as host-owned attempt state: do not mutate it or use it to switch providers/models inside a turn.

Request-transport contract

supports(ctx) receives the resolved model transport in ctx.modelProvider. Two secret-free provider-owned facts describe the selected route:

runtimePolicy.compatibleIds lists the runtime ids the provider declares compatible with that concrete route. An absent policy means the provider did not declare route-level compatibility; it is not permission to assume support.
requestTransportOverrides: "none" means no authored provider/model request override must be reproduced. "present" means authored headers, auth transport, proxy, TLS, local-service, private-network behavior, or request parameters exist. The fact does not expose those values.

Return { supported: false, reason } when the harness cannot reproduce the prepared transport. Do not infer support by reading raw config after selection. Add fallbackRuntime: "openclaw" only when the built-in runtime can reproduce the exact prepared request without dropping authored behavior. Core then uses that fallback for explicit and persisted selections as well as multi-route retry sets. Leave it absent for provider, route, or authentication failures that must remain fail-closed.

When auth preparation yields multiple retry routes, one harness must support all of them before dispatch. Implicit selection uses OpenClaw if no plugin can own the full set; an explicit or persisted plugin selection fails closed unless the plugin declares the lossless OpenClaw fallback.

Register a harness

Import: openclaw/plugin-sdk/agent-harness

import type { AgentHarnessV2 } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarnessV2 = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    const routeSupportsHarness =
      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;
    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";
    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest
      ? { supported: true, priority: 100 }
      : { supported: false, reason: "effective route is not harness-compatible" };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

authBootstrap is intentionally absent from this generic example. Add authBootstrap: "harness" only when the harness meets the contract above.

Isolated completion

The optional runIsolatedCompletionV2(params) capability serves product paths that require one fresh prompt-only inference call with a literal empty model-callable tool surface. Core passes provider and model ids, prompts, deadline controls, and one prepared authorization:

owner: "host" contains the exact transport model and resolved auth.
owner: "harness" contains the prepared runtime auth plan and a credential snapshot restricted to the single profile selected for that call. Core owns automatic fallback order and invokes the harness separately for each candidate.

Host-authorized calls must use the supplied model and credential without substitution. Harness-authorized calls may resolve only the supplied prepared route and scoped profiles, or the harness's native account when the plan leaves auth to the harness. The harness must not switch routes, reuse a native thread, attach tools, invoke agent lifecycle hooks, or deliver output.

Return { assistant: AssistantMessage }. Core accepts only terminal text/thinking content with a stop or length stop reason; tool calls, failed stops, and empty output are rejected. If the harness cannot prove these semantics, omit the capability. Callers that require isolated completion then fail closed before invoking that harness; OpenClaw does not replay the request through another runtime. Plugin callers select this behavior through api.runtime.llm.complete({ execution: { mode: "isolated-agent-runtime" } }); the harness callback is the provider-side enforcement SPI, not a second caller API.

The legacy runIsolatedCompletion(params) host-auth-only capability is deprecated and remains available for external plugins through 2026-10-12. Implement V2 for harness-owned or native authentication; OpenClaw never invents a host credential when only the legacy capability is present.

Native agent servers often have ambient built-in tools even when OpenClaw sends an empty tool list. Disable and attest those native capabilities for the fresh turn, use a separate transport that can serialize a true zero-tool request, or leave the capability unsupported.

Delegated execution

A harness owner can assign delegatedExecutionPluginIds the ids of plugins it trusts to run an existing model-locked session, for instance a voice transport that keeps a Codex-backed conversation going. This is static owner consent, not a core allowlist. Keep the list tight.

Delegates get only work admission and embedded execution. OpenClaw demands the exact stored session key, store path, and session id; modelSelectionLocked: true; and matching agentHarnessId and agentHarnessRuntimeOverride values. The run is then scoped through the harness owner. Creating, patching, resetting, deleting, archiving sessions, and mutating the Gateway remain owner-only operations.

Selection policy

OpenClaw picks a harness after provider/model resolution:

Model-scoped runtime policy takes precedence.
Provider-scoped runtime policy is next in priority.
auto asks registered harnesses whether they support the resolved effective route. Provider/model prefixes alone never select a harness.
If no registered harness matches, OpenClaw falls back to its embedded runtime.

Plugin harness failures surface as run failures. In auto mode, embedded fallback applies only when no registered plugin harness supports the resolved provider/model. Once a plugin harness has claimed a run, OpenClaw does not replay that same turn through another runtime, because that can change auth/runtime semantics or duplicate side effects.

A failure that occurs before the harness starts any model work may use AgentHarnessPreflightError from openclaw/plugin-sdk/agent-harness-runtime. The default error remains terminal for the whole model-fallback chain. Pass { scope: "harness" } only when the failure is local to the selected harness and retrying another model on that same harness would repeat it. OpenClaw records the actual selected harness at the attempt boundary, skips only later candidates proven to use that harness, and runs any differently owned candidate through its normal runtime and policy checks. Plugins opt into the scope but never name the harness owner on the error. Do not use harness scope after a request or tool action may have produced side effects.

Configured runtime policy remains authoritative about the desired runtime. A persisted session agentHarnessId keeps ownership of its native transcript while route/auth preparation is still pending. Neither makes an incompatible route compatible: once prepared facts exist, the selected or pinned harness must support them or the run fails closed. /status shows the effective runtime selected from policy, persisted ownership, and route support. Prepared status is explicit: missing runtimePolicy stays undeclared instead of being inferred from whichever transport fields happen to be present. When harness-owned auth leaves multiple physical routes unresolved, the prepared support fact is the intersection of their compatible runtime ids and reports request overrides if any candidate has them. One undeclared candidate therefore makes native compatibility empty; preparedAuth.source: "harness" is an auth owner, not permission to infer route support.

If the selected harness is surprising, enable agents/harness debug logging and inspect the gateway's structured agent harness selected record: it includes the selected harness id, selection reason, runtime/fallback policy, and, in auto mode, each plugin candidate's support result.

The bundled Codex plugin registers codex as its harness id. Core treats that as an ordinary plugin harness id; Codex-specific aliases belong in the plugin or operator config, not in the shared runtime selector.

Provider plus harness pairing

Most harnesses should also register a provider. The provider makes model refs, auth status, model metadata, and /model selection visible to the rest of OpenClaw. The harness then claims that provider in supports(...).

The bundled Codex plugin follows this pattern:

preferred user model refs: openai/gpt-5.6-sol
compatibility refs: legacy codex/gpt-* refs remain accepted, but new configs should not use them as normal provider/model refs
harness id: codex
auth: synthetic provider availability, because the Codex harness owns the native Codex login/session
app-server request: OpenClaw sends the bare model id to Codex and lets the harness talk to the native app-server protocol

The Codex plugin is additive. With runtime policy unset or auto, OpenAI may select Codex only when its provider-owned route contract declares codex compatible: an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. The openai/* prefix alone never selects Codex. Custom endpoints, Completions adapters, and authored request behavior stay on OpenClaw. Plaintext official HTTP endpoints are rejected. Older codex/gpt-* refs remain compatibility inputs. See OpenAI implicit agent runtime.

For operator setup, model prefix examples, and Codex-only configs, see Codex Harness.

The Codex plugin enforces the minimum app-server version documented in Codex Harness. It checks the initialize handshake and blocks older or unversioned servers, so OpenClaw only runs against the protocol surface it has tested.

Tool-result middleware

Bundled plugins and explicitly enabled installed plugins with matching manifest contracts can attach runtime-neutral tool-result middleware through api.registerAgentToolResultMiddleware(...) when their manifest declares the targeted runtime ids in contracts.agentToolResultMiddleware. This trusted seam is for async tool-result transforms that must run before OpenClaw or Codex feeds tool output back into the model.

Middleware options may combine runtimes with a matcher tool-name list. Each registration keeps that pair intact, so registering the same handler for different runtimes does not broaden either matcher. Matchers use non-empty canonical OpenClaw tool ids; omit matcher to match all tools.

Legacy bundled plugins can still use api.registerCodexAppServerExtensionFactory(...) for Codex app-server-only middleware, but new result transforms should use the runtime-neutral API. The embedded-runner-only api.registerEmbeddedExtensionFactory(...) hook has been removed; embedded tool-result transforms must use runtime-neutral middleware.

Terminal outcome classification

Native harnesses that own their own protocol projection can use classifyAgentHarnessTerminalOutcome(...) from openclaw/plugin-sdk/agent-harness-runtime when a completed turn produced no visible assistant text. The helper returns empty, reasoning-only, or planning-only so OpenClaw's fallback policy can decide whether to retry on a different model. planning-only requires the harness's explicit planText field; OpenClaw does not infer it from assistant prose. The helper intentionally leaves prompt errors, in-flight turns, and intentional silent replies such as NO_REPLY unclassified.

Agent-end side effects

Native harnesses must call runAgentEndSideEffects(...) from openclaw/plugin-sdk/agent-harness-runtime after they finalize an attempt. It dispatches the portable agent_end hook and OpenClaw's research capture without delaying interactive replies. Use awaitAgentEndSideEffects(...) for local, non-interactive runs where the attempt must not resolve until those side effects finish. Both helpers accept the same { event, ctx } payload as runAgentHarnessAgentEndHook(...); their failures do not alter the completed attempt result.

User input and tool surfaces

Native harnesses that expose a runtime-level user-input request should use the user-input helpers from openclaw/plugin-sdk/agent-harness-runtime to format the prompt, deliver it through OpenClaw's blocking reply path, and normalize choice/free-form answers back into the runtime's native response shape. The helper keeps channel/TUI presentation consistent while each harness keeps its own protocol parsing and pending-request lifecycle.

Each prepared attempt also gets a versioned params.hostCapabilities object. Call bindToolSurface(...) before exposing plugin-built OpenClaw tools, and apply its policy and approval operations for native actions. A native action whose working directory is different from the attempt can pass nativeOperation: { cwd } to runBeforeToolCall(...); the host normalizes that bounded action fact while keeping identity and policy authority closure-bound. The closure binds the host-resolved run, sandbox, requester, route, and approval identity; plugins must not reconstruct those fields or retain the capability after the attempt returns. Calls made after attempt settlement fail closed.

New harnesses should implement AgentHarnessV2 and type prepared attempts as AgentHarnessAttemptParamsV2, EmbeddedRunAttemptParamsV2, and AgentHarnessSideQuestionParamsV2; those contracts require hostCapabilities. Packages adopting V2 must declare openclaw.compat.pluginApi: ">=2026.8.1" (or a newer floor) so older hosts reject them before load. Import the parameter types from the runtime subpath:

import type {
  AgentHarnessAttemptParamsV2,
  AgentHarnessSideQuestionParamsV2,
  EmbeddedRunAttemptParamsV2,
} from "openclaw/plugin-sdk/agent-harness-runtime";

The older AgentHarness, AgentHarnessAttemptParams, and EmbeddedRunAttemptParams names remain source-compatible for existing plugins, so the capability field is optional in those deprecated parameter types through 2026-10-12. The public AgentHarnessSideQuestionParams contract has the same compatibility window and optional field. Core still supplies the capability on every selected attempt. Compatibility is type-level only: current harness code must not add a runtime path that operates without the host capability.

Native harnesses that need PI-like compact tool routing should use createAgentHarnessToolSurfaceRuntime(...) from openclaw/plugin-sdk/agent-harness-tool-runtime. It owns tool-search/code-mode control selection, local-model lean defaults, runtime-compatible schema filtering, hidden catalog execution, directory hydration, and catalog cleanup. Harnesses still own their SDK-specific tool conversion and native execution callback.

Native MCP inventory

A harness that owns MCP connections outside OpenClaw's in-process MCP runtime can implement loadMcpToolCatalog(params). The callback is used by read-only control surfaces such as the composer Tool access view. It receives the authoritative session identity, runtime config, workspace, and sparse session MCP overrides. mcpServerNames is the bounded set of OpenClaw-configured servers whose session policy the harness may represent. Return OpenClaw's McpToolCatalog shape for only that set.

Use only an already-bound native process and thread. Returning undefined means no live catalog is available; do not start a new harness process merely to answer inventory. Preserve raw server/tool names, assign collision-safe server names with assignMcpCatalogSafeServerNames(...), and retain tools hidden only by a session denial in sessionDeniedTools. Core still applies the final OpenClaw tool policy and schema compatibility checks before exposing the rows.

Harnesses that forward embedded attempt params should pass skillWorkshopProposalOnly through. Proposal-only skill-workshop runs are deliberately narrow single-tool runs, and the runtime keeps them on the raw tool surface instead of engaging code mode or a tool-search catalog.

Native Codex harness mode

The bundled codex harness is the native Codex mode for embedded OpenClaw agent turns. Enable the bundled codex plugin first, and include codex in plugins.allow if your config uses a restrictive allowlist. Native app-server configs should use openai/gpt-*; OpenAI agent turns select the Codex harness only when the effective route declares Codex compatibility. Legacy Codex model refs should be repaired with openclaw doctor --fix, and legacy codex/* model refs remain compatibility aliases for the native harness.

When this mode runs, Codex owns the native thread id, resume behavior, compaction, and app-server execution. OpenClaw still owns the chat channel, visible transcript mirror, tool policy, approvals, media delivery, and session selection. Use provider/model agentRuntime.id: "codex" when you need to prove that only the Codex app-server path can claim the run. Explicit plugin runtimes fail closed; Codex app-server selection failures and runtime failures are not retried through another runtime.

Runtime strictness

By default, OpenClaw uses auto provider/model runtime policy: registered plugin harnesses can claim compatible effective routes, and the embedded runtime handles the turn when none match. A provider/model prefix alone never selects a harness. Use an explicit provider/model plugin runtime such as agentRuntime.id: "codex" when missing harness selection should fail instead of routing through the embedded runtime. Explicit selection does not make an incompatible route compatible. Selected plugin harness failures always fail hard. This does not block an explicit provider/model agentRuntime.id: "openclaw".

For Codex-only embedded runs:

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.6-sol"
    }
  }
}

If you want a CLI backend for one canonical model, put the runtime on that model entry:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-5",
      "models": {
        "anthropic/claude-opus-5": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}

Per-agent overrides use the same model-scoped shape:

{
  "agents": {
    "entries": {
      "codex-only": {
        "default": true,
        "model": "openai/gpt-5.6-sol",
        "models": {
          "openai/gpt-5.6-sol": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    }
  }
}

Legacy whole-agent runtime examples like this are ignored:

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

With an explicit plugin runtime, a session fails early when the requested harness is not registered, does not support the resolved provider/model, or fails before producing turn side effects. That is intentional for Codex-only deployments and for live tests that must prove the Codex app-server path is actually in use.

This setting only controls the embedded agent harness. It does not disable image, video, music, TTS, PDF, or other provider-specific model routing.

Native sessions and transcript mirror

A harness may keep a native session id, thread id, or daemon-side resume token. Keep that binding explicitly associated with the OpenClaw session, and keep mirroring user-visible assistant/tool output into the OpenClaw transcript.

The OpenClaw transcript remains the compatibility layer for:

channel-visible session history
transcript search and indexing
switching back to the built-in OpenClaw harness on a later turn
generic /new, /reset, and session deletion behavior

If your harness stores a sidecar binding, implement reset(...) so OpenClaw can clear it when the owning OpenClaw session is reset.

Tool and media results

Core constructs the OpenClaw tool list and passes it into the prepared attempt. When a harness executes a dynamic tool call, return the tool result back through the harness result shape instead of sending channel media yourself.

This keeps text, image, video, music, TTS, approval, and messaging-tool outputs on the same delivery path as OpenClaw-backed runs.

Set AgentHarnessAttemptResult.hostOwnedToolMediaUrls only for native artifacts that the trusted harness runtime created and persisted itself. Every entry must also appear in toolMediaUrls. Never include model-selected dynamic-tool or OpenClaw-tool media. On message_tool_only routes, this narrow provenance lets native runtime artifacts survive source-reply suppression; normal send policy and ambient-room admission still apply.

Terminal tool outcomes

AgentHarnessAttemptParams.observeToolTerminal is the host-owned terminal outcome accumulator. A harness that executes OpenClaw dynamic tools or native tools must call it when each tool reaches one terminal outcome, before the attempt result is finalized. Harnesses that do not execute tools do not need to call it.

Report facts from the execution boundary:

Pass the protocol call id when one exists, the canonical tool name, and the arguments that actually reached the tool after preparation or hook rewrites.
Set executionStarted: false when validation, approval, or another guard stopped the call before the tool implementation began. Once dispatch may have happened, report true conservatively.
Report outcome: "success" or outcome: "failure". Include the structured failure fields available from the runtime instead of inferring failure from display text.
Use nativeMutation only for native tools that do not use an OpenClaw tool definition. Supply protocol-owned mutation and replay facts there; do not copy OpenClaw's mutation classifier into the harness.

The callback returns the canonical resolution for that call. Carry its lastToolError into AgentHarnessAttemptResult and use its execution, arguments, and side-effect facts in the harness projection instead of deriving parallel state. The host keeps an unresolved mutating failure across unrelated successful tools and clears it only after the matching action succeeds.

The callback remains optional for source compatibility with older experimental harnesses. Optional does not mean ignorable for a harness that executes tools: without terminal reports, OpenClaw cannot preserve mutating-tool failure truth across later tool calls, including quiet heartbeat completion.

Settled tool finalization

OpenClaw may need to produce a single final visible response after a harness has executed all of its tool calls, yet the native turn concluded without any assistant text. By implementing finalizeSettledTurn({ attempt, settledAttempt }), a harness can choose to participate in that recovery path.

This callback functions as a distinct capability rather than another standard attempt. The requirements are:

it must rely on either the exact restricted native transcript or a full application transcript that was frozen at the settled tool-result boundary;
no tools, permission-granting, user-input, native execution hooks, agents, skills, memory, scheduling, extensions, or remote control may be exposed;
only the host-supplied finalization prompt is allowed to be sent; and
if the chosen transcript or isolation strategy cannot guarantee those constraints, it must fail closed.

OpenClaw triggers the callback once as a terminal sub-operation, outside the normal attempt and retry flow. When it fails, the run terminates with the side-effect-aware incomplete-turn warning; ordinary auth or profile rotation, model fallback, context recovery, compaction continuation, and hook-requested revision paths are all off-limits. Finalization also bypasses plugin prompt mutation, before_agent_run, LLM input/output, terminal revision, and agent_end hooks. Core diagnostics continue to log the operation and its failure.

The callback yields AgentHarnessSettledTurnFinalizationResult rather than a standard attempt result. Its public fields are restricted to the completed assistant message, finalization-call usage, transcript-ownership metadata, and diagnostic trace. Tool, delivery, media, spawn, lifecycle, replay, session, and fallback state cannot cross this result boundary. Unknown fields and assistant tool calls fail closed.

When a harness internally reuses its full attempt engine, it can invoke projectSettledTurnFinalizationAttemptResult(...) before returning. That helper rejects canonical failure, tool, delivery, replay, and lifecycle evidence, then projects only the narrow result. It serves as defense in depth after native isolation, not as a replacement for removing the native capability surface.

A projection-backed harness must place the complete context on settledAttempt.settledTurnFinalizationContext with source: "openclaw-transcript". It must capture the active branch after the settled turn is mirrored, verify that the current prompt and every current tool call or result are present through that boundary, and freeze the resulting message array before returning the attempt. The finalizer must reject a missing, unsupported, ambiguous, or oversized context. It must not truncate messages, drop earlier history, or present this application transcript as exact native history. Harnesses that resume one restricted native session do not need this projection field.

Do not implement this callback by calling runAttempt with a best-effort disableTools hint. The harness owner must enforce the complete native capability boundary. OpenClaw offers no generic fallback because it cannot attest that an arbitrary native runtime honored those restrictions.

The callback stays optional for experimental third-party harness compatibility. When the selected harness omits it, OpenClaw keeps the existing incomplete-turn error rather than risking repeated side effects.

Current limitations

The public import path is generic, but some attempt or result type aliases still retain legacy names for compatibility.
Third-party harness installation is experimental. Prefer provider plugins until you need a native session runtime.
Harness switching is supported across turns. Do not switch harnesses in the middle of a turn after native tools, approvals, assistant text, or message sends have started.