Agent Harness

The agent harness is a set of safety and reliability services that wrap every sub-agent execution in proto. Most features fire automatically — you configure only the ones that need project-specific setup.

Features at a glance

Doom loop detection

Detects when an agent repeats the same tool-call pattern. A fingerprint is computed from (tool_name, args_hash). If the same fingerprint appears 3+ times in a sliding 20-call window, the harness injects a recovery message.

No configuration required.

Scope lock (sprint contract)

Before starting a bounded implementation task, an agent (or a user-supplied skill) constructs a sprint contract — the set of files that may be written. Activating a contract arms a glob-based scope lock; any write outside the permitted set is blocked with a structured error naming the violating path and the permitted set.

The contract is persisted to .proto/sprint-contract.json and automatically restored on session restart.

Note: The fork previously bundled a prescriptive sprint-contract skill that walked the agent through negotiating one. It was removed alongside the rest of the “superpowers” workflow skills so consumers can choose their own choreography. The underlying primitive (packages/core/src/services/sprintContractService.ts) is unchanged — drop in your own skill or call SprintContractService directly when you want this gate.

File format

{
  "allowedPaths": ["src/auth/", "tests/auth/"],
  "activatedAt": "2026-04-07T14:00:00.000Z"
}

Git checkpoints

Before every file-mutating tool call (write_file, edit), the harness commits the current project state to a shadow repository at ~/.proto/history/<project_hash>.

Inspect or restore:

git -C ~/.proto/history/<project_hash> log --oneline
git -C ~/.proto/history/<project_hash> show <hash>:path/to/file > path/to/file

No configuration required.

Observation masking

When the context window grows large during a long agent run, the harness summarizes old tool-call/result pairs as [OBSERVATION_MASK: N pairs omitted] while keeping the most recent exchanges verbatim. Prevents context overflow without losing work history.

No configuration required.

Reactive compression

Compression normally runs proactively — before a turn is sent, once history crosses a token threshold. Estimates can still be wrong (a tool returns far more than expected, or a provider counts tokens differently), so the harness also compresses reactively: if a provider rejects a request because the prompt exceeds the context window, the harness force-compresses the live history once and retries the same request automatically.

Context-overflow rejections are classified provider-agnostically (distinguished from superficially-similar timeouts, which are not compressed). The reactive retry fires at most once per request — if the prompt is still too large after compression, the original error surfaces rather than looping.

No configuration required.

Repo map

repo_map is a tool available to agents that builds a PageRank-ranked map of the most relevant source files in the repository, using the import graph and optionally seed files to personalize results.

The Explore and plan agents use it automatically at the start of tasks on large codebases. Any agent can call it explicitly.

Results are cached at .proto/repo-map-cache.json.

Behavior verification gate

Run automatic post-task verification scenarios after a sub-agent completes successfully. If any scenario fails, the failure is fed back to the agent for self-correction.

Create .proto/verify-scenarios.json:

[
  {
    "name": "Unit tests pass",
    "command": "npm test -- --run",
    "timeoutMs": 60000
  },
  {
    "name": "Build succeeds",
    "command": "npm run build",
    "timeoutMs": 30000
  }
]

Scenarios run in parallel. Each has:

Exit code 0 = pass (when no expectedPattern).

Multi-sample retry

For high-stakes tasks where a single failed attempt is costly, set multi_sample: true on an Agent tool call. The harness retries up to 2 more times with escalating temperatures (0.7 → 1.0 → 1.3) if the first attempt fails.

Each retry receives a [RETRY CONTEXT] block summarizing what went wrong.

Scoring

The highest-scoring attempt is returned. Ties go to the lower-temperature (earlier) attempt.

Use for: complex implementation tasks. Do not use for: searches, read-only queries.