pi-harness-delegate 0.7.1 → 0.7.3

package/extensions/harnesses/devin.ts

@@ -39,7 +39,8 @@ function isRecord(v: unknown): v is Record<string, unknown> {
 }
 
 /** Exact structural match to Claude's tiers (session/new's captured `availableModes`: plan, accept-edits,
- *  smart, ask, bypass). `smart`/`ask` stay reachable via the existing `nativePermission` escape hatch. */
+ *  smart, ask, bypass). `smart`/`ask` stay reachable via the existing `nativePermission` escape hatch
+ *  (`smart` only as danger — see `safeNativePermissions`). */
 const PERMISSION_MAP: Record<NormalizedPermission, string> = {
   readonly: 'plan',
   edit: 'accept-edits',
@@ -203,6 +204,13 @@ export const devinHarness: Harness = {
     edit: [PERMISSION_MAP.edit],
     danger: [PERMISSION_MAP.danger],
   },
+  // ACP `availableModes` (fixture): accept-edits, smart, ask, plan, bypass. `ask` prompts for every
+  // 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

@@ -371,6 +371,12 @@ export const opencodeHarness: Harness = {
     return null;
   },
   permissionMap: { readonly: ['plan'], edit: ['build'], danger: ['build', '--auto'] },
+  // `--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,29 +54,92 @@ 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']);
 
 /**
- * Does this native permission string mean "unrestricted" for this harness?
+ * How a template's native permission string (`permission: <native>` escape hatch) classifies on
+ * this harness:
+ * - `none` — no native permission declared.
+ * - `safe` — on the harness's `safeNativePermissions` allowlist (readonly/edit-equivalent).
+ * - `danger` — the harness's own danger mode (`permissionMap.danger`, joined) or a legacy danger
+ *   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';
+
+export function classifyNativePermission(
+  harness: Harness | undefined,
+  nativePermission: string | undefined,
+): NativePermissionClass {
+  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(' ').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?
  *
  * A template can declare any native mode via the escape hatch (`permission: <native>`), and
  * `normalizePermission` files anything unrecognised under `nativePermission` with a normalized
- * tier of `edit`. Without this check, a template declaring `yolo` (amp) or `bypass` (devin) would
- * skip the `allowDangerous` gate entirely and run the harness unsandboxed while `delegate()`
- * recorded the run as `edit` — breaking the invariant that danger is only ever reachable through
- * an explicit per-call `allowDangerous: true`.
+ * tier of `edit`. This used to be a denylist (the harness's own danger mode + legacy spellings),
+ * so a permissive mode that wasn't listed ran unsandboxed while recorded as `edit`. It is now an
+ * allowlist: only values in the harness's `safeNativePermissions` pass as non-danger; everything
+ * else needs an explicit per-call `allowDangerous: true`, preserving the invariant that danger is
+ * never reachable without one.
  *
- * Matches the harness's own `permissionMap.danger`, joined, so a multi-token danger mode is
- * compared as a whole: opencode's danger is `['build', '--auto']`, and bare `build` is its *edit*
- * token — treating each token separately would wrongly gate legitimate `edit` templates.
+ * Multi-token danger modes compare joined: opencode's danger is `['build', '--auto']`, and bare
+ * `build` is its *edit* token (on the allowlist).
  */
 export function isNativeDangerPermission(harness: Harness | undefined, nativePermission: string | undefined): boolean {
-  if (!nativePermission) return false;
-  const native = nativePermission.trim();
-  if (LEGACY_DANGER_TOKENS.has(native)) return true;
-  const danger = harness?.permissionMap?.danger;
-  return Array.isArray(danger) && danger.length > 0 && native === danger.join(' ');
+  const cls = classifyNativePermission(harness, nativePermission);
+  return cls === 'danger' || cls === 'unlisted';
 }
 
 /**

package/extensions/harnesses/types.ts

@@ -91,6 +91,18 @@ export interface Harness {
   /** Normalized -> native CLI arg fragments, used by the 'stdout' transport's buildArgs/nativePermission. */
   permissionMap?: Record<NormalizedPermission, string[]>;
   permissionHint?: (permission: NormalizedPermission) => string[];
+  /** Allowlist of native permission values (a template's `permission: <native>` escape hatch) that are
+   *  readonly- or edit-equivalent for this harness. Anything else — including a value this list has
+   *  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

@@ -14,14 +14,22 @@
  * Legacy: { claudeDelegate: {...} } is auto-migrated.
  */
 
-import { type ExtensionAPI, type ExtensionContext, getMarkdownTheme } from '@earendil-works/pi-coding-agent';
+import type { ImageContent, TextContent } from '@earendil-works/pi-ai';
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  getMarkdownTheme,
+  type ToolDefinition,
+} from '@earendil-works/pi-coding-agent';
 import { Container, Markdown, type OverlayHandle, Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 import { formatToolUse, ToolCallIndex } from './activity.ts';
 import {
   aliasUsage,
   delegateUsage,
+  emptyHarnessSpecError,
   isFanoutSpec,
+  normalizeHarnessSpec,
   parseDelegateCommand,
   resolveDefaults,
   resolveHarnessFilter,
@@ -36,7 +44,6 @@ import {
   runDelegateForTool,
   runMetrics,
   summarize,
-  type ToolProgressUpdate,
   takePendingReport,
 } from './engine.ts';
 import { closeWhenMounted, type RunUiState, runFanoutCommand, runFanoutTool } from './fanout.ts';
@@ -50,79 +57,104 @@ import { type DelegateTemplate, loadTemplates } from './templates.ts';
 import { mapClaudeUsage } from './usage.ts';
 import { confirmDangerousCommand, confirmDangerousToolCall, confirmToolAddDirs } from './validate.ts';
 
+/** Tool-result `details` for the `delegate` tool (and its partial progress updates). */
+type DelegateToolDetails = Record<string, unknown>;
+
+const DELEGATE_TOOL_DESCRIPTION =
+  'Delegate a task to any harness (claude, codex, opencode, amp, devin) running headless in the repo and return its streamed report (cost, token usage, context %, session id). harness selects the backend (default from config, fallback claude) — pass "all" or a comma list (e.g. "claude,codex") to fan out the same task to several harnesses and get back one comparison report. mode selects a template: review, plan, implement, security-audit, docs, general, or custom — some templates run a host-side check (e.g. "bun test") after the harness exits and report pass/fail as separate evidence; that is configured on the template, not a parameter here. scope restricts work: diff for current git diff, pr for PR diff, path list, or whole repo. sessionId continues a prior session.';
+
+const DELEGATE_TOOL_GUIDELINES: readonly string[] = [
+  'delegate runs a harness headless in the working directory and returns a streamed report with cost, token usage, and a session id for follow-ups.',
+  'Pass harness (claude|codex|opencode|amp|devin) + focused task string + intent and constraints. Use scope: diff for current git diff, pr for PR diff, path list, or omit for whole repo.',
+  'mode selects the template and its permission level: review/plan/security-audit are readonly; implement/docs/general are edit. Custom template names also work. Some templates verify their own work (e.g. running tests) automatically after the harness finishes — that is not something you configure here.',
+  'harness: "all" or a comma list (e.g. "codex,opencode") fans the same task out to each detected harness and returns one synthesized comparison report — costs multiply, so only use it when the user actually wants a multi-harness comparison.',
+  'sessionId resumes a previous delegated session instead of starting fresh — pass the exact session id from a previous run\'s details (letters, digits, . _ : - only). It cannot be combined with a fan-out harness ("all" or a comma list) — a session belongs to one harness.',
+  'pr must be a PR number, an http(s) pull-request URL (https://<host>/<owner>/<repo>/pull/<n>), or owner/repo#123.',
+  'addDirs inside the working directory are accepted as-is; any entry outside it asks the human to confirm interactively and is refused in a non-interactive session.',
+  'Do not set allowDangerous unless the user explicitly asks for unrestricted access (danger permission). Setting it always asks the human to confirm interactively; in a non-interactive session it is refused outright.',
+];
+
+const DELEGATE_TOOL_PARAMS = Type.Object({
+  harness: Type.Optional(
+    Type.String({
+      description:
+        'Harness to use: claude, codex, opencode, amp (aliases: omp), devin. "all" or a comma list (e.g. "claude,codex") fans out to each detected harness. Defaults to config defaultHarness.',
+    }),
+  ),
+  task: Type.String({ description: 'The task/intent to delegate. Be specific.' }),
+  mode: Type.Optional(
+    Type.String({
+      description:
+        'Template/mode to run: review, plan, implement, security-audit, docs, general, or custom. Defaults to config defaultMode.',
+    }),
+  ),
+  scope: Type.Optional(
+    Type.String({
+      description:
+        'Restrict the work: diff (git diff), pr (PR diff), comma/space-separated path list, or omit for whole repo.',
+    }),
+  ),
+  model: Type.Optional(Type.String({ description: 'Model (e.g. sonnet, opus, gpt-5). Defaults to template/config.' })),
+  maxBudgetUsd: Type.Optional(Type.Number({ description: 'Hard spend cap in USD for the run.' })),
+  sessionId: Type.Optional(
+    Type.String({
+      description: 'Resume an existing delegated session (pass its session id from a previous run details).',
+    }),
+  ),
+  allowDangerous: Type.Optional(
+    Type.Boolean({
+      description:
+        'Escalate to danger permission (unrestricted). Always requires interactive human confirmation; refused without a UI.',
+    }),
+  ),
+  pr: Type.Optional(
+    Type.String({ description: 'GitHub PR number, http(s) PR URL, or owner/repo#123 (alternative to scope pr).' }),
+  ),
+  addDirs: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        'Extra directories the harness may access. Relative paths resolve against the working directory. Any entry that resolves (after symlinks) outside the working directory requires interactive human confirmation and is refused without a UI. Not every harness supports this (opencode ignores it; codex ignores it on resume).',
+    }),
+  ),
+  // Deliberately no `verify` param — see the trust-model comment on DelegateToolParams/runVerify.
+});
+
+/** The text parts of a tool result, joined — images (never produced by this tool) are skipped. */
+function textOf(content: readonly (TextContent | ImageContent)[] | undefined): string {
+  return (content ?? []).flatMap(c => (c.type === 'text' ? [c.text] : [])).join('\n');
+}
+
 export default function (pi: ExtensionAPI) {
   const ui: RunUiState = { activeRunId: 0, activeOverlay: null };
 
   // ── Tools ────────────────────────────────────────────────────────────────
-  const delegateToolDef = {
-    name: 'delegate',
-    label: 'Delegate',
-    description:
-      'Delegate a task to any harness (claude, codex, opencode, amp, devin) running headless in the repo and return its streamed report (cost, token usage, context %, session id). harness selects the backend (default from config, fallback claude) — pass "all" or a comma list (e.g. "claude,codex") to fan out the same task to several harnesses and get back one comparison report. mode selects a template: review, plan, implement, security-audit, docs, general, or custom — some templates run a host-side check (e.g. "bun test") after the harness exits and report pass/fail as separate evidence; that is configured on the template, not a parameter here. scope restricts work: diff for current git diff, pr for PR diff, path list, or whole repo. sessionId continues a prior session.',
-    promptSnippet: 'Delegate a subtask to a harness and return its report',
-    promptGuidelines: [
-      'delegate runs a harness headless in the working directory and returns a streamed report with cost, token usage, and a session id for follow-ups.',
-      'Pass harness (claude|codex|opencode|amp|devin) + focused task string + intent and constraints. Use scope: diff for current git diff, pr for PR diff, path list, or omit for whole repo.',
-      'mode selects the template and its permission level: review/plan/security-audit are readonly; implement/docs/general are edit. Custom template names also work. Some templates verify their own work (e.g. running tests) automatically after the harness finishes — that is not something you configure here.',
-      'harness: "all" or a comma list (e.g. "codex,opencode") fans the same task out to each detected harness and returns one synthesized comparison report — costs multiply, so only use it when the user actually wants a multi-harness comparison.',
-      'sessionId resumes a previous delegated session instead of starting fresh — pass the exact session id from a previous run\'s details (letters, digits, . _ : - only). It cannot be combined with a fan-out harness ("all" or a comma list) — a session belongs to one harness.',
-      'pr must be a PR number, an http(s) pull-request URL (https://<host>/<owner>/<repo>/pull/<n>), or owner/repo#123.',
-      'addDirs inside the working directory are accepted as-is; any entry outside it asks the human to confirm interactively and is refused in a non-interactive session.',
-      'Do not set allowDangerous unless the user explicitly asks for unrestricted access (danger permission). Setting it always asks the human to confirm interactively; in a non-interactive session it is refused outright.',
-    ],
-    parameters: Type.Object({
-      harness: Type.Optional(
-        Type.String({
-          description:
-            'Harness to use: claude, codex, opencode, amp (aliases: omp), devin. "all" or a comma list (e.g. "claude,codex") fans out to each detected harness. Defaults to config defaultHarness.',
-        }),
-      ),
-      task: Type.String({ description: 'The task/intent to delegate. Be specific.' }),
-      mode: Type.Optional(
-        Type.String({
-          description:
-            'Template/mode to run: review, plan, implement, security-audit, docs, general, or custom. Defaults to config defaultMode.',
-        }),
-      ),
-      scope: Type.Optional(
-        Type.String({
-          description:
-            'Restrict the work: diff (git diff), pr (PR diff), comma/space-separated path list, or omit for whole repo.',
-        }),
-      ),
-      model: Type.Optional(
-        Type.String({ description: 'Model (e.g. sonnet, opus, gpt-5). Defaults to template/config.' }),
-      ),
-      maxBudgetUsd: Type.Optional(Type.Number({ description: 'Hard spend cap in USD for the run.' })),
-      sessionId: Type.Optional(
-        Type.String({
-          description: 'Resume an existing delegated session (pass its session id from a previous run details).',
-        }),
-      ),
-      allowDangerous: Type.Optional(
-        Type.Boolean({
-          description:
-            'Escalate to danger permission (unrestricted). Always requires interactive human confirmation; refused without a UI.',
-        }),
-      ),
-      pr: Type.Optional(
-        Type.String({ description: 'GitHub PR number, http(s) PR URL, or owner/repo#123 (alternative to scope pr).' }),
-      ),
-      addDirs: Type.Optional(
-        Type.Array(Type.String(), {
-          description:
-            'Extra directories the harness may access. Relative paths resolve against the working directory. Any entry that resolves (after symlinks) outside the working directory requires interactive human confirmation and is refused without a UI. Not every harness supports this (opencode ignores it; codex ignores it on resume).',
-        }),
-      ),
-      // Deliberately no `verify` param — see the trust-model comment on DelegateToolParams/runVerify.
-    }),
-    async execute(
-      _toolCallId: string,
-      params: DelegateToolParams,
-      signal: AbortSignal | undefined,
-      onUpdate: ((u: ToolProgressUpdate) => void) | undefined,
-      ctx: ExtensionContext,
-    ) {
+
+  /**
+   * Build one registration of the `delegate` tool. The primary tool and the deprecated
+   * `claude_delegate` alias are the same definition — same schema, guidelines, execute path and
+   * renderers — differing only in the fields `spec` sets (name/label/description/snippet) and, for
+   * the alias, a pinned harness applied before anything else in `execute`.
+   */
+  const makeDelegateTool = (
+    name: string,
+    spec: { label: string; description: string; promptSnippet: string; forceHarness?: string },
+  ): ToolDefinition<typeof DELEGATE_TOOL_PARAMS, DelegateToolDetails> => ({
+    name,
+    label: spec.label,
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    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. 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.
@@ -161,16 +193,15 @@ export default function (pi: ExtensionAPI) {
         : `${details.harness} ${details.mode} (${result.numTurns ?? '—'} turn(s), ${formatCost(result.totalCostUsd)})${resumed}`;
       const body = result.isError ? `\n${summary.text}` : `\n\n${summary.text}`;
       const footer = summary.truncated ? `\nFull output: ${details.file}` : `\nTranscript: ${details.file}`;
-      (details as Record<string, unknown>).markdown = summary.text;
+      details.markdown = summary.text;
       return {
         content: [{ type: 'text', text: `${head}${body}${footer}` }],
         details,
         usage: result.usage ? mapClaudeUsage({ ...result.usage, totalCostUsd: result.totalCostUsd }) : undefined,
       };
     },
-    renderCall(args: unknown, theme: { fg: (c: string, s: string) => string; bg: (c: string, s: string) => string }) {
-      const params = args as { harness?: string; mode?: string; task?: string };
-      const harness = params.harness ?? 'delegate';
+    renderCall(params, theme) {
+      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}` : '';
@@ -178,19 +209,12 @@ export default function (pi: ExtensionAPI) {
         theme.bg('toolPendingBg', s),
       );
     },
-    renderResult(
-      result: { content?: { type: string; text: string }[]; details?: Record<string, unknown> },
-      options: { isPartial: boolean },
-      theme: { fg: (c: string, s: string) => string; bg: (c: string, s: string) => string },
-    ) {
+    renderResult(result, options, theme) {
       if (options.isPartial) {
-        const text = (result.content ?? [])
-          .filter(c => c.type === 'text')
-          .map(c => c.text)
-          .join('\n');
+        const text = textOf(result.content);
         return new Text(text, 1, 1, s => theme.bg('toolPendingBg', s));
       }
-      const details = (result.details ?? {}) as Record<string, unknown>;
+      const details: DelegateToolDetails = result.details ?? {};
       const harness = typeof details.harness === 'string' ? details.harness : 'delegate';
       const mode = typeof details.mode === 'string' ? details.mode : 'delegate';
       const cost = typeof details.totalCostUsd === 'number' ? details.totalCostUsd : null;
@@ -213,10 +237,7 @@ export default function (pi: ExtensionAPI) {
       const md = typeof details.markdown === 'string' && details.markdown ? details.markdown : null;
       if (md) container.addChild(new Markdown(md, 1, 1, getMarkdownTheme()));
       else {
-        const text = (result.content ?? [])
-          .filter(c => c.type === 'text')
-          .map(c => c.text)
-          .join('\n');
+        const text = textOf(result.content);
         container.addChild(new Text(text, 1, 1));
       }
       const foot: string[] = [];
@@ -225,46 +246,25 @@ export default function (pi: ExtensionAPI) {
       if (foot.length > 0) container.addChild(new Text(theme.fg('dim', foot.join('   ')), 1, 1));
       return container;
     },
-  };
+  });
 
-  // SAFETY: delegateToolDef satisfies registerTool params via TypeBox, widened for alias registration
-  pi.registerTool(delegateToolDef as unknown as Parameters<typeof pi.registerTool>[0]); // SAFETY: delegateToolDef satisfies registerTool params
+  pi.registerTool(
+    makeDelegateTool('delegate', {
+      label: 'Delegate',
+      description: DELEGATE_TOOL_DESCRIPTION,
+      promptSnippet: 'Delegate a subtask to a harness and return its report',
+    }),
+  );
 
   // deprecated alias
-  pi.registerTool({
-    name: 'claude_delegate',
-    label: 'Claude Delegate (deprecated)',
-    description:
-      'Deprecated alias for delegate{harness:claude}. Use delegate tool with harness:claude instead. ' +
-      (delegateToolDef as { description: string }).description,
-    promptSnippet: 'Delegate a subtask to Claude Code (deprecated alias)',
-    // SAFETY: delegateToolDef promptGuidelines is string[] from literal, safe to spread
-    promptGuidelines: [...(delegateToolDef as unknown as { promptGuidelines: string[] }).promptGuidelines], // SAFETY: promptGuidelines is string[]
-    parameters: (delegateToolDef as { parameters: unknown }).parameters as never,
-    async execute(
-      toolCallId: string,
-      params: DelegateToolParams,
-      signal: AbortSignal | undefined,
-      onUpdate: never,
-      ctx: ExtensionContext,
-    ) {
-      return (
-        // SAFETY: deprecated alias delegates to primary tool, shape identical
-        (
-          delegateToolDef as unknown as {
-            // SAFETY: alias shape identical
-            execute: (a: string, b: unknown, c: unknown, d: unknown, e: unknown) => Promise<unknown>;
-          }
-        ).execute(toolCallId, { ...params, harness: 'claude' }, signal, onUpdate, ctx)
-      );
-    },
-    // SAFETY: delegateToolDef renderCall matches expected signature
-    renderCall: (delegateToolDef as unknown as { renderCall: (a: unknown, b: unknown) => unknown }).renderCall, // SAFETY: matches signature
-    // SAFETY: delegateToolDef renderResult matches expected signature
-    renderResult: (delegateToolDef as unknown as { renderResult: (a: unknown, b: unknown, c: unknown) => unknown }) // SAFETY: matches signature
-      .renderResult,
-    // SAFETY: final alias tool matches registerTool overload
-  } as unknown as Parameters<typeof pi.registerTool>[0]); // SAFETY: alias tool matches overload
+  pi.registerTool(
+    makeDelegateTool('claude_delegate', {
+      label: 'Claude Delegate (deprecated)',
+      description: `Deprecated alias for delegate{harness:claude}. Use delegate tool with harness:claude instead. ${DELEGATE_TOOL_DESCRIPTION}`,
+      promptSnippet: 'Delegate a subtask to Claude Code (deprecated alias)',
+      forceHarness: 'claude',
+    }),
+  );
 
   // ── Commands ─────────────────────────────────────────────────────────────
 

package/extensions/notify.ts

@@ -14,20 +14,33 @@ export function joinBatch(lines: string[]): string {
   return `${lines.length} runs completed:\n${lines.map(l => `  · ${l}`).join('\n')}`;
 }
 
+/** The timer primitives the batcher schedules its debounce with — injectable so tests can drive a
+ *  fake clock instead of sleeping for real. */
+export interface BatcherTimers {
+  set(fn: () => void, ms: number): unknown;
+  clear(handle: unknown): void;
+}
+
+const REAL_TIMERS: BatcherTimers = {
+  set: (fn, ms) => setTimeout(fn, ms),
+  clear: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
 export class NotifyBatcher {
   private pending: string[] = [];
-  private timer: ReturnType<typeof setTimeout> | null = null;
+  private timer: unknown = null;
 
   constructor(
     private readonly emit: NotifyFn,
     private readonly debounceMs = 400,
+    private readonly timers: BatcherTimers = REAL_TIMERS,
   ) {}
 
   /** Queue a successful-completion line; flushes as one combined notification after a quiet period. */
   success(line: string): void {
     this.pending.push(line);
-    if (this.timer) clearTimeout(this.timer);
-    this.timer = setTimeout(() => this.flush(), this.debounceMs);
+    if (this.timer !== null) this.timers.clear(this.timer);
+    this.timer = this.timers.set(() => this.flush(), this.debounceMs);
   }
 
   /** Flush any pending batch immediately, then emit this failure on its own — never delayed. */
@@ -38,8 +51,8 @@ export class NotifyBatcher {
 
   /** Emit whatever is pending as one notification, then clear it. No-op when nothing is pending. */
   flush(): void {
-    if (this.timer) {
-      clearTimeout(this.timer);
+    if (this.timer !== null) {
+      this.timers.clear(this.timer);
       this.timer = null;
     }
     if (this.pending.length === 0) return;