A mental model for the whole repository

• infer_model("provider:model") selects the adapter and creates provider/settings objects.
• ModelNotice values are rendered with render_model_notices() and inserted into provider input by each session method; prompt starts/corrections append text, while tool continuations may add notice content after tool outputs.
• _responses_tool_to_anthropic() and _responses_tool_to_chat() convert the common function-tool schema.
• _extract_responses_tool_calls(), _extract_anthropic_tool_calls(), and _extract_chat_tool_calls() convert provider-specific tool calls into ModelToolCall objects.

ThinHarness uses different Python object types for different responsibilities. The short rule is: serializable setup uses Pydantic, runtime records use dataclasses, long-lived state holders use ordinary classes, and callable boundaries use functions or protocols.

Inheritance is intentionally light. Provider session classes implement the same session protocol, but the core loop mostly uses composition: Harness owns a model, tool specs, hooks, tracing options, skill registry, and MCP server list. Built-in tools often use classes as state holders, then hand bound methods to ToolSpec.

The run loop is divided by ownership. core.py coordinates the public run, runtime.py owns one run's mutable state, the active-session TurnDriver, and the repeated wrapper around each provider call, and tool_execution.py owns model-requested tool batches and the hook/tracing flow for one tool call.

The important handoff is TurnDriver plus RunContext.advance_model(request, trace_snapshot, output_retry=False). core.py chooses whether to start, resume, send tool outputs, or send a correction, and TurnDriver supplies the matching provider-session method call. The run-loop diagram may label the second case as "continue" for space, but the code path is continue_with_tools(...). runtime.py wraps that callable with limit checks, usage accounting, model tracing, notice computation, response capture, and output turn resolution.

This keeps provider API payload knowledge in providers.py while keeping the repeated provider-call wrapper in one place.

Approval-required tools are a loop primitive rather than a special model output format. A custom ToolSpec can set requires_approval=True. When a model turn asks for any such tool, core.py pauses before the batch reaches ToolBatchExecutor, so neither the approval-required call nor any normal sibling call has side effects yet.

Rejected calls bypass tool hooks and do not execute. They still produce ordered tool outputs for the provider: a failed ToolResult with error_type="ApprovalRejected". From the model's perspective, it requested tools and then received tool results on the next turn; it never sees the host pause itself.

The paused batch counts against usage.tool_calls at pause time and is not counted again during resume. The post-resume result contains the whole logical run history, not only the second half of the run. This is why approval envelopes are larger than plain resume state: they carry provider transcript state, prior responses, and accounting as well as the provider checkpoint.

A provider returns one ModelTurn. That object has text, a tool_calls list, and raw provider JSON. The tool_calls field is a list[ModelToolCall], where each ModelToolCall has the provider call id, tool name, and raw JSON argument string.

When resolve_turn_output() decides the turn should continue with ordinary tools, the harness executes the whole model-emitted batch and sends one ordered set of ToolOutput values back through continue_with_tools(...).

• ToolBatchExecutor chooses serial execution if any requested tool is marked sequential=True; otherwise it can run calls concurrently.
• ToolCallExecutor sets the current tool-call context, then runs before_tool_call hooks that may cancel the call.
• The executor parses JSON arguments, validates them with Pydantic when a model exists, and calls the async handler directly or the sync handler in a worker thread.
• Handler output is normalized into the standard {"ok", "content", "metadata"} tool envelope.
• Retry metadata is captured before after_tool_call hooks can rewrite the output text the model sees.
• Tracing records one tool span per call, while tool_call_records and provider-facing ToolOutput values preserve the original model order.

These are the main branches after a model asks for a tool call. They determine whether ThinHarness asks the model to repair its request, reports a normal tool failure, or continues the provider conversation.

Provider adapters are deliberately layered. Provider transport classes own auth, base URL, timeout, and HTTP client setup/cleanup. Model classes own reusable static settings. Session classes own mutable conversation state.

In plain terms: a Model is the reusable object you pass into Harness(..., model=...). It knows which provider/model/settings to use, but it should not hold the live conversation transcript. For each Harness.run(...), it creates a fresh ModelSession; that session is the object the harness actually talks to during the run.

The core loop should not know OpenAI Responses, Anthropic Messages, or OpenRouter Chat Completions API formats. It receives a ModelTurn and applies the same output resolution, tool execution, tracing, hook, limit, and retry logic regardless of provider.

Provider-specific translation stays in providers.py: common function tools become Anthropic input_schema tools or Chat Completions function tools; native structured output requests become provider-specific API fields; notice text is rendered into each provider's input format.

Structured output is not bolted onto every provider separately. The harness builds an OutputSchema from the caller's output spec, then providers translate the provider-native request details when native mode is used. resolve_turn_output() decides what one returned ModelTurn means.

final_result is harness-created, not a normal user tool. It is reserved only when structured tool mode is active, is not exposed in self.tools, does not fire tool hooks, does not count as usage.tool_calls, and makes the exit non-resumable because the provider transcript would contain an unanswered synthetic tool call. Native and prompted structured-output exits can still be resumable when the provider session can dump clean resume state.

Non-object output schemas such as lists are wrapped under a single value argument for tool mode because function tool arguments must be JSON objects. Validation uses Pydantic's public TypeAdapter API and local schema cleanup. The local implementation is intentionally narrower than Pydantic AI: it does not stream partial structured objects, treat a Python function signature as the output schema, or run custom output validator hooks.

Invalid structured output creates corrective model requests until output_retries is exhausted. Retry-budget exhaustion is handled by the caller of the resolver: Harness.run() turns it into a run failure, while ParallelLlmTool turns it into a per-entry failure.

Harness is reusable setup; RunContext is one invocation's state. That distinction is the main reason repeated runs on the same harness do not leak responses, usage, limit warnings, or resume bookkeeping.

resume_from starts a new turn from a previous clean result. It is not a failed-request retry, interrupted-tool continuation, or transcript repair mechanism. Errors, cancellation, limit exits, tool retry exhaustion, output validation failure, unexpected model behavior, and tool-mode final_result exits intentionally produce no checkpoint.

Resume also carries model reasoning. Each built-in session keeps the provider's native reasoning parts in the neutral transcript, so resuming on the same provider replays them verbatim — Anthropic signed thinking blocks, OpenAI encrypted_content, OpenRouter reasoning_details. An opaque blob cannot be replayed to a different provider, so cross-provider resume degrades every reasoning part to a leading <thinking>-tagged text block and drops the blob. Native re-emit also requires the resuming request to be able to accept the block:

Because resume_state can therefore hold encrypted reasoning blobs and signed thinking, treat it as sensitive, like the local traces it mirrors.

Extras are specialized capabilities that an application can ignore unless it uses that feature. They still enter the run through existing ToolSpec, Harness, and provider-session boundaries.