pi-harness-delegate 0.7.3 → 0.8.0

package/README.md

@@ -47,6 +47,7 @@ Only the prompt is required. A **harness as first word** and/or **mode as next w
 | `--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`) |
+| `--timeout=<sec>` | Harness timeout for this run in whole seconds (plain digits), `10`–`7200`; replaces the template's `timeout:` and the config, up or down. Out of range is an error, not ignored. (The tool's `timeoutSec` can only *lower* it — see [Security model](#security-model)) |
 | `--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)) |
@@ -70,9 +71,9 @@ Flag values may be quoted (`--verify="bun test && bun run lint"`). `--resume`, `
 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`, `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).
+The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `timeoutSec` (whole seconds, `10`–`7200`; can only shorten the timeout the template/config gives the run, never lengthen it), `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}`.
+`claude_delegate` remains as a deprecated alias for `delegate{harness:claude}`. A read-only `delegate_modes` tool lets the model list the available modes, their permission tier per harness and the installed harnesses before it delegates (see [Discovering modes](#modes-templates)).
 
 ### Fan out to multiple harnesses
 
@@ -148,7 +149,7 @@ 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` |
+| `description` | Shown by `/delegate list` and the `delegate_modes` tool (sanitized, as data) |
 | `permission` | `readonly` \| `edit` \| `danger` (default `edit`). Any other value is treated as a native permission string |
 | `permissionMode` / `sandbox` | Legacy tier keys, only read when `permission` is absent (see below) |
 | `model` | Default model for this mode (call → template → harness → global) |
@@ -159,8 +160,10 @@ All frontmatter keys (one `key: value` per line; only `name` is required):
 | `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`) |
+| `harnesses` | Default harness(es) for this mode, used **only when no harness is given** (comma list, e.g. `codex` or `claude, codex`). See below |
+| `timeout` | Per-run harness timeout in whole seconds, `10`–`7200`. See below |
 
-**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, put the native value in `permission:` (e.g. `permission: ask` in a `devin/` template) — it is passed to that harness as-is. Legacy `permissionMode:`/`sandbox:` keys only map onto the normalized tiers, and only when `permission:` is absent (`permission:` always wins; a legacy key that disagrees with it is ignored but flagged with a `⚠` warning). Both keys accept both vocabularies, case-, whitespace- and `_`/`-`-insensitively: Claude's `plan` and Codex's `read-only` → `readonly`; `acceptEdits`/`dontAsk`/`auto`/`manual` and `workspace-write` → `edit`; `bypassPermissions` and `danger-full-access` → `danger` (gated behind `allowDangerous` / `--allow-dangerous` like any danger template). The three permission key names (`permission`, `permissionMode`, `sandbox`) are themselves case-insensitive (`Sandbox: read-only` counts); if a key appears more than once, or both legacy keys are set, the least permissive tier wins. An **unrecognized** legacy value fails closed: the template still loads, but as `readonly` (so it cannot write, and any `verify:` is skipped), with a `⚠ unrecognized sandbox: "…"` warning prefixed to its description in `/delegate list` and repeated on every run (a notification, a `- warning:` transcript line, and a prefix on the returned result). It is not dropped, because a dropped override would let a same-named builtin (e.g. `implement`, which is `edit`) run in its place, and that can be wider than what the author meant.
+**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, put the native value in `permission:` (e.g. `permission: ask` in a `devin/` template) — it is passed to that harness as-is. Legacy `permissionMode:`/`sandbox:` keys only map onto the normalized tiers, and only when `permission:` is absent (`permission:` always wins; a legacy key that disagrees with it — or legacy keys that disagree with each other — is ignored but flagged with a `⚠` warning — for a native `permission:` value, such as `permission: plan` next to `sandbox: workspace-write`, the check happens at run time against what that value means on the harness actually running it, e.g. `⚠ template "x": permission: "plan" (readonly on claude) overrides sandbox: "workspace-write" (ignored)`, so it appears on the run rather than in `/delegate list`). Both keys accept both vocabularies, case-, whitespace- and `_`/`-`-insensitively: Claude's `plan` and Codex's `read-only` → `readonly`; `acceptEdits`/`dontAsk`/`auto`/`manual` and `workspace-write` → `edit`; `bypassPermissions` and `danger-full-access` → `danger` (gated behind `allowDangerous` / `--allow-dangerous` like any danger template). The three permission key names (`permission`, `permissionMode`, `sandbox`) are themselves case-insensitive (`Sandbox: read-only` counts, and warnings name the key as you wrote it); if a key appears more than once, or both legacy keys are set, the least permissive tier wins. An **unrecognized** legacy value fails closed: the template still loads, but as `readonly` (so it cannot write, and any `verify:` is skipped), with a `⚠ unrecognized sandbox: "…"` warning prefixed to its description in `/delegate list` and repeated on every run (a notification, a `- warning:` transcript line, and a prefix on the returned result). It is not dropped, because a dropped override would let a same-named builtin (e.g. `implement`, which is `edit`) run in its place, and that can be wider than what the author meant.
 
 Native values are checked against a per-harness **allowlist** of readonly/edit-equivalent modes; anything else — the harness's own danger mode *or a value not on the list* — is treated as `danger` and needs `allowDangerous` / `--allow-dangerous` (fail closed). Once confirmed, an unlisted value still runs as declared rather than being swapped for the harness's danger mode. Matching is case-insensitive (`Plan` is claude's `plan`), and an allowlisted value always reaches the harness in its canonical spelling (e.g. `acceptEdits`); a case variant of a danger mode (`Yolo`, `BYPASSPERMISSIONS`) is still danger. A native value that is genuinely read-only on its harness (**bold** below) runs as the `readonly` tier: it is recorded as `readonly` and a `verify:` command on it is skipped, exactly like `permission: readonly`.
 
@@ -178,6 +181,16 @@ Native values are checked against a per-harness **allowlist** of readonly/edit-e
 - **Never runs on a `readonly` template** — including a native read-only one (`permission: plan`, codex `read-only`; see the table above). `readonly` (`review`/`plan`/`security-audit`) guarantees no execution or modification — a verify command riding along on one would quietly break that guarantee. If a `readonly` template (or override) has a `verify` configured, it's recorded as skipped (`### Verify: \`cmd\`` / `⊘ skipped (readonly run)`) rather than run, and never silently dropped.
 - A project-local template's `verify` command is gated by the same project-trust check as the rest of the template.
 
+**Default harnesses (`harnesses:`):** consulted only when the caller names no harness — an explicit `--harness=`, harness-as-first-word, alias command (`/codex`, …) or the tool's `harness` param always wins. The template copy that decides is the `defaultHarness`'s own copy of the mode when it has one (only that copy — copies kept for other harnesses never mix in); a mode kept only under other harnesses' folders (e.g. `~/.pi/agent/delegate/templates/codex/x.md`) uses the first such copy, in harness order (claude, codex, opencode, amp, devin), that declares `harnesses:`. The same rule drives `/delegate`, the `delegate` tool and `delegate_modes`, which shows the result (or that a harness must be named). Project-local copies count only for a trusted project, as for a run (an untrusted project's template can never pick the harness).
+- The list is used the same way by `/delegate <mode> …` and by the `delegate` **tool**: one name is a normal single run on that harness; several make it a normal [fan-out](#fan-out-to-multiple-harnesses): uninstalled/unknown names are skipped and reported, runs queue for `maxConcurrent` slots, a danger escalation (`--allow-dangerous` / the tool's `allowDangerous`) asks once naming every harness and is refused headless, the tool's out-of-cwd `addDirs` confirm covers every harness, and resuming (`--resume` / `sessionId`) is rejected (a session belongs to one harness — name it explicitly). The model sees each mode's default harnesses in `delegate_modes`, and can always pin one with `harness`.
+- `all` is not accepted (name the harnesses), and anything that isn't a plain harness-shaped word is dropped; both are flagged with a `⚠` warning. A template can't change permission through this — every harness runs the mode at its own tier, with the usual gates.
+
+**Timeout (`timeout:`):** whole seconds from `10` to `7200` (2 h). The harness timeout for a run is resolved most-specific first: the template's `timeout:` → the per-harness `harnesses.<name>.timeoutMs` → the global `timeoutMs`. A per-call timeout then applies: your `/delegate --timeout=<sec>` replaces it (up or down), while the tool's model-set `timeoutSec` can only lower it — a larger value has no effect. A call or template value never exceeds 7200 s. Every transcript records the timeout the run got (`- timeout: …s`). An invalid template value (out of range, fractional, `600s`, …) is ignored — the next level applies — and flagged with a `⚠` warning in `/delegate list`, `delegate_modes` and on every run (same places as a permission warning); an invalid per-call value is an error and nothing runs.
+
+**Discovering modes:** `/delegate list [harness]` shows every mode with its permission tier on each harness, where it came from (`builtin`/`user`/`project`), its defaults and any warnings. The model gets the same data from the read-only **`delegate_modes`** tool (optional `harness` filter), so it can pick a mode before delegating: per-harness tier (danger and unlisted native modes are marked as needing `allowDangerous`), whether a default task/scope or a host-run check is configured, the `harnesses:`/`timeout:` defaults, and which harnesses are on `PATH`. It runs nothing (a `PATH` lookup, not a `--version` probe — so "on PATH" isn't a guarantee it works), lists project-local templates only for a trusted project, and never shows a `verify:` command, prompt body, `defaultTask`/`defaultScope` text or file paths. Template text is untrusted: names, descriptions, models and warnings are stripped of ANSI escapes, control, bidi, zero-width, private-use and other invisible characters (including Unicode tag characters used to smuggle hidden text, Hangul fillers and the blank Braille pattern), runs of combining marks are cut to two, everything is kept to one line and length-capped, and in the tool's output it is JSON-quoted, with descriptions labelled as data, not instructions. Mode and model names also have every non-ASCII character shown escaped (`revi\u{435}w`) with a warning, so a look-alike name can't pass for a real one like `review`. `/delegate list` gets the same sanitizing, so a hostile description can't drive your terminal. When harness-specific copies of a mode differ (model, timeout, `harnesses:`, host check, …), the listing says which fields differ and whose copy it shows. Modes are listed builtin first, then user, then project, at most 50 from each source (the overflow is counted per source) — so a project with many templates can't push the builtin modes out of the list. A permission warning that only makes sense on a chosen harness (a native `permission:` value overriding ignored legacy keys) appears on the run, not in discovery.
+
+Templates have no variable substitution (`{{task}}` etc.) — the task and scope are always appended by the extension.
+
 **Template sources (later wins):**
 
 - `templates/shared/*.md` — portable prompt bodies
@@ -275,7 +288,9 @@ One deliberate, narrow exception: pi's own `Usage` (the footer/session token+cos
 - `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.
+- **Model-set parameters can only narrow resource limits, never widen them.** The tool's `timeoutSec` can only shorten the timeout the template / your config gives a run — a prompt-injected model can't stretch a run (and its concurrency slot) past what you configured. `/delegate --timeout=` is yours and can raise it.
 - 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.
+- Template values echoed back in a `⚠` warning (the offending `sandbox:`/`permissionMode:`/`permission:`/`timeout:`/`harnesses:` value and the template's name) are quoted, with the same control and invisible characters that mode discovery strips (see **Discovering modes** — C0/C1 incl. the 8-bit CSI, bidi overrides/isolates, zero-width, line separators, tag characters, private-use, …) escaped as `\uXXXX` instead, and capped, so a hostile template can't recolor, reorder or hide text in the warning while you still see what it wrote.
 - 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.
 - External content in the delegated prompt — the `git diff` for `diff`, the `gh pr diff` body for `pr`/`--pr`, and `gh`'s error output if the PR can't be fetched — is wrapped in an **untrusted-data block**: a backtick fence longer than any backtick run inside it, between `BEGIN/END UNTRUSTED DATA <nonce>` markers with a fresh random nonce, plus an instruction that the content is data to analyze, not instructions. A malicious PR can't close the block early or forge its end marker, and the PR is named in the prompt only as `owner/repo#n`/`#n`, never by its raw URL. A free-text `--scope` (e.g. `src/a.ts, src/b`, or a template's `defaultScope`) is delimited the same way between `BEGIN/END SCOPE <nonce>` markers, but framed as a restriction the harness must honor — it can narrow the task, never add to it. Your own task text stays the instruction and isn't fenced. This is a mitigation, not a guarantee — models can still be swayed by injected text.
 

package/extensions/activity.ts

@@ -463,6 +463,8 @@ export function buildTranscript(
     budget?: BudgetNote;
     /** A template permission warning (e.g. an unrecognized legacy value failed closed to readonly). */
     warning?: string;
+    /** The harness timeout this run was given (`resolveRunTimeoutMs`), when known. */
+    timeoutMs?: number;
   } & Record<string, unknown>,
 ): string {
   const harness = (opts.harness as string | undefined) ?? 'claude';
@@ -516,6 +518,7 @@ export function buildTranscript(
     `- context: ${context ?? 'n/a'}`,
     `- duration: ${duration ?? 'n/a'}`,
     `- stop reason: ${opts.stopReason ?? 'n/a'}`,
+    ...(typeof opts.timeoutMs === 'number' ? [`- timeout: ${Math.round(opts.timeoutMs / 1000)}s`] : []),
     ...(opts.warning ? [`- warning: ${opts.warning}`] : []),
     ...(opts.budget ? [formatBudgetLine(opts.budget)] : []),
     ...(opts.budget?.message ? ['', opts.budget.message] : []),

package/extensions/command.ts

@@ -1,4 +1,9 @@
-import type { DelegateTemplate } from './templates.ts';
+import {
+  callTimeoutError,
+  type DelegateTemplate,
+  TEMPLATE_TIMEOUT_MAX_SEC,
+  TEMPLATE_TIMEOUT_MIN_SEC,
+} from './templates.ts';
 
 /**
  * Pure parser for /delegate and alias commands: --key=value flags, with optional
@@ -12,6 +17,8 @@ export interface DelegateCommandArgs {
   model?: string;
   scope?: string;
   budget?: number;
+  /** Per-call harness timeout in seconds (--timeout=<sec>); wins over the template's `timeout:`. */
+  timeoutSec?: number;
   /** Resume an existing delegated session (--resume=<id>). */
   sessionId?: string;
   /** GitHub PR number/URL to review (--pr=). */
@@ -42,7 +49,7 @@ export type ClaudeCommandArgs = DelegateCommandArgs;
  * description, so the hints can't drift from what `parseDelegateCommand` actually parses.
  */
 export const COMMAND_FLAGS_HINT =
-  '[--mode=review|plan|implement|security-audit|docs|general] [--model=…] [--scope=diff|pr|paths] [--pr=<n|url>] [--budget=<usd>] [--verify=<cmd>] [--resume=<id>] [--add-dir=<path>] [--allow-dangerous] <prompt>';
+  '[--mode=review|plan|implement|security-audit|docs|general] [--model=…] [--scope=diff|pr|paths] [--pr=<n|url>] [--budget=<usd>] [--timeout=<sec>] [--verify=<cmd>] [--resume=<id>] [--add-dir=<path>] [--allow-dangerous] <prompt>';
 
 /** Usage line for `/delegate` itself. */
 export function delegateUsage(): string {
@@ -84,6 +91,22 @@ export function normalizeHarnessSpec(spec: string): string | undefined {
   return parts.join(',');
 }
 
+/**
+ * The harness spec a template's `harnesses:` frontmatter contributes when the caller named no
+ * harness (`undefined` when it declares none). Callers only consult this when no harness was given —
+ * an explicit `--harness=`, first-word harness, alias command or tool `harness` param always wins.
+ *
+ * The same on both paths (the `/delegate` command and the `delegate` tool): one name is a normal
+ * single run (fail-fast at capacity); several are a fan-out spec, which each path hands to its
+ * unchanged fan-out runner (`runFanoutCommand` / `runFanoutTool`) — `resolveHarnessList` detection
+ * filtering and unknown/skipped reporting, `waitForSlot: true` through `acquireSlot`,
+ * `fanoutResumeError`, and the path's own danger/addDirs confirm gates resolved against this spec.
+ */
+export function templateHarnessDefault(harnesses: readonly string[] | undefined): string | undefined {
+  if (!harnesses || harnesses.length === 0) return undefined;
+  return normalizeHarnessSpec(harnesses.join(','));
+}
+
 /** The error for a harness spec that normalizes to nothing (`,`, `" , "`) — shared by `/delegate`'s
  *  `--harness=` and the `delegate` tool's `harness` param, so neither silently runs the default. */
 export function emptyHarnessSpecError(raw: string): string {
@@ -105,6 +128,7 @@ const RECOGNIZED_FLAGS = new Set([
   'model',
   'scope',
   'budget',
+  'timeout',
   'resume',
   'pr',
   'verify',
@@ -128,7 +152,8 @@ export function parseDelegateCommand(
   const errors: string[] = [];
   const notices: string[] = [];
   let allowDangerousBare = false;
-  let budgetWithoutValue = false;
+  // `--budget` / `--timeout` given with no `=value` (e.g. the space form `--budget 5`)
+  const valuelessLimits = new Set<string>();
   const rest = raw.replace(
     FLAG_OR_PROSE,
     (
@@ -155,11 +180,11 @@ export function parseDelegateCommand(
       }
       const hasValue = dq !== undefined || sq !== undefined || bare !== undefined;
       if (!hasValue) {
-        // bare boolean flag: only `--allow-dangerous`. A bare `--budget` (e.g. the space form
-        // `--budget 5`) is an explicit cap we can't honor — an error, never silently "no cap".
-        // Any other bare `--word` is prose.
-        if (k === 'budget') {
-          budgetWithoutValue = true;
+        // bare boolean flag: only `--allow-dangerous`. A bare `--budget`/`--timeout` (e.g. the space
+        // form `--budget 5`) is an explicit limit we can't honor — an error, never silently "no
+        // limit". Any other bare `--word` is prose.
+        if (k === 'budget' || k === 'timeout') {
+          valuelessLimits.add(k);
           return m;
         }
         if (k !== 'allow-dangerous') return m;
@@ -188,10 +213,14 @@ export function parseDelegateCommand(
       'unbalanced " or ` in the command — flags around it can\'t be told apart from prompt text; close the quote (or remove it) and try again',
     );
   }
-  if (budgetWithoutValue && flags.budget === undefined) {
-    errors.push(
-      '--budget needs a value: use --budget=<usd> (or wrap the text in backticks if it is part of the prompt)',
-    );
+  for (const [k, unit] of [
+    ['budget', 'usd'],
+    ['timeout', 'sec'],
+  ] as const) {
+    if (valuelessLimits.has(k) && flags[k] === undefined)
+      errors.push(
+        `--${k} needs a value: use --${k}=<${unit}> (or wrap the text in backticks if it is part of the prompt)`,
+      );
   }
 
   let harness = flags.harness !== undefined ? normalizeHarnessSpec(flags.harness) : undefined;
@@ -225,6 +254,16 @@ export function parseDelegateCommand(
     if (flags.budget.trim() !== '' && Number.isFinite(budget) && budget > 0) out.budget = budget;
     else errors.push(`--budget must be a positive number of USD (got "${flags.budget}")`);
   }
+  if (flags.timeout !== undefined) {
+    const v = flags.timeout.trim();
+    const sec = /^\d{1,9}$/.test(v) ? Number(v) : Number.NaN;
+    // an explicit time limit that can't be honored is an error, never silently "the configured one"
+    if (callTimeoutError(sec) === null) out.timeoutSec = sec;
+    else
+      errors.push(
+        `--timeout must be a whole number of seconds from ${TEMPLATE_TIMEOUT_MIN_SEC} to ${TEMPLATE_TIMEOUT_MAX_SEC} (got "${flags.timeout.slice(0, 40)}")`,
+      );
+  }
   if (flags.resume) out.sessionId = flags.resume;
   if (flags.pr) out.pr = flags.pr;
   if (flags.verify) out.verify = flags.verify;

package/extensions/config.ts

@@ -12,6 +12,7 @@ import {
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DEFAULT_TIMEOUT_MS, type Harness, type Transport } from './harnesses/types.ts';
+import { TEMPLATE_TIMEOUT_MAX_SEC } from './templates.ts';
 
 export interface HarnessConfig {
   model?: string;
@@ -431,6 +432,44 @@ export function writeDelegateConfig(delegateSubtree: unknown): WriteConfigResult
   }
 }
 
+/**
+ * The harness timeout for one run. The **configured** timeout is, most specific first:
+ *
+ * 1. the template's `timeout:` frontmatter;
+ * 2. the **per-harness** config `harnesses.<name>.timeoutMs`;
+ * 3. the **global** config `timeoutMs` (always set, defaults to `DEFAULT_TIMEOUT_MS`).
+ *
+ * A **per-call** timeout then applies on top, and who set it matters:
+ *
+ * - `callMayRaise: true` — a human typed it (`/delegate --timeout=<sec>`): it replaces the configured
+ *   timeout, up or down;
+ * - `callMayRaise: false` (the default) — the model set it (`delegate` tool `timeoutSec`): it can only
+ *   **lower** the configured timeout, never raise it. A tool param is model-settable and the model's
+ *   context is attacker-influenceable, so a raising value would let a prompt-injected model hold every
+ *   `maxConcurrent` slot far past what the user configured. Same "model-settable params only narrow"
+ *   rule as `allowDangerous`/`addDirs`/`verify`.
+ *
+ * Never unbounded: a call or template value (seconds) is clamped to `TEMPLATE_TIMEOUT_MAX_SEC` here
+ * as defense in depth — `parseTemplateTimeout` / `callTimeoutError` already reject out-of-range
+ * values with a clear message — and config values are only ever positive numbers (`loadConfig`).
+ * With neither a call nor a template timeout this is exactly the previous
+ * `harnesses.<name>.timeoutMs ?? timeoutMs`.
+ */
+export function resolveRunTimeoutMs(
+  cfg: DelegateConfig,
+  harnessName: string,
+  templateTimeoutSec?: number,
+  callTimeoutSec?: number,
+  callMayRaise = false,
+): number {
+  const usable = (v: number | undefined): v is number => typeof v === 'number' && Number.isFinite(v) && v > 0;
+  const capMs = (sec: number) => Math.min(sec, TEMPLATE_TIMEOUT_MAX_SEC) * 1000;
+  const raw = cfg.harnesses[harnessName]?.timeoutMs;
+  const configured = usable(templateTimeoutSec) ? capMs(templateTimeoutSec) : usable(raw) ? raw : cfg.timeoutMs;
+  if (!usable(callTimeoutSec)) return configured;
+  return callMayRaise ? capMs(callTimeoutSec) : Math.min(capMs(callTimeoutSec), configured);
+}
+
 export function resolveModelForHarness(
   cfg: DelegateConfig,
   harness: string,

package/extensions/engine.ts

@@ -30,6 +30,7 @@ import {
   legacyOutputsDir,
   loadConfig,
   resolveModelForHarness,
+  resolveRunTimeoutMs,
   resolveTransport,
 } from './config.ts';
 import {
@@ -43,10 +44,13 @@ import {
 import type { ActivityEvent, NormalizedPermission } from './harnesses/types.ts';
 import { runHarness } from './runner.ts';
 import {
+  callTimeoutError,
   type DelegateTemplate,
   describeSkippedProjectTemplates,
   loadTemplates,
+  nativeOverrideWarning,
   projectTemplatePresence,
+  quoteValue,
   resolveNativePermission,
 } from './templates.ts';
 import { validateDelegateInputs } from './validate.ts';
@@ -68,6 +72,17 @@ export interface DelegateOptions {
   /** Extra directories the harness may access, merged with the template's `addDirs` (relative
    *  paths resolve against the run's cwd). Per-harness limits apply — see each `buildArgs`. */
   addDirs?: string[];
+  /**
+   * Per-call harness timeout in seconds, bounded like a template timeout (an out-of-range value fails
+   * the run). By default it can only **lower** the configured timeout (template > per-harness >
+   * global) — the model-settable `delegate` tool's semantics; see `resolveRunTimeoutMs`.
+   */
+  timeoutSec?: number;
+  /**
+   * The per-call `timeoutSec` was typed by a human (`/delegate --timeout=`), so it may also raise the
+   * configured timeout. Only the command paths set this — never the tool path, never from config.
+   */
+  timeoutSecMayRaise?: boolean;
   /**
    * Host-run verification command override — takes precedence over the template's `verify`
    * frontmatter. Internal engine option only, not exposed on the `delegate` tool's schema — see
@@ -333,6 +348,11 @@ export async function delegate(
     addDirs: opts.addDirs,
     cwd: ctx.cwd,
   });
+  // a per-call timeout we can't honor is an error, never silently "the configured timeout"
+  if (opts.timeoutSec !== undefined) {
+    const timeoutErr = callTimeoutError(opts.timeoutSec);
+    if (timeoutErr) throw new Error(timeoutErr);
+  }
   const config = loadConfig();
   const harnessName = opts.harness ?? config.defaultHarness ?? 'claude';
   const harness = getHarness(harnessName);
@@ -351,19 +371,6 @@ export async function delegate(
     );
   const task = opts.task || template.defaultTask;
   if (!task) throw new Error(`delegate mode "${mode}" requires a task`);
-  // A template permission problem (an unrecognized legacy value failed closed to readonly, or an
-  // ignored legacy key) is otherwise only visible in `/delegate list` — say so where the run happens.
-  const warning = template.permissionWarning && `⚠ template "${mode}": ${template.permissionWarning}`;
-  if (warning) {
-    if (ctx.hasUI) ctx.ui.notify?.(warning, 'warning');
-    else process.stderr.write(`${warning}\n`);
-  }
-
-  // Fail-fast, before acquireSlot()/spawn — configuring e.g. transport:'acp' for a harness with no
-  // ACP surface (or 'stdout' for an ACP-only one) should error immediately with a clear message,
-  // not spawn the process and surface a cryptic native failure. See config.ts's resolveTransport.
-  const transport = resolveTransport(config, harnessName, harness);
-
   // permission: normalized, danger requires explicit per-call allowDangerous:true (tool: model-set,
   // human-confirmed in execute(); command: --allow-dangerous, human-confirmed in the handler). Resolved (and
   // the danger refusal thrown) before acquireSlot() — it's pure, so a refused run never occupies
@@ -377,6 +384,41 @@ export async function delegate(
     nativeClass === 'safe'
       ? (nativePermissionTier(harness, template.nativePermission) ?? template.permission)
       : template.permission;
+  const isNativeDanger = nativeClass === 'danger' || nativeClass === 'unlisted';
+
+  // A template permission problem (an unrecognized legacy value failed closed to readonly, or an
+  // ignored legacy key) is otherwise only visible in `/delegate list` — say so where the run happens.
+  // A legacy key ignored next to a *native* `permission:` can only be judged here, where the native
+  // value's tier on this harness is known (danger/unlisted run as danger once confirmed). Report-only:
+  // the tier above is untouched — `permission:` still wins.
+  const permissionWarning =
+    template.permissionWarning ??
+    (template.ignoredLegacyPermission && template.nativePermission
+      ? nativeOverrideWarning(
+          template.ignoredLegacyPermission,
+          template.nativePermission,
+          isNativeDanger ? 'danger' : templateTier,
+          harness.name,
+        )
+      : undefined);
+  // The mode is a template `name:` — frontmatter, so quoted/escaped like every other echoed value…
+  // …and so is a non-permission frontmatter field that was ignored (an out-of-range `timeout:`, a
+  // rejected `harnesses:` entry) — same channels, one line per problem.
+  const warning =
+    [permissionWarning, ...(template.fieldWarnings ?? [])]
+      .filter(Boolean)
+      .map(w => `⚠ template ${quoteValue(mode, 200)}: ${w}`)
+      .join('\n') || undefined;
+  if (warning) {
+    if (ctx.hasUI) ctx.ui.notify?.(warning, 'warning');
+    else process.stderr.write(`${warning}\n`);
+  }
+
+  // Fail-fast, before acquireSlot()/spawn — configuring e.g. transport:'acp' for a harness with no
+  // ACP surface (or 'stdout' for an ACP-only one) should error immediately with a clear message,
+  // not spawn the process and surface a cryptic native failure. See config.ts's resolveTransport.
+  const transport = resolveTransport(config, harnessName, harness);
+
   let permission: NormalizedPermission = templateTier;
   // A safe native matches its allowlist case-insensitively (`Plan`), but what reaches argv/ACP is
   // always the allowlist's canonical spelling (`plan`, claude's camelCase `acceptEdits`) — never the
@@ -385,15 +427,14 @@ export async function delegate(
     nativeClass === 'safe'
       ? canonicalSafeNativePermission(harness, template.nativePermission)
       : template.nativePermission;
-  const isNativeDanger = nativeClass === 'danger' || nativeClass === 'unlisted';
   if (template.permission === 'danger' || isNativeDanger) {
     if (opts.allowDangerous !== true) {
       const why =
         nativeClass === 'unlisted'
-          ? ` (native permission "${nativePerm}" is not a known readonly/edit mode for ${harnessName}, so it is treated as danger)`
+          ? ` (native permission ${quoteValue(String(nativePerm), 200)} is not a known readonly/edit mode for ${harnessName}, so it is treated as danger)`
           : '';
       throw new Error(
-        `template "${mode}" requires danger permission${why} — never a default: pass allowDangerous:true on the delegate tool, or --allow-dangerous on /delegate (both ask you to confirm interactively)`,
+        `template ${quoteValue(mode, 200)} requires danger permission${why} — never a default: pass allowDangerous:true on the delegate tool, or --allow-dangerous on /delegate (both ask you to confirm interactively)`,
       );
     }
     permission = 'danger';
@@ -415,6 +456,15 @@ export async function delegate(
   const addDirs = mergeAddDirs(ctx.cwd, template.addDirs, opts.addDirs);
   const maxBudgetUsd =
     opts.maxBudgetUsd ?? template.maxBudgetUsd ?? config.maxBudgetUsd ?? config.harnesses[harnessName]?.maxBudgetUsd;
+  // template `timeout:` > per-harness config > global config; a per-call timeout only lowers that unless
+  // a human typed it — never past the hard cap. See config.ts.
+  const timeoutMs = resolveRunTimeoutMs(
+    config,
+    harnessName,
+    template.timeoutSec,
+    opts.timeoutSec,
+    opts.timeoutSecMayRaise === true,
+  );
 
   // concurrency guard — see concurrency.ts. Single runs (waitForSlot unset) fail fast at capacity,
   // exactly as before; fan-out passes waitForSlot:true to queue instead.
@@ -466,7 +516,7 @@ export async function delegate(
       model,
       maxBudgetUsd,
       signal: opts.signal,
-      timeoutMs: config.harnesses[harnessName]?.timeoutMs ?? config.timeoutMs,
+      timeoutMs,
       resumeSessionId: opts.sessionId,
       addDirs,
       onStream: (t: string) => {
@@ -509,6 +559,7 @@ export async function delegate(
             activityLog: collectActivityLog(activityEvents),
             output: streamedFull,
             warning,
+            timeoutMs,
           }),
         );
       } catch (_e) {
@@ -578,6 +629,7 @@ export async function delegate(
       verify,
       budget,
       warning,
+      timeoutMs,
     }),
   );
   pruneOutputs(outputsDirFor(harnessName), config.maxTranscripts);
@@ -610,7 +662,9 @@ export async function delegate(
       usage: result.usage,
       verify,
       budget,
-      permissionWarning: template.permissionWarning ?? null,
+      permissionWarning: permissionWarning ?? null,
+      templateWarnings: template.fieldWarnings ?? [],
+      timeoutMs,
     },
     result,
     activityLog: collectActivityLog(activityEvents),
@@ -701,6 +755,9 @@ export interface DelegateToolParams {
   sessionId?: string;
   pr?: string;
   addDirs?: string[];
+  /** Per-call harness timeout in seconds, bounded — can only lower the configured timeout, never
+   *  raise it (model-settable). See `DelegateOptions.timeoutSec` / `resolveRunTimeoutMs`. */
+  timeoutSec?: number;
 }
 
 /** One `delegate()` call with the tool's live-feed progress reporting (`onUpdate`). Shared by the

package/extensions/fanout.ts

@@ -109,6 +109,7 @@ export async function runFanoutTool(
           scope: params.scope,
           model: params.model,
           maxBudgetUsd: params.maxBudgetUsd,
+          timeoutSec: params.timeoutSec,
           allowDangerous: params.allowDangerous === true,
           sessionId: params.sessionId,
           pr: params.pr,
@@ -190,6 +191,7 @@ export interface FanoutSpec {
   scope?: string;
   model?: string;
   budget?: number;
+  timeoutSec?: number;
   sessionId?: string;
   pr?: string;
   addDirs?: string[];
@@ -271,6 +273,8 @@ export async function runFanoutConcurrent(
       scope: spec.scope,
       model: spec.model,
       maxBudgetUsd: spec.budget,
+      timeoutSec: spec.timeoutSec,
+      timeoutSecMayRaise: true, // command path only: --timeout= is human-typed
       sessionId: spec.sessionId,
       pr: spec.pr,
       addDirs: spec.addDirs,
@@ -448,6 +452,7 @@ export async function runFanoutCommand(
       scope: resolvedTaskScope.scope,
       model: parsed.model,
       budget: parsed.budget,
+      timeoutSec: parsed.timeoutSec,
       sessionId: parsed.sessionId,
       pr: parsed.pr,
       addDirs: parsed.addDirs,