Agent Harness Loop Contract
The harness is the agent. The model is a coprocessor. This lesson freezes the loop contract you can wire any model into.
Learning Objectives
- Specify an agent harness loop as a deterministic state machine with explicit transitions.
- Implement ten lifecycle hook topics that operators wire policy, telemetry, and guardrails into.
- Define two pull points where the loop yields control back to the caller and resumes on a fresh input.
- Enforce per-session budgets (turns, tool calls, wall-clock) without leaking partial state on exceeding.
- Emit a typed stream of eleven event types so downstream UIs and tracers can subscribe without inspecting the loop directly.
The frame
A coding agent that runs unattended for forty turns is not a chat loop. It is a state machine whose nodes the operator can intercept and whose edges the operator can audit. Once you write the contract down, swapping models, tools, or policies stops being a refactor. It becomes a registration call.
This lesson builds that contract. We name six states, ten hook topics, two pull points, eleven event types, and a budget envelope. Everything else in the harness (tool registry, JSON-RPC transport, dispatcher, planner) plugs into this shape.
The states
The loop has six states. Five are active. One is terminal.
IDLE is the only legal entry point. DONE is the only legal exit. AWAITING_TOOL is the only state that yields a pull point. Every other transition is internal.
The state machine is deterministic. Given the same event log, the harness re-enters the same state. That property is what lets you replay sessions for debugging without re-calling the model.
The hook topics
Hooks are the operator's seam into the loop. The harness fires ten topics. Each topic accepts any number of subscribers. Subscribers fire in registration order. A subscriber may mutate the payload, raise to abort the turn, or return a sentinel to skip the next step.
before_plan after_plan
before_tool_call after_tool_call
before_step after_step
on_error
on_pause
on_budget_exceeded
on_completeThe shape mirrors what Claude Code, Cursor, and OpenCode all converged on by mid-2025. The names are functional, not branded. A hook that blocks rm -rf lives in before_tool_call. A hook that ships an OpenTelemetry span lives in after_step. A hook that resumes on a paused session lives in on_pause.
The pull points
The loop yields control twice. First on AWAITING_TOOL when it cannot make progress without a tool result. Second on on_pause when the budget is exhausted or a hook explicitly requests human review.
A pull point is not an exception. It is a return. The caller inspects the harness state, fetches whatever the harness asked for, and calls resume(payload). The harness picks up where it stopped. This is the same shape as a Python generator. The transport over the pull point is your choice. In a TUI it is keypress. Over MCP it is tools/call. Over a queue it is a job poll.
The event stream
The loop appends events to a typed stream at specific points in the contract. The stream is append-only and subscribers can replay from any offset. The eleven implemented event types are:
session.startemitted once whenrun(goal)is calledplan.draftemitted when the planner returns a draft planplan.commitemitted after the draft is committed as the active planstep.startemitted at the start of each executing stepstep.endemitted at the end of each executing steptool.callemitted when a tool-requiring step yields control to the callertool.resultemitted on resume with a tool resulttool.erroremitted on resume with an error or when a hook aborts the callbudget.warnemitted when a budget limit is reachedsession.pauseemitted when the loop yields on a pause (budget or hook)session.completeemitted once when the loop reachesDONE
The events do not duplicate hook payloads. Hooks are imperative (mutate, abort). Events are observational (record, ship). Treat them as orthogonal.
The budget envelope
A session carries three limits. Turn count, tool call count, wall-clock seconds. Each turn increments turns by one. Each tool call increments tool calls by one. Wall-clock is checked on every state transition. When any limit is reached, the loop fires on_budget_exceededemits budget.warnthen transitions to IDLE with a budget-exceeded reason on the next pull point.
The budget is not a kill switch. It is a yield. The caller decides whether to extend the budget and resume, or to close the session.
What this lesson does not do
It does not call a model. It does not register real tools. It does not implement a transport. Those are the next four lessons. This lesson nails the contract so the next four can plug into it without rewriting.
The deterministic planner in main.py is a stand-in. It returns a hardcoded plan of three steps, two of which require a tool result. The point is the loop, not the plan.
How to read the code
HarnessLoop is the main class. It holds state, fires hooks, emits events. Budget tracks limits. Event is the typed envelope on the stream. HookRegistry is the dispatch table. _transition is the only function that changes state, so the state machine invariants live in one place.
Read main.py top to bottom. Then read code/tests/test_loop.py. The tests pin every transition and every hook firing order.
Going further
The hardest part of building a harness in production is not the state machine. It is making the contract enforceable. The contract has to survive a hot reload of the planner. It has to survive a tool that returns malformed JSON. It has to survive a hook that raises in before_tool_call two-thirds of the way through a forty-turn session. The tests in this lesson exercise those failure modes. Run them. Break them. Add cases.
The next lesson adds the tool registry. After that, the JSON-RPC transport. After that, the dispatcher. By lesson twenty-four, the loop in this file will be running a real plan against real tools with real budgets enforced.
Check what you learned
7 questions. Answer each one to see why.
Why model the harness loop as an explicit state machine rather than a while loop with flags?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""Agent harness loop contract — deterministic state machine, hooks, pull points.
Conceptual references:
- ./docs/en.md (this lesson)
- Phase 14 lesson 01 (agent loop fundamentals)
- Phase 13 lesson 02 (tool protocols overview)
Stdlib only. Run: python3 code/main.py
"""
from __future__ import annotations
import json
import time
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Callable, Iterable
class State(str, Enum):
IDLE = "idle"
PLANNING = "planning"
EXECUTING = "executing"
AWAITING_TOOL = "awaiting_tool"
REFLECTING = "reflecting"
DONE = "done"
HOOK_TOPICS = (
"before_plan",
"after_plan",
"before_step",
"after_step",
"before_tool_call",
"after_tool_call",
"on_error",
"on_pause",
"on_budget_exceeded",
"on_complete",
)
EVENT_TYPES = (
"session.start",
"plan.draft",
"plan.commit",
"step.start",
"step.end",
"tool.call",
"tool.result",
"tool.error",
"budget.warn",
"session.pause",
"session.complete",
)
class HookAbort(Exception):
"""Raised by a hook to cancel the in-flight turn."""
@dataclass
class Event:
type: str
payload: dict
ts: float
def to_dict(self) -> dict:
return {"type": self.type, "payload": self.payload, "ts": self.ts}
@dataclass
class Budget:
max_turns: int = 8
max_tool_calls: int = 16
max_wall_seconds: float = 30.0
turns: int = 0
tool_calls: int = 0
started_at: float = field(default_factory=time.time)
def remaining_seconds(self) -> float:
return max(0.0, self.max_wall_seconds - (time.time() - self.started_at))
def exceeded(self) -> str | None:
if self.turns >= self.max_turns:
return "turns"
if self.tool_calls >= self.max_tool_calls:
return "tool_calls"
if self.remaining_seconds() <= 0.0:
return "wall_clock"
return None
@dataclass
class Step:
id: int
description: str
requires_tool: bool
tool_name: str | None = None
tool_args: dict = field(default_factory=dict)
result: Any = None
error: str | None = None
@dataclass
class PullRequest:
"""Returned from run()/resume() when the loop yields control."""
reason: str
state: State
payload: dict
@dataclass
class SessionResult:
state: State
reason: str
steps: list[Step]
events: list[Event]
class HookRegistry:
def __init__(self) -> None:
self._subs: dict[str, list[Callable[[dict], Any]]] = {t: [] for t in HOOK_TOPICS}
def on(self, topic: str, fn: Callable[[dict], Any]) -> None:
if topic not in self._subs:
raise ValueError(f"unknown hook topic: {topic}")
self._subs[topic].append(fn)
def fire(self, topic: str, payload: dict) -> list[Any]:
results = []
for fn in self._subs[topic]:
results.append(fn(payload))
return results
Planner = Callable[[str, list[Step]], list[Step]]
def _default_planner(goal: str, history: list[Step]) -> list[Step]:
"""Deterministic stand-in planner. Returns a fixed three-step plan."""
if history:
return []
return [
Step(id=1, description=f"interpret goal: {goal}", requires_tool=False),
Step(id=2, description="fetch user record", requires_tool=True,
tool_name="db.get_user", tool_args={"id": 42}),
Step(id=3, description="summarize and respond", requires_tool=True,
tool_name="format.summary", tool_args={"style": "short"}),
]
class HarnessLoop:
"""Six-state deterministic loop with hook topics and event stream."""
def __init__(
self,
planner: Planner | None = None,
budget: Budget | None = None,
) -> None:
self.state: State = State.IDLE
self.hooks = HookRegistry()
self.budget = budget or Budget()
self._planner: Planner = planner or _default_planner
self._goal: str = ""
self._plan: list[Step] = []
self._cursor: int = 0
self._events: list[Event] = []
self._history: list[Step] = []
self._reason: str = ""
self._prev_state: State | None = None
@property
def events(self) -> list[Event]:
return list(self._events)
@property
def plan(self) -> list[Step]:
return list(self._plan)
def _emit(self, etype: str, payload: dict) -> None:
if etype not in EVENT_TYPES:
raise ValueError(f"unknown event type: {etype}")
self._events.append(Event(type=etype, payload=payload, ts=time.time()))
def _transition(self, target: State) -> None:
legal: dict[State, set[State]] = {
State.IDLE: {State.PLANNING},
State.PLANNING: {State.EXECUTING, State.IDLE, State.DONE},
State.EXECUTING: {State.AWAITING_TOOL, State.REFLECTING, State.IDLE},
State.AWAITING_TOOL: {State.REFLECTING, State.IDLE},
State.REFLECTING: {State.PLANNING, State.EXECUTING, State.DONE, State.IDLE},
State.DONE: set(),
}
if target not in legal[self.state]:
raise RuntimeError(f"illegal transition {self.state.value} -> {target.value}")
self.state = target
def _check_budget(self) -> PullRequest | None:
which = self.budget.exceeded()
if which is None:
return None
self._emit("budget.warn", {"limit": which})
self.hooks.fire("on_budget_exceeded", {"limit": which, "budget": self.budget})
self._reason = f"budget_exceeded:{which}"
self._prev_state = self.state
return self._pause(self._reason)
def _pause(self, reason: str) -> PullRequest:
self._emit("session.pause", {"reason": reason})
self.hooks.fire("on_pause", {"reason": reason})
self._transition(State.IDLE)
return PullRequest(reason=reason, state=self.state, payload={"reason": reason})
def run(self, goal: str) -> PullRequest | SessionResult:
if self.state != State.IDLE:
raise RuntimeError(f"run() requires IDLE, got {self.state.value}")
self._goal = goal
self.budget.started_at = time.time()
self._emit("session.start", {"goal": goal})
return self._step()
def resume(self, payload: dict | None = None) -> PullRequest | SessionResult:
if self.state == State.IDLE and self._reason.startswith("budget_exceeded"):
self.budget.turns = 0
self.budget.tool_calls = 0
self.budget.started_at = time.time()
self._reason = ""
prev = self._prev_state
self._prev_state = None
if not self._plan:
return self._begin_plan()
if prev == State.EXECUTING:
self.state = State.EXECUTING
else:
self.state = State.REFLECTING
return self._step()
if self.state == State.AWAITING_TOOL:
if payload is None:
raise ValueError("resume from AWAITING_TOOL requires a payload")
current = self._plan[self._cursor]
if "error" in payload:
current.error = str(payload["error"])
self._emit("tool.error", {"step": current.id, "error": current.error})
self.hooks.fire("on_error", {"step": current, "error": current.error})
else:
current.result = payload.get("result")
self._emit("tool.result", {"step": current.id, "result": current.result})
self.hooks.fire("after_tool_call", {"step": current})
self._transition(State.REFLECTING)
return self._step()
raise RuntimeError(f"resume() unsupported from state {self.state.value}")
def _begin_plan(self) -> PullRequest | SessionResult:
self._transition(State.PLANNING)
self.hooks.fire("before_plan", {"goal": self._goal, "history": list(self._history)})
draft = self._planner(self._goal, list(self._history))
self._emit("plan.draft", {"steps": [s.description for s in draft]})
self.hooks.fire("after_plan", {"steps": draft})
self._plan = draft
self._cursor = 0
self._emit("plan.commit", {"count": len(draft)})
if not draft:
return self._complete("no_plan")
self._transition(State.EXECUTING)
return self._step()
def _step(self) -> PullRequest | SessionResult:
if self.state == State.IDLE:
return self._begin_plan()
budget_hit = self._check_budget()
if budget_hit is not None:
return budget_hit
if self.state == State.REFLECTING:
self._cursor += 1
self.budget.turns += 1
if self._cursor >= len(self._plan):
return self._complete("goal_met")
self._transition(State.EXECUTING)
return self._step()
if self.state != State.EXECUTING:
raise RuntimeError(f"_step requires EXECUTING/REFLECTING, got {self.state.value}")
step = self._plan[self._cursor]
self.hooks.fire("before_step", {"step": step})
self._emit("step.start", {"step_id": step.id, "desc": step.description})
if step.requires_tool:
try:
self.hooks.fire("before_tool_call", {"step": step})
except HookAbort as exc:
step.error = f"hook_abort:{exc}"
self._emit("tool.error", {"step": step.id, "error": step.error})
self.hooks.fire("on_error", {"step": step, "error": step.error})
self._transition(State.REFLECTING)
return self._step()
self.budget.tool_calls += 1
self._emit("tool.call", {"step": step.id, "tool": step.tool_name, "args": step.tool_args})
self._transition(State.AWAITING_TOOL)
self._emit("step.end", {"step_id": step.id, "outcome": "awaiting_tool"})
self.hooks.fire("after_step", {"step": step, "outcome": "awaiting_tool"})
return PullRequest(
reason="tool_call",
state=self.state,
payload={"tool": step.tool_name, "args": step.tool_args, "step_id": step.id},
)
step.result = f"ok:{step.description}"
self._emit("step.end", {"step_id": step.id, "outcome": "ok"})
self.hooks.fire("after_step", {"step": step, "outcome": "ok"})
self._transition(State.REFLECTING)
return self._step()
def _complete(self, reason: str) -> SessionResult:
self._emit("session.complete", {"reason": reason})
self.hooks.fire("on_complete", {"reason": reason})
self._transition(State.DONE)
self._reason = reason
return SessionResult(state=self.state, reason=reason, steps=list(self._plan), events=list(self._events))
def _demo() -> None:
loop = HarnessLoop()
fired: list[str] = []
for topic in HOOK_TOPICS:
loop.hooks.on(topic, lambda payload, t=topic: fired.append(t))
out = loop.run("ship the release notes")
assert isinstance(out, PullRequest) and out.reason == "tool_call"
out = loop.resume({"result": {"id": 42, "name": "ada"}})
assert isinstance(out, PullRequest) and out.reason == "tool_call"
final = loop.resume({"result": "summary text"})
assert isinstance(final, SessionResult)
assert final.state == State.DONE
assert final.reason == "goal_met"
report = {
"events": [e.type for e in final.events],
"hooks_fired": fired,
"final_state": final.state.value,
"final_reason": final.reason,
}
print(json.dumps(report, indent=2))
if __name__ == "__main__":
_demo()