pi-harness-delegate 0.7.3 → 0.8.0

package/extensions/sanitize.ts

@@ -0,0 +1,85 @@
+/**
+ * The one sanitizer for template-authored text shown to a model or a terminal (`delegate_modes`,
+ * `/delegate list`). Template files are attacker-influenceable in a trusted-but-hostile repo, so
+ * everything a reader could be fooled by — terminal escapes, invisible characters, stacked combining
+ * marks, homoglyph names — is neutralized here, in one place, rather than per call site.
+ */
+
+// ANSI CSI / OSC / two-byte escape sequences.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping terminal escapes is the point
+const ANSI_RE = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u001b[@-Z\\-_]/g;
+
+/**
+ * Characters that render as nothing (or act on the terminal) but that a model still reads:
+ *
+ * - `\p{Cc}` C0/C1 controls and DEL (U+009B is the 8-bit CSI);
+ * - `\p{Cf}` every format character — soft hyphen, Arabic letter mark, Mongolian vowel separator,
+ *   zero-width space/joiners, bidi marks/embeddings/overrides/isolates (Trojan Source), word joiner
+ *   and invisible operators, BOM, interlinear annotation anchors, the invisible musical-notation
+ *   formatters, and Unicode tag characters U+E0000–E007F ("ASCII smuggling");
+ * - `\p{Zl}`/`\p{Zp}` line / paragraph separators;
+ * - `\p{Co}` private-use characters (no standard glyph — free to mean anything to a font or model);
+ * - invisible characters outside those categories: variation selectors (U+FE00–FE0F, U+E0100–E01EF),
+ *   the combining grapheme joiner U+034F, the Hangul fillers U+115F/U+1160/U+3164/U+FFA0, the Khmer
+ *   inherent vowels U+17B4/U+17B5, and the blank Braille pattern U+2800;
+ * - the whole U+2060–U+206F and U+E0000–U+E007F (tag) blocks by range, including their unassigned
+ *   code points, which `\p{Cf}` alone would miss.
+ *
+ * The one shared set: `sanitizeTemplateText` strips it (discovery output), `quoteValue` (templates.ts)
+ * escapes it as `\uXXXX` (permission/field warnings). Only the character set is shared — each channel
+ * keeps its own treatment. Never add a second list elsewhere; widen this one.
+ */
+// Built from a string so the escapes stay escapes (a formatter would otherwise inline them as literal
+// invisible characters).
+export const INVISIBLE_OR_CONTROL_RE = new RegExp(
+  [
+    '[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Co}',
+    '\\u034f\\u115f\\u1160\\u17b4\\u17b5\\u2800\\u3164\\ufe00-\\ufe0f\\uffa0\\u{e0100}-\\u{e01ef}',
+    '\\u2060-\\u206f\\u{e0000}-\\u{e007f}]',
+  ].join(''),
+  'gu',
+);
+
+/** At most this many combining marks in a row survive — enough for real scripts, not for "Zalgo". */
+export const MAX_COMBINING_RUN = 2;
+const COMBINING_RUN_RE = new RegExp(`(\\p{M}{${MAX_COMBINING_RUN}})\\p{M}+`, 'gu');
+
+/** Cap `text` at `max` code points (with `…`), never leaving half a surrogate pair behind. */
+function capText(text: string, max: number): string {
+  const chars = Array.from(text);
+  return chars.length > max ? `${chars.slice(0, Math.max(0, max - 1)).join('')}…` : text;
+}
+
+/**
+ * Template-authored free text made safe to show: ANSI escapes removed, invisible / control
+ * characters (`INVISIBLE_OR_CONTROL_RE`) replaced by a space, runs of combining marks cut to
+ * `MAX_COMBINING_RUN`, whitespace (including newlines) collapsed to one line, capped at `max`.
+ */
+export function sanitizeTemplateText(text: string, max: number): string {
+  const clean = text
+    .replace(ANSI_RE, '')
+    .replace(INVISIBLE_OR_CONTROL_RE, ' ')
+    .replace(COMBINING_RUN_RE, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return capText(clean, max);
+}
+
+/**
+ * An identifier (a mode name, a model name) made safe **and unambiguous** to show: sanitized as
+ * above, then every character outside printable ASCII escaped as `\u{…}`, so a homoglyph or
+ * mixed-script name (`reviеw` with a Cyrillic `е`) can never look identical to a real one (`review`).
+ * `escaped` says whether anything was escaped, for a warning alongside it.
+ */
+export function sanitizeIdentifier(text: string, max: number): { text: string; escaped: boolean } {
+  const clean = sanitizeTemplateText(text, Number.MAX_SAFE_INTEGER);
+  let escaped = false;
+  const ascii = Array.from(clean)
+    .map(ch => {
+      if (/^[\x20-\x7e]$/.test(ch)) return ch;
+      escaped = true;
+      return `\\u{${(ch.codePointAt(0) ?? 0).toString(16)}}`;
+    })
+    .join('');
+  return { text: capText(ascii, max), escaped };
+}

package/extensions/subcommands.ts

@@ -16,34 +16,34 @@ import {
   writeDelegateConfig,
 } from './config.ts';
 import { isProjectTrusted } from './engine.ts';
-import { ALIASES, detectAll, getHarness, HARNESS_NAMES, isKnownHarness } from './harnesses/registry.ts';
+import {
+  ALIASES,
+  detectAll,
+  getHarness,
+  HARNESS_NAMES,
+  isKnownHarness,
+  resolveHarnessName,
+} from './harnesses/registry.ts';
 import { readAllHistory } from './history.ts';
-import { type DelegateTemplate, loadTemplates } from './templates.ts';
-export function formatTemplateRow(t: DelegateTemplate): string {
-  const parts = [
-    t.name,
-    `[${t.permission}]`,
-    t.model ? `model=${t.model}` : '',
-    t.defaultTask ? '↳ default task' : '',
-    t.harness ? `(${t.harness})` : '',
-  ];
-  return `${parts.filter(Boolean).join('  ')}  —  ${t.description}`;
-}
-
+import { collectModes, formatModeRow, formatOmitted } from './modes.ts';
+import { loadTemplates, projectTemplatePresence } from './templates.ts';
+/**
+ * `/delegate list [harness]` — the same read-only discovery data (`collectModes`) the model's
+ * `delegate_modes` tool sees, one row per mode: per-harness tier, source tier, defaults, sanitized
+ * description. Project-local templates only when the project is trusted, as for a run.
+ */
 export async function showModes(ctx: ExtensionContext, harnessFilter?: string): Promise<void> {
-  const all = new Map<string, DelegateTemplate>();
   const trusted = isProjectTrusted(ctx);
-  // collect from all harnesses if no filter
-  if (harnessFilter) {
-    for (const [k, v] of loadTemplates(ctx.cwd, harnessFilter, trusted)) all.set(k, v);
-  } else {
-    for (const h of [...HARNESS_NAMES, 'shared']) {
-      for (const [k, v] of loadTemplates(ctx.cwd, h, trusted)) if (!all.has(k)) all.set(k, v);
-    }
-    // also load without harness param
-    for (const [k, v] of loadTemplates(ctx.cwd, undefined, trusted)) if (!all.has(k)) all.set(k, v);
-  }
-  const rows = [...all.values()].map(formatTemplateRow);
+  const report = collectModes(
+    ctx.cwd,
+    trusted,
+    harnessFilter ? [harnessFilter] : HARNESS_NAMES,
+    resolveHarnessName(loadConfigWithSource().config.defaultHarness),
+  );
+  const rows = report.modes.map(formatModeRow);
+  if (report.omitted > 0) rows.push(`… +${report.omitted} more not shown (${formatOmitted(report)})`);
+  if (!trusted && projectTemplatePresence(ctx.cwd, HARNESS_NAMES).dirs.length > 0)
+    rows.push('(project untrusted — its project-local templates were not loaded; see /delegate status)');
   if (!ctx.hasUI) {
     process.stdout.write(`${rows.join('\n')}\n`);
     return;

package/extensions/templates.ts

@@ -3,6 +3,10 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { NormalizedPermission } from './harnesses/types.ts';
+import { INVISIBLE_OR_CONTROL_RE } from './sanitize.ts';
+
+/** Where a loaded template came from: shipped with the package, the user's own dirs, or the project. */
+export type TemplateSource = 'builtin' | 'user' | 'project';
 
 export type PermissionMode = 'plan' | 'acceptEdits' | 'bypassPermissions' | 'dontAsk' | 'auto' | 'manual';
 
@@ -29,6 +33,12 @@ export interface DelegateTemplate {
    * legacy key that disagrees with `permission:` and was ignored (tier unchanged).
    */
   permissionWarning?: string;
+  /**
+   * Set when `permission:` is a native value and legacy `permissionMode:`/`sandbox:` keys were also
+   * present (and ignored). Whether they *disagree* depends on the native value's tier, which is only
+   * known per harness — so `delegate()` decides, via `nativeOverrideWarning()`. Never changes the tier.
+   */
+  ignoredLegacyPermission?: IgnoredLegacyPermission;
   model?: string;
   maxBudgetUsd?: number;
   skill?: string;
@@ -40,6 +50,95 @@ export interface DelegateTemplate {
   addDirs?: string[];
   prompt: string;
   harness?: string;
+  /** Which tier this template was loaded from — set by `loadTemplates`, absent from `parseTemplate`. */
+  source?: TemplateSource;
+  /**
+   * Per-run harness timeout in seconds (`timeout: 900`), an integer within
+   * [`TEMPLATE_TIMEOUT_MIN_SEC`, `TEMPLATE_TIMEOUT_MAX_SEC`]. An out-of-range or non-integer value is
+   * ignored (the config timeout applies) and reported in `fieldWarnings`. See `resolveRunTimeoutMs`.
+   */
+  timeoutSec?: number;
+  /**
+   * Default harness(es) for this mode (`harnesses: codex` or `harnesses: claude, codex`), used ONLY
+   * when the caller names no harness. Lowercased; well-formed but unknown names are kept so the
+   * existing fan-out reporting (`resolveHarnessList`) names them. Never widens permission. Several
+   * names make a run with no harness a fan-out on both the `/delegate` command and the `delegate`
+   * tool — see `templateHarnessDefault` (command.ts).
+   */
+  harnesses?: string[];
+  /**
+   * Non-permission frontmatter problems (an invalid `timeout:`, a rejected `harnesses:` entry):
+   * the value was ignored and the default applies. Shown in `/delegate list`, `delegate_modes` and
+   * at run time — never silently dropped.
+   */
+  fieldWarnings?: string[];
+}
+
+/** Bounds for a template's `timeout:` (seconds). A template can never raise a run past the max. */
+export const TEMPLATE_TIMEOUT_MIN_SEC = 10;
+export const TEMPLATE_TIMEOUT_MAX_SEC = 7200;
+
+const HARNESS_NAME_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+
+/**
+ * `harnesses:` frontmatter → a deduped, lowercased list. `all` is refused (a template must name
+ * its harnesses — `all` would silently fan out, and multiply spend, to whatever happens to be
+ * installed) and so is anything that isn't a plain harness-shaped word; both are reported as
+ * warnings and dropped. Unknown-but-well-formed names are kept for the run-time reporting.
+ */
+export function parseTemplateHarnesses(raw: string | undefined): { harnesses?: string[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const out: string[] = [];
+  for (const item of parseList(raw) ?? []) {
+    const name = item.toLowerCase();
+    if (name === 'all') {
+      warnings.push('harnesses: "all" ignored — name the harnesses explicitly');
+      continue;
+    }
+    if (!HARNESS_NAME_RE.test(name)) {
+      warnings.push(`harnesses: entry ${quoteValue(item)} ignored — not a harness name`);
+      continue;
+    }
+    if (!out.includes(name)) out.push(name);
+  }
+  return { harnesses: out.length > 0 ? out : undefined, warnings };
+}
+
+/** `timeout:` frontmatter → seconds, or a warning (value ignored) when it isn't a bounded integer. */
+export function parseTemplateTimeout(raw: string | undefined): { timeoutSec?: number; warning?: string } {
+  const v = raw?.trim();
+  if (!v) return {};
+  const n = /^\d{1,9}$/.test(v) ? Number(v) : NaN;
+  if (Number.isInteger(n) && n >= TEMPLATE_TIMEOUT_MIN_SEC && n <= TEMPLATE_TIMEOUT_MAX_SEC) return { timeoutSec: n };
+  return {
+    warning: `timeout: ${quoteValue(v)} ignored — must be a whole number of seconds from ${TEMPLATE_TIMEOUT_MIN_SEC} to ${TEMPLATE_TIMEOUT_MAX_SEC}; the configured timeout applies`,
+  };
+}
+
+/**
+ * A per-call timeout (`delegate` tool `timeoutSec`, `/delegate --timeout=<sec>`) must be a whole
+ * number of seconds within the same bounds as a template's `timeout:`. Unlike a bad frontmatter
+ * value (ignored with a warning — the template author isn't there to ask), a bad per-call value is
+ * an error: the caller asked for a specific limit we can't honor. `null` when valid.
+ */
+export function callTimeoutError(sec: unknown): string | null {
+  if (
+    typeof sec === 'number' &&
+    Number.isInteger(sec) &&
+    sec >= TEMPLATE_TIMEOUT_MIN_SEC &&
+    sec <= TEMPLATE_TIMEOUT_MAX_SEC
+  )
+    return null;
+  const shown =
+    typeof sec === 'number' && Number.isFinite(sec) ? String(sec) : JSON.stringify(String(sec)).slice(0, 40);
+  return `timeout must be a whole number of seconds from ${TEMPLATE_TIMEOUT_MIN_SEC} to ${TEMPLATE_TIMEOUT_MAX_SEC} (got ${shown})`;
+}
+
+/** The legacy keys ignored next to a native `permission:` value — keys already sanitized (`displayKey`). */
+export interface IgnoredLegacyPermission {
+  /** The `permission:` key as the author spelled it. */
+  permissionKey: string;
+  legacy: FrontmatterEntry[];
 }
 
 /** Tier order, least permissive first — used to pick the safer of two conflicting legacy keys. */
@@ -62,12 +161,23 @@ const LEGACY_SANDBOX_TIERS: Record<string, NormalizedPermission> = {
   'danger-full-access': 'danger',
 };
 
+/** Each match → `\uXXXX` (per UTF-16 code unit), so it is visible and inert. */
+function escapeInvisible(text: string): string {
+  return text.replace(INVISIBLE_OR_CONTROL_RE, ch =>
+    Array.from({ length: ch.length }, (_, i) => `\\u${ch.charCodeAt(i).toString(16).padStart(4, '0')}`).join(''),
+  );
+}
+
 /**
- * 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.
+ * A frontmatter-derived string echoed back in a warning (`/delegate list`, run-time notes): JSON-quoted
+ * so C0 controls / ANSI escapes are inert, the characters `JSON.stringify` leaves raw (C1, bidi,
+ * zero-width, U+2028/9, tag characters, … — the shared `INVISIBLE_OR_CONTROL_RE` set from
+ * `sanitize.ts`) escaped as `\uXXXX` too, and capped at `max` chars so a huge value can't flood the
+ * line. Escaped rather than stripped (unlike `sanitizeTemplateText`): a warning must show what the
+ * author actually wrote.
  */
-function quoteValue(value: string): string {
-  return JSON.stringify(value).slice(0, 60);
+export function quoteValue(value: string, max = 60): string {
+  return escapeInvisible(JSON.stringify(value)).slice(0, max);
 }
 
 interface LegacyPermission {
@@ -96,23 +206,48 @@ function classifyLegacyValue(value: string): Omit<LegacyPermission, 'permissionW
   return tier ? { permission: tier, permissionMode: TIER_PERMISSION_MODE[tier] } : null;
 }
 
-/** The legacy keys actually set (non-empty), as `[key, value]` pairs. */
+/** The legacy keys actually set (non-empty), as `[key, value]` pairs — `key` as the author spelled it. */
 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]),
-  ];
+  return [...entries(permissionMode, 'permissionMode'), ...entries(sandbox, 'sandbox')];
+}
+
+/** One occurrence of a permission key: its value, plus the key as the author spelled it (`Sandbox`). */
+export interface FrontmatterEntry {
+  key: string;
+  value: 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.
+ * A bare string element is attributed to the canonical key; a `FrontmatterEntry` keeps the author's.
  */
-type FrontmatterValues = string | readonly string[] | undefined;
+type FrontmatterValues = string | readonly (string | FrontmatterEntry)[] | undefined;
+
+/** Non-empty trimmed `[key, value]` pairs — an empty value means "not set". */
+function entries(v: FrontmatterValues, canonical: string): [string, string][] {
+  return (typeof v === 'string' ? [v] : (v ?? []))
+    .map((x): [string, string] =>
+      typeof x === 'string' ? [canonical, x.trim()] : [displayKey(x.key, canonical), x.value.trim()],
+    )
+    .filter(([, value]) => value !== '');
+}
 
 /** 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);
+  return entries(v, '').map(([, value]) => value);
+}
+
+/**
+ * A frontmatter key echoed back in a warning: the author's own spelling (`Sandbox`, `SANDBOX`) so
+ * the warning points at the line they actually wrote — but only when it is a plain case variant of
+ * the canonical key made of `[A-Za-z_]` (capped). Keys come from template files a hostile project
+ * controls, so anything else (control chars, ANSI escapes, Unicode look-alikes) falls back to the
+ * canonical name rather than reaching the terminal.
+ */
+export function displayKey(raw: string, canonical: string): string {
+  const key = raw.trim();
+  return /^[A-Za-z_]{1,32}$/.test(key) && key.toLowerCase() === canonical.toLowerCase() ? key : canonical;
 }
 
 /**
@@ -156,6 +291,7 @@ export function normalizePermission(
   nativePermission?: string;
   permissionMode: PermissionMode;
   permissionWarning?: string;
+  ignoredLegacyPermission?: IgnoredLegacyPermission;
 } {
   // Prefer normalized permission
   const raws = values(raw);
@@ -166,36 +302,87 @@ export function normalizePermission(
     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}`,
-      };
+      const listed = raws.map(v => quoteValue(v)).join(', ');
+      const least = all.some(r => r.nativePermission)
+        ? undefined
+        : all.reduce((a, b) => (TIER_RANK[b.permission] < TIER_RANK[a.permission] ? b : a));
+      const resolved = least
+        ? {
+            ...least,
+            permissionWarning: `conflicting permission: values ${listed} — using the least permissive, ${least.permission}`,
+          }
+        : {
+            permission: 'readonly' as const,
+            permissionMode: 'plan' as const,
+            permissionWarning: `conflicting permission: values ${listed} — loaded as readonly (fail closed)`,
+          };
+      // Legacy keys are ignored here too — judged against the tier this resolved to, and appended
+      // rather than dropped (no native value survives this branch, so delegate() can't judge them).
+      const [[permissionKey]] = entries(raw, 'permission');
+      const ignored = legacyOverrideWarning(
+        `${permissionKey}: ${resolved.permission}`,
+        resolved.permission,
+        legacyEntries(fallbackMode, sandbox),
+      );
+      return ignored ? { ...resolved, permissionWarning: `${resolved.permissionWarning}; ${ignored}` } : resolved;
     }
   }
   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.
+    // wrote `sandbox: read-only` next to `permission: edit` should see which one ran. For a native
+    // value the tier is only known per harness, so the ignored keys are carried for delegate() to judge.
     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)` };
+    if (legacy.length === 0) return resolved;
+    const [[permissionKey]] = entries(raw, 'permission');
+    if (resolved.nativePermission)
+      return {
+        ...resolved,
+        ignoredLegacyPermission: { permissionKey, legacy: legacy.map(([key, value]) => ({ key, value })) },
+      };
+    const warning = legacyOverrideWarning(`${permissionKey}: ${resolved.permission}`, resolved.permission, legacy);
+    return warning ? { ...resolved, permissionWarning: warning } : resolved;
   }
   // Legacy permissionMode/sandbox mapping — fails closed to readonly on an unrecognized value
   return normalizeLegacyPermission(fallbackMode, sandbox);
 }
 
+/**
+ * `<label> overrides <legacy keys> (ignored)` unless every ignored legacy value is recognized and maps
+ * to exactly `tier` — so one that disagrees with `tier`, one that is unrecognized, or ignored keys that
+ * disagree with each other (`sandbox: read-only` + `Sandbox: workspace-write`, even when the least
+ * permissive of them matches `tier`) are all flagged; `undefined` when there are none or they all
+ * agree. Keys are echoed as given (already `displayKey`-sanitized), values quoted via `quoteValue`.
+ */
+function legacyOverrideWarning(
+  label: string,
+  tier: NormalizedPermission,
+  legacy: readonly [string, string][],
+): string | undefined {
+  if (legacy.every(([, v]) => classifyLegacyValue(v)?.permission === tier)) return undefined;
+  const ignored = legacy.map(([k, v]) => `${k}: ${quoteValue(v)}`).join(', ');
+  return `${label} overrides ${ignored} (ignored)`;
+}
+
+/**
+ * The run-time counterpart of the override warning for a native `permission:` value: `delegate()`
+ * passes the tier that value actually runs at on `harnessName` (readonly/edit for an allowlisted
+ * value, danger for one gated as danger); `harnessName` must be the canonical, registry-resolved
+ * name (it is echoed unquoted). Only a warning — the tier is never changed by it.
+ */
+export function nativeOverrideWarning(
+  ignored: IgnoredLegacyPermission,
+  nativePermission: string,
+  tier: NormalizedPermission,
+  harnessName: string,
+): string | undefined {
+  return legacyOverrideWarning(
+    `${ignored.permissionKey}: ${quoteValue(nativePermission)} (${tier} on ${harnessName})`,
+    tier,
+    ignored.legacy.map(e => [e.key, e.value]),
+  );
+}
+
 /** One `permission:` value → tier, or (unknown value) the native escape hatch. */
 function normalizeTierValue(raw: string): {
   permission: NormalizedPermission;
@@ -242,14 +429,15 @@ export function parseTemplate(text: string): DelegateTemplate | 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: [] };
+  // Each occurrence keeps the author's key spelling, so a warning names the line they wrote.
+  const perm: Record<PermissionKey, FrontmatterEntry[]> = { permission: [], permissionMode: [], sandbox: [] };
   for (const line of m[1].split('\n')) {
     const i = line.indexOf(':');
     if (i <= 0) continue;
     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);
+    if (permKey) perm[permKey].push({ key, value });
     else meta[key] = value;
   }
 
@@ -260,6 +448,11 @@ export function parseTemplate(text: string): DelegateTemplate | null {
 
   const budget = meta.maxBudgetUsd ? Number(meta.maxBudgetUsd) : NaN;
   const description = meta.description ?? '';
+  const fieldWarnings: string[] = [];
+  const timeout = parseTemplateTimeout(meta.timeout);
+  if (timeout.warning) fieldWarnings.push(timeout.warning);
+  const harnesses = parseTemplateHarnesses(meta.harnesses);
+  fieldWarnings.push(...harnesses.warnings);
 
   return {
     name,
@@ -271,6 +464,7 @@ export function parseTemplate(text: string): DelegateTemplate | null {
     nativePermission: norm.nativePermission,
     permissionMode: norm.permissionMode,
     permissionWarning: norm.permissionWarning,
+    ignoredLegacyPermission: norm.ignoredLegacyPermission,
     model: meta.model || undefined,
     maxBudgetUsd: Number.isFinite(budget) && budget > 0 ? budget : undefined,
     skill: meta.skill || undefined,
@@ -280,16 +474,19 @@ export function parseTemplate(text: string): DelegateTemplate | null {
     addDirs: parseList(meta.addDirs),
     prompt: m[2].trim(),
     harness: meta.harness || undefined,
+    timeoutSec: timeout.timeoutSec,
+    harnesses: harnesses.harnesses,
+    fieldWarnings: fieldWarnings.length > 0 ? fieldWarnings : undefined,
   };
 }
 
-function loadDir(dir: string, out: Map<string, DelegateTemplate>): void {
+function loadDir(dir: string, out: Map<string, DelegateTemplate>, source: TemplateSource): void {
   if (!existsSync(dir)) return;
   for (const f of readdirSync(dir)) {
     if (!f.endsWith('.md')) continue;
     try {
       const t = parseTemplate(readFileSync(join(dir, f), 'utf8'));
-      if (t) out.set(t.name, t);
+      if (t) out.set(t.name, { ...t, source });
     } catch {
       // skip unreadable files
     }
@@ -342,20 +539,20 @@ export function loadTemplates(cwd: string, harnessName?: string, trusted = false
   const out = new Map<string, DelegateTemplate>();
   const harness = harnessName ?? 'claude';
   // legacy root builtins (templates/*.md) lowest — for migration from pi-claude-delegate
-  loadDir(builtinTemplatesDir(), out);
+  loadDir(builtinTemplatesDir(), out, 'builtin');
   // shared canonical bodies
-  loadDir(sharedTemplatesDir(), out);
+  loadDir(sharedTemplatesDir(), out, 'builtin');
   // harness-specific builtins override shared
-  loadDir(builtinHarnessTemplatesDir(harness), out);
+  loadDir(builtinHarnessTemplatesDir(harness), out, 'builtin');
   // user globals: legacy before new so new wins
-  loadDir(legacyUserTemplatesDir(), out);
-  loadDir(userTemplatesDir(), out);
-  loadDir(userTemplatesDir(harness), out);
+  loadDir(legacyUserTemplatesDir(), out, 'user');
+  loadDir(userTemplatesDir(), out, 'user');
+  loadDir(userTemplatesDir(harness), out, 'user');
   // project locals: legacy before new so new wins — only if trusted
   if (trusted) {
-    loadDir(legacyProjectTemplatesDir(cwd), out);
-    loadDir(projectTemplatesDir(cwd), out);
-    loadDir(projectTemplatesDir(cwd, harness), out);
+    loadDir(legacyProjectTemplatesDir(cwd), out, 'project');
+    loadDir(projectTemplatesDir(cwd), out, 'project');
+    loadDir(projectTemplatesDir(cwd, harness), out, 'project');
   }
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "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",