Skip to content

Opt-in Python harness contract

The harness controls only callables explicitly wrapped by the host application. Creating a run does not intercept other model, tool, framework, or provider calls. Ordinary AgentLoop tracing has no harness dependency and remains unchanged.

The implementation and evidence review maps the completed roadmap to supported capabilities, tests and retained workload results.

from agentloop.harness import Decision, Harness, HarnessConfig, Hook, Policy

guard = Policy(
    policy_id="reviewed-tool-denial",
    version="1",
    evaluate=lambda context: Decision("deny", "requires_review"),
    hooks={Hook("tool")},
    actions={"deny"},
)
run = Harness(HarnessConfig(mode="shadow", policies=(guard,))).start_run("task-01")
protected_tool = run.wrap(lambda: "result", boundary="tool", branch_id="lookup")
assert protected_tool() == "result"  # Shadow records the denial but admits the call.
assert run.results[0].action == "deny"
assert run.results[0].applied is False

Use mode="enforce" only after reviewing policy configuration and the adapter's coverage. The same call then raises HarnessDeniedError before dispatch. Handle HarnessDeniedError, HarnessStoppedError, and HarnessEscalationError in the host application's control flow. Roll back by creating a disabled configuration; an existing run retains its immutable settings and decisions.

Run uv run python examples/harness_controls.py for the three modes together. The disabled and shadow cases each dispatch once; the enforced case dispatches zero times. These synthetic cases verify control flow, not policy usefulness.

Contract 1.0

HarnessConfig fixes a mode (disabled, shadow, or enforce) and an ordered set of versioned policies. Disabled is the default. Each policy declares its before/after hooks, possible actions, priority, and JSON configuration. Settings are deeply immutable; canonical hashes cover the configuration, policy identity and version, ordering, and mode. A hash identifies settings, not callback code or anonymous data. Change a policy's version when its implementation changes.

Harness.start_run() returns explicit, run-local state. There is no implicit process-global active run. A host shares one run across concurrent branches and assigns branch IDs when wrapping functions, or creates separate runs for separate executions. Hook callbacks are synchronous, bounded, and serialized within a run; protected work executes outside that lock. Callbacks must use their supplied policy state rather than mutable globals and must not retain that state beyond the hook. Calling a protected wrapper from a policy is rejected to prevent recursive policy execution. This is a cooperation contract, not a sandbox for untrusted policy code.

Hooks cover model, tool, iteration, and completion. The host defines the corresponding dispatch boundary; an iteration is not inferred from repeated tool names. Before hooks run before invoking the callable. After hooks receive an execution status, including denial, failure, cancellation, and stream closure; they do not receive raw arguments, results, or exception messages. Existing trace and parent IDs are read through public trace-context helpers, without taking over tracing or changing the active context.

HookContext.dispatched and HookResult.dispatched are false before admission and on cleanup after a failed/denied before hook. They are true once the wrapper attempts to invoke the callable. This distinguishes a policy cancellation before dispatch from cancellation of admitted work, without inferring provider usage or side effects. Even an attempted invocation can fail before the callable's body does any work (for example, argument binding can fail).

Policies run by ascending priority, then policy ID. All matching policies are evaluated; conflict resolution is escalate > stop > deny > continue. An explicit adapter capability declaration is checked at construction. Enforced hooks or actions outside those capabilities are rejected before any work starts. Returning an undeclared action is a policy error, not implicit permission to dispatch. Enforced adapters must also support stop and escalation for intrinsic policy failure handling, even when the configured policy normally only continues.

Action Enforced behavior
continue Admit this call or preserve its result
deny Reject this call before dispatch; other calls remain eligible
stop Stop admission for this run and raise a control exception
escalate Stop admission and raise an escalation for the host to resolve

deny is only valid for before hooks. An after-hook stop/escalation cannot undo completed work and may prevent returning its result. If the protected call itself raises or is cancelled, that original exception is preserved even when an after hook fails; the hook failure is recorded and enforced future admission stops. Already admitted work is not forcibly interrupted by a later stop.

In shadow mode, decisions and policy failures are observable but do not deny, stop, reroute, retry, or change the callable's return value. Shadow policy state is hypothetical and run-local. In enforce mode, policy errors stop admission and raise escalation rather than silently allowing protected work. Cancellation and other process-control exceptions retain their original identity.

Streaming and boundaries

Python wrappers distinguish ordinary, coroutine, generator, and async-generator functions. Generator admission is lazy: no policy or callable executes until the first resume. Send, throw, close, async equivalents, and generator return values are preserved. After hooks run once, at exhaustion, closure, failure, or denial. A generator never resumed produces no decisions. Disabled wrappers return the original callable, preserving all existing behavior and instrumentation. Wrapping the same protected function again with the same run/boundary/branch is a no-op. Metadata copied onto a different function does not bypass its admission.

A normal function that returns an SDK stream is controlled only through its return, not through subsequent consumption. Wrap an explicit generator that delegates to that stream to control its full lifetime. Wrappers do not claim coverage of hidden provider retries, arbitrary blocking code, remote side effects, or unsupported framework dispatch. Stopping is cooperative; there is no process termination, automatic retry, or spend guarantee in this contract.

Evidence and extensions

The run exposes immutable in-memory hook results and versioned decision evidence. Active traces retain policy snapshots, proposal dispositions, dispatch status, timing, and explicit retry/conflict links through native JSON, supported OTLP round trips, and HTML. The existing intervention ledger links actual comparisons without treating a logged action as a measured benefit. Raw policy configuration capture is disabled by default.

Admission budgets use the same hooks for atomic reservation and reconciliation, with explicit unknown-usage policies and cooperative deadlines. DispatchOptions carries typed bounds and retry origin; an optional synchronous usage_reader returns normalized ResourceUsage without retaining raw results. Retry and loop guards use explicit step identities and caller fingerprints, with bounded retry and optional repetition/oscillation rules. Decision.retry_of annotates a host-declared relationship; nothing automatically executes a retry or replans the workflow.

Explicit context controls bind an opt-in synchronous before-model adapter for caller-selected optional tool-result summaries. They preserve message roles and protected evidence, charge summaries to the same run, and retain transformation receipts without adding generic policy actions. Explicit routing adds reviewed model bindings, capability checks and bounded fallback on the same run budget. Declared scheduling adds bounded tool concurrency with explicit dependencies and resource safety. Completion verification checks explicit criteria and bounds repair on the same run. Host checkpoint recovery preserves built-in policy state through one explicit LangGraph checkpoint path. Reviewed policy promotion gates one budget-policy family on held-out evidence, explicit operator approval and bounded canary rollback. No required provider SDK is introduced.