pi-harness-delegate 0.6.2 → 0.7.0

package/README.md

@@ -39,10 +39,38 @@ Manual delegation:
 
 Only the prompt is required. A **harness as first word** and/or **mode as next word** selects them; every `--flag` is optional (harness defaults to `delegate.defaultHarness`, mode to `delegate.defaultMode`, scope to whole repo).
 
+| Flag | Meaning |
+| --- | --- |
+| `--harness=<name>` | `claude`, `codex`, `opencode`, `amp` (`omp`), `devin`, `all`, or a comma list (fan-out, below) |
+| `--mode=<template>` | Any template name (`review`, `plan`, `implement`, `security-audit`, `docs`, `general`, or your own) |
+| `--model=<model>` | Model or alias (`economy`/`balanced`/`max`, see `modelAliases`) |
+| `--scope=<scope>` | `diff` (current `git diff HEAD`), `pr` (`gh pr diff` for the current branch), or a path list |
+| `--pr=<pr>` | A specific PR to scope to: a number, an http(s) PR URL (`https://<host>/<owner>/<repo>/pull/<n>`, no `user@`), or `owner/repo#123` (implies the PR diff as scope) |
+| `--budget=<usd>` | Per-run spend cap in USD (same as the tool's `maxBudgetUsd`) |
+| `--add-dir=<path>` | Extra directory the harness may access; repeatable (`--add-dir=../shared --add-dir=/opt/lib`) |
+| `--resume=<session-id>` | Continue a previous delegated session (single harness only — not with a fan-out) |
+| `--verify="<cmd>"` | Host-run check after the harness exits (see [Verify](#modes-templates)) |
+| `--allow-dangerous` | Run this one invocation with `danger` (unrestricted) permission — required for a `permission: danger` template, and escalates any other template to `danger`. Always asks you to confirm first (one prompt for a whole fan-out); refused in a non-interactive session. Never read from config. `--allow-dangerous=true` also works; any other value is off. See [Security model](#security-model) |
+
+Extra directories (`--add-dir`, the tool's `addDirs`, and template `addDirs:`) are merged, resolved against the working directory, and passed as each harness's native option where one exists: `--add-dir` for `claude`, `codex` (fresh runs only — `codex exec resume` has no such flag), and `amp`/`omp`; `additionalDirectories` on the ACP session for `devin`/`opencode` over ACP. `opencode run` (stdout) has no equivalent, so they're ignored there. On the `delegate` **tool**, `addDirs` entries that resolve (after `..` and symlinks) outside the working directory ask you to confirm interactively and are refused in a non-interactive session — the model alone can't widen a run to arbitrary host paths. Template `addDirs:` and `/delegate --add-dir` (both set by you) are not gated.
+
+Flag values may be quoted (`--verify="bun test && bun run lint"`). `--resume`, `--model`, and `--pr` values are validated before anything runs — e.g. a value starting with `-` is rejected, so it can never be smuggled into a harness's command line as a flag.
+
+**Subcommands** (work on `/delegate` and on every alias, where the alias pins the harness filter):
+
+| Subcommand | What it does |
+| --- | --- |
+| `/delegate list [harness]` | Available modes/templates (all harnesses, or one) |
+| `/delegate history [harness]` (alias `logs`) | Past transcripts, newest first; open one to read it (and see its resume hint) |
+| `/delegate status [harness]` (aliases `health`, `doctor`, `check`) | Config provenance, project trust, per-harness detection/version/templates/active-vs-cap, spend rollup |
+| `/delegate config` | What was read from `settings.json` and the effective config (print-only) |
+| `/delegate config init` | Write the effective config into `settings.json`'s `delegate` key (the only write this extension does) |
+| `/delegate watch` (alias `show`) | Re-open a minimized progress overlay |
+
 Some modes have **default tasks** when the prompt is omitted:
 `/delegate review` reviews the current git diff (`scope: diff`), `/delegate security-audit` audits the repo. Modes without a default (`plan`, `implement`, `docs`, `general`) print a hint asking for a prompt.
 
-The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `allowDangerous`, `sessionId`, `pr`. (`verify` is deliberately *not* a tool parameter — see below.)
+The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `allowDangerous`, `sessionId`, `pr`, `addDirs`. (`verify` is deliberately *not* a tool parameter — see below.) Setting `allowDangerous` from the tool always asks you to confirm interactively, and is refused outright in a non-interactive session — see [Security model](#security-model).
 
 `claude_delegate` remains as a deprecated alias for `delegate{harness:claude}`.
 
@@ -56,10 +84,9 @@ The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff
 delegate({ harness: "all", mode: "review", scope: "diff" })   # tool call form
 ```
 
-- `all` resolves against *detected* harnesses, so Devin joins a fan-out automatically once `devin` is installed — a 5-harness fan-out costs more (and runs one more concurrent process) than the 4-harness one did, budget accordingly.
-
-- `all` resolves to whatever's actually installed (`detectAll()`) — an uninstalled harness is skipped and named in the report, it doesn't fail the run. An explicit list is validated the same way; an unknown name is also reported rather than aborting the rest.
-- Each harness's run goes through the same `delegate()` engine as a single-harness call and writes its own transcript to its own `~/.pi/agent/delegate/outputs/<harness>/`. Runs are launched together and execute in parallel, bounded by `maxConcurrent` (default `4`, one slot per supported harness) — a run beyond the cap queues for a free slot instead of failing, and the cap is enforced across pi processes, not just this one. **This means fan-out spend is genuinely simultaneous**: with the default cap, a 4-harness fan-out can bill all four at once instead of one after another — budget accordingly (`maxBudgetUsd` still applies per run).
+- `all` resolves to whatever's actually installed (`detectAll()`) — an uninstalled harness is skipped and named in the report, it doesn't fail the run. An explicit list is validated the same way; an unknown name is also reported rather than aborting the rest. With all five harnesses installed, `all` means five runs.
+- Each harness's run goes through the same `delegate()` engine as a single-harness call and writes its own transcript to its own `~/.pi/agent/delegate/outputs/<harness>/`. Runs are launched together and execute in parallel, bounded by `maxConcurrent` (default `4`) — a run beyond the cap queues for a free slot instead of failing (so a 5-harness `all` runs four at once and the fifth when a slot frees), and the cap is enforced across pi processes, not just this one. **This means fan-out spend is genuinely simultaneous**: up to `maxConcurrent` harnesses can bill at once instead of one after another — budget accordingly (`maxBudgetUsd` still applies per run, not to the fan-out as a whole).
+- `--resume`/`sessionId` can't be combined with a fan-out — a session id belongs to exactly one harness — and is rejected up front with a message saying so.
 - The synthesized report is always ordered by the resolved harness list (e.g. `claude, codex, opencode`), regardless of which harness actually finishes first — it groups each harness's metrics + output and a total spend line (unknown-cost runs called out separately, same as `/delegate status`), assembled mechanically, not by asking a model to summarize.
 - A single-harness call (`harness: "claude"`, or omitted) behaves exactly as before, including the concurrency guard: it still fails fast with "another delegate run is already in progress" at capacity rather than queueing. Fan-out is opt-in by typing `all`/a list.
 - `/delegate all …` batches successful completions into one notification instead of one per harness; a failure is never delayed or folded into the batch — it surfaces immediately.
@@ -89,7 +116,7 @@ Detect availability: `delegate` checks `harness --version` at startup; missing h
 
 ### Transport
 
-Every harness runs over its native CLI's stdout (`stdout`, the default and only option for `claude`/`codex`/`amp`). `opencode` and `devin` also speak [ACP](https://agentclientprotocol.com) (Agent Client Protocol — bidirectional JSON-RPC over stdio): Devin ships ACP-only (no stdout mode exists), and `opencode` supports both — `stdout` stays the default, `transport: "acp"` is opt-in per harness in config (see below). ACP gives `opencode` a genuine `cost`/`contextWindow` (both `null` over stdout today) and a resume path independently proven to recall cross-process state; the tradeoff is `model`/`numTurns` staying unmeasured (`null`) either way. `amp`/`omp` has a real `acp` subcommand too, but isn't offered as a `transport` value — its ACP mode surface has only 2 permission tiers against the stdout CLI's genuine 3, a real regression, not just an unverified one. Configuring a transport a harness doesn't support fails immediately with a clear error, before anything spawns.
+Every harness runs over its native CLI's stdout (`stdout`, the default and only option for `claude`/`codex`/`amp`). `opencode` and `devin` also speak [ACP](https://agentclientprotocol.com) (Agent Client Protocol — bidirectional JSON-RPC over stdio): Devin ships ACP-only (no stdout mode exists), and `opencode` supports both — `stdout` stays the default, `transport: "acp"` is opt-in per harness in config (see below). ACP gives `opencode` a genuine `contextWindow` (`null` over stdout) and a server-side running cost total (stdout reports cost too, summed from each step's `step_finish` — `null` only if no step reported one), plus a resume path independently proven to recall cross-process state; the tradeoff is `model`/`numTurns` staying unmeasured (`null`) either way. `amp`/`omp` has a real `acp` subcommand too, but isn't offered as a `transport` value — its ACP mode surface has only 2 permission tiers against the stdout CLI's genuine 3, a real regression, not just an unverified one. Configuring a transport a harness doesn't support fails immediately with a clear error, before anything spawns.
 
 ## Modes (templates)
 
@@ -116,6 +143,23 @@ You are a senior engineer delegated by the pi coding agent.
 ...
 ```
 
+All frontmatter keys (one `key: value` per line; only `name` is required):
+
+| Key | Meaning |
+| --- | --- |
+| `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) |
+| `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 |
+| `defaultTask` | Task used when the prompt is omitted (e.g. `review` → review the current diff) |
+| `defaultScope` | Scope used with `defaultTask` (e.g. `diff`) |
+| `verify` | Host-run check command (see below) |
+| `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, use the native key (`permissionMode: dontAsk`, `sandbox: ...`) — it overrides `permission` for that harness.
 
 **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.
@@ -144,7 +188,7 @@ Custom templates are just files dropped in the above dirs — any registered nam
 ## Inspecting what the harness is doing
 
 - **Live activity feed** — `▶ Bash: ... ✓/✗`, `💭 thinking…`, text tail. `/delegate` shows a framed progress window (spinner, `danger` banner for `danger` permission, `esc`×2 cancels, `m` minimizes, `watch` re-opens).
-- **Full transcript every run** — `~/.pi/agent/delegate/outputs/<harness>/<ts>-<mode>.md` (also legacy `claude-delegate/outputs/` for claude). Tool result ends with path.
+- **Full transcript every run** — `~/.pi/agent/delegate/outputs/<harness>/<ts>-<mode>.md` (also legacy `claude-delegate/outputs/` for claude). Tool result ends with path. Transcripts contain your prompts, diffs, and the harness's full output, so they're written owner-only (directory `0700`, files `0600`).
 - **Resume:** every run records a session id.
 
 ```bash
@@ -157,7 +201,7 @@ Reveal thinking live with `"inspectThinking": true` in config (off by default).
 
 ## Config
 
-In `~/.pi/agent/settings.json`:
+In `~/.pi/agent/settings.json` (or `$PI_CODING_AGENT_DIR/settings.json` — `PI_CODING_AGENT_DIR`, pi's own agent-dir override, relocates everything this extension keeps under `~/.pi/agent`: settings, user templates, transcripts, and the active-run registry):
 
 ```json
 {
@@ -198,6 +242,14 @@ Config lives as a key inside pi's own `~/.pi/agent/settings.json` rather than a
 
 `autoDelegateHints` is off by default — no system-prompt bias. When `true`, explicit markers (`@harness`, `with codex`, `delegate … to claude`) and imperative review/plan phrasing append a hint.
 
+### Budgets (`maxBudgetUsd` / `--budget`)
+
+A per-run cap, resolved call → template → global config → per-harness config. How it's enforced depends on the harness, and the outcome is always recorded (tool result `details.budget`, a `- budget:` line in the transcript):
+
+- **Native** — `claude` gets `--max-budget-usd` and enforces it itself.
+- **Host-enforced (best-effort)** — harnesses with no budget flag that *do* stream a running cost (`opencode`, `amp`/`omp`, and `opencode` over ACP): the host checks the reported total each time the harness reports one and kills the run once it's over the cap, recording `budget exceeded` (`stopReason: budget_exceeded`, a `⛔ budget exceeded … run stopped` line at the top of the result, `(host-enforced, best-effort)` in the transcript). This is **not a hard cap**: cost is only visible at the step/turn boundaries the harness reports, so spend already incurred within the step that crossed the line can't be prevented — a run can overshoot by up to one step/turn (more if a single step is expensive). Use a native-budget harness (`claude`) when the cap must be strict. For `opencode` over ACP the reported cost is a session running total, so on a resumed session only the spend since this run started counts against the cap (the reported cost still includes prior turns).
+- **Not enforceable** — `codex` (no `$` cost on ChatGPT-plan auth) and `devin` report no cost and have no flag, so a budget can't be applied; the run proceeds and the result starts with `⚠ maxBudgetUsd … was not enforced`, never silently.
+
 ## Metrics recorded
 
 Every run records in details + transcript: harness, mode, permission (normalized + native), cost, tokens (input/output/cache), context% (prompt ÷ window), model, turns, duration, TTFT, stop reason, session id. Token + cost feed pi's `Usage`.
@@ -210,7 +262,11 @@ One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cos
 
 - `readonly` — no edits (e.g. Claude `plan`, Codex `read-only`).
 - `edit` — workspace writes auto-accepted (e.g. `acceptEdits`, `workspace-write`).
-- `danger` — unrestricted, **only via `allowDangerous:true` on the call** — never a default. Shows `⚠ danger` banner. `review`/`plan`/`security-audit` templates stay `readonly`.
+- `danger` — unrestricted, **only via an explicit per-call opt-in** — `allowDangerous:true` on the tool, or `--allow-dangerous` on `/delegate` — never a default (and never from config). Shows `⚠ danger` banner. `review`/`plan`/`security-audit` templates stay `readonly`.
+- When the **model** sets `allowDangerous: true` on the `delegate` tool, the extension asks you to confirm it (`Allow dangerous delegation?`) before anything runs; declining aborts the call, and in a non-interactive session (no UI to ask) it is refused outright. The model alone can never grant `danger`.
+- `/delegate --allow-dangerous` (and the `/claude`, `/codex`, … aliases) is the human-typed counterpart: it also asks you to confirm (`Allow dangerous delegation?`, naming the harness(es), mode, and that it runs with full, unrestricted permissions) — a fan-out gets one prompt covering every harness — and a decline runs nothing. In a non-interactive session it is refused outright, since there's no one to confirm with. It applies to that invocation only.
+- Likewise, when the **model** passes `addDirs` on the `delegate` tool, entries that resolve (after `..` and symlinks) outside the working directory need your interactive confirmation (`Allow access outside the project?`) and are refused in a non-interactive session. Entries inside the working directory, template `addDirs:`, and `/delegate --add-dir` are not gated.
+- Values that end up on a harness's command line (`sessionId`/`--resume`, `model`, `pr`) are validated first — notably, nothing starting with `-` is accepted, so a prompt-injected value can't masquerade as a CLI flag.
 
 Review what the harness is asked to do before granting broad permissions.
 

package/extensions/acp-runner.ts

@@ -21,7 +21,13 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { DEFAULT_TIMEOUT_MS, type Harness, type ParseState, type StreamedResult } from './harnesses/types.ts';
-import type { HarnessResult, RunHarnessOptions } from './runner.ts';
+import {
+  budgetStoppedResult,
+  type HarnessResult,
+  isCostOverBudget,
+  isOverBudget,
+  type RunHarnessOptions,
+} from './runner.ts';
 
 /** Bound on the initial handshake (initialize / session/new / session/set_mode) so a hung agent
  *  doesn't wedge the whole `timeoutMs` budget before `session/prompt` — the actual work — even starts. */
@@ -60,6 +66,26 @@ function supportsSessionModes(sessionResult: unknown): boolean {
   return false;
 }
 
+/** Placeholder for a run the host stops mid-turn before the harness produced anything result-shaped. */
+function emptyResult(): StreamedResult {
+  return {
+    result: '',
+    isError: false,
+    numTurns: null,
+    totalCostUsd: null,
+    sessionId: null,
+    stopReason: null,
+    permissionDenials: [],
+    durationMs: null,
+    durationApiMs: null,
+    ttftMs: null,
+    model: null,
+    contextWindow: null,
+    maxOutputTokens: null,
+    usage: null,
+  };
+}
+
 interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (err: Error) => void;
@@ -68,6 +94,12 @@ interface PendingRequest {
 
 export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
   return new Promise((resolve, reject) => {
+    // Already cancelled (e.g. the user hit cancel while this run was still being set up) —
+    // never spawn a process just to kill it.
+    if (opts.signal?.aborted) {
+      reject(new Error('cancelled'));
+      return;
+    }
     const args = opts.harness.buildArgs({
       prompt: opts.prompt,
       cwd: opts.cwd,
@@ -89,6 +121,14 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     // prompt's — set once session/prompt is actually sent, so replayed text/activities (and a
     // replay-skewed TTFT) never reach the caller. See the handshake IIFE below.
     let promptSent = false;
+    // Host budget accounting. opencode's ACP `usage_update.cost` is a *session* running total, so
+    // on a resume it already includes every prior turn — `costBaseline` is what the session had
+    // spent before this run's prompt, and only the delta counts against `maxBudgetUsd`. A fresh
+    // session starts at 0. On a resume it's the last cost replayed before the prompt (if any), else
+    // the first cost seen after it — which under-counts that first step, a deliberate bias toward
+    // never killing a resumed run for spend it didn't incur.
+    let prePromptCost: number | undefined;
+    let costBaseline: number | undefined;
     const startAt = Date.now();
     const MAX_STREAMED = 5 * 1024 * 1024; // 5MB cap to prevent OOM on compromised harness
     const MAX_ACTIVITIES = 5000;
@@ -96,18 +136,26 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     let nextId = 1;
     const pending = new Map<number, PendingRequest>();
 
-    const finish = (r: StreamedResult) => {
+    const finish = (r: StreamedResult, budgetExceeded = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       rejectAllPending(new Error('session ended'));
       const ttft = firstTokenAt !== null ? firstTokenAt - startAt : r.ttftMs;
-      resolve({ ...r, ttftMs: ttft, streamedText: state.streamedText, harness: opts.harness.name });
+      resolve({
+        ...r,
+        ttftMs: ttft,
+        streamedText: state.streamedText,
+        harness: opts.harness.name,
+        ...(budgetExceeded ? { budgetExceeded: true } : {}),
+      });
     };
     const fail = (err: Error) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
       rejectAllPending(err);
       reject(err);
     };
@@ -210,6 +258,29 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       }
 
       const outcome = opts.harness.parseLine(line, state);
+      if (typeof outcome.runningCostUsd === 'number') {
+        if (!promptSent) prePromptCost = outcome.runningCostUsd;
+        else {
+          costBaseline ??= outcome.runningCostUsd;
+          if (!settled && isCostOverBudget(opts.harness, opts.maxBudgetUsd, outcome.runningCostUsd, costBaseline)) {
+            proc.kill('SIGKILL');
+            const partial = state.result ?? opts.harness.extractResult(state) ?? emptyResult();
+            const latchedId = state._harness?.sessionId;
+            finish(
+              budgetStoppedResult(
+                {
+                  ...partial,
+                  totalCostUsd: outcome.runningCostUsd,
+                  sessionId: partial.sessionId ?? (typeof latchedId === 'string' ? latchedId : null),
+                },
+                state.streamedText,
+              ),
+              true,
+            );
+            return;
+          }
+        }
+      }
       // Discard streamed text/activities from anything that arrives before the new session/prompt
       // is sent — on a resume that's the replayed prior conversation, not the new turn's own output.
       if (promptSent && outcome.streamedText) {
@@ -235,6 +306,22 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       if (outcome.result) {
         if (!outcome.result.result) outcome.result.result = state.streamedText;
         state.result = outcome.result;
+        // Same host-side budget enforcement as runner.ts (see isOverBudget). Replayed history
+        // from a resume can't trip it — only once the new prompt is in flight.
+        if (
+          promptSent &&
+          !settled &&
+          isOverBudget(
+            opts.harness,
+            opts.maxBudgetUsd,
+            state.result,
+            // a resume that never saw a cost during this run has no evidence of new spend at all
+            costBaseline ?? (opts.resumeSessionId ? Number.POSITIVE_INFINITY : 0),
+          )
+        ) {
+          proc.kill('SIGKILL');
+          finish(budgetStoppedResult(state.result, state.streamedText), true);
+        }
       }
     });
 
@@ -265,14 +352,13 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
     }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     timer.unref?.();
 
-    opts.signal?.addEventListener(
-      'abort',
-      () => {
-        proc.kill('SIGKILL');
-        fail(new Error('cancelled'));
-      },
-      { once: true },
-    );
+    // Removed again in finish()/fail() — a long-lived signal (e.g. one shared by a fan-out, or the
+    // tool call's own) must not accumulate a dead listener per run.
+    function onAbort(): void {
+      proc.kill('SIGKILL');
+      fail(new Error('cancelled'));
+    }
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
 
     // Drive the handshake. `session/prompt` has no separate timeout — it's the actual work,
     // bounded by the overall `timer` above like everything else.
@@ -345,6 +431,7 @@ export function runAcpHarness(opts: RunHarnessOptions): Promise<HarnessResult> {
       await sendRequest('session/set_mode', { sessionId, modeId }, HANDSHAKE_TIMEOUT_MS);
       if (settled) return;
       promptSent = true;
+      costBaseline = opts.resumeSessionId ? prePromptCost : 0;
       await sendRequest('session/prompt', { sessionId, prompt: [{ type: 'text', text: opts.prompt }] });
       if (settled) return;
       // The agent doesn't exit on its own once the turn is done — an ACP session can outlive a

package/extensions/activity.ts

@@ -1,4 +1,4 @@
-import { readdirSync, rmSync, statSync } from 'node:fs';
+import { chmodSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ActivityEvent, NormalizedPermission } from './harnesses/types.ts';
 
@@ -169,6 +169,68 @@ export function formatVerifySection(v: VerifyResult): string {
   return lines.join('\n');
 }
 
+/** How a run's `maxBudgetUsd` was (or wasn't) enforced, and whether it was exceeded. */
+export interface BudgetNote {
+  limitUsd: number;
+  /** `native`: the harness CLI enforces it itself. `host`: best-effort — the runner kills the run
+   *  when the harness's streamed cost (checked only at the step/turn boundaries it reports) is over
+   *  the cap, so spend can overshoot by up to one step/turn. `unenforced`: neither — no native flag and no cost reported. */
+  enforcement: 'native' | 'host' | 'unenforced';
+  exceeded: boolean;
+  /** Human-readable warning, or null when there's nothing to warn about. */
+  message: string | null;
+}
+
+/**
+ * Pure: describe a run's budget outcome. Undefined when no budget was set. `stoppedByHost` is the
+ * runner's own `budgetExceeded` flag; `costUsd` is the run's final `totalCostUsd` (null = unmeasured).
+ */
+export function describeBudget(opts: {
+  harness: string;
+  limitUsd: number | undefined;
+  native: boolean;
+  costUsd: number | null;
+  stoppedByHost: boolean;
+}): BudgetNote | undefined {
+  const { harness, limitUsd, native, costUsd, stoppedByHost } = opts;
+  if (limitUsd === undefined) return undefined;
+  const limit = `$${limitUsd.toFixed(3)}`;
+  const cost = costUsd !== null ? `$${costUsd.toFixed(3)}` : '$—';
+  if (native) {
+    const exceeded = costUsd !== null && costUsd > limitUsd;
+    return {
+      limitUsd,
+      enforcement: 'native',
+      exceeded,
+      message: exceeded ? `⛔ budget exceeded: ${cost} spent against a ${limit} cap (enforced by ${harness})` : null,
+    };
+  }
+  if (stoppedByHost) {
+    return {
+      limitUsd,
+      enforcement: 'host',
+      exceeded: true,
+      message: `⛔ budget exceeded: ${harness} reported ${cost} against a ${limit} cap — run stopped (best-effort: cost is only checked at each step/turn the harness reports, so spend can overshoot the cap)`,
+    };
+  }
+  if (costUsd === null) {
+    return {
+      limitUsd,
+      enforcement: 'unenforced',
+      exceeded: false,
+      message: `⚠ maxBudgetUsd ${limit} was not enforced — ${harness} has no native budget flag and reported no cost`,
+    };
+  }
+  return { limitUsd, enforcement: 'host', exceeded: costUsd > limitUsd, message: null };
+}
+
+/** One transcript header line for a budget note. */
+export function formatBudgetLine(b: BudgetNote): string {
+  const how =
+    b.enforcement === 'native' ? 'native' : b.enforcement === 'host' ? 'host-enforced, best-effort' : 'NOT enforced';
+  return `- budget: $${b.limitUsd.toFixed(3)} (${how})${b.exceeded ? ' · budget exceeded' : ''}`;
+}
+
 /** Build the markdown report content injected into the session on the next turn. */
 export function buildReportContent(opts: {
   harness?: string;
@@ -256,6 +318,30 @@ export function buildClaudeReportContent(opts: {
 }
 
 /** Delete oldest transcript files beyond `maxCount` (0 = keep everything). */
+/**
+ * Write one transcript to `dir` (created if needed) and return its path. Transcripts hold the
+ * delegated prompt, repo diffs, and the harness's full output — owner-only: the directory is
+ * `0700` and each file `0600` (chmod'd explicitly too, since `mkdirSync`'s `mode` only applies to
+ * directories it creates and is subject to the umask).
+ */
+export function writeTranscript(dir: string, mode: string, text: string): string {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    // best-effort — e.g. a dir owned by someone else; the file mode below still applies
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = join(dir, `${stamp}-${safeSegmentName(mode)}.md`);
+  writeFileSync(file, text, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // best-effort
+  }
+  return file;
+}
+
 export function pruneOutputs(dir: string, maxCount: number): void {
   if (maxCount <= 0) return;
   let files: string[];
@@ -373,6 +459,8 @@ export function buildTranscript(
     output: string;
     /** Host-run verification result, when a `verify` command was configured for this run. */
     verify?: VerifyResult;
+    /** Budget outcome, when `maxBudgetUsd` was set for this run. */
+    budget?: BudgetNote;
   } & Record<string, unknown>,
 ): string {
   const harness = (opts.harness as string | undefined) ?? 'claude';
@@ -426,6 +514,8 @@ export function buildTranscript(
     `- context: ${context ?? 'n/a'}`,
     `- duration: ${duration ?? 'n/a'}`,
     `- stop reason: ${opts.stopReason ?? 'n/a'}`,
+    ...(opts.budget ? [formatBudgetLine(opts.budget)] : []),
+    ...(opts.budget?.message ? ['', opts.budget.message] : []),
     '',
     '## Activity',
     opts.activityLog.length > 0 ? opts.activityLog.join('\n') : '(no tool activity)',

package/extensions/command.ts

@@ -18,6 +18,14 @@ export interface DelegateCommandArgs {
   pr?: string;
   /** Host-run verification command override (--verify=); takes precedence over the template's. */
   verify?: string;
+  /** Extra directories the harness may access (--add-dir=, repeatable). */
+  addDirs?: string[];
+  /**
+   * `--allow-dangerous` (or `--allow-dangerous=true`): a human asking to run this one invocation
+   * with danger permission. Only ever honored after an interactive confirm in the command handler
+   * — never inherited from config, never applied headless. Absent unless explicitly true.
+   */
+  allowDangerous?: boolean;
 }
 
 export type ClaudeCommandArgs = DelegateCommandArgs;
@@ -38,14 +46,26 @@ export function parseDelegateCommand(
   knownHarnesses: ReadonlySet<string> = KNOWN_HARNESSES,
 ): DelegateCommandArgs {
   const flags: Record<string, string> = {};
+  const addDirs: string[] = [];
   // supports quoted values ("…"/'…') so multi-word flags like --verify="bun test" survive intact
-  const rest = raw.replace(
+  let rest = raw.replace(
     /--([a-zA-Z-]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
     (_m, k: string, dq: string | undefined, sq: string | undefined, bare: string | undefined) => {
-      flags[k] = dq ?? sq ?? bare ?? '';
+      const value = dq ?? sq ?? bare ?? '';
+      // --add-dir is the one repeatable flag — every occurrence is kept, in order
+      if (k === 'add-dir') {
+        if (value) addDirs.push(value);
+      } else flags[k] = value;
       return '';
     },
   );
+  // bare boolean flag(s): `--allow-dangerous` with no `=value`. Run after the `--key=value` pass, so
+  // a quoted flag value (e.g. --verify="echo --allow-dangerous") is already gone and can't match.
+  let allowDangerousBare = false;
+  rest = rest.replace(/(^|\s)--allow-dangerous(?=\s|$)/g, (_m, lead: string) => {
+    allowDangerousBare = true;
+    return lead;
+  });
 
   let harness = flags.harness?.toLowerCase();
   let mode = flags.mode;
@@ -78,6 +98,9 @@ export function parseDelegateCommand(
   if (flags.resume) out.sessionId = flags.resume;
   if (flags.pr) out.pr = flags.pr;
   if (flags.verify) out.verify = flags.verify;
+  if (addDirs.length > 0) out.addDirs = addDirs;
+  // `=true` is tolerated; any other explicit value (`=false`, `=yes`, …) means off — fail closed
+  if (allowDangerousBare || flags['allow-dangerous']?.toLowerCase() === 'true') out.allowDangerous = true;
   return out;
 }
 
@@ -92,6 +115,16 @@ export function isFanoutSpec(harness: string | undefined): boolean {
   return lower === 'all' || lower.includes(',');
 }
 
+/**
+ * A session id belongs to exactly one harness's session store, so resuming "it" across a fan-out
+ * is meaningless — every other harness would either error out or silently start fresh under a
+ * foreign id. Returns the rejection message (null when fine); shared by the tool and command paths.
+ */
+export function fanoutResumeError(harnessSpec: string | undefined, sessionId: string | undefined): string | null {
+  if (!sessionId || !isFanoutSpec(harnessSpec)) return null;
+  return `cannot resume session "${sessionId}" across a fan-out (harness "${harnessSpec}") — a session id belongs to one harness; resume it with that single harness instead (e.g. /delegate --harness=<name> --resume=${sessionId} …)`;
+}
+
 export type HarnessFilterResolution =
   | { kind: 'none' } // no filter word given
   | { kind: 'known'; harness: string } // resolved to its canonical name (aliases/case normalized)

package/extensions/concurrency.ts

@@ -104,7 +104,10 @@ export async function acquireSlot(opts: AcquireSlotOptions): Promise<() => void>
       continue;
     }
 
-    activeRuns.set(harness, perHarnessCount + 1);
+    // In-process counters count only this process's own runs — never seed them from
+    // `activeCount()` (which already folds in other processes' registry entries), or a foreign
+    // run gets baked into our local count and outlives that run's own release.
+    activeRuns.set(harness, (activeRuns.get(harness) ?? 0) + 1);
     globalActiveRuns++;
     const runHandle = claim.status === 'acquired' ? claim.handle : null;
     let released = false;