pi-harness-delegate 0.6.2 → 0.7.1

package/extensions/validate.ts

@@ -0,0 +1,214 @@
+/**
+ * Input validation for values that end up on a harness's (or `gh`'s) command line.
+ *
+ * `sessionId`, `model`, and `pr` all reach `spawn()`/`pi.exec()` argv — no shell, so no shell
+ * injection, but a value starting with `-` would be parsed by the target CLI as a *flag* (argument
+ * injection: e.g. a `sessionId` of `--dangerously-bypass-…` or a `pr` of `--repo=evil/x`). These
+ * values are model-settable on the `delegate` tool, and the model's context is attacker-influenceable,
+ * so they're validated once at the shared `delegate()` entry (both tool and `/delegate` paths) and
+ * up front on fan-out — never left to each harness's `buildArgs`.
+ */
+
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+const SESSION_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const PR_NUMBER_RE = /^\d{1,10}$/;
+const PR_SHORTHAND_RE = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}#\d{1,10}$/;
+// http(s)://<host>/<owner>/<repo>/pull/<n>[/files|?…|#…] — any host (GitHub Enterprise), but no
+// userinfo (`user:pass@`) and nothing that isn't actually a pull-request URL.
+const PR_URL_RE = /^https?:\/\/[^/@\s]+\/[^/\s]+\/[^/\s]+\/pull\/\d{1,10}(?:[/?#]\S*)?$/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+
+/** Returns an error message, or null when `id` is an acceptable session id. */
+export function sessionIdError(id: string): string | null {
+  if (id.startsWith('-') || !SESSION_ID_RE.test(id))
+    return `invalid sessionId ${JSON.stringify(id.slice(0, 60))} — expected 1-128 chars of [A-Za-z0-9._:-], not starting with "-" (use the session id from a previous run's details)`;
+  return null;
+}
+
+/** Returns an error message, or null when `model` is an acceptable model name. */
+export function modelError(model: string): string | null {
+  if (model.length === 0 || model.length > 200 || model.startsWith('-') || CONTROL_RE.test(model))
+    return `invalid model ${JSON.stringify(model.slice(0, 60))} — must be a non-empty name, not starting with "-"`;
+  return null;
+}
+
+/** Returns an error message, or null when `pr` is a PR number, an http(s) pull-request URL
+ *  (`<host>/<owner>/<repo>/pull/<n>`, no userinfo), or `owner/repo#n`. */
+export function prError(pr: string): string | null {
+  const bad = `invalid pr ${JSON.stringify(pr.slice(0, 80))} — expected a PR number, an http(s) PR URL, or owner/repo#123`;
+  if (pr.startsWith('-') || CONTROL_RE.test(pr)) return bad;
+  if (PR_NUMBER_RE.test(pr) || PR_SHORTHAND_RE.test(pr)) return null;
+  if (PR_URL_RE.test(pr)) return null;
+  return bad;
+}
+
+/**
+ * Returns an error message, or null when `dir` is an acceptable extra directory path. Judged on its
+ * *resolved* form, which is what actually reaches argv (`mergeAddDirs` resolves every entry against
+ * cwd): an absolute path can't be parsed as a flag, so a legitimate relative dir like `-foo`
+ * (→ `<cwd>/-foo`) is fine. Empty, oversized, and control-character entries are still rejected.
+ */
+export function addDirError(dir: string, cwd: string = process.cwd()): string | null {
+  const bad = `invalid addDirs entry ${JSON.stringify(dir.slice(0, 80))} — must be a non-empty path without control characters`;
+  if (dir.length === 0 || dir.length > 4096 || CONTROL_RE.test(dir)) return bad;
+  const abs = resolve(cwd, dir);
+  if (!isAbsolute(abs) || abs.startsWith('-')) return bad;
+  return null;
+}
+
+export interface ValidatableInputs {
+  sessionId?: string;
+  model?: string;
+  pr?: string;
+  addDirs?: string[];
+  /** What relative `addDirs` resolve against (the run's cwd). */
+  cwd?: string;
+}
+
+/** Throws a clear Error on the first invalid argv-bound input; returns normally otherwise. */
+export function validateDelegateInputs(inputs: ValidatableInputs): void {
+  const errors = [
+    inputs.sessionId !== undefined ? sessionIdError(inputs.sessionId) : null,
+    inputs.model !== undefined ? modelError(inputs.model) : null,
+    inputs.pr !== undefined ? prError(inputs.pr) : null,
+    ...(inputs.addDirs ?? []).map(d => addDirError(d, inputs.cwd)),
+  ];
+  const first = errors.find((e): e is string => e !== null);
+  if (first) throw new Error(first);
+}
+
+type ConfirmCtx = Pick<ExtensionContext, 'hasUI'> & { ui?: { confirm?: ExtensionContext['ui']['confirm'] } };
+
+/**
+ * The one danger-confirmation primitive shared by the tool and command paths: with a UI, ask via
+ * `ctx.ui.confirm` (a decline or a throwing dialog counts as "no"); without one there is nobody to
+ * ask, so fail closed. Resolves only on an explicit approval; throws the caller's message otherwise.
+ */
+async function askDangerConfirmation(
+  ctx: ConfirmCtx,
+  opts: { task: string; body: string; noUiError: string; declinedError: string },
+): Promise<void> {
+  if (!ctx.hasUI || typeof ctx.ui?.confirm !== 'function') throw new Error(opts.noUiError);
+  const task = opts.task.length > 200 ? `${opts.task.slice(0, 199)}…` : opts.task;
+  let ok = false;
+  try {
+    ok = await ctx.ui.confirm('Allow dangerous delegation?', `${opts.body}\n\nTask: ${task}`);
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new Error(opts.declinedError);
+}
+
+/**
+ * Gate a model-requested `allowDangerous: true` on the `delegate` tool behind a human: a tool
+ * param is model-settable (prompt-injection reachable), and `danger` means an unrestricted
+ * harness, so the model alone must never be able to grant it. With a UI, ask via
+ * `ctx.ui.confirm`; without one there is nobody to ask, so fail closed with a clear error. The
+ * `/delegate` command path uses `confirmDangerousCommand` instead.
+ */
+export async function confirmDangerousToolCall(
+  ctx: ConfirmCtx,
+  summary: { harness?: string; mode?: string; task: string },
+): Promise<void> {
+  const target = `${summary.harness ?? 'default harness'} ${summary.mode ?? 'default mode'}`;
+  await askDangerConfirmation(ctx, {
+    task: summary.task,
+    body: `The agent wants to run ${target} with DANGER permission (unrestricted: no sandbox, no approval prompts).`,
+    noUiError: `allowDangerous requested for ${target}, but there is no interactive UI to confirm it with — refusing (danger permission needs a human's explicit approval; run it from an interactive session)`,
+    declinedError: `allowDangerous for ${target} was declined by the user`,
+  });
+}
+
+/**
+ * Gate a human-typed `/delegate --allow-dangerous` behind the same interactive confirm. A human
+ * typed the flag, but it's one token away from an unrestricted run (and also escalates a
+ * non-danger template), so it's confirmed once more naming exactly what will run — one prompt
+ * covering every harness of a fan-out. Headless sessions never honor it: there's no one to
+ * confirm with, so it fails closed exactly like the tool path.
+ */
+export async function confirmDangerousCommand(
+  ctx: ConfirmCtx,
+  summary: { harnesses: string[]; mode: string; task: string },
+): Promise<void> {
+  const n = summary.harnesses.length;
+  const names = summary.harnesses.join(', ');
+  const target = `${names} ${summary.mode}`;
+  await askDangerConfirmation(ctx, {
+    task: summary.task,
+    body: `--allow-dangerous: run "${summary.mode}" on ${n > 1 ? `all ${n} harnesses (${names})` : names} with DANGER permission — full, unrestricted permissions (no sandbox, no approval prompts). Applies to this invocation only.`,
+    noUiError: `--allow-dangerous for ${target} needs interactive confirmation, but there is no UI — refusing (a headless /delegate never runs with danger permission)`,
+    declinedError: `--allow-dangerous for ${target} was declined — nothing was run`,
+  });
+}
+
+/** realpath of `p`, or — when `p` doesn't exist yet — realpath of its nearest existing ancestor
+ *  with the missing tail re-appended, so a not-yet-created dir under a symlink still resolves
+ *  through that symlink. */
+function realpathOrAncestor(p: string): string {
+  let cur = p;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return p;
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * The model-supplied `addDirs` entries that resolve **outside** `cwd` — after `resolve()` against
+ * `cwd` and symlink resolution on both sides, so neither `..` nor a symlink inside the repo
+ * pointing out of it escapes. Empty when every entry stays inside the working directory.
+ */
+export function addDirsOutsideCwd(cwd: string, addDirs: string[] | undefined): string[] {
+  if (!addDirs || addDirs.length === 0) return [];
+  const root = realpathOrAncestor(resolve(cwd));
+  const out: string[] = [];
+  for (const d of addDirs) {
+    const real = realpathOrAncestor(resolve(cwd, d));
+    const rel = relative(root, real);
+    const inside = rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    if (!inside) out.push(real);
+  }
+  return out;
+}
+
+/**
+ * Gate model-requested `addDirs` on the `delegate` tool. `addDirs` widens what the harness may
+ * touch — on `codex`/`claude`/`amp` the extra dir is writable on any non-readonly run, and even a
+ * `readonly` run can read it — so a model-set entry (prompt-injection reachable, same trust model as
+ * `allowDangerous`/`verify`) may only stay inside the working directory on its own. Anything that
+ * resolves outside it needs a human's `ctx.ui.confirm`; with no UI, fail closed. Template
+ * frontmatter (trusted on-disk config) and the human-typed `/delegate --add-dir` never call this.
+ */
+export async function confirmToolAddDirs(
+  ctx: Pick<ExtensionContext, 'hasUI' | 'cwd'> & { ui?: { confirm?: ExtensionContext['ui']['confirm'] } },
+  addDirs: string[] | undefined,
+): Promise<void> {
+  const outside = addDirsOutsideCwd(ctx.cwd, addDirs);
+  if (outside.length === 0) return;
+  const list = outside.join(', ');
+  if (!ctx.hasUI || typeof ctx.ui?.confirm !== 'function') {
+    throw new Error(
+      `addDirs outside the working directory requested (${list}), but there is no interactive UI to confirm it with — refusing (extra directories outside the project need a human's explicit approval)`,
+    );
+  }
+  let ok = false;
+  try {
+    ok = await ctx.ui.confirm(
+      'Allow access outside the project?',
+      `The agent wants the delegated harness to access directories outside ${ctx.cwd}:\n\n${outside.map(d => `  ${d}`).join('\n')}\n\nOn non-readonly runs these may be writable.`,
+    );
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new Error(`addDirs outside the working directory (${list}) were declined by the user`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.6.2",
-  "description": "Delegate work to any harness (Claude Code, Muse, OpenCode, Amp) from the pi coding agent \u2014 code reviews, plans, implementation, security audits, docs, or your own custom templates.",
+  "version": "0.7.1",
+  "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",
   "engines": {
@@ -21,6 +21,8 @@
     "codex",
     "opencode",
     "amp",
+    "devin",
+    "acp",
     "delegate",
     "subagent",
     "code-review",

package/extensions/run-claude.ts

@@ -1,61 +0,0 @@
-/** @deprecated use extensions/runner.ts + harnesses/claude.ts directly */
-
-import { claudeHarness } from './harnesses/claude.ts';
-import type { ActivityEvent, StreamedResult } from './harnesses/types.ts';
-import { runHarness } from './runner.ts';
-
-export interface RunClaudeOptions {
-  prompt: string;
-  cwd: string;
-  permissionMode: string;
-  model?: string;
-  maxBudgetUsd?: number;
-  addDirs?: string[];
-  signal?: AbortSignal;
-  timeoutMs?: number;
-  resumeSessionId?: string;
-  onStream?: (text: string) => void;
-  onActivity?: (ev: ActivityEvent) => void;
-}
-
-export interface ClaudeResult extends StreamedResult {
-  streamedText: string;
-}
-
-export const DEFAULT_TIMEOUT_MS = 600_000;
-
-function mapPerm(mode: string): 'readonly' | 'edit' | 'danger' {
-  if (mode === 'plan') return 'readonly';
-  if (mode === 'bypassPermissions') return 'danger';
-  return 'edit';
-}
-
-export function runClaude(opts: RunClaudeOptions): Promise<ClaudeResult> {
-  const perm = mapPerm(opts.permissionMode);
-  const _nativePerm =
-    perm === 'readonly' && opts.permissionMode !== 'plan'
-      ? opts.permissionMode
-      : perm === 'danger' && opts.permissionMode !== 'bypassPermissions'
-        ? opts.permissionMode
-        : undefined;
-  // normalize: if caller passed a non-standard mode, preserve as native
-  const isStandard =
-    opts.permissionMode === 'plan' ||
-    opts.permissionMode === 'acceptEdits' ||
-    opts.permissionMode === 'bypassPermissions';
-  return runHarness({
-    harness: claudeHarness,
-    prompt: opts.prompt,
-    cwd: opts.cwd,
-    permission: perm,
-    nativePermission: isStandard ? undefined : opts.permissionMode,
-    model: opts.model,
-    maxBudgetUsd: opts.maxBudgetUsd,
-    addDirs: opts.addDirs,
-    signal: opts.signal,
-    timeoutMs: opts.timeoutMs,
-    resumeSessionId: opts.resumeSessionId,
-    onStream: opts.onStream,
-    onActivity: opts.onActivity,
-  }).then(r => ({ ...r, streamedText: r.streamedText }));
-}

package/extensions/stream-parse.ts

@@ -1,37 +0,0 @@
-/** @deprecated use extensions/harnesses/claude.ts parse directly */
-export type {
-  ActivityEvent,
-  ParseOutcome,
-  ParseState,
-  StreamedResult,
-  StreamedUsage,
-  StreamParseOutcome,
-} from './harnesses/types.ts';
-
-import { parseClaudeLine } from './harnesses/claude.ts';
-import type { ParseState, StreamParseOutcome } from './harnesses/types.ts';
-
-export function parseStreamLines(lines: Iterable<string>): StreamParseOutcome {
-  const state: ParseState = { streamedText: '', activities: [], result: null };
-  let streamedText = '';
-  const activities: StreamParseOutcome['activities'] = [];
-  let result: StreamParseOutcome['result'] = null;
-  for (const line of lines) {
-    const out = parseClaudeLine(line, state);
-    if (out.streamedText) {
-      streamedText += out.streamedText;
-      state.streamedText += out.streamedText;
-    }
-    if (out.activities) {
-      for (const a of out.activities) {
-        activities.push(a);
-        state.activities.push(a);
-      }
-    }
-    if (out.result) {
-      result = out.result;
-      state.result = out.result;
-    }
-  }
-  return { streamedText, result, activities };
-}