The harness

An agent harness equips an AI agent with tools, connects it to its environment, and manages the loop that lets it do real work. Users calibrate their expectations on tools like Claude Code and the Claude and ChatGPT apps, and the distance between a working demo and that experience is a long list of features teams normally discover one incident at a time. This page catalogs that list.

Two layers

nvoken builds on Dive, Deep Noodle's Go library for cross-provider LLM support and building agents. Dive is the in-process harness: the loop, the tool system, context engineering, and the model layer. nvoken runs that harness as a durable service: it owns the Sessions, makes the turn survivable, and manages the exchange of tool calls, events, and usage with your application.

The loop

• The tool call loop. Multi-round execution of model calls and tool dispatch until the turn produces a final response.
• Guardrails. Iteration, total-time, active-time, and waiting-time limits bound every run, and on the last allowed iteration tools are disabled and the model is instructed to answer, so a turn never strands mid tool call.
• Limits. Output-token, estimated-cost, iteration, and time limits from the execution spec, enforced while the turn runs.
• Parallel and background execution. Batches of tool calls run concurrently, with sequential fallback when a tool must run alone, and long-running work can move to the background so the turn continues.
• Failure containment. A tool failure becomes an error result the model can react to rather than ending the turn, and a failed turn still returns its usage and partial output.

Tools

• Execution modes. Builtin tools execute service-side, callback tools are signed calls to your endpoints, and host tools are recoverable through reads and the stream for your application to execute. The exchange is durable: stable tool call IDs, deadlines, and exactly one accepted result per call.
• Annotations and previews. Read-only, destructive, idempotent, and open-world hints drive permission decisions, and a tool can render a human-readable summary of what a call will do before it runs.
• Live output and rich results. A running tool can stream text and publish structured progress, and results carry text, image, or audio content, an optional display variant, and error status.
• Ready-made capability. A toolkit of file, shell, web, and interaction tools aligned with Claude Code's tool shapes, MCP servers adapted into tools, provider server-side tools where offered, and subagents with their own prompt, tool policy, and model routing.

Control and human-in-the-loop

• Suspend and resume. Any tool can pause the whole turn to wait for an async result, an approval, an authentication step, or a long external delay.
• Permissions. An allow/ask/deny rules engine with pattern matching over commands, paths, and domains, and deny rules that are absolute.
• Hooks. Lifecycle interception points from session start through tool gates to the stop decision — deny a call, rewrite its arguments, inject context, or force the loop to continue, including LLM-as-judge variants.
• Cancellation and steering. A running turn can be cancelled or steered through its Invocation without corrupting its state.
• Ask the user. The model itself can ask the user a question mid-task.

Context engineering

• Typed system reminders with authority tiers, so injected guidance is never confused with user content.
• Context injection of documents and guidance before generation or mid-loop.
• Compaction — token-threshold summarization of history, including mid-turn.
• Prompt caching with automatic cache-breakpoint placement, on by default where the provider supports it.

Provider portability

• One interface, many providers. Anthropic, OpenAI, Google, Grok, Mistral, Ollama, and OpenRouter normalize to a single response and content representation, including multimodal input.
• Round-trip state. Thinking signatures, tool call IDs, and tool result formats are normalized, so a Session is not welded to one vendor.
• Common model settings. Reasoning effort, thinking limits, and tool choice configured one way and normalized per model.
• Structured output. Final output produced against a schema you provide.
• Retries. Transient failures are classified and retried with backoff.

Usage and observability

• Usage and attribution. Normalized usage per Invocation, for rebilling and analytics.
• Cost tracking. Token usage including cache and reasoning tokens, priced by a per-model registry. Estimated-cost caps fail closed before a provider call when the registry lacks pricing.
• Tracing. Nested spans for the turn, each model call, and each tool call, with an OpenTelemetry adapter emitting GenAI semantic-convention spans and metrics.

Built to stay out of your way

A harness that installs its own persona, policy, or data model gets in the way of the application it serves. nvoken is designed the other way: agent behavior arrives with each request as the execution spec, tools with side effects run on your side of the boundary, and approval policy, memory, and product state remain yours to shape. The harness supplies the machinery; your application keeps the voice, the rules, and the data.