pi-harness-delegate 0.7.1 → 0.7.3

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.1",
+  "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",
@@ -40,6 +40,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "verify": "bun run lint && bun run typecheck && bun run test",