add-harness

# 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:

1. **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.
2. **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.
3. **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)?
4. **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`.
- C