| name | add-harness |
| description | Playbook for adding a new coding-agent harness to Agenta (Codex, Hermes, Gemini, OpenCode, ...). Use when starting, planning, or reviewing a new-harness project. Covers the readiness audit of prior art, the spike-first milestone plan, the full integration-surface checklist, the per-harness variance axes to probe, and the process/communication contract with Mahmoud. Living document: every harness project appends its lessons to resources/LESSONS.md. |
Add a harness to Agenta
A harness is the coding-agent program Agenta runs on behalf of a user (Pi, Claude
Code, Codex, ...). This skill encodes how we add one: what to build, in what order,
what to probe empirically first, and how to run the project so Mahmoud can steer it.
It was extracted from the Codex harness project (2026-07, docs/design/codex-harness/
in that project's worktree) and grows with every subsequent harness.
Read resources/LESSONS.md after this file: it is the append-only log of things that
surprised us, per harness. If you are about to start a new harness project, the
combination of this file plus the lessons log IS the project template.
Step 0: audit prior art before writing anything
If a draft PR or old branch exists for this harness, do a readiness audit first and
assume salvage, not rebase. Judge it on five axes: permissions, human-in-the-loop
approvals, Agenta tool delivery, event/streaming protocol, auth modes. Then measure
rebase distance not in commits but in structure: have the files it touches been
split, renamed, or re-contracted on main? (The Codex drafts were 1,450 commits behind
and their central wiring file had been exploded into eleven modules; the SDK adapter
skeleton survived, everything else was rewritten.) Deliver the audit as a
salvage/rewrite/discard table before proposing a plan.
Step 1: check what the daemon already does
The runner executes harnesses through the pinned sandbox-agent npm daemon, which
spawns each harness behind an ACP (Agent Client Protocol) bridge. Before assuming you
must build a runtime: read the daemon's embedded adapter registry (in the pinned
package under services/runner/node_modules/sandbox-agent, plus the repo's patch
file) for the harness name, the bridge package it maps to, the credential probe it
runs, and its embedded model default. For Codex the daemon already knew how to
install the CLI and bridge; the whole project was config, credentials, permissions,
and approvals plumbing. If the daemon does NOT support the harness, that is a
different, much larger project (a daemon/bridge contribution) and the plan must say
so explicitly.
Step 2: spike before design (Checkpoint 1 gate)
Run a throwaway spike against the real daemon before writing production code. The
four standard questions, refined per harness:
- Approvals shape. Does the harness's ACP bridge raise permission requests?
Under which of the harness's native permission settings? Record the exact frame
shape; the runner classifies approval gates per harness in a closed union
(
acp-interactions.ts), so a new gate type needs the real frames.
- Config split. Where does the harness read its config? Can its home/config
directory variable separate login state (mounted, read-write) from per-run config
(rendered fresh)? This decides the mount layout, which is a Mahmoud decision.
- Tool delivery. Can the runner's internal
agenta-tools MCP server reach the
harness, over which channel (ACP session params vs config file), and can specific
tools be pre-allowed/denied natively (the F-046 question: an "allow" tool must run
without pausing)?
- Auth mechanisms, enumerated from source. Do NOT probe a candidate list of
credential forms and stop at the first that works; that satisficing locked the
Codex project into a file-based design for three milestones while a file-free
mechanism sat one function away. Instead: find the harness's credential
RESOLUTION/PRECEDENCE function in its source at the pinned version and read it
top to bottom; precedence functions are small and enumerate the whole mechanism
space by construction. Table every branch (env-at-request-time, files, stores,
login flows), then probe the promising ones through the daemon path. The same
rule applies to any capability that shapes a design: config delivery, state
location, continuity. Also determine what the subscription sidecar must produce.
Everything unverified in the design stays marked "TO VERIFY IN SPIKE" until the spike
answers it with a saved transcript. The spike ends in a findings memo plus a decision
register, and the project stops at Checkpoint 1: Mahmoud rules on the mount
layout, the human-in-the-loop posture, and the handling of anything the harness
cannot express, before milestones that depend on those answers start.
The integration surface (what every harness touches)
SDK (sdks/python/agenta/sdk/agents/):
HarnessType value, identity entry, supported_harnesses.- An adapter class in
adapters/harnesses.py mirroring ClaudeHarness
(_to_harness_config, drop-with-warning for Pi builtins).
- A
<harness>_settings.py sibling of claude_settings.py when the harness takes a
config file: author's harness-native options pass through verbatim (Layer 1), plus
derived reinforcement rules from the sandbox boundary (Layer 2) and per-MCP-server
and per-tool permissions (Layer 3). We never invent an Agenta-abstract permission
vocabulary; authors write the harness's own settings.
capabilities.py entry, curated model-catalog JSON under agents/data/, provider
family mapping, PI_SUBSCRIPTION_MODELS interplay if the provider overlaps Pi.- Golden wire fixture plus contract tests (Python side).
Runner (services/runner/src/engines/sandbox_agent/):
run-plan.ts: acpAgent mapping (often a passthrough already), the api-key env var
name, the subscription mount variable branch, the Daytona-plus-subscription
rejection (subscription state never ships to a third-party sandbox).environment-setup.ts: local credential/asset preparation (create-if-absent,
restrictive modes, delete-only-if-created).daemon.ts: provider env var group (least-privilege set).- Approvals: a gate type in the
ParkedApprovalGateType union, classification for
the harness's frames, park/resume tests mirroring Claude's.
- Harness files: rendered by the SDK, written blind by
prepareWorkspace.
- Contract tests (TypeScript side) against the same golden fixture.
Platform edges:
- Subscription sidecar login support for the provider.
- A cell in the agent release gate.
- Docs kept in sync in the same PR train (
keep-docs-in-sync).
Variance axes (what actually differs between harnesses)
Judge similarity on these, not on gut feel. Pi was expensive because it fails most of
them; Codex was cheap because it fails only the permission-vocabulary one.
- Protocol path: behind the shared ACP daemon (cheap) vs native protocol (expensive).
- Permission vocabulary: fine-grained per-tool rules (Claude) vs coarse global modes
(Codex). Coarse vocabularies raise expressibility questions that go to the
decision register, never get silently approximated.
- Config layout: separate login dir and project config (Claude) vs one directory for
both (Codex). One-directory harnesses make the mount layout a real design.
- Auth forms: env var vs credential file vs OAuth tokens, and whether the
subscription sidecar already speaks the provider's OAuth.
- Tool-delivery channel and native pre-allow support (the F-046 question).
Process (how the project runs)
- One worktree per harness with its own deployment. Ports: pick a free Traefik/
Postgres pair (
deploy-worktree-testing skill has the table), unique compose
project name. Fresh-worktree gotchas so far: chmod -R o+w web/ee/public web/oss/public before the web container will boot; the repo gitignore is
allowlist-style for .env* so worktree .env files are safe for keys.
- Bootstrap through the UI as the first act (signup, project, API key into the
worktree
.env): it doubles as a smoke test of main and catches UI regressions
free of charge.
- Design workspace per
plan-feature (research.md, spike/findings.md, design.md,
decisions.md, plan.md, status.md, reports/). The decision register is the no-
implicit-decisions mechanism: anything that is not an obvious copy of an existing
harness pattern is proposed there and waits.
- Vertical slices in this order: managed-key text-only run, Agenta tools, permissions
plus human-in-the-loop, subscription auth, Daytona plus docs plus release gate.
Risk always moves to the earliest slice that can kill it.
- Implementation via Codex (gpt5.6-sol), review via Opus, then desloppify and
/simplify, after every milestone. Code quality bar: the adapter must read like
the Claude adapter it sits next to.
- Every milestone ends with a written report for Mahmoud (
reports/), live QA in the
worktree deployment, and a recording when the milestone has a visible behavior.
Merging is always Mahmoud's action.
Communication contract (learned, do not relearn)
- Reports lead with what works now and what he can click; evidence follows.
- Decision asks give context, then options with trade-offs, then a recommendation
with the reason. One checkpoint per project phase beats scattered questions.
- Never present a degraded behavior (something the harness cannot express) as done;
present it as a register entry with options.
- Full sentences, no fragments, no internal codenames without a plain-language
explanation, no em dashes.
