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.
1---2name: add-harness3description: Add a harness to Agenta4---56# Add a harness to Agenta78A harness is the coding-agent program Agenta runs on behalf of a user (Pi, Claude9Code, Codex, ...). This skill encodes how we add one: what to build, in what order,10what to probe empirically first, and how to run the project so Mahmoud can steer it.11It was extracted from the Codex harness project (2026-07, `docs/design/codex-harness/`12in that project's worktree) and grows with every subsequent harness.1314Read `resources/LESSONS.md` after this file: it is the append-only log of things that15surprised us, per harness. If you are about to start a new harness project, the16combination of this file plus the lessons log IS the project template.1718## Step 0: audit prior art before writing anything1920If a draft PR or old branch exists for this harness, do a readiness audit first and21assume salvage, not rebase. Judge it on five axes: permissions, human-in-the-loop22approvals, Agenta tool delivery, event/streaming protocol, auth modes. Then measure23rebase distance not in commits but in structure: have the files it touches been24split, renamed, or re-contracted on main? (The Codex drafts were 1,450 commits behind25and their central wiring file had been exploded into eleven modules; the SDK adapter26skeleton survived, everything else was rewritten.) Deliver the audit as a27salvage/rewrite/discard table before proposing a plan.2829## Step 1: check what the daemon already does3031The runner executes harnesses through the pinned `sandbox-agent` npm daemon, which32spawns each harness behind an ACP (Agent Client Protocol) bridge. Before assuming you33must build a runtime: read the daemon's embedded adapter registry (in the pinned34package under `services/runner/node_modules/sandbox-agent`, plus the repo's patch35file) for the harness name, the bridge package it maps to, the credential probe it36runs, and its embedded model default. For Codex the daemon already knew how to37install the CLI and bridge; the whole project was config, credentials, permissions,38and approvals plumbing. If the daemon does NOT support the harness, that is a39different, much larger project (a daemon/bridge contribution) and the plan must say40so explicitly.4142## Step 2: spike before design (Checkpoint 1 gate)4344Run a throwaway spike against the real daemon before writing production code. The45four standard questions, refined per harness:46471. **Approvals shape.** Does the harness's ACP bridge raise permission requests?48 Under which of the harness's native permission settings? Record the exact frame49 shape; the runner classifies approval gates per harness in a closed union50 (`acp-interactions.ts`), so a new gate type needs the real frames.512. **Config split.** Where does the harness read its config? Can its home/config52 directory variable separate login state (mounted, read-write) from per-run config53 (rendered fresh)? This decides the mount layout, which is a Mahmoud decision.543. **Tool delivery.** Can the runner's internal `agenta-tools` MCP server reach the55 harness, over which channel (ACP session params vs config file), and can specific56 tools be pre-allowed/denied natively (the F-046 question: an "allow" tool must run57 without pausing)?584. **Auth mechanisms, enumerated from source.** Do NOT probe a candidate list of59 credential forms and stop at the first that works; that satisficing locked the60 Codex project into a file-based design for three milestones while a file-free61 mechanism sat one function away. Instead: find the harness's credential62 RESOLUTION/PRECEDENCE function in its source at the pinned version and read it63 top to bottom; precedence functions are small and enumerate the whole mechanism64 space by construction. Table every branch (env-at-request-time, files, stores,65 login flows), then probe the promising ones through the daemon path. The same66 rule applies to any capability that shapes a design: config delivery, state67 location, continuity. Also determine what the subscription sidecar must produce.6869Everything unverified in the design stays marked "TO VERIFY IN SPIKE" until the spike70answers it with a saved transcript. The spike ends in a findings memo plus a decision71register, and the project stops at **Checkpoint 1**: Mahmoud rules on the mount72layout, the human-in-the-loop posture, and the handling of anything the harness73cannot express, before milestones that depend on those answers start.7475## The integration surface (what every harness touches)7677SDK (`sdks/python/agenta/sdk/agents/`):78- `HarnessType` value, identity entry, `supported_harnesses`.79- An adapter class in `adapters/harnesses.py` mirroring `ClaudeHarness`80 (`_to_harness_config`, drop-with-warning for Pi builtins).81- A `<harness>_settings.py` sibling of `claude_settings.py` when the harness takes a82 config file: author's harness-native options pass through verbatim (Layer 1), plus83 derived reinforcement rules from the sandbox boundary (Layer 2) and per-MCP-server84 and per-tool permissions (Layer 3). We never invent an Agenta-abstract permission85 vocabulary; authors write the harness's own settings.86- `capabilities.py` entry, curated model-catalog JSON under `agents/data/`, provider87 family mapping, `PI_SUBSCRIPTION_MODELS` interplay if the provider overlaps Pi.88- Golden wire fixture plus contract tests (Python side).8990Runner (`services/runner/src/engines/sandbox_agent/`):91- `run-plan.ts`: acpAgent mapping (often a passthrough already), the api-key env var92 name, the subscription mount variable branch, the Daytona-plus-subscription93 rejection (subscription state never ships to a third-party sandbox).94- `environment-setup.ts`: local credential/asset preparation (create-if-absent,95 restrictive modes, delete-only-if-created).96- `daemon.ts`: provider env var group (least-privilege set).97- Approvals: a gate type in the `ParkedApprovalGateType` union, classification for98 the harness's frames, park/resume tests mirroring Claude's.99- Harness files: rendered by the SDK, written blind by `prepareWorkspace`.100- Contract tests (TypeScript side) against the same golden fixture.101102Platform edges:103- Subscription sidecar login support for the provider.104- A cell in the agent release gate.105- Docs kept in sync in the same PR train (`keep-docs-in-sync`).106107## Variance axes (what actually differs between harnesses)108109Judge similarity on these, not on gut feel. Pi was expensive because it fails most of110them; Codex was cheap because it fails only the permission-vocabulary one.1111121. Protocol path: behind the shared ACP daemon (cheap) vs native protocol (expensive).1132. Permission vocabulary: fine-grained per-tool rules (Claude) vs coarse global modes114 (Codex). Coarse vocabularies raise expressibility questions that go to the115 decision register, never get silently approximated.1163. Config layout: separate login dir and project config (Claude) vs one directory for117 both (Codex). One-directory harnesses make the mount layout a real design.1184. Auth forms: env var vs credential file vs OAuth tokens, and whether the119 subscription sidecar already speaks the provider's OAuth.1205. Tool-delivery channel and native pre-allow support (the F-046 question).121122## Process (how the project runs)123124- One worktree per harness with its own deployment. Ports: pick a free Traefik/125 Postgres pair (`deploy-worktree-testing` skill has the table), unique compose126 project name. Fresh-worktree gotchas so far: `chmod -R o+w web/ee/public127 web/oss/public` before the web container will boot; the repo gitignore is128 allowlist-style for `.env*` so worktree `.env` files are safe for keys.129- Bootstrap through the UI as the first act (signup, project, API key into the130 worktree `.env`): it doubles as a smoke test of main and catches UI regressions131 free of charge.132- Design workspace per `plan-feature` (research.md, spike/findings.md, design.md,133 decisions.md, plan.md, status.md, reports/). The decision register is the no-134 implicit-decisions mechanism: anything that is not an obvious copy of an existing135 harness pattern is proposed there and waits.136- Vertical slices in this order: managed-key text-only run, Agenta tools, permissions137 plus human-in-the-loop, subscription auth, Daytona plus docs plus release gate.138 Risk always moves to the earliest slice that can kill it.139- Implementation via Codex (gpt5.6-sol), review via Opus, then desloppify and140 `/simplify`, after every milestone. Code quality bar: the adapter must read like141 the Claude adapter it sits next to.142- Every milestone ends with a written report for Mahmoud (`reports/`), live QA in the143 worktree deployment, and a recording when the milestone has a visible behavior.144 Merging is always Mahmoud's action.145146## Communication contract (learned, do not relearn)147148- Reports lead with what works now and what he can click; evidence follows.149- Decision asks give context, then options with trade-offs, then a recommendation150 with the reason. One checkpoint per project phase beats scattered questions.151- Never present a degraded behavior (something the harness cannot express) as done;152 present it as a register entry with options.153- Full sentences, no fragments, no internal codenames without a plain-language154 explanation, no em dashes.