Connecting an external agent¶
An agent is connected in one of two ways:
- a built-in adapter (since 2.0) for Claude Code, Codex, Gemini CLI or Aider: the harness runs the agent CLI itself in its non-interactive mode, renders the task as a prompt and reads the CLI's own output, including the tokens and cost it reports (see built-in adapters);
- the command provider: a program that the harness launches in the
IMPLEMENTATIONphase, sends the task and plan as JSON on standard input, and reads one JSON result from standard output. Anything that can be wrapped in such a program can be governed.
The harness calls no model API itself.
The provider only proposes a change. It never evaluates or approves it: verification, independent review, the gate and the human decision stay with the harness.
Register the provider¶
In .harness/project.yaml:
agentProvider: local_wrapper # default provider for `harness run start`
agentProviders:
local_wrapper:
kind: command
command: [python, examples/structured-command-agent.py]
model: deterministic-example # label recorded on the agent invocation
harness run start --task <id> --provider local_wrapper selects it explicitly. The first element
of command must be allowed by a process.execute capability (the Python profile allows
python, the Node.js profile npm and node); add a grant in capabilities.grants for anything
else, or, under governance.phaseCapabilities (which harness init writes and where
capabilities.grants only narrows the profiles), in capabilities.extend. A provider command no
grant allows is refused before it starts: under governance.phaseCapabilities the run records a
HIGH capabilities.command-denied finding and stops BLOCKED (exit 6), and
harness config validate warns about it beforehand. The process runs with cwd set to the
workspace, without a shell, with the runtime.commandTimeoutSeconds timeout and the
runtime.maxOutputBytes output bound.
Built-in adapters¶
agentProvider: claude
agentProviders:
claude:
kind: claude-code # or codex, gemini-cli, aider
model: claude-sonnet-4-5 # passed as --model and recorded on the invocation
passEnv: [ANTHROPIC_API_KEY, HTTPS_PROXY]
capabilities:
grants: []
extend: # added to the profiles with or without phaseCapabilities
- capability: process.execute
scope: [claude]
kind |
Runs (before args) |
Prompt | Reads |
|---|---|---|---|
claude-code |
claude -p --output-format json --permission-mode acceptEdits |
standard input | result, is_error, subtype, session_id, usage (input tokens are input, cache-creation and cache-read tokens; the cache reads are also kept as cacheReadTokens), total_cost_usd |
codex |
codex exec --json --full-auto --skip-git-repo-check - |
standard input | JSON events: the last agent_message, turn.completed usage (no cost), turn.failed or error, the thread_id |
gemini-cli |
gemini --output-format json --approval-mode auto_edit --prompt <a pointer to standard input> |
standard input | response, error, stats.models.*.tokens (prompt, candidates, thoughts, cached as cache reads; no cost) |
aider |
aider --yes-always --no-auto-commits --no-dirty-commits --no-stream --no-pretty --no-gitignore --no-check-update --analytics-disable, history files in the null device, --message <prompt> |
command line (recorded as <prompt>) |
the Tokens: … sent, … received. Cost: $… message, $… session. lines (counts above 1,000 are printed rounded) |
command replaces the executable (for example [npx, -y, "@anthropic-ai/claude-code"] or a
wrapper script); args adds arguments after the adapter's own, such as --allowedTools for
Claude Code. The first element of the command needs a process.execute grant, as for any
provider. The adapters run under the same sandbox, capability grant, timeout, output bound and
transient-failure retries as a command provider, and a failed call's summary carries the end of
its standard error.
A read-only request (readOnly: true: clarify, plan, acceptance, locate, architecture,
review and the reviewers of the panel) runs without the arguments that let the agent edit
(#92). In the wave 9 pilot a clarify call ran with --permission-mode acceptEdits, answered
and also wrote a test file. The request already said it was read-only; the adapters now enforce
it with what each CLI offers:
kind |
A read-only call runs (before args) |
What it gives |
|---|---|---|
claude-code |
claude -p --output-format json --permission-mode default --allowedTools Read,Grep,Glob --disallowedTools Write Edit MultiEdit NotebookEdit Bash |
No tool that writes a file and no shell. A reviewer of the panel keeps its own tool allowlist without those five. |
codex |
codex exec --json --sandbox read-only --skip-git-repo-check - |
Codex's read-only sandbox. |
gemini-cli |
gemini --output-format json --approval-mode default |
No approval of edits: the non-interactive CLI leaves out the tools that would ask (write, edit, shell). A limitation: the adapter passes no tool allowlist. |
aider |
the arguments above plus --chat-mode ask --dry-run --no-suggest-shell-commands |
A limitation: aider has no read-only sandbox; these arguments ask it to answer without editing files or running commands. |
These arguments follow each CLI's documentation and are tested against fake CLIs, not against
the live agents. They do not replace the check of the harness: the workspace is compared before
and after every read-only call, a call that changed it is undone and gets a HIGH
agent.read-only-violation finding, and under runtime.contractRetry it is sent once more (see
a second attempt for a broken answer).
An implement call keeps the arguments of the first table. This is a fix of the adapters, which
did not honour the request; it applies always, with no new key.
The prompt holds the task (title, intent, requirements, acceptance criteria, constraints, the
files it owns or the patches it describes), the plan, the governed memory selected for the run, the
feedback block of a correction attempt (gate, findings with their location, the end of the
failing validators' output and a reviewer's rationale) and, under provenance.selfReport, the
request for a self-report. The prompt digest recorded on the invocation is the digest of the same
request a command provider would receive.
The command lines follow each CLI's documentation. They are covered by tests with fake CLIs that
print each documented output format (tests/integration/test_native_adapters.py); they have not
been run against the live agents in this repository. Codex has its own sandbox: under
runtime.agentSandbox: enforce on macOS a sandbox inside sandbox-exec may be refused by the
operating system (not verified); args: [--sandbox, danger-full-access] leaves confinement to the
harness's sandbox.
Environment and secrets¶
The process runner gives a provider only PATH, HOME, SYSTEMROOT, TMPDIR, TEMP, LANG
and LC_ALL. A provider declares what else it receives:
agentProviders:
claude:
kind: claude-code
passEnv: [HTTPS_PROXY, SSL_CERT_FILE] # passed as they are, when set
env:
ANTHROPIC_API_KEY: {fromEnv: HARNESS_ANTHROPIC_KEY} # read when the provider starts
CLAUDE_CODE_MAX_OUTPUT_TOKENS: "16000" # a literal value
A fromEnv variable that is not set stops IMPLEMENTATION (BLOCKED) before the provider starts,
instead of running the agent without its credentials. Only the names are recorded (evidence and an
agent.environment.applied event). Every value that comes from the environment (passEnv and
fromEnv, of every configured provider and of the project validators' passEnv) of at least 8
characters is redacted from every stored artifact and from the agent's summary as
<REDACTED_ENV>; shorter values are not, so that a value such as 1 does not erase every
occurrence in an output. With runtime.extendedRedaction the stored artifacts are also cleaned of
model-API keys, Slack tokens, JSON Web Tokens and passwords in URLs.
Write confinement¶
A project created by harness init has runtime.agentSandbox: enforce: on macOS the provider runs
under sandbox-exec and on Linux under bwrap, and the operating system denies its writes outside
the workspace, $TMPDIR and runtime.sandboxWritePaths. Reads, network and process execution are
not restricted. On a host without a mechanism (Linux without bubblewrap, Windows) IMPLEMENTATION
is BLOCKED with a sandbox.unavailable finding instead of running the agent unconfined. Details,
the default write paths and the recorded evidence: agent sandbox.
With a provider that writes outside the workspace, harness run start on macOS exited with 6, the
run was FAILED in IMPLEMENTATION, the file was not created and the run had the finding
sandbox.write-denied MEDIUM The agent sandbox denied a write: /Users/<user>/harness-cli-escape.txt.
Claude Code 2.1.287 was run directly (not through the harness) under the profile the harness builds
from the init defaults, on macOS 15 with the user's own login:
sandbox-exec -p <profile> claude -p "Create a file hello.txt containing hi in the current
directory, then reply done." --model claude-haiku-4-5-20251001 --output-format json
--permission-mode acceptEdits --tools Write,Read --no-session-persistence exited with 0
("subtype":"success", "result":"done") and created hello.txt. Asked to write to a file in the
home directory (with --add-dir on the home directory, so that Claude Code's own permission check
allowed it), its Write tool failed with EPERM: operation not permitted and no file was created.
The protocol¶
Request (stdin), one JSON document:
{
"schemaVersion": "1.0",
"task": { "task_id": "…", "title": "…", "intent": "…", "requirements": [], "acceptance_criteria": [],
"constraints": [], "implementation": {"mode": "…", "patches": []}, "metadata": {} },
"plan": { "…": "the recorded plan: steps, capabilities, expected evidence" }
}
The task and plan are serialized with the model field names (snake_case). When the project has
governed memory that applies to the run, the request also carries context, with the selected
records and their digest ({"records": [...], "digest": "sha256:…"}); a run without memory sends
no context key. See memory and retrospective decisions.
When runtime.providerFeedback is true (written by harness init), the attempt that follows a
failed VERIFICATION (see runtime.verificationCorrections) or a REQUEST_CHANGES decision also
carries feedback: why the previous attempt was not accepted. Its contract is
schemas/v1/provider-feedback.schema.json; unlike the task and plan it uses camelCase names.
This one was sent by the fixture agent of tests/integration/test_verification_corrections.py,
whose first attempt left apply_discount unchanged (abridged: a python.ruff finding and the
start of the pytest output are left out):
"feedback": {
"schemaVersion": "1.0",
"attempt": 2,
"trigger": "VERIFICATION_FAILED",
"changeSetDigest": "sha256:70dccacdd7bf806dd7f315a6386f90f966f1a431557e70030fed13a832c576d8",
"gate": {"gateId": "verification", "gateEvaluationId": null, "status": "FAILED",
"reasonCodes": ["python.pytest_FAILED"]},
"findings": [
{"ruleId": "python.pytest.failed", "severity": "HIGH", "validatorId": "python.pytest",
"location": {"path": null, "startLine": null, "endLine": null},
"message": "python.pytest failed with exit code 1"},
{"ruleId": "agent.unsupported-claim", "severity": "MEDIUM", "validatorId": "harness.claim-check",
"location": null,
"message": "The agent reported PASSED ('Implemented the threshold discount') but verification failed: python.pytest FAILED"}
],
"omittedFindings": 0,
"validators": [{"validatorId": "python.pytest", "status": "FAILED", "exitCode": 1,
"summary": "python.pytest failed with exit code 1",
"stdout": "…E assert 100 == 90\nE + where 100 = apply_discount(100, 100, 0.1)\n\ntests/test_pricing.py:4: AssertionError\n…FAILED tests/test_pricing.py::test_at_threshold - assert 100 == 90\n1 failed in 0.01s\n",
"stderr": "", "stdoutTruncated": false, "stderrTruncated": false}],
"decision": null
}
| Field | Content |
|---|---|
attempt |
Number of the IMPLEMENTATION attempt that receives the request (2 or more). |
trigger |
VERIFICATION_FAILED (automatic correction) or CHANGES_REQUESTED (human decision). |
gate |
For VERIFICATION_FAILED, the verification status and one reason code per failing mandatory validator (<validatorId>_<STATUS>); for CHANGES_REQUESTED, the delivery_candidate gate the person decided on, with its id, status and reason codes. |
findings |
Up to 20 findings, most severe first: rule, severity, validator, location and message (at most 1,000 characters). omittedFindings counts the rest. |
validators |
Each failing mandatory validator with the end of its redacted stdout and stderr: at most 4,000 characters per stream and 16,000 for all streams together; *Truncated says that something was cut. |
decision |
After REQUEST_CHANGES: the decision, the rationale (at most 4,000 characters) and the actor id; otherwise null. |
The first attempt of a run, and every request of a project without the setting, has no
feedback key, so the request and its prompt digest are the same as before.
Response (stdout): the whole standard output must be one JSON object, and the process must exit with 0:
{"status": "PASSED", "summary": "Structured patches applied"}
| Field | Values |
|---|---|
status |
PASSED, FAILED or BLOCKED |
summary |
optional text recorded on the agent invocation |
usage |
optional object with any of inputTokens, outputTokens, reasoningTokens, cacheTokens (non-negative integers; cacheTokens, since 2.0, is the part of inputTokens read from or written to a prompt cache; cacheReadTokens, since 2.0, is the part of cacheTokens read from it, which the agent contract's token budget does not count) and costUsd (non-negative number), as reported by the agent |
When usage is present it is stored as a ResourceUsage record of quality REPORTED and summed
into the metrics tokens.* and cost.usd. The harness records what the provider reports and
never estimates it; an empty object, an unknown field or a negative value is a PROTOCOL_ERROR.
Anything else on standard output (logs, progress) breaks the protocol and the invocation is
recorded as ERROR (PROTOCOL_ERROR). Write diagnostics to standard error; both streams are stored
as redacted artifacts. A non-zero exit code is recorded with the process status without parsing
the output.
A call that does not pass with a transient cause (a network, overload, rate-limit or usage-limit
message on standard error or in the JSON result) is repeated with the same request when
runtime.providerRetries is set; a process killed at the timeout is not. If the agent answers
PASSED and the verification of its change fails, the run records an agent.unsupported-claim
finding. See provider feedback loop.
Request kinds (protocol 1.1)¶
With the agent-results settings that harness init writes, the provider also receives
read-only requests of kind clarify, acceptance, plan, review and (since #55)
locate, and the implement request may carry gate, permissions, routing, budget,
contextFiles, lessons, acceptanceTests, locations and attachments. An adapter that speaks only the 1.0 protocol treats every request as an
implementation: on a read-only request it changes the workspace, the harness undoes the change
and blocks the phase. Read kind (absent means implement), answer the read-only kinds with a
result object and apply routing.flags to your CLI if you want the router's model and effort.
The kinds, results and keys are described in better agent results.
Declare what the agent may change¶
The ChangeSet is what a person approves, so declare the files the task owns:
implementation.mode: patchwithpatches: the patch paths are owned (the bundled example agent applies exactly these patches).- Otherwise,
metadata.ownedPaths: a list of exact relative paths. - With neither, every file that changes during the run is part of the ChangeSet.
metadata:
ownedPaths: [src/pricing/__init__.py, tests/test_pricing.py]
Verified example¶
examples/structured-command-agent.py applies the task's structured patches and answers
{"status": "PASSED", …}. Registered as above on the greenfield project of the
greenfield guide, harness run start --task task_discount_rule exited with 4,
the gate was PASSED (ALL_MANDATORY_VALIDATIONS_PASSED), the run recorded one agent invocation
with the model label, and the ChangeSet contained the two owned files.
Wrapping an agent CLI (template, not tested against a live agent)¶
The following wrapper shows the shape of an adapter for an agent CLI such as Claude Code or Codex.
It has not been run against a real agent in this repository; adapt the command line to the
agent's documented non-interactive mode and review its permission settings. Remember that the
harness is not a full sandbox: with agentSandbox: enforce the agent cannot write outside the
allowed paths, but it reads, connects and runs programs with your user's permissions.
#!/usr/bin/env python3
"""Adapter: harness command-provider protocol -> an agent CLI (template)."""
import json
import os
import shlex
import subprocess
import sys
request = json.load(sys.stdin)
task = request["task"]
criteria = "\n".join(f"- {item['text']}" for item in task["acceptance_criteria"])
owned = task.get("metadata", {}).get("ownedPaths", [])
prompt = (
f"{task['title']}\n\n{task['intent']}\n\nAcceptance criteria:\n{criteria}\n\n"
f"Only modify these files: {', '.join(owned)}. Do not commit."
)
# AGENT_COMMAND is the agent's non-interactive invocation, for example the documented
# 'print' or 'exec' mode of your agent CLI; the prompt is appended as the last argument.
# The provider receives it through passEnv (see below).
command = shlex.split(os.environ["AGENT_COMMAND"]) + [prompt]
result = subprocess.run(command, capture_output=True, text=True)
sys.stderr.write(result.stdout + result.stderr) # keep stdout for the protocol only
status = "PASSED" if result.returncode == 0 else "FAILED"
print(json.dumps({"status": status, "summary": f"agent exited with {result.returncode}"}))
Register it and declare the variables it reads; before 2.0 the guide said to set
AGENT_COMMAND in the environment of the harness process, but the provider only received
PATH, HOME, LANG and TMPDIR, and the wrapper failed with KeyError: 'AGENT_COMMAND':
agentProviders:
wrapped:
kind: command
command: [python, tools/agent_adapter.py]
passEnv: [AGENT_COMMAND, ANTHROPIC_API_KEY]
For Claude Code, Codex, Gemini CLI and Aider a built-in adapter replaces
the wrapper. If the agent CLI reports its token and cost usage, forward it in usage; otherwise the
metrics tokens.* and cost.usd stay NOT_AVAILABLE (see metrics). Under
provenance.selfReport the request also carries selfReport, and the response may answer
selfReport with assumptions, alternativesDiscarded (lists of text), lowConfidenceAreas and
unrequestedChanges (lists of {path, description}); it is stored as REPORTED data and a
malformed one is recorded with its problems, never as a protocol error. Under
verification.acceptanceTests.disputes the report may also carry disputedAcceptanceTests, a
list of {test, reason} for frozen acceptance tests the agent believes are wrong (see
write protection and disputes).
External plugins¶
Separately from agent providers, src/governed_harness/plugins defines a versioned one-request,
one-response JSON protocol for out-of-process extensions (harness plugins list shows the built-in
extensions and the protocol version 1.0). It is implemented and tested as a contract; the
built-in profiles use internal validators, so external plugins are not yet part of the main run.