pi-harness-delegate 0.7.2 → 0.7.3

package/README.md

@@ -76,7 +76,7 @@ The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff
 
 ### Fan out to multiple harnesses
 
-`harness` also accepts `all` or a comma-separated list — the same task runs on every harness **concurrently**, up to `maxConcurrent`, and comes back as one comparison report instead of one report per harness:
+`harness` also accepts `all` or a comma-separated list — the same task runs on every harness **concurrently**, up to `maxConcurrent`, and comes back as one comparison report instead of one report per harness (on `/delegate` and the `delegate` tool alike, the spec is case-insensitive and empty elements are dropped, so `claude,` is a plain single `claude` run, not a one-harness fan-out; a spec with no harness in it at all, like `,`, is an error rather than the default harness):
 
 ```bash
 /delegate all review the auth flow                 # every *detected* harness
@@ -150,7 +150,7 @@ All frontmatter keys (one `key: value` per line; only `name` is required):
 | `name` | The mode name used to select it (`--mode=`/`mode`) |
 | `description` | Shown by `/delegate list` |
 | `permission` | `readonly` \| `edit` \| `danger` (default `edit`). Any other value is treated as a native permission string |
-| `permissionMode` / `sandbox` | Legacy/native escape hatch (see below) |
+| `permissionMode` / `sandbox` | Legacy tier keys, only read when `permission` is absent (see below) |
 | `model` | Default model for this mode (call → template → harness → global) |
 | `maxBudgetUsd` | Default per-run spend cap in USD (a call's `maxBudgetUsd`/`--budget` wins) |
 | `skill` | Appends `Use the "<skill>" skill.` to the prompt |
@@ -160,22 +160,22 @@ All frontmatter keys (one `key: value` per line; only `name` is required):
 | `addDirs` | Comma-separated extra directories the harness may access (merged with the call's `addDirs`/`--add-dir`) |
 | `harness` | Informational: which harness a template targets (shown by `/delegate list`) |
 
-**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, put the native value in `permission:` (e.g. `permission: ask` in a `devin/` template) — it is passed to that harness as-is. Legacy `permissionMode:`/`sandbox:` keys only map onto the normalized tiers (`plan` → `readonly`, `bypassPermissions` → `danger`, anything else → `edit`).
+**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, put the native value in `permission:` (e.g. `permission: ask` in a `devin/` template) — it is passed to that harness as-is. Legacy `permissionMode:`/`sandbox:` keys only map onto the normalized tiers, and only when `permission:` is absent (`permission:` always wins; a legacy key that disagrees with it is ignored but flagged with a `⚠` warning). Both keys accept both vocabularies, case-, whitespace- and `_`/`-`-insensitively: Claude's `plan` and Codex's `read-only` → `readonly`; `acceptEdits`/`dontAsk`/`auto`/`manual` and `workspace-write` → `edit`; `bypassPermissions` and `danger-full-access` → `danger` (gated behind `allowDangerous` / `--allow-dangerous` like any danger template). The three permission key names (`permission`, `permissionMode`, `sandbox`) are themselves case-insensitive (`Sandbox: read-only` counts); if a key appears more than once, or both legacy keys are set, the least permissive tier wins. An **unrecognized** legacy value fails closed: the template still loads, but as `readonly` (so it cannot write, and any `verify:` is skipped), with a `⚠ unrecognized sandbox: "…"` warning prefixed to its description in `/delegate list` and repeated on every run (a notification, a `- warning:` transcript line, and a prefix on the returned result). It is not dropped, because a dropped override would let a same-named builtin (e.g. `implement`, which is `edit`) run in its place, and that can be wider than what the author meant.
 
-Native values are checked against a per-harness **allowlist** of readonly/edit-equivalent modes; anything else — the harness's own danger mode *or a value not on the list* — is treated as `danger` and needs `allowDangerous` / `--allow-dangerous` (fail closed). Once confirmed, an unlisted value still runs as declared rather than being swapped for the harness's danger mode.
+Native values are checked against a per-harness **allowlist** of readonly/edit-equivalent modes; anything else — the harness's own danger mode *or a value not on the list* — is treated as `danger` and needs `allowDangerous` / `--allow-dangerous` (fail closed). Once confirmed, an unlisted value still runs as declared rather than being swapped for the harness's danger mode. Matching is case-insensitive (`Plan` is claude's `plan`), and an allowlisted value always reaches the harness in its canonical spelling (e.g. `acceptEdits`); a case variant of a danger mode (`Yolo`, `BYPASSPERMISSIONS`) is still danger. A native value that is genuinely read-only on its harness (**bold** below) runs as the `readonly` tier: it is recorded as `readonly` and a `verify:` command on it is skipped, exactly like `permission: readonly`.
 
 | Harness | Native values treated as non-danger |
 | --- | --- |
-| `claude` | `plan`, `acceptEdits`, `manual`, `default` (`auto`, `dontAsk`, `bypassPermissions` → danger) |
-| `codex` | `read-only`, `workspace-write` |
-| `opencode` | `plan`, `build` (custom agents, `build --auto` → danger) |
-| `amp`/`omp` | `always-ask`, `write` |
-| `devin` | `plan`, `accept-edits`, `ask` (`smart`, `bypass` → danger) |
+| `claude` | **`plan`**, `acceptEdits`, `manual`, `default` (`auto`, `dontAsk`, `bypassPermissions` → danger) |
+| `codex` | **`read-only`**, `workspace-write` |
+| `opencode` | **`plan`**, `build` (custom agents, `build --auto` → danger) |
+| `amp`/`omp` | `always-ask`, `write` (`always-ask` stays `edit`: what `-p` does with an unanswerable ask is undocumented) |
+| `devin` | **`plan`**, `accept-edits`, `ask` (`smart`, `bypass` → danger) |
 
 **Verify:** `verify` is a shell command run **on the host** (never handed to the harness) right after it exits — e.g. `verify: bun test` on an `implement`/`docs`/`general` template turns "the harness says it's done" into an actual pass/fail. It's report-only: a failing verify is appended as its own section in the transcript and injected report, and surfaced in the tool result's `details.verify` (`{command, exitCode, ok}`), but it never changes whether the run itself is reported as an error — that stays whatever the harness reported. No template ships one by default — there's no universally-correct check command, so nothing is invented for you.
 
 - **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.
+- **Never runs on a `readonly` template** — including a native read-only one (`permission: plan`, codex `read-only`; see the table above). `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 project-trust check as the rest of the template.
 
 **Template sources (later wins):**

package/extensions/acp-runner.ts

@@ -128,6 +128,9 @@ interface PendingRequest {
 export interface AcpRunnerInternals {
   /** Overrides `HANDSHAKE_TIMEOUT_MS` so a hung-handshake test doesn't take 30s. */
   handshakeTimeoutMs?: number;
+  /** Replaces `child_process.spawn`, so a test can inject a stdin 'error' (EPIPE) deterministically —
+   *  bun never emits one for a real closed pipe, which left the stdin error guard untestable. */
+  spawn?: typeof spawn;
 }
 
 export function runAcpHarness(opts: RunHarnessOptions, internals: AcpRunnerInternals = {}): Promise<HarnessResult> {
@@ -150,7 +153,10 @@ export function runAcpHarness(opts: RunHarnessOptions, internals: AcpRunnerInter
       resumeSessionId: opts.resumeSessionId,
     });
 
-    const proc = spawn(opts.harness.binary, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    const proc = (internals.spawn ?? spawn)(opts.harness.binary, args, {
+      cwd: opts.cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
     // A write to a child that already exited surfaces as an async EPIPE 'error' on stdin — not as a
     // throw from write() (writeLine's try/catch can't see it). Unhandled, that event would crash the
     // host process; the run itself already ends through the 'close'/timeout/abort paths.

package/extensions/activity.ts

@@ -461,6 +461,8 @@ export function buildTranscript(
     verify?: VerifyResult;
     /** Budget outcome, when `maxBudgetUsd` was set for this run. */
     budget?: BudgetNote;
+    /** A template permission warning (e.g. an unrecognized legacy value failed closed to readonly). */
+    warning?: string;
   } & Record<string, unknown>,
 ): string {
   const harness = (opts.harness as string | undefined) ?? 'claude';
@@ -514,6 +516,7 @@ export function buildTranscript(
     `- context: ${context ?? 'n/a'}`,
     `- duration: ${duration ?? 'n/a'}`,
     `- stop reason: ${opts.stopReason ?? 'n/a'}`,
+    ...(opts.warning ? [`- warning: ${opts.warning}`] : []),
     ...(opts.budget ? [formatBudgetLine(opts.budget)] : []),
     ...(opts.budget?.message ? ['', opts.budget.message] : []),
     '',

package/extensions/command.ts

@@ -68,11 +68,12 @@ function looksLikeHarnessSpec(word: string, knownHarnesses: ReadonlySet<string>)
 }
 
 /**
- * Normalize a harness spec the same way whether it came from `--harness=` or the first word:
- * lowercased, empty list elements dropped (`claude,` -> `claude`, `,` -> none), and a single name
- * alias-normalized (`omp` -> `amp`). A real list / `all` is left for `resolveHarnessList`.
+ * Normalize a harness spec the same way whether it came from `--harness=`, the first word, or the
+ * `delegate` tool's `harness` param: lowercased, empty list elements dropped (`claude,` -> `claude`,
+ * `,` -> none), and a single name alias-normalized (`omp` -> `amp`). A real list / `all` is left for
+ * `resolveHarnessList`. Sharing it is what keeps both paths agreeing on single run vs fan-out.
  */
-function normalizeHarnessSpec(spec: string): string | undefined {
+export function normalizeHarnessSpec(spec: string): string | undefined {
   const parts = spec
     .toLowerCase()
     .split(',')
@@ -83,6 +84,12 @@ function normalizeHarnessSpec(spec: string): string | undefined {
   return parts.join(',');
 }
 
+/** The error for a harness spec that normalizes to nothing (`,`, `" , "`) — shared by `/delegate`'s
+ *  `--harness=` and the `delegate` tool's `harness` param, so neither silently runs the default. */
+export function emptyHarnessSpecError(raw: string): string {
+  return `harness ${JSON.stringify(raw)} names no harness: give a harness name, a comma-separated list, or "all" (omit it for the default harness)`;
+}
+
 /**
  * One pass over the raw command: a backticked or double-quoted prose span is skipped verbatim (so
  * `explain "--mode=x"` or `` `--allow-dangerous` `` in the prompt is never eaten as a flag); a
@@ -188,6 +195,9 @@ export function parseDelegateCommand(
   }
 
   let harness = flags.harness !== undefined ? normalizeHarnessSpec(flags.harness) : undefined;
+  // `--harness=,` / `--harness=" , "` / `--harness=` name no harness at all: an explicit choice we
+  // can't honor is an error, never a silent fall-back to the default harness.
+  if (flags.harness !== undefined && harness === undefined) errors.push(emptyHarnessSpecError(flags.harness));
   let mode = flags.mode;
   let task = rest.trim();
 

package/extensions/config.ts

@@ -145,21 +145,25 @@ export function parseMaxConcurrent(raw: unknown): DelegateConfig['maxConcurrent'
  * that changes a default (maxConcurrent 1 -> 4 already did) would never reach that user.
  */
 export function nonDefaultConfig(cfg: DelegateConfig): Partial<DelegateConfig> {
-  const defaults = defaultDelegateConfig() as unknown as Record<string, unknown>;
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(cfg as unknown as Record<string, unknown>)) {
-    if (v === undefined) continue;
+  const defaults = defaultDelegateConfig();
+  const out: Partial<DelegateConfig> = {};
+  // Typed per key so each value is copied into `out` under its own field type — no casts.
+  const keep = <K extends keyof DelegateConfig>(k: K): void => {
+    const v = cfg[k];
+    if (v !== undefined && JSON.stringify(v) !== JSON.stringify(defaults[k])) out[k] = v;
+  };
+  for (const k of Object.keys(cfg) as (keyof DelegateConfig)[]) {
     if (k === 'modelAliases') {
       // The loader merges aliases additively onto the defaults, so only the keys that differ need
       // writing — whole-object diffing would pin the untouched default aliases next to a custom one.
-      const d = defaults.modelAliases as Record<string, string>;
-      const diff = Object.fromEntries(Object.entries(v as Record<string, string>).filter(([a, t]) => d[a] !== t));
-      if (Object.keys(diff).length > 0) out[k] = diff;
+      const d = defaults.modelAliases;
+      const diff = Object.fromEntries(Object.entries(cfg.modelAliases ?? {}).filter(([a, t]) => d[a] !== t));
+      if (Object.keys(diff).length > 0) out.modelAliases = diff;
       continue;
     }
-    if (JSON.stringify(v) !== JSON.stringify(defaults[k])) out[k] = v;
+    keep(k);
   }
-  return out as Partial<DelegateConfig>;
+  return out;
 }
 
 /**

package/extensions/engine.ts

@@ -32,7 +32,14 @@ import {
   resolveModelForHarness,
   resolveTransport,
 } from './config.ts';
-import { ALIASES, classifyNativePermission, getHarness, HARNESS_NAMES } from './harnesses/registry.ts';
+import {
+  ALIASES,
+  canonicalSafeNativePermission,
+  classifyNativePermission,
+  getHarness,
+  HARNESS_NAMES,
+  nativePermissionTier,
+} from './harnesses/registry.ts';
 import type { ActivityEvent, NormalizedPermission } from './harnesses/types.ts';
 import { runHarness } from './runner.ts';
 import {
@@ -344,6 +351,13 @@ export async function delegate(
     );
   const task = opts.task || template.defaultTask;
   if (!task) throw new Error(`delegate mode "${mode}" requires a task`);
+  // A template permission problem (an unrecognized legacy value failed closed to readonly, or an
+  // ignored legacy key) is otherwise only visible in `/delegate list` — say so where the run happens.
+  const warning = template.permissionWarning && `⚠ template "${mode}": ${template.permissionWarning}`;
+  if (warning) {
+    if (ctx.hasUI) ctx.ui.notify?.(warning, 'warning');
+    else process.stderr.write(`${warning}\n`);
+  }
 
   // Fail-fast, before acquireSlot()/spawn — configuring e.g. transport:'acp' for a harness with no
   // ACP surface (or 'stdout' for an ACP-only one) should error immediately with a clear message,
@@ -354,9 +368,23 @@ export async function delegate(
   // human-confirmed in execute(); command: --allow-dangerous, human-confirmed in the handler). Resolved (and
   // the danger refusal thrown) before acquireSlot() — it's pure, so a refused run never occupies
   // (or, for fan-out, waits for) a concurrency slot it can't use.
-  let permission: NormalizedPermission = template.permission;
-  const nativePerm = template.nativePermission;
-  const nativeClass = classifyNativePermission(harness, nativePerm);
+  const nativeClass = classifyNativePermission(harness, template.nativePermission);
+  // The tier the template actually runs at: a native read-only value (`permission: plan`) is filed
+  // under `edit` by normalizePermission, but runs as `readonly` — recorded as such and, above all,
+  // subject to resolveVerifyPlan's readonly skip. Only ever narrows (never `danger`), and the
+  // canonical native value below is still what reaches argv/ACP.
+  const templateTier: NormalizedPermission =
+    nativeClass === 'safe'
+      ? (nativePermissionTier(harness, template.nativePermission) ?? template.permission)
+      : template.permission;
+  let permission: NormalizedPermission = templateTier;
+  // A safe native matches its allowlist case-insensitively (`Plan`), but what reaches argv/ACP is
+  // always the allowlist's canonical spelling (`plan`, claude's camelCase `acceptEdits`) — never the
+  // template's. Danger/unlisted values keep the template's own spelling (see registry.ts).
+  const nativePerm =
+    nativeClass === 'safe'
+      ? canonicalSafeNativePermission(harness, template.nativePermission)
+      : template.nativePermission;
   const isNativeDanger = nativeClass === 'danger' || nativeClass === 'unlisted';
   if (template.permission === 'danger' || isNativeDanger) {
     if (opts.allowDangerous !== true) {
@@ -381,7 +409,7 @@ export async function delegate(
   const nativePermissionForRun =
     nativeClass === 'unlisted' && permission === 'danger'
       ? nativePerm
-      : resolveNativePermission(template.permission, permission, nativePerm);
+      : resolveNativePermission(templateTier, permission, nativePerm);
 
   const model = resolveModelForHarness(config, harnessName, opts.model, template.model);
   const addDirs = mergeAddDirs(ctx.cwd, template.addDirs, opts.addDirs);
@@ -480,6 +508,7 @@ export async function delegate(
             contextWindow: null,
             activityLog: collectActivityLog(activityEvents),
             output: streamedFull,
+            warning,
           }),
         );
       } catch (_e) {
@@ -548,6 +577,7 @@ export async function delegate(
       output: result.result || result.streamedText,
       verify,
       budget,
+      warning,
     }),
   );
   pruneOutputs(outputsDirFor(harnessName), config.maxTranscripts);
@@ -556,7 +586,7 @@ export async function delegate(
 
   const output = result.result || result.streamedText || '(empty result)';
   return {
-    content: budget?.message ? `${budget.message}\n\n${output}` : output,
+    content: [warning, budget?.message, output].filter(Boolean).join('\n\n'),
     details: {
       harness: harnessName,
       mode,
@@ -580,6 +610,7 @@ export async function delegate(
       usage: result.usage,
       verify,
       budget,
+      permissionWarning: template.permissionWarning ?? null,
     },
     result,
     activityLog: collectActivityLog(activityEvents),

package/extensions/harnesses/amp.ts

@@ -273,6 +273,9 @@ export const ampHarness: Harness = {
   permissionMap: { readonly: ['always-ask'], edit: ['write'], danger: ['yolo'] },
   // `omp --approval-mode` values: always-ask, write, yolo.
   safeNativePermissions: ['always-ask', 'write'],
+  // No `readonlyNativePermissions`: `omp --help` only says `always-ask` asks before tool calls — what a
+  // non-interactive `-p` run does with an unanswerable ask (deny, hang, or proceed) is undocumented and
+  // unverified, so a native `always-ask` stays `edit` (and its `verify:` still runs) until it is.
   // `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

package/extensions/harnesses/claude.ts

@@ -161,6 +161,9 @@ export const claudeHarness: Harness = {
   // `auto` (a classifier auto-approves actions), and `dontAsk` — its effective reach is whatever the
   // user's allow rules grant, which this extension can't see, so it fails closed.
   safeNativePermissions: ['plan', 'acceptEdits', 'manual', 'default'],
+  // `plan` is claude's read-only mode. `manual`/`default` are not listed: under `-p` they deny what
+  // would need approval, but that is a consequence of the user's allow rules, not a no-write mode.
+  readonlyNativePermissions: ['plan'],
   // `--max-budget-usd` (see buildArgs) — claude enforces the cap itself.
   nativeBudget: true,
   // No `acp` subcommand exists (docs/acp-harness-assessment.md §2) — confirmed against the full

package/extensions/harnesses/codex.ts

@@ -293,6 +293,7 @@ export const codexHarness: Harness = {
   permissionMap: { readonly: ['read-only'], edit: ['workspace-write'], danger: ['danger-full-access'] },
   // `codex exec --sandbox` values: read-only, workspace-write, danger-full-access.
   safeNativePermissions: ['read-only', 'workspace-write'],
+  readonlyNativePermissions: ['read-only'],
   // No `acp` subcommand exists; `app-server` is a different, codex-proprietary JSON-RPC protocol,
   // not ACP (docs/acp-harness-assessment.md §2) — confirmed against the full `--help` output of
   // `codex`, `codex mcp-server`, `codex app-server`, and `codex exec`.

package/extensions/harnesses/devin.ts

@@ -208,6 +208,9 @@ export const devinHarness: Harness = {
   // action, which the ACP runner always declines. Not listed (=> danger): `bypass`, and `smart`
   // ("additionally auto-runs actions a fast model judges safe" per `devin --help`).
   safeNativePermissions: ['plan', 'accept-edits', 'ask'],
+  // `ask` is not listed: it is read-only here only because the ACP runner declines every permission
+  // request — a property of this client, not of the mode.
+  readonlyNativePermissions: ['plan'],
   // ACP-only — no stdout mode exists to select between, so there's nothing to configure.
   supportsTransports: ['acp'],
 };

package/extensions/harnesses/opencode.ts

@@ -374,6 +374,9 @@ export const opencodeHarness: Harness = {
   // `--agent <name>` (stdout) / ACP mode id: only the built-in `plan`/`build` agents are known
   // quantities — a user-defined agent can carry any permission config, so it fails closed.
   safeNativePermissions: ['plan', 'build'],
+  // the built-in `plan` agent (stdout) / ACP mode is read-only — live-captured blocking a write
+  // (docs/acp-harness-assessment.md §4).
+  readonlyNativePermissions: ['plan'],
   // ACP path — opt-in only (transport defaults to 'stdout'; see config.ts's resolveTransport).
   // `--model` isn't wired here: `opencode acp --help` has no such flag, unlike `devin acp
   // --model`; the ACP handshake's own `configOptions` "model" category is the real mechanism

package/extensions/harnesses/registry.ts

@@ -3,7 +3,7 @@ import { claudeHarness } from './claude.ts';
 import { codexHarness } from './codex.ts';
 import { devinHarness } from './devin.ts';
 import { opencodeHarness } from './opencode.ts';
-import type { Harness } from './types.ts';
+import type { Harness, NormalizedPermission } from './types.ts';
 
 export const HARNESSES: Record<string, Harness> = {
   claude: claudeHarness,
@@ -54,8 +54,9 @@ export const normalizeHarnessName = resolveHarnessName;
 
 /**
  * Legacy danger spellings, kept for templates written before harnesses were partitioned.
+ * Lowercase: native permissions are compared case-insensitively (see `classifyNativePermission`).
  */
-const LEGACY_DANGER_TOKENS = new Set(['bypassPermissions', 'danger-full-access', 'danger']);
+const LEGACY_DANGER_TOKENS = new Set(['bypasspermissions', 'danger-full-access', 'danger']);
 
 /**
  * How a template's native permission string (`permission: <native>` escape hatch) classifies on
@@ -66,6 +67,13 @@ const LEGACY_DANGER_TOKENS = new Set(['bypassPermissions', 'danger-full-access',
  *   spelling: running it is exactly the harness's normalized danger tier.
  * - `unlisted` — anything else. Treated as danger (fail closed): a permissive mode nobody listed
  *   (claude `auto`, devin `smart`, a custom opencode agent, …) must not slip past the gate.
+ *
+ * Matching is whitespace-trimmed and case-insensitive (`Plan` is claude's `plan`), and the danger
+ * checks run first, so a case variant of a danger token (`BYPASSPERMISSIONS`, `Yolo`) is still
+ * `danger`. A `safe` match is only a classification — the value that reaches argv/`session/set_mode`
+ * must be the allowlist's own spelling, via `canonicalSafeNativePermission` (claude's `acceptEdits`
+ * is camelCase; harness CLIs are case-sensitive, and a custom opencode agent named `PLAN` must
+ * never run in place of the built-in `plan` it was classified as).
  */
 export type NativePermissionClass = 'none' | 'safe' | 'danger' | 'unlisted';
 
@@ -73,15 +81,48 @@ export function classifyNativePermission(
   harness: Harness | undefined,
   nativePermission: string | undefined,
 ): NativePermissionClass {
-  const native = nativePermission?.trim();
+  const native = nativePermission?.trim().toLowerCase();
   if (!native) return 'none';
   if (LEGACY_DANGER_TOKENS.has(native)) return 'danger';
   const danger = harness?.permissionMap?.danger;
-  if (Array.isArray(danger) && danger.length > 0 && native === danger.join(' ')) return 'danger';
-  if (harness?.safeNativePermissions?.includes(native)) return 'safe';
+  if (Array.isArray(danger) && danger.length > 0 && native === danger.join(' ').toLowerCase()) return 'danger';
+  if (canonicalSafeNativePermission(harness, nativePermission) !== undefined) return 'safe';
   return 'unlisted';
 }
 
+/**
+ * The harness's own allowlist spelling of a native permission that matches it case-insensitively
+ * (whitespace-trimmed), or `undefined` when it isn't on the allowlist. Only meaningful for a value
+ * `classifyNativePermission` calls `safe` — that's the one class whose value is ever rewritten.
+ */
+export function canonicalSafeNativePermission(
+  harness: Harness | undefined,
+  nativePermission: string | undefined,
+): string | undefined {
+  const native = nativePermission?.trim().toLowerCase();
+  if (!native) return undefined;
+  return harness?.safeNativePermissions?.find(v => v.toLowerCase() === native);
+}
+
+/**
+ * The normalized tier a native escape-hatch value actually runs at, when it is narrower than the
+ * `edit` tier `normalizePermission` files every native value under: `readonly` for a value on the
+ * harness's `readonlyNativePermissions` (claude/devin/opencode `plan`, codex `read-only`), matched
+ * case-insensitively through the same allowlist as `canonicalSafeNativePermission`. `undefined`
+ * otherwise — the template's own tier stands. Only ever narrows: it never reports `danger`, so it
+ * can't touch the danger gate, and it changes nothing about what reaches argv/ACP (the canonical
+ * native value is still what the harness gets). What it does change is the recorded permission and
+ * `resolveVerifyPlan`'s readonly skip — a native read-only run must never execute a `verify:` command.
+ */
+export function nativePermissionTier(
+  harness: Harness | undefined,
+  nativePermission: string | undefined,
+): NormalizedPermission | undefined {
+  const canonical = canonicalSafeNativePermission(harness, nativePermission);
+  if (canonical === undefined) return undefined;
+  return harness?.readonlyNativePermissions?.includes(canonical) ? 'readonly' : undefined;
+}
+
 /**
  * Does this native permission string require the danger gate on this harness?
  *

package/extensions/harnesses/types.ts

@@ -96,6 +96,13 @@ export interface Harness {
    *  never heard of — is treated as danger (fail closed) by `isNativeDangerPermission` in registry.ts.
    *  Omitted -> no native value is considered safe. Covers both transports' vocabularies. */
   safeNativePermissions?: readonly string[];
+  /** The subset of `safeNativePermissions` that is genuinely read-only (no writes, no command
+   *  execution) on this harness. A native escape-hatch value listed here runs as the normalized
+   *  `readonly` tier — recorded as `readonly` and, crucially, never lets a `verify:` command execute
+   *  host-side (see `resolveVerifyPlan`). Conservative by design: only list a mode whose read-only
+   *  behavior is documented for a non-interactive run; anything else stays `edit`. Must be spelled
+   *  exactly as in `safeNativePermissions` (matching is case-insensitive via that allowlist). */
+  readonlyNativePermissions?: readonly string[];
   /** True when `buildArgs` passes `maxBudgetUsd` to a native CLI budget flag (claude's
    *  `--max-budget-usd`). Otherwise the runners enforce it host-side from the streamed
    *  `totalCostUsd` — possible only when the harness actually reports cost. */

package/extensions/index.ts

@@ -27,7 +27,9 @@ import { formatToolUse, ToolCallIndex } from './activity.ts';
 import {
   aliasUsage,
   delegateUsage,
+  emptyHarnessSpecError,
   isFanoutSpec,
+  normalizeHarnessSpec,
   parseDelegateCommand,
   resolveDefaults,
   resolveHarnessFilter,
@@ -144,8 +146,15 @@ export default function (pi: ExtensionAPI) {
     promptGuidelines: [...DELEGATE_TOOL_GUIDELINES],
     parameters: DELEGATE_TOOL_PARAMS,
     async execute(_toolCallId, rawParams, signal, onUpdate, ctx) {
-      // the deprecated alias pins its harness; everything below sees the effective params
-      const params: DelegateToolParams = spec.forceHarness ? { ...rawParams, harness: spec.forceHarness } : rawParams;
+      // the deprecated alias pins its harness; everything below sees the effective params. The spec is
+      // normalized exactly as /delegate does (normalizeHarnessSpec), so `claude,` is a single run —
+      // fail-fast at capacity, single-run result shape — not a one-harness fan-out, and `omp` is `amp`.
+      // A non-empty spec that normalizes to nothing (`,`, `" , "`) is refused rather than silently run
+      // on the default harness (`""` stays "unset", the way a model omitting the field means it).
+      const harnessSpec = spec.forceHarness ?? rawParams.harness;
+      const harness = harnessSpec === undefined ? undefined : normalizeHarnessSpec(harnessSpec);
+      if (harnessSpec && harness === undefined) throw new Error(emptyHarnessSpecError(harnessSpec));
+      const params: DelegateToolParams = { ...rawParams, harness };
       const config = loadConfig();
       // A model-set allowDangerous is never honored on its own — a human confirms it (or, with no
       // UI to ask, it's refused). Checked once up front, before any fan-out. See validate.ts.
@@ -192,7 +201,7 @@ export default function (pi: ExtensionAPI) {
       };
     },
     renderCall(params, theme) {
-      const harness = params.harness ?? 'delegate';
+      const harness = spec.forceHarness ?? params.harness ?? 'delegate';
       const mode = params.mode ?? 'general';
       const task = params.task ?? '';
       const taskStr = task ? ` — ${task.length > 60 ? `${task.slice(0, 59)}…` : task}` : '';

package/extensions/templates.ts

@@ -23,6 +23,12 @@ export interface DelegateTemplate {
   nativePermission?: string;
   /** Legacy raw permissionMode for transcript compat. */
   permissionMode: PermissionMode;
+  /**
+   * A problem with the template's permission keys, shown in `/delegate list` and at run time: an
+   * unrecognized legacy `permissionMode:`/`sandbox:` value (failed closed to `readonly`), or a
+   * legacy key that disagrees with `permission:` and was ignored (tier unchanged).
+   */
+  permissionWarning?: string;
   model?: string;
   maxBudgetUsd?: number;
   skill?: string;
@@ -36,35 +42,180 @@ export interface DelegateTemplate {
   harness?: string;
 }
 
+/** Tier order, least permissive first — used to pick the safer of two conflicting legacy keys. */
+const TIER_RANK: Record<NormalizedPermission, number> = { readonly: 0, edit: 1, danger: 2 };
+
+const TIER_PERMISSION_MODE: Record<NormalizedPermission, PermissionMode> = {
+  readonly: 'plan',
+  edit: 'acceptEdits',
+  danger: 'bypassPermissions',
+};
+
+/** Claude `PermissionMode` names, matched case- and `-`/`_`-insensitively (`accept-edits` → `acceptEdits`). */
+const PERMISSION_MODES_BY_LOWER = new Map<string, PermissionMode>([...PERMISSION_MODES].map(m => [m.toLowerCase(), m]));
+
+/** Codex `--sandbox` values (the legacy `sandbox:` key) → normalized tier. Keys are lowercase, `_`→`-`. */
+const LEGACY_SANDBOX_TIERS: Record<string, NormalizedPermission> = {
+  'read-only': 'readonly',
+  readonly: 'readonly',
+  'workspace-write': 'edit',
+  'danger-full-access': 'danger',
+};
+
+/**
+ * A frontmatter value echoed back in a warning (`/delegate list`, run-time notes): JSON-quoted so
+ * control characters / ANSI escapes are inert, and capped so a huge value can't flood the line.
+ */
+function quoteValue(value: string): string {
+  return JSON.stringify(value).slice(0, 60);
+}
+
+interface LegacyPermission {
+  permission: NormalizedPermission;
+  permissionMode: PermissionMode;
+  /** Set when a legacy value was unrecognized and the template was failed closed to `readonly`. */
+  permissionWarning?: string;
+}
+
+/**
+ * Map one legacy `permissionMode:`/`sandbox:` value onto a normalized tier. Both keys accept both
+ * vocabularies (claude PermissionMode names and codex sandbox values), case/whitespace/`-`/`_`-insensitive.
+ * Returns `null` for an unrecognized value — the caller fails that closed.
+ */
+function classifyLegacyValue(value: string): Omit<LegacyPermission, 'permissionWarning'> | null {
+  const lower = value.trim().toLowerCase();
+  // Claude names have no separators of their own, so `accept-edits`/`bypass_permissions` can only
+  // ever mean that same name (and tier) — danger stays gated behind allowDangerous downstream.
+  const mode = PERMISSION_MODES_BY_LOWER.get(lower.replace(/[-_]/g, ''));
+  if (mode) {
+    if (mode === 'plan') return { permission: 'readonly', permissionMode: mode };
+    if (mode === 'bypassPermissions') return { permission: 'danger', permissionMode: mode };
+    return { permission: 'edit', permissionMode: mode };
+  }
+  const tier = LEGACY_SANDBOX_TIERS[lower.replace(/_/g, '-')];
+  return tier ? { permission: tier, permissionMode: TIER_PERMISSION_MODE[tier] } : null;
+}
+
+/** The legacy keys actually set (non-empty), as `[key, value]` pairs. */
+function legacyEntries(permissionMode: FrontmatterValues, sandbox: FrontmatterValues): [string, string][] {
+  return [
+    ...values(permissionMode).map(v => ['permissionMode', v] as [string, string]),
+    ...values(sandbox).map(v => ['sandbox', v] as [string, string]),
+  ];
+}
+
+/**
+ * A permission key's value(s): the keys are read case-insensitively and every occurrence is kept
+ * (`sandbox:` + `Sandbox:` is two values), so callers take an array; a single string still works.
+ */
+type FrontmatterValues = string | readonly string[] | undefined;
+
+/** Non-empty trimmed values — an empty value means "not set". */
+function values(v: FrontmatterValues): string[] {
+  return (typeof v === 'string' ? [v] : (v ?? [])).map(x => x.trim()).filter(Boolean);
+}
+
+/**
+ * Legacy `permissionMode:`/`sandbox:` keys → normalized tier. Only consulted when `permission:` is
+ * absent. An empty/absent value means "not set" (default `edit`, as always).
+ *
+ * **Fails closed:** an unrecognized value (a typo, a value from some other harness's vocabulary)
+ * yields `readonly` plus `permissionWarning` — never the old silent `edit`, and never a refusal
+ * to load. Not loading would let a same-named lower tier (e.g. the builtin `implement`, `edit`)
+ * silently win instead, which can be MORE permissive than an author who wrote `sandbox: readonyl`
+ * meant; `readonly` is the one tier that can never exceed what any author meant (and it also skips
+ * `verify:`). When both keys (or several case variants of one) are set, the least permissive wins.
+ */
+export function normalizeLegacyPermission(
+  permissionMode: FrontmatterValues,
+  sandbox: FrontmatterValues,
+): LegacyPermission {
+  const set = legacyEntries(permissionMode, sandbox);
+  if (set.length === 0) return { permission: 'edit', permissionMode: 'acceptEdits' };
+  let best: Omit<LegacyPermission, 'permissionWarning'> | null = null;
+  for (const [key, value] of set) {
+    const c = classifyLegacyValue(value);
+    if (!c) {
+      return {
+        permission: 'readonly',
+        permissionMode: 'plan',
+        permissionWarning: `unrecognized ${key}: ${quoteValue(value)} — loaded as readonly (fail closed)`,
+      };
+    }
+    if (!best || TIER_RANK[c.permission] < TIER_RANK[best.permission]) best = c;
+  }
+  return best as LegacyPermission;
+}
+
 export function normalizePermission(
-  raw: string | undefined,
-  fallbackMode: string | undefined,
-): { permission: NormalizedPermission; nativePermission?: string; permissionMode: PermissionMode } {
+  raw: FrontmatterValues,
+  fallbackMode: FrontmatterValues,
+  sandbox?: FrontmatterValues,
+): {
+  permission: NormalizedPermission;
+  nativePermission?: string;
+  permissionMode: PermissionMode;
+  permissionWarning?: string;
+} {
   // Prefer normalized permission
-  if (raw) {
-    const lower = raw.trim().toLowerCase();
-    if (lower === 'readonly' || lower === 'read-only' || lower === 'read_only')
-      return { permission: 'readonly', permissionMode: 'plan' };
-    if (lower === 'edit' || lower === 'acceptedits' || lower === 'accept-edits')
-      return { permission: 'edit', permissionMode: 'acceptEdits' };
-    if (
-      lower === 'danger' ||
-      lower === 'bypasspermissions' ||
-      lower === 'danger-full-access' ||
-      lower === 'danger_full_access'
-    )
-      return { permission: 'danger', permissionMode: 'bypassPermissions' };
-    // Unknown native — treat as native escape hatch
-    return { permission: 'edit', nativePermission: raw.trim(), permissionMode: 'acceptEdits' };
+  const raws = values(raw);
+  if (raws.length > 1) {
+    // `permission:` given more than once (e.g. `permission:` and `Permission:`) — the same tier is
+    // fine; disagreeing tiers take the least permissive, and a disagreement involving a native value
+    // (whose tier is per-harness, so not comparable here) fails closed to readonly. Never "last wins".
+    const all = raws.map(normalizeTierValue);
+    const distinct = new Set(all.map(r => `${r.permission}|${r.nativePermission ?? ''}`));
+    if (distinct.size > 1) {
+      const listed = raws.map(quoteValue).join(', ');
+      if (all.some(r => r.nativePermission))
+        return {
+          permission: 'readonly',
+          permissionMode: 'plan',
+          permissionWarning: `conflicting permission: values ${listed} — loaded as readonly (fail closed)`,
+        };
+      const least = all.reduce((a, b) => (TIER_RANK[b.permission] < TIER_RANK[a.permission] ? b : a));
+      return {
+        ...least,
+        permissionWarning: `conflicting permission: values ${listed} — using the least permissive, ${least.permission}`,
+      };
+    }
   }
-  // Legacy permissionMode mapping
-  if (fallbackMode && PERMISSION_MODES.has(fallbackMode as PermissionMode)) {
-    const m = fallbackMode as PermissionMode;
-    if (m === 'plan') return { permission: 'readonly', permissionMode: m };
-    if (m === 'bypassPermissions') return { permission: 'danger', permissionMode: m };
-    return { permission: 'edit', permissionMode: m };
+  if (raws.length > 0) {
+    const resolved = normalizeTierValue(raws[0]);
+    // `permission:` always wins; a legacy key that disagrees is ignored, but said so — an author who
+    // wrote `sandbox: read-only` next to `permission: edit` should see which one ran. Skipped for a
+    // native value: its tier is only known per harness at run time, so "disagrees" isn't decidable here.
+    const legacy = legacyEntries(fallbackMode, sandbox);
+    if (resolved.nativePermission || legacy.length === 0) return resolved;
+    const l = normalizeLegacyPermission(fallbackMode, sandbox);
+    if (!l.permissionWarning && l.permission === resolved.permission) return resolved;
+    const ignored = legacy.map(([k, v]) => `${k}: ${quoteValue(v)}`).join(', ');
+    return { ...resolved, permissionWarning: `permission: ${resolved.permission} overrides ${ignored} (ignored)` };
   }
-  return { permission: 'edit', permissionMode: 'acceptEdits' };
+  // Legacy permissionMode/sandbox mapping — fails closed to readonly on an unrecognized value
+  return normalizeLegacyPermission(fallbackMode, sandbox);
+}
+
+/** One `permission:` value → tier, or (unknown value) the native escape hatch. */
+function normalizeTierValue(raw: string): {
+  permission: NormalizedPermission;
+  nativePermission?: string;
+  permissionMode: PermissionMode;
+} {
+  const lower = raw.trim().toLowerCase();
+  if (lower === 'readonly' || lower === 'read-only' || lower === 'read_only')
+    return { permission: 'readonly', permissionMode: 'plan' };
+  if (lower === 'edit' || lower === 'acceptedits' || lower === 'accept-edits')
+    return { permission: 'edit', permissionMode: 'acceptEdits' };
+  if (
+    lower === 'danger' ||
+    lower === 'bypasspermissions' ||
+    lower === 'danger-full-access' ||
+    lower === 'danger_full_access'
+  )
+    return { permission: 'danger', permissionMode: 'bypassPermissions' };
+  // Unknown native — treat as native escape hatch
+  return { permission: 'edit', nativePermission: raw.trim(), permissionMode: 'acceptEdits' };
 }
 
 /** Comma-separated frontmatter list (`a, b`) — undefined when absent or empty. */
@@ -76,33 +227,50 @@ function parseList(raw: string | undefined): string[] | undefined {
   return items.length > 0 ? items : undefined;
 }
 
+type PermissionKey = 'permission' | 'permissionMode' | 'sandbox';
+const PERMISSION_KEYS = new Map<string, PermissionKey>([
+  ['permission', 'permission'],
+  ['permissionmode', 'permissionMode'],
+  ['sandbox', 'sandbox'],
+]);
+
 /** Parse a template file: frontmatter (---\nkey: value\n---) + markdown body. */
 export function parseTemplate(text: string): DelegateTemplate | null {
   const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text.trimStart());
   if (!m) return null;
 
   const meta: Record<string, string> = {};
+  // The keys that decide the tier are matched case-insensitively and keep every occurrence: an
+  // exact-case lookup let `Sandbox: read-only` be silently ignored (→ the `edit` default, verify on).
+  const perm: Record<PermissionKey, string[]> = { permission: [], permissionMode: [], sandbox: [] };
   for (const line of m[1].split('\n')) {
     const i = line.indexOf(':');
     if (i <= 0) continue;
-    meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    const key = line.slice(0, i).trim();
+    const value = line.slice(i + 1).trim();
+    const permKey = PERMISSION_KEYS.get(key.toLowerCase());
+    if (permKey) perm[permKey].push(value);
+    else meta[key] = value;
   }
 
   const name = meta.name?.trim();
   if (!name) return null;
 
-  const permRaw = meta.permission?.trim();
-  const permModeRaw = meta.permissionMode?.trim() ?? meta.sandbox?.trim();
-  const norm = normalizePermission(permRaw, permModeRaw);
+  const norm = normalizePermission(perm.permission, perm.permissionMode, perm.sandbox);
 
   const budget = meta.maxBudgetUsd ? Number(meta.maxBudgetUsd) : NaN;
+  const description = meta.description ?? '';
 
   return {
     name,
-    description: meta.description ?? '',
+    // A permission-key problem is surfaced where the template is listed (`/delegate list`).
+    description: norm.permissionWarning
+      ? `⚠ ${norm.permissionWarning}${description ? ` · ${description}` : ''}`
+      : description,
     permission: norm.permission,
     nativePermission: norm.nativePermission,
     permissionMode: norm.permissionMode,
+    permissionWarning: norm.permissionWarning,
     model: meta.model || undefined,
     maxBudgetUsd: Number.isFinite(budget) && budget > 0 ? budget : undefined,
     skill: meta.skill || undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Delegate work to any harness (Claude Code, Muse, OpenCode, Amp, Devin) from the pi coding agent \u2014 code reviews, plans, implementation, security audits, docs, or your own custom templates.",
   "type": "module",
   "packageManager": "bun@1.3.14",