Default Harness

Purpose and Scope

The default harness is the out-of-the-box runtime shape that every eve agent receives before an application author adds project-specific capabilities. It contains the framework-owned agent loop and built-in tool descriptors, so a newly scaffolded agent can reason, inspect files, run commands, fetch context, and continue a durable conversation without requiring those primitives to be authored as local tools. Treat the harness as the baseline operating environment: your instructions, authored tools, skills, sandbox configuration, channels, and schedules extend it rather than replacing it by default.

Sources: docs/concepts/default-harness.md

The harness page deliberately separates built-in runtime behavior from the deeper execution model. The default harness explains what ships with the agent and how it protects long-running sessions from context-window exhaustion. The mechanics of how a turn checkpoints, resumes, or restarts belong to the execution model and durability documentation. This distinction matters when debugging: if a tool descriptor appears automatically, that is harness behavior; if a run resumes after interruption, that is durable execution behavior supported by the broader runtime.

Sources: docs/concepts/default-harness.md

Relevant Source Files

• docs/concepts/default-harness.md - First-party concept documentation for the default harness, including compaction behavior, the built-in tools visible to every agent, and the runtime locations where those tools execute.

System-to-Code Mapping

The user-facing contract is configured through normal agent configuration rather than through a separate harness object. For example, compaction is tuned under compaction in agent.ts, while the built-in tools are simply present for every agent with no import. That means most projects should begin by authoring domain behavior in conventional files and only adjust harness settings when the default behavior is too eager, too late, or inappropriate for the agent’s expected session length.

Sources: docs/concepts/default-harness.md

The default tool set is presented to the model as descriptors before any tool executes. Discovery is descriptive, not effectful: the harness shows the available tool interfaces, then runs only the calls the model actually emits. This is important for safe mental modeling because listing tools does not read files, run shell commands, fetch URLs, or mutate workspace state. Effects occur only after the model selects a specific tool call and the harness dispatches it to the correct runtime location.

Sources: docs/concepts/default-harness.md

The harness also defines a practical split between the app runtime and the sandbox. Shell and file-oriented tools run through the app runtime but proxy their work into the agent’s single sandbox, so their effects land in the sandboxed filesystem or process environment. Other visible tools, such as web fetching and web search, run in the app runtime. When investigating a surprising side effect, ask both which tool was called and where its effect lands, because the table’s “Where it runs” column is part of the contract.

Sources: docs/concepts/default-harness.md

Compaction Behavior

Compaction is the harness feature that keeps long sessions from exceeding the model’s context window. Once the conversation crosses a configured fraction of that window, controlled by thresholdPercent, the harness summarizes older turns into a compact representation and continues the session. The documented default threshold is 0.9, which means compaction waits until the conversation is close to the limit unless the agent configuration lowers the threshold. The summary uses the active turn model unless the agent config overrides that behavior.

Sources: docs/concepts/default-harness.md

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  compaction: {
    thresholdPercent: 0.75,
  },
});

Lowering the threshold is useful for agents that perform long investigations, use large tool outputs, or maintain many intermediate turns. A value such as 0.75 makes the harness summarize earlier, trading some detail for more headroom in later reasoning. Raising or leaving the default can be appropriate for short conversations or agents where retaining raw history longer is more valuable. The key is that compaction is not an authored skill or tool; it is harness behavior configured through the agent.

Sources: docs/concepts/default-harness.md

Compaction also preserves framework-owned tool state. The documentation calls out two important details: read-before-write tracking is reset, and the active todo list is re-injected after summarization. Resetting read-before-write tracking prevents a later write from relying on file evidence that has been summarized away; the next write must re-read the relevant file. Re-injecting the todo list lets the model keep its task plan across the compacted history, which helps long-running work stay coherent after older turns are summarized.

Sources: docs/concepts/default-harness.md

There is no per-tool compaction hook to configure. Developers should therefore design around the framework-level compaction behavior instead of expecting each built-in or authored tool to preserve its own private state during summarization. If an agent needs information to survive compaction, store it in durable project-visible state, in the conversation’s current task plan, or in outputs that can be re-read. For file edits in particular, expect the harness to favor fresh read evidence after a summary.

Sources: docs/concepts/default-harness.md

Built-in Tools

The built-in tools ship with every agent and require no imports. The visible documented set includes shell execution, file reading and writing, globbing, grep search, web fetching, and web search. These tools provide a minimum operational vocabulary for agents that inspect repositories, edit files, run commands, and collect external context. Project-authored tools should add domain-specific capabilities, not duplicate this baseline unless there is a reason to enforce different validation, authorization, or side-effect behavior.

Sources: docs/concepts/default-harness.md

The file tools are intentionally stateful from the model’s perspective. read_file produces line-numbered evidence, and write_file enforces read-before-write and stale-read detection. That means file mutation is not just a raw write primitive; it is guarded by evidence that the agent has recently inspected the target. This behavior pairs with compaction’s reset of read-before-write tracking: after old file evidence is summarized away, the harness requires a fresh read before allowing a write that depends on that context.

Sources: docs/concepts/default-harness.md

Implementation Details and Developer Guidance

For day-to-day agent authoring, the safest path is to accept the default harness and focus on the agent’s unique behavior. Put durable instructions in the agent instructions file, add typed domain tools only when the model needs capabilities beyond the built-ins, and tune compaction when real sessions show that the default threshold is not a good fit. The harness is designed to make the first version useful without boilerplate while still leaving room for explicit configuration as the workload becomes clearer.

Sources: docs/concepts/default-harness.md

When troubleshooting, separate descriptor visibility from tool execution. If the model sees bash, read_file, or web_fetch, that is expected because the harness exposes built-in descriptors to every agent. If a command ran, a file changed, or a URL was fetched, look for the actual tool call in the run rather than assuming discovery caused the effect. This distinction helps teams reason about safety reviews, logs, approvals, and sandbox boundaries without confusing available capabilities with executed actions.

Sources: docs/concepts/default-harness.md

Next Steps

Read the execution model and durability material next when you need to understand how turns checkpoint and resume. Read the sandbox material when you need to reason about where shell and filesystem effects land. Read agent configuration when tuning compaction, especially thresholdPercent and any model override for summaries. Finally, review tools and approvals before adding sensitive domain tools, because the harness gives you baseline capabilities but your authored tools define the application-specific side effects the agent can perform.