pi-harness-delegate 0.5.0 → 0.6.0

package/README.md

@@ -81,12 +81,16 @@ delegate({ harness: "all", mode: "review", scope: "diff" })   # tool call form
 | --- | --- | --- | --- |
 | `claude` | `claude` | `readonly→plan`, `edit→acceptEdits`, `danger→bypassPermissions` | Full stream-json, cost + context%. Schema-verified against Claude Code 2.1.247. |
 | `codex` | `codex` | `readonly→read-only`, `edit→workspace-write`, `danger→danger-full-access` | `codex exec --json`. Schema-verified against codex-cli 0.149.1; cost is always unmeasured (`null`) on ChatGPT-plan auth. |
-| `opencode` | `opencode` | `readonly→read-only`, `edit→allow-edit`, `danger→danger` | `opencode run --format json`. Schema-verified against opencode 1.18.16. |
-| `amp` | `amp` (`omp` alias) | `readonly→read-only`, `edit→workspace`, `danger→danger` | `<binary> -p --mode json`, resolves whichever of `amp`/`omp` is actually on `PATH`. Schema-verified against omp 17.2.9 (Sourcegraph's real Amp CLI is unverified). |
+| `opencode` | `opencode` | `readonly→plan`, `edit→build`, `danger→build --auto` | `opencode run --format json` (stdout, default) or `opencode acp` ([ACP](https://agentclientprotocol.com), opt-in via `transport: "acp"` — see Config). Schema-verified against opencode 1.18.16. |
+| `amp` | `amp` (`omp` alias) | `readonly→always-ask`, `edit→write`, `danger→yolo` | `<binary> -p --mode json`, resolves whichever of `amp`/`omp` is actually on `PATH`. Schema-verified against omp 17.2.9 (Sourcegraph's real Amp CLI is unverified). `omp acp` is real but not offered as a `transport` option — its ACP mode surface only has 2 tiers against this CLI's genuine 3. |
 | `devin` | `devin` | `readonly→plan`, `edit→accept-edits`, `danger→bypass` | Runs `devin acp` — [Agent Client Protocol](https://agentclientprotocol.com) over stdio, not stdout JSONL (see `acp-runner.ts`). Real tool-call ids, a genuine context-window %, and a working `sessionId`/resume via `session/load`. Reports no `$` cost (stays `null`) and no turn count. `model` is wired via `devin acp --model <MODEL>` (fuzzy names, e.g. `opus`); the reported `model` is read back from Devin's own `_cognition.ai/agent_stopped` event rather than echoed from the request, so it reflects what actually ran. Schema-verified against `devin 3000.6.7 (260a97c8)`. |
 
 Detect availability: `delegate` checks `harness --version` at startup; missing harnesses hint install instructions.
 
+### Transport
+
+Every harness runs over its native CLI's stdout (`stdout`, the default and only option for `claude`/`codex`/`amp`). `opencode` and `devin` also speak [ACP](https://agentclientprotocol.com) (Agent Client Protocol — bidirectional JSON-RPC over stdio): Devin ships ACP-only (no stdout mode exists), and `opencode` supports both — `stdout` stays the default, `transport: "acp"` is opt-in per harness in config (see below). ACP gives `opencode` a genuine `cost`/`contextWindow` (both `null` over stdout today) and a resume path independently proven to recall cross-process state; the tradeoff is `model`/`numTurns` staying unmeasured (`null`) either way. `amp`/`omp` has a real `acp` subcommand too, but isn't offered as a `transport` value — its ACP mode surface has only 2 permission tiers against the stdout CLI's genuine 3, a real regression, not just an unverified one. Configuring a transport a harness doesn't support fails immediately with a clear error, before anything spawns.
+
 ## Modes (templates)
 
 | Mode | Permission | Purpose |
@@ -118,18 +122,20 @@ You are a senior engineer delegated by the pi coding agent.
 
 - **Sources, deliberately limited:** a verify command can only come from a template's `verify:` frontmatter, or a human typing `/delegate --verify="<cmd>"` (quotes needed for multi-word commands) — the call-level value wins over the template's. **It is not a parameter on the `delegate` tool** — that's on purpose, not an oversight: a tool param is set by the model, and the model's context includes repo content and delegated-harness output, both of which an attacker could influence, so a model-settable verify command would be a prompt-injection → arbitrary-host-command path. A model that wants verification simply picks a template that declares one.
 - **Never runs on a `readonly` template.** `readonly` (`review`/`plan`/`security-audit`) guarantees no execution or modification — a verify command riding along on one would quietly break that guarantee. If a `readonly` template (or override) has a `verify` configured, it's recorded as skipped (`### Verify: \`cmd\`` / `⊘ skipped (readonly run)`) rather than run, and never silently dropped.
-- A project-local template's `verify` command is gated by the same trust check (`PI_TRUSTED=1` / `.pi/trusted`) as the rest of the template.
+- A project-local template's `verify` command is gated by the same project-trust check as the rest of the template.
 
 **Template sources (later wins):**
 
 - `templates/shared/*.md` — portable prompt bodies
 - `templates/<harness>/*.md` — harness-specific frontmatter (built-ins)
 - `~/.pi/agent/delegate/templates/<harness>/<name>.md` (global)
-- `.pi/delegate/templates/<harness>/<name>.md` (project — when trusted)
+- `.pi/delegate/templates/<harness>/<name>.md` (project — only when the project is trusted, see below)
 - Legacy `~/.pi/agent/claude-delegate/templates/` and `.pi/claude-delegate/templates/` still loaded for migration
 
 Custom templates are just files dropped in the above dirs — any registered name becomes a valid `mode`.
 
+**Project trust:** project-local templates (`.pi/delegate/templates/`) load only when pi itself considers the current project trusted (`ctx.isProjectTrusted()`, backed by pi's own trust store outside the project — the same trust that gates other project-scoped behavior). Trust it via pi's own trust prompt (shown the first time you open an untrusted directory) or your `defaultProjectTrust` setting; `/delegate status` reports whether the current project is trusted and, if not, that project-local templates are being skipped. There is **no way to grant trust from inside the project** — no `.pi/trusted` file, no environment variable. Earlier versions supported both (`.pi/trusted` containing `1`, or `PI_TRUSTED=1`/`PI_DELEGATE_TRUSTED=1` in the environment); both were removed as a security fix — a repo could commit `.pi/trusted` and declare itself trusted, letting a cloned hostile repo's templates silently override a builtin (e.g. widening `review` from `readonly` to `edit` and attaching a `verify:` command that runs host-side). If you relied on either, switch to pi's trust prompt or `defaultProjectTrust`.
+
 ## How the main session consumes the output
 
 - **Agent-driven (`delegate` tool)** — report is the tool result, flows into agent context.
@@ -170,16 +176,24 @@ In `~/.pi/agent/settings.json`:
     "harnesses": {
       "claude": { "model": "sonnet" },
       "codex": { "model": "gpt-5" },
-      "opencode": { "model": "opencode-default" }
+      "opencode": { "model": "opencode-default", "transport": "acp" }
     }
   }
 }
 ```
 
-Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated).
+Run `/delegate config` to see exactly what was read from `settings.json` (or why nothing was — no file, no `delegate` key, or a parse error), plus the effective config with defaults filled in, as a paste-ready JSON block for the `delegate` key. `/delegate status` shows the same provenance as one summary line.
+
+`/delegate config init` writes that effective config into `settings.json` under the `delegate` key — the only thing this extension ever writes there, and only on this explicit command. It reads the whole file, replaces only the `delegate` key, and preserves every other key (pi's `theme`/`defaultProvider`/`packages`/…, and a leftover `claudeDelegate`, verbatim). The write is atomic (temp file + rename in the same directory — no torn file if the process dies mid-write) and refuses outright if the existing file fails to parse, rather than clobbering whatever's actually in it; `/delegate config`'s paste-ready block is the fallback in that case.
+
+Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated) — most fields migrate, including per-harness settings like `harnesses.<name>.transport`. Two things never migrate, though, and stay silently unreachable as long as `claudeDelegate` is your *only* key (no `delegate` key at all): `defaultHarness` (stays pinned to `claude`) and a top-level default `model` (only `claudeDelegate.model` → `harnesses.claude.model` migrates — there's no global fallback). Both `/delegate status` and `/delegate config` call this out when it's happening; fix it by renaming `claudeDelegate` to `delegate`, or by running `/delegate config init`, which writes an explicit `delegate` key (with the legacy values already correctly migrated) without touching `claudeDelegate` itself.
+
+Config lives as a key inside pi's own `~/.pi/agent/settings.json` rather than a dedicated file — small enough that this fits comfortably, and pi's extension docs don't prescribe a convention either way for global (as opposed to project-local) preferences. If per-project overrides are ever wanted, pi's documented pattern for extension-owned project config is `.pi/<CONFIG_DIR_NAME>/pi-harness-delegate.json` (gated by project trust); not implemented today.
+
+- `harnesses.<name>.transport` — `"stdout"` (default for every harness except `devin`, which is ACP-only) or `"acp"`. Only legal where the harness actually supports it — see [Transport](#transport) above; an unsupported value fails the run immediately with a clear message rather than being silently ignored or failing at spawn time.
 
 - `modelAliases` — templates may use `economy|balanced|max` or any alias; resolution: call → template → harness → global.
-- `maxConcurrent` — cap overlapping runs (default **`4`**, one slot per supported harness; may be `{global:4, perHarness:{claude:1}}`). Enforced across pi processes, not just the current one — a file-based registry under `~/.pi/agent/delegate/runs/` tracks active runs, so the slots available to you also depend on any other pi session running `delegate`. This is a **genuinely parallel** spend cap now, not just a "don't overlap" guard: a single-harness `/delegate` call still fails fast (`another delegate run is already in progress`) the moment it's at capacity, but `/delegate all …` fan-out queues for a free slot instead and can run up to `maxConcurrent` harnesses at once — meaning up to that many harnesses billing simultaneously. Lower it if you want fan-out to stay sequential/cheaper (`"maxConcurrent": 1` restores the old one-at-a-time behavior for everything, single runs included).
+- `maxConcurrent` — cap overlapping runs (default **`4`**, one slot per supported harness; may be `{global:4, perHarness:{claude:1}}`). Enforced across pi processes, not just the current one — a file-based registry under `~/.pi/agent/delegate/runs/` tracks active runs, so the slots available to you also depend on any other pi session running `delegate`. This is a **genuinely parallel** spend cap now, not just a "don't overlap" guard: a single-harness `/delegate` call still fails fast (`another delegate run is already in progress`) the moment it's at capacity, but `/delegate all …` fan-out queues for a free slot instead and can run up to `maxConcurrent` harnesses at once — meaning up to that many harnesses billing simultaneously. Lower it if you want fan-out to stay sequential/cheaper (`"maxConcurrent": 1` restores the old one-at-a-time behavior for everything, single runs included). `/delegate status` shows each harness's `active` count next to the cap that actually applies to it (e.g. `1/2`), so a `{perHarness: {...}}` override is visible per-row, not just the raw config JSON in the header; the summary line at the bottom shows the same for the global cap.
 - `maxTranscripts` — oldest transcripts pruned beyond this count per harness (`0` disables).
 
 `autoDelegateHints` is off by default — no system-prompt bias. When `true`, explicit markers (`@harness`, `with codex`, `delegate … to claude`) and imperative review/plan phrasing append a hint.
@@ -190,6 +204,8 @@ Every run records in details + transcript: harness, mode, permission (normalized
 
 Claude reports turns and cost on every run; Codex/OpenCode/Amp don't always. An unmeasured turn count or cost renders as `—`/`n/a` (never `0`/`$0.000`) everywhere it's shown — the transcript header, `formatMetrics`, tool results, and `/delegate history` — so an unmeasured run is never mistaken for a free one. `/delegate status` shows a per-harness spend rollup (e.g. `$1.234 over 12 run(s) (3 unknown)`); runs with unknown cost are counted separately rather than folded into the total as `$0`.
 
+One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cost stats) has no way to express "cost unknown" — its `cost.total` field is mandatory. Codex and Devin never report a `$` cost, so treating unknown-cost as unknown-usage there would drop those two harnesses' tokens out of pi's session totals entirely. `mapHarnessUsage`/`mapClaudeUsage` (`extensions/usage.ts`) report the real token counts with `cost.total: 0` in that one case — under-reporting spend by a bounded, knowable amount beats losing 40% of token accounting. This does not change anything above: transcripts, `formatMetrics`, and `/delegate status` still render unmeasured cost as `—`/`n/a`, never `$0`.
+
 ## Security model
 
 - `readonly` — no edits (e.g. Claude `plan`, Codex `read-only`).

package/extensions/acp-runner.ts

@@ -8,15 +8,19 @@
  * doesn't hang, since we run non-interactively with a permission mode already negotiated.
  *
  * Exposes the exact `RunHarnessOptions`/`HarnessResult` shape as runner.ts, so `delegate()`
- * can pick either runner from `harness.transport` and everything downstream (transcripts,
- * `ToolCallIndex`, progress overlays, fan-out, spend rollup) is unchanged.
+ * can pick either runner from the resolved `transport` (see config.ts's `resolveTransport`) and
+ * everything downstream (transcripts, `ToolCallIndex`, progress overlays, fan-out, spend rollup)
+ * is unchanged.
  *
- * Deliberately general: an agent's mode ids and result shape live in its `Harness` (`buildArgs`,
- * `permissionMap`, `parseLine`, `extractResult`) — this file only knows the ACP wire protocol.
+ * Deliberately general: an agent's mode ids and result shape live in its `Harness` (`buildArgs`/
+ * `buildAcpArgs`, `permissionMap`/`acpPermissionMap`, `parseLine`/`parseAcpLine`, `extractResult`)
+ * — this file only knows the ACP wire protocol. Callers driving a dual-transport harness over ACP
+ * pass it through `acpView()` (below) first, so this file always reads the stdout-shaped field
+ * names regardless of which harness it's given.
  */
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { DEFAULT_TIMEOUT_MS, type ParseState, type StreamedResult } from './harnesses/types.ts';
+import { DEFAULT_TIMEOUT_MS, type Harness, type ParseState, type StreamedResult } from './harnesses/types.ts';
 import type { HarnessResult, RunHarnessOptions } from './runner.ts';
 
 /** Bound on the initial handshake (initialize / session/new / session/set_mode) so a hung agent
@@ -29,6 +33,33 @@ function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
+/** Presents the ACP-shaped view of a dual-transport `Harness` (buildAcpArgs/parseAcpLine/
+ *  acpPermissionMap) to this file, falling back to the stdout-shaped fields for an ACP-only
+ *  harness like Devin that never declares the Acp-prefixed ones. Devin needs zero changes for
+ *  this — every field below already exists on it under the stdout-shaped name. */
+export function acpView(harness: Harness): Harness {
+  return {
+    ...harness,
+    buildArgs: harness.buildAcpArgs ?? harness.buildArgs,
+    parseLine: harness.parseAcpLine ?? harness.parseLine,
+    permissionMap: harness.acpPermissionMap ?? harness.permissionMap,
+  };
+}
+
+/** Does this `session/new`/`session/load` result advertise support for switching session modes?
+ *  Two independently-real dialects, both live-verified (docs/acp-harness-assessment.md §2/§4):
+ *  the spec-standard `modes` field (Devin, omp), or a `configOptions` entry with `category: "mode"`
+ *  (opencode, which never populates `modes` at all but implements `session/set_mode` anyway). Either
+ *  signal is enough to trust the upcoming `session/set_mode` call. */
+function supportsSessionModes(sessionResult: unknown): boolean {
+  if (!isRecord(sessionResult)) return false;
+  if (isRecord(sessionResult.modes)) return true;
+  if (Array.isArray(sessionResult.configOptions)) {
+    return sessionResult.configOptions.some(o => isRecord(o) && o.category === 'mode');
+  }
+  return false;
+}
+
 interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (err: Error) => void;
@@ -247,7 +278,7 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     // bounded by the overall `timer` above like everything else.
     (async () => {
       const modeId = opts.nativePermission ?? opts.harness.permissionMap?.[opts.permission]?.[0] ?? opts.permission;
-      await sendRequest(
+      const initResult = await sendRequest(
         'initialize',
         {
           protocolVersion: PROTOCOL_VERSION,
@@ -256,6 +287,15 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
         HANDSHAKE_TIMEOUT_MS,
       );
       if (settled) return;
+      // The client "should disconnect" (spec text) if the agent didn't echo back the version we
+      // asked for — only `1` has ever shipped, so this is cheap insurance against a future
+      // version-mismatched agent producing a confusing mid-handshake failure instead of a clear one.
+      const negotiatedVersion = isRecord(initResult) ? initResult.protocolVersion : undefined;
+      if (negotiatedVersion !== PROTOCOL_VERSION) {
+        throw new Error(
+          `${opts.harness.binary} negotiated ACP protocolVersion ${JSON.stringify(negotiatedVersion)}, expected ${PROTOCOL_VERSION}`,
+        );
+      }
       const sessionParams = {
         cwd: opts.cwd,
         mcpServers: [],
@@ -267,12 +307,18 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       // advertised in agentCapabilities and a real session/load + follow-up prompt round-trips
       // cleanly, replaying history and continuing the same token-usage accounting.
       let sessionId: string | null;
+      let sessionResult: unknown;
       if (opts.resumeSessionId) {
-        await sendRequest('session/load', { sessionId: opts.resumeSessionId, ...sessionParams }, HANDSHAKE_TIMEOUT_MS);
+        sessionResult = await sendRequest(
+          'session/load',
+          { sessionId: opts.resumeSessionId, ...sessionParams },
+          HANDSHAKE_TIMEOUT_MS,
+        );
         sessionId = opts.resumeSessionId;
       } else {
-        const newSession = await sendRequest('session/new', sessionParams, HANDSHAKE_TIMEOUT_MS);
-        sessionId = isRecord(newSession) && typeof newSession.sessionId === 'string' ? newSession.sessionId : null;
+        sessionResult = await sendRequest('session/new', sessionParams, HANDSHAKE_TIMEOUT_MS);
+        sessionId =
+          isRecord(sessionResult) && typeof sessionResult.sessionId === 'string' ? sessionResult.sessionId : null;
       }
       if (settled) return;
       if (!sessionId) throw new Error('session/new did not return a sessionId');
@@ -282,6 +328,20 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
         state._harness ??= {};
         state._harness.sessionId = sessionId;
       }
+      // `session/set_mode` (and `NewSessionResponse.modes`) are spec-optional — calling it
+      // unconditionally against a mode-less agent would fail the whole handshake with a raw
+      // "method not found" instead of a clear message. Every agent this project has captured
+      // (Devin, opencode, omp) does support it, so this never fires for a real run today — but per
+      // the brief, a mode we can't confirm is a hard error, not a silent downgrade to whatever the
+      // agent's default permissiveness happens to be: we already promised the caller a specific
+      // permission tier.
+      if (!supportsSessionModes(sessionResult)) {
+        throw new Error(
+          `${opts.harness.binary} does not advertise session-mode support (no "modes" field or ` +
+            `configOptions "mode" category on session/${opts.resumeSessionId ? 'load' : 'new'}) — ` +
+            `cannot verify the "${opts.permission}" permission tier would be honored over ACP`,
+        );
+      }
       await sendRequest('session/set_mode', { sessionId, modeId }, HANDSHAKE_TIMEOUT_MS);
       if (settled) return;
       promptSent = true;

package/extensions/command.ts

@@ -92,6 +92,27 @@ export function isFanoutSpec(harness: string | undefined): boolean {
   return lower === 'all' || lower.includes(',');
 }
 
+export type HarnessFilterResolution =
+  | { kind: 'none' } // no filter word given
+  | { kind: 'known'; harness: string } // resolved to its canonical name (aliases/case normalized)
+  | { kind: 'unknown'; requested: string }; // word given, but not a known harness or alias
+
+/**
+ * Resolve a single optional harness-filter word — as used by `/delegate list`/`history`'s bare
+ * word or `--harness=` flag — to its canonical name via `aliasOf`, case-insensitively, so `omp`,
+ * `OMP`, and `amp` all filter identically. Pure and shared by both subcommands so they can't drift
+ * on alias/case handling the way they once did.
+ */
+export function resolveHarnessFilter(
+  word: string | undefined,
+  opts: { isKnown: (name: string) => boolean; aliasOf: (name: string) => string },
+): HarnessFilterResolution {
+  if (!word) return { kind: 'none' };
+  const lower = word.toLowerCase();
+  if (!opts.isKnown(lower)) return { kind: 'unknown', requested: word };
+  return { kind: 'known', harness: opts.aliasOf(lower) };
+}
+
 export interface HarnessListResolution {
   /** Canonical harness names to run, in request order, deduped. */
   resolved: string[];

package/extensions/concurrency.ts

@@ -11,7 +11,7 @@
  */
 
 import { type DelegateConfig, getMaxConcurrent } from './config.ts';
-import { acquireRun, countActiveRuns, releaseRun } from './run-registry.ts';
+import { acquireRunWithinLimits, countActiveRuns, releaseRun } from './run-registry.ts';
 
 const activeRuns = new Map<string, number>();
 let globalActiveRuns = 0;
@@ -70,7 +70,11 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * never throws) once a slot is held; the caller must call it exactly once when the run finishes.
  *
  * Checks the global limit before the per-harness limit — same precedence and error text as the
- * original inline guard, so single-run (`wait: false`) callers see unchanged behavior.
+ * original inline guard, so single-run (`wait: false`) callers see unchanged behavior. Those two
+ * checks are still a plain (racy) read, kept as a cheap fail-fast/error-message step; the actual
+ * grant is `acquireRunWithinLimits()` (run-registry.ts), which re-verifies after registering so a
+ * race lost between the check here and the write there is caught — see its doc comment. Losing
+ * that race is handled exactly like losing the check above: throw (wait:false) or poll (wait:true).
  */
 export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void> {
   const { harness, mode, config, wait, signal, pollIntervalMs = 200 } = opts;
@@ -91,9 +95,18 @@ export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void>
       continue;
     }
 
+    const claim = acquireRunWithinLimits(harness, mode, maxGlobal, perHarnessLimit);
+    if (claim.status === 'full') {
+      // the check above passed, but another racer's write landed first and used up the slot —
+      // handled exactly like hitting the cap on the check itself.
+      if (!wait) throw new ConcurrencyLimitError(`another delegate run claimed the last available slot for ${harness}`);
+      await sleep(pollIntervalMs, signal);
+      continue;
+    }
+
     activeRuns.set(harness, perHarnessCount + 1);
     globalActiveRuns++;
-    const runHandle = acquireRun(harness, mode);
+    const runHandle = claim.status === 'acquired' ? claim.handle : null;
     let released = false;
     return () => {
       if (released) return;

package/extensions/config.ts

@@ -1,13 +1,20 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { DEFAULT_TIMEOUT_MS } from './harnesses/types.ts';
+import { dirname, join } from 'node:path';
+import { DEFAULT_TIMEOUT_MS, type Harness, type Transport } from './harnesses/types.ts';
 
 export interface HarnessConfig {
   model?: string;
   timeoutMs?: number;
   allowDangerous?: boolean;
   maxBudgetUsd?: number;
+  /** Overrides the harness's default transport ('stdout' unless the harness itself defaults to
+   *  'acp', e.g. Devin). A malformed value (not 'stdout'/'acp') is dropped at load time, same as
+   *  every other per-harness field's defensive parsing below; a well-formed but unsupported value
+   *  (e.g. 'acp' for a harness with no ACP surface) is *not* dropped here — it's validated against
+   *  `Harness.supportsTransports` by `resolveTransport()` instead, so misconfiguring it fails the
+   *  run with a clear message rather than being silently ignored. */
+  transport?: Transport;
 }
 
 export interface DelegateConfig {
@@ -25,6 +32,36 @@ export interface DelegateConfig {
   harnesses: Record<string, HarnessConfig>;
 }
 
+/**
+ * Provenance for how `loadConfig()` actually resolved its settings — the bit a bare `try/catch {}`
+ * used to erase entirely, making "no file", "file, no relevant key", and "file, unparseable" all
+ * look identical (empty defaults, no signal anywhere). `usedKey` is which key ended up populating
+ * `cfg`: `'delegate'` and `'claudeDelegate'` are mutually exclusive (the legacy branch only runs
+ * when `delegate` is *absent*), so `'claudeDelegate'` here means the legacy-only case that costs
+ * the user every setting under `delegate` — not "legacy key present at all" (see
+ * `legacyKeyPresent` for that). `raw` is the literal value of whichever key was used, exactly as
+ * read from the file — no defaults merged in, no per-field sanitizing — so `/delegate config` can
+ * show what was actually written next to what it resolved to.
+ */
+export interface ConfigSource {
+  file: string;
+  fileExists: boolean;
+  /** Set when the file exists but `JSON.parse` failed, or the parsed value isn't a JSON object
+   *  (e.g. an array or a bare string) — either way `cfg` fell back to defaults. */
+  parseError?: string;
+  usedKey: 'delegate' | 'claudeDelegate' | 'none';
+  /** Whether a `claudeDelegate` key exists in the file at all, independent of `usedKey` — true
+   *  even when `delegate` won and `claudeDelegate` was only partially merged (the `model`
+   *  fallback below). */
+  legacyKeyPresent: boolean;
+  raw?: unknown;
+}
+
+export interface ConfigLoadResult {
+  config: DelegateConfig;
+  source: ConfigSource;
+}
+
 export function agentDir(): string {
   return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
 }
@@ -38,7 +75,24 @@ export function legacyOutputsDir(): string {
   return join(agentDir(), 'claude-delegate', 'outputs');
 }
 
-export function loadConfig(): DelegateConfig {
+/** Drops a malformed `transport` (anything but 'stdout'/'acp', including absent) before it's
+ *  stored — the rest of `HarnessConfig`'s fields are spread through as-is by `loadConfig()`. */
+function sanitizeHarnessConfig(v: HarnessConfig): HarnessConfig {
+  const out = { ...v };
+  if (out.transport !== 'stdout' && out.transport !== 'acp') delete out.transport;
+  return out;
+}
+
+/**
+ * Loads `delegate` config from `~/.pi/agent/settings.json` alongside `ConfigSource`, describing
+ * how that happened (file present? which key won? did it fail to parse?) — see `ConfigSource`'s
+ * doc comment. `loadConfig()` below is a thin wrapper for the existing call sites that only want
+ * the resolved values; this is the one place that actually reads/parses the file, so a caller
+ * needing both never pays for a second parse. Never throws — any failure (missing file, bad JSON,
+ * a non-object root) is recorded on `source` and falls back to the same defaults `loadConfig()`
+ * has always returned.
+ */
+export function loadConfigWithSource(): ConfigLoadResult {
   const cfg: DelegateConfig = {
     timeoutMs: DEFAULT_TIMEOUT_MS,
     defaultMode: 'general',
@@ -51,15 +105,31 @@ export function loadConfig(): DelegateConfig {
     maxTranscripts: 100,
     harnesses: {},
   };
+  const file = join(agentDir(), 'settings.json');
+  const source: ConfigSource = { file, fileExists: false, usedKey: 'none', legacyKeyPresent: false };
   try {
-    const file = join(agentDir(), 'settings.json');
-    if (!existsSync(file)) return cfg;
-    const settings = JSON.parse(readFileSync(file, 'utf8')) as {
+    if (!existsSync(file)) return { config: cfg, source };
+    source.fileExists = true;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (err) {
+      source.parseError = err instanceof Error ? err.message : String(err);
+      return { config: cfg, source };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      source.parseError = 'settings.json root is not a JSON object';
+      return { config: cfg, source };
+    }
+    const settings = parsed as {
       delegate?: Partial<DelegateConfig & { harnesses: Record<string, HarnessConfig> }>;
       claudeDelegate?: Partial<DelegateConfig & { model?: string }>;
     };
+    source.legacyKeyPresent = Boolean(settings.claudeDelegate);
     // Legacy claudeDelegate -> delegate.harnesses.claude migration
     if (settings.claudeDelegate && !settings.delegate) {
+      source.usedKey = 'claudeDelegate';
+      source.raw = settings.claudeDelegate;
       const c = settings.claudeDelegate as Partial<DelegateConfig>;
       if (typeof c.model === 'string') cfg.harnesses.claude = { ...(cfg.harnesses.claude ?? {}), model: c.model };
       if (typeof c.timeoutMs === 'number' && c.timeoutMs > 0) cfg.timeoutMs = c.timeoutMs;
@@ -92,12 +162,15 @@ export function loadConfig(): DelegateConfig {
       if (typeof c.maxTranscripts === 'number' && c.maxTranscripts >= 0) cfg.maxTranscripts = c.maxTranscripts;
       if (c.harnesses && typeof c.harnesses === 'object') {
         for (const [k, v] of Object.entries(c.harnesses)) {
-          if (v && typeof v === 'object') cfg.harnesses[k] = { ...(cfg.harnesses[k] ?? {}), ...(v as HarnessConfig) };
+          if (v && typeof v === 'object')
+            cfg.harnesses[k] = { ...(cfg.harnesses[k] ?? {}), ...sanitizeHarnessConfig(v as HarnessConfig) };
         }
       }
       // also map harnesses.claude if any
-      return cfg;
+      return { config: cfg, source };
     }
+    source.usedKey = settings.delegate ? 'delegate' : 'none';
+    source.raw = settings.delegate;
     const d = settings.delegate ?? {};
     if (typeof d.defaultHarness === 'string' && d.defaultHarness) cfg.defaultHarness = d.defaultHarness;
     if (typeof d.defaultMode === 'string') cfg.defaultMode = d.defaultMode;
@@ -129,7 +202,7 @@ export function loadConfig(): DelegateConfig {
     if (typeof d.maxTranscripts === 'number' && d.maxTranscripts >= 0) cfg.maxTranscripts = d.maxTranscripts;
     if (d.harnesses && typeof d.harnesses === 'object') {
       for (const [k, v] of Object.entries(d.harnesses)) {
-        if (v && typeof v === 'object') cfg.harnesses[k] = { ...(v as HarnessConfig) };
+        if (v && typeof v === 'object') cfg.harnesses[k] = sanitizeHarnessConfig(v as HarnessConfig);
       }
     }
     // also support legacy claudeDelegate merged when delegate also present (delegate wins)
@@ -139,10 +212,121 @@ export function loadConfig(): DelegateConfig {
         cfg.harnesses.claude = { ...(cfg.harnesses.claude ?? {}), model: c.model };
       }
     }
-  } catch {
-    // invalid settings — fall back to defaults
+  } catch (err) {
+    // Anything unexpected (e.g. a read error after existsSync's check raced a delete) — still
+    // never throw; record it as a parse error so it's not silently indistinguishable from "no
+    // config" if it wasn't already caught (and thus reported) above.
+    if (!source.parseError) source.parseError = err instanceof Error ? err.message : String(err);
+  }
+  return { config: cfg, source };
+}
+
+export function loadConfig(): DelegateConfig {
+  return loadConfigWithSource().config;
+}
+
+/**
+ * Human-readable lines describing how `loadConfig()` actually resolved its settings — the
+ * provenance report used by both `/delegate status` and `/delegate config`. Pure: takes the
+ * `ConfigSource` companion to `loadConfigWithSource()`'s result, no I/O, so it's testable without
+ * touching the filesystem.
+ */
+export function describeConfigSource(source: ConfigSource): string[] {
+  if (source.parseError) {
+    return [
+      `⚠ ${source.file} exists but failed to parse: ${source.parseError}`,
+      '  using defaults until this is fixed',
+    ];
+  }
+  if (!source.fileExists) {
+    return [`${source.file} not found — using defaults`];
+  }
+  if (source.usedKey === 'none') {
+    return [`${source.file} has no "delegate" key — using defaults`];
+  }
+  if (source.usedKey === 'claudeDelegate') {
+    return [
+      `⚠ using legacy "claudeDelegate" key in ${source.file}`,
+      '  two settings can never be reached this way: "defaultHarness" stays pinned to "claude", and there\'s no',
+      '  top-level default "model" (only claudeDelegate.model -> harnesses.claude.model migrates) — everything',
+      '  else (including per-harness settings like harnesses.<name>.transport) migrates fine',
+      '  rename "claudeDelegate" to "delegate" to unlock those two, or run `/delegate config init` to write an',
+      '  explicit "delegate" key for you (claudeDelegate itself is left untouched either way)',
+    ];
+  }
+  const lines = [`"delegate" key in ${source.file}`];
+  if (source.legacyKeyPresent) {
+    lines.push('  legacy "claudeDelegate" key is also present — ignored except claudeDelegate.model as a fallback');
+  }
+  return lines;
+}
+
+/**
+ * Full `/delegate config` report: provenance (`describeConfigSource`), the raw `delegate`/
+ * `claudeDelegate` value exactly as written in the file, and the effective config with defaults
+ * merged in — so a user can see both what they wrote and what it resolved to, and has a
+ * paste-ready starting point either way. Pure — takes an already-loaded `ConfigLoadResult`.
+ */
+export function buildConfigReport(result: ConfigLoadResult): string[] {
+  const lines = [...describeConfigSource(result.source)];
+  lines.push('');
+  lines.push('from file (as written, before defaults are applied):');
+  lines.push(JSON.stringify(result.source.raw ?? {}, null, 2));
+  lines.push('');
+  lines.push('effective config (file merged with defaults) — paste under "delegate" in settings.json,');
+  lines.push('or run `/delegate config init` to write it there directly:');
+  lines.push(JSON.stringify({ delegate: result.config }, null, 2));
+  return lines;
+}
+
+export interface WriteConfigResult {
+  ok: boolean;
+  file: string;
+  message: string;
+}
+
+/**
+ * Writes `delegateSubtree` into `settings.json` under the `delegate` key — replacing only that
+ * key and preserving every other top-level key verbatim (including a leftover `claudeDelegate`,
+ * which is never touched or removed here; that's the user's call, made by editing the file
+ * themselves). Read-modify-write, atomic: writes to `<file>.<pid>.tmp` in the same directory then
+ * `renameSync`s over the target, so a process death mid-write can never leave a torn file. Refuses
+ * to write (returns `ok: false`, file untouched) when the existing file is present but fails to
+ * parse or isn't a JSON object — overwriting an already-broken file would destroy whatever the
+ * user has in it; the caller should fall back to `buildConfigReport`'s paste-ready block instead.
+ * Never throws. Only ever called from an explicit user action (`/delegate config init`) — never
+ * on the strength of a read like `loadConfig()`/`showStatus`.
+ */
+export function writeDelegateConfig(delegateSubtree: unknown): WriteConfigResult {
+  const file = join(agentDir(), 'settings.json');
+  try {
+    let root: Record<string, unknown> = {};
+    if (existsSync(file)) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+      } catch (err) {
+        return {
+          ok: false,
+          file,
+          message: `refusing to write: ${file} exists but failed to parse (${err instanceof Error ? err.message : String(err)}) — fix or remove it first`,
+        };
+      }
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, file, message: `refusing to write: ${file} exists but its root isn't a JSON object` };
+      }
+      root = parsed as Record<string, unknown>;
+    }
+    root.delegate = delegateSubtree;
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `settings.json.${process.pid}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(root, null, 2)}\n`, 'utf8');
+    renameSync(tmp, file);
+    return { ok: true, file, message: `wrote "delegate" key to ${file}` };
+  } catch (err) {
+    return { ok: false, file, message: `failed to write ${file}: ${err instanceof Error ? err.message : String(err)}` };
   }
-  return cfg;
 }
 
 export function resolveModelForHarness(
@@ -155,6 +339,25 @@ export function resolveModelForHarness(
   return resolve(model) ?? resolve(templateModel) ?? resolve(cfg.harnesses[harness]?.model) ?? resolve(cfg.model);
 }
 
+/**
+ * Which transport a run should actually use: config override, falling back to the harness's own
+ * default (`harness.transport`, e.g. Devin's static 'acp'), falling back to 'stdout'. Validated
+ * against `harness.supportsTransports` — the ceiling of what the binary can actually do, distinct
+ * from what's configured — *before* the caller acquires a run slot or spawns anything, so
+ * misconfiguring e.g. `transport: 'acp'` for `claude` fails fast with a clear message instead of a
+ * cryptic "unknown subcommand" from the spawned process. See docs/acp-harness-assessment.md §5/§6.
+ */
+export function resolveTransport(cfg: DelegateConfig, harnessName: string, harness: Harness): Transport {
+  const transport = cfg.harnesses[harnessName]?.transport ?? harness.transport ?? 'stdout';
+  const allowed = harness.supportsTransports ?? [harness.transport ?? 'stdout'];
+  if (!allowed.includes(transport)) {
+    throw new Error(
+      `delegate.harnesses.${harnessName}.transport is "${transport}", but ${harnessName} only supports: ${allowed.join(', ')}`,
+    );
+  }
+  return transport;
+}
+
 export function getMaxConcurrent(cfg: DelegateConfig, harness?: string): number {
   if (typeof cfg.maxConcurrent === 'number') return cfg.maxConcurrent;
   // if object shape {global, perHarness}

package/extensions/harnesses/amp.ts

@@ -159,14 +159,22 @@ export function parseAmpLine(line: string, state: ParseState): ParseOutcome {
         ? (o.messages[o.messages.length - 1] as Record<string, unknown>)
         : null;
     const measured = (hs.turnCount ?? 0) > 0;
+    // real error shape: message.stopReason === 'error' + message.errorMessage — observed live on a
+    // 429 quota rejection, where message.content is an empty array, so the text-block extraction
+    // above never sets streamedText and this would otherwise silently report success with empty
+    // text (tests/fixtures/amp-error.jsonl).
+    const errorMessage = typeof msg?.errorMessage === 'string' ? (msg.errorMessage as string) : undefined;
+    const isErrorTurn = msg?.stopReason === 'error' || errorMessage !== undefined;
     const result: StreamedResult = {
       result:
         typeof o.result === 'string'
           ? o.result
-          : streamedText
-            ? state.streamedText + streamedText
-            : state.streamedText || (text ?? ''),
-      isError: o.is_error === true,
+          : errorMessage
+            ? errorMessage
+            : streamedText
+              ? state.streamedText + streamedText
+              : state.streamedText || (text ?? ''),
+      isError: o.is_error === true || isErrorTurn,
       numTurns: measured ? (hs.turnCount as number) : null,
       totalCostUsd: measured ? (hs.costAccum as number) : null,
       sessionId:
@@ -228,6 +236,9 @@ export const ampHarness: Harness = {
     const args = ['-p', '--mode', 'json', '--approval-mode', approvalMode];
     if (opts.model) args.push('--model', opts.model);
     if (opts.resumeSessionId) args.push('--resume', opts.resumeSessionId);
+    // `--add-dir=<value>` is real and repeatable per `omp --help` — confirmed live: a run with
+    // --add-dir echoed the directory back in the session line's `additionalDirectories`. (Earlier
+    // research had flagged this as possibly absent; that was wrong for omp 17.2.9.)
     for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
     args.push(opts.prompt);
     return args;
@@ -259,4 +270,13 @@ export const ampHarness: Harness = {
     return null;
   },
   permissionMap: { readonly: ['always-ask'], edit: ['write'], danger: ['yolo'] },
+  // `omp acp` is real and live-verified (docs/acp-harness-assessment.md §2/§4) — but deliberately
+  // NOT offered as a config value yet: its ACP mode surface only has 2 tiers (`default`/`plan`),
+  // while the stdout `--approval-mode` above has 3 genuine ones. Adding 'acp' here would let a
+  // user configure `edit`, expecting "ask before every write", and silently collapse it onto the
+  // same `default` mode as `danger` — a real permission-tier regression, not a cosmetic one. Only
+  // revisit if a future omp ACP version exposes a third tier (e.g. an `approval-mode`-shaped
+  // `configOptions` category, the same slot `thinking` already occupies today) — redo the §4-style
+  // live permission-tier analysis before changing this, don't just add 'acp' to the list.
+  supportsTransports: ['stdout'],
 };

package/extensions/harnesses/claude.ts

@@ -156,4 +156,7 @@ export const claudeHarness: Harness = {
     edit: ['acceptEdits'],
     danger: ['bypassPermissions'],
   },
+  // No `acp` subcommand exists (docs/acp-harness-assessment.md §2) — confirmed against the full
+  // `claude --help` output, not just an earlier probe.
+  supportsTransports: ['stdout'],
 };