@henryqw/pi-subagent 7.0.0 → 8.0.0

package/CONTEXT.md

@@ -24,7 +24,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
+- One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns`, positive safe integer) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. On continuing `turn_end`, the existing child Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`maxTurns` default 50; `timeout.idleMinutes`/`maxMinutes` defaults 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
 - Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.

package/README.md

@@ -92,15 +92,16 @@ A rebase that drops all unit commits is a no-op: Flow validates it, skips Review
 
 pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`, which holds two kinds of user-owned configuration: one Markdown file per Role (see [Roles](#roles)) and its own optional JSON file below. Model routing is *not* configured here; children resolve routes through the shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
 
-`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts. All fields are optional; a missing file uses defaults.
+`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and execution budgets. All fields are optional; a missing file uses defaults.
 
 | Field | Required | Possible values | Default |
 | --- | --- | --- | --- |
 | `maxSubagents` | No | Safe integer ≥ 1 | `5` |
+| `maxTurns` | No | Safe integer ≥ 1 | `50` |
 | `timeout.idleMinutes` | No | Positive number of minutes where minutes × 60 000 ms ≤ 2,147,483,647 | `10` |
 | `timeout.maxMinutes` | No | Positive number within the same ms cap that must be greater than `timeout.idleMinutes`, otherwise the whole `timeout` object falls back to defaults | `30` |
 
-Excess children wait FIFO without consuming child timeout. `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session (positive integer; an invalid value prevents the extension from loading, leaving `delegate_task` unavailable).
+Excess children wait FIFO without consuming child timeout. A terminal response on turn 50 succeeds; an attempted continuation starts no model work and rejects with `turn_limit`. Before a continuing turn, the child receives the execution-budget warning once when completed turns reach 80% and once when elapsed time reaches 80% of the maximum runtime; thresholds first reached together produce one combined warning. `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session (positive integer; an invalid value prevents the extension from loading, leaving `delegate_task` unavailable).
 
 This JSON is read leniently: malformed JSON, a non-object root, unknown keys, or invalid values are collected into one warning and the affected settings fall back to defaults; the file is never rewritten.
 
@@ -153,6 +154,6 @@ A Role explicitly owns base tools, extensions, named Skills, instructions, and o
 
 ## Library API
 
-The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support. After Pi itself exits, it drains inherited stdout/stderr normally but destroys streams still held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
+The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support. It defaults to a 50-turn hard cap and rejects attempted continuation with `turn_limit` while preserving accumulated usage and bounded output. After Pi itself exits, it drains inherited stdout/stderr normally but destroys streams still held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
 
 Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` with a caller-owned Model Task declaration against the latest Pi context.

package/dist/ephemeral.d.ts

@@ -1,11 +1,14 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import type { PiLaunch } from "./index.ts";
+export declare const DEFAULT_MAX_TURNS = 50;
+export declare const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 export interface EphemeralSubagentTimeout {
     idleMs: number;
     maxMs: number;
 }
 export interface EphemeralSubagentExecutorOptions {
     maxConcurrency: number;
+    maxTurns?: number;
     timeout: EphemeralSubagentTimeout;
 }
 export type EphemeralSubagentActivityEvent = {
@@ -44,12 +47,13 @@ export type EphemeralSubagentResult = (EphemeralSubagentResultBase & {
 }) | (EphemeralSubagentResultBase & {
     outcome: "failure";
 });
-export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "spawn" | "protocol" | "prepare" | "callback";
+export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "turn_limit" | "spawn" | "protocol" | "prepare" | "callback";
 export declare class EphemeralSubagentError extends Error {
     name: string;
     readonly code: EphemeralSubagentErrorCode;
     readonly usage?: Usage;
-    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage);
+    readonly output?: string;
+    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage, output?: string);
 }
 export interface EphemeralSubagentExecutor {
     run(input: EphemeralSubagentRunInput): Promise<EphemeralSubagentResult>;

package/dist/ephemeral.js

@@ -4,6 +4,8 @@ import { basename } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_TURNS = 50;
+export const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 const MAX_ACTIVITY_TEXT_BYTES = 4 * 1024;
 // A JSON string byte can take six source bytes (for example, \u0000).
 const MAX_ACTIVITY_PREFIX_BYTES = 2 * MAX_ACTIVITY_TEXT_BYTES * 6 + 1024;
@@ -43,10 +45,12 @@ export class EphemeralSubagentError extends Error {
     name = "EphemeralSubagentError";
     code;
     usage;
-    constructor(code, message, cause, usage) {
+    output;
+    constructor(code, message, cause, usage, output) {
         super(message, cause === undefined ? undefined : { cause });
         this.code = code;
         this.usage = usage;
+        this.output = output;
     }
 }
 function positiveDelay(value, field) {
@@ -61,6 +65,9 @@ function validateOptions(options) {
     if (!Number.isSafeInteger(options.maxConcurrency) || options.maxConcurrency < 1) {
         throw new RangeError("maxConcurrency must be a positive safe integer.");
     }
+    const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1)
+        throw new RangeError("maxTurns must be a positive safe integer.");
     if (!options.timeout || typeof options.timeout !== "object")
         throw new TypeError("timeout is required.");
     const timeout = {
@@ -69,7 +76,7 @@ function validateOptions(options) {
     };
     if (timeout.maxMs <= timeout.idleMs)
         throw new RangeError("timeout.maxMs must be greater than timeout.idleMs.");
-    return { maxConcurrency: options.maxConcurrency, timeout };
+    return { maxConcurrency: options.maxConcurrency, maxTurns, timeout };
 }
 function abortError(signal, cause = signal?.reason, usage) {
     return new EphemeralSubagentError("aborted", "Subagent was aborted.", cause, usage);
@@ -202,7 +209,7 @@ export function createEphemeralSubagentExecutor(options) {
                 }
                 if (input.signal?.aborted)
                     throw abortError(input.signal);
-                return await runPi(prepared, input, validated.timeout, invocation);
+                return await runPi(prepared, input, validated, invocation);
             }
             finally {
                 release();
@@ -362,16 +369,23 @@ export function formatDuration(milliseconds) {
     const minutes = Math.floor(seconds % 3_600 / 60);
     return hours ? `${hours}h ${minutes}m` : minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
 }
-async function runPi(prepared, input, timeoutPolicy, invocation) {
+async function runPi(prepared, input, budget, invocation) {
     if (input.signal?.aborted)
         throw abortError(input.signal);
+    const timeoutPolicy = budget.timeout;
     return await new Promise((resolve, reject) => {
         const args = [...invocation.args, "--mode", "json", "-p", ...prepared.launch.args, `Task: ${prepared.task}`];
+        const startedAt = Date.now();
+        const maxDeadline = startedAt + timeoutPolicy.maxMs;
         let child;
         try {
             child = spawn(invocation.command, args, {
                 cwd: prepared.cwd,
-                env: { ...process.env, ...prepared.launch.env },
+                env: {
+                    ...process.env,
+                    ...prepared.launch.env,
+                    [EXECUTION_BUDGET_ENV]: JSON.stringify({ maxTurns: budget.maxTurns, maxMs: timeoutPolicy.maxMs, startedAt }),
+                },
                 shell: false,
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
@@ -397,8 +411,8 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
         let spawnError;
         let protocolError;
         let aborted = false;
-        const startedAt = Date.now();
-        const maxDeadline = startedAt + timeoutPolicy.maxMs;
+        let turnLimited = false;
+        let startedTurns = 0;
         let lastEventAt = startedAt;
         let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline);
         let timedOutAfterMs;
@@ -480,6 +494,11 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                     : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
                 reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
             }
+            else if (turnLimited) {
+                const summary = `Subagent reached its maximum turn limit of ${budget.maxTurns}.`;
+                const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
+                reject(new EphemeralSubagentError("turn_limit", message, new Error(message), accumulatedUsage(), output));
+            }
             else if (protocolError) {
                 reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
             }
@@ -551,7 +570,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             scheduleDeadline();
         };
         const processLine = (line) => {
-            if (!line.trim())
+            if (turnLimited || !line.trim())
                 return;
             let event;
             try {
@@ -566,6 +585,12 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             if (typeof record.type !== "string" || !Object.hasOwn(PI_JSON_EVENTS, record.type))
                 return;
             observeEvent();
+            if (record.type === "turn_start" && ++startedTurns > budget.maxTurns) {
+                if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                    turnLimited = true;
+                stop(true);
+                return;
+            }
             if (record.type === "message_start") {
                 partial.prefix = "";
                 partial.totalBytes = 0;
@@ -690,7 +715,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
         };
         onStdoutData = (data) => {
             armPostExitIdleDeadline();
-            if (callbackFailure || protocolError)
+            if (callbackFailure || protocolError || turnLimited)
                 return;
             let offset = 0;
             while (offset < data.length) {
@@ -731,7 +756,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                         invokeCallback("onActivity", input.onActivity, activity);
                     }
                 }
-                if (callbackFailure)
+                if (callbackFailure || turnLimited)
                     return;
                 lineParts = [];
                 lineBytes = 0;
@@ -771,13 +796,13 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             killTimer.unref();
         }
         const abort = () => {
-            if (timedOutAfterMs !== undefined || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || childExited)
                 return;
             aborted = true;
             stop();
         };
         function timeout(afterMs, reason) {
-            if (timedOutAfterMs !== undefined || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || childExited)
                 return;
             if (reason === "maximum") {
                 if (!aborted) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type HerdrExecutor } from "@henryqw/pi-herdr";
 import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
-export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, EphemeralSubagentError, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode, startPiAgent } from "@henryqw/pi-herdr";
 import { modelReference, orderedProfileRoutes, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
-export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, EphemeralSubagentError, formatDuration, } from "./ephemeral.js";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;

package/docs/orchestration.md

@@ -161,11 +161,12 @@ A loaded `Role` contains `name`, `description`, required normalized `tools`, `ex
 ```js
 const executorOptions = {
   maxConcurrency: 4,
+  maxTurns: 50,
   timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
 };
 ```
 
-Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency`, `idleMs`, and `maxMs` must be positive; `maxMs` must exceed `idleMs`.
+Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency`, `maxTurns`, `idleMs`, and `maxMs` must be positive; integer limits must be safe integers, `maxMs` must exceed `idleMs`, and omitted `maxTurns` defaults to 50.
 
 The executor is **active-Pi-only**. It reuses the currently running Pi invocation and does not locate or support a standalone Node.js Pi installation. Once direct Pi exits, stdout/stderr drain normally until EOF; an escaped descendant retaining either stream is cut off after short output inactivity or a one-second hard deadline so it cannot retain the FIFO permit.
 
@@ -193,6 +194,7 @@ export function createRunRole(pi) {
 
   const executor = createEphemeralSubagentExecutor({
     maxConcurrency: 4,
+    maxTurns: 50,
     timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
   });
 
@@ -244,7 +246,7 @@ export function createRunRole(pi) {
 }
 ```
 
-`run` resolves to `EphemeralSubagentResult`. Both outcome variants contain `exitCode`, `output`, `stderr`, and optional `stopReason`, `errorMessage`, and `usage`. A launched child/model failure is a typed `{ outcome: "failure", ... }` result. Abort, timeout, spawn, protocol, preparation, and callback failures reject with `EphemeralSubagentError` and a stable `code`. Assistant `output` and `stderr` are bounded, and `usage` contains aggregate child usage when Pi supplies it.
+`run` resolves to `EphemeralSubagentResult`. Both outcome variants contain `exitCode`, `output`, `stderr`, and optional `stopReason`, `errorMessage`, and `usage`. A launched child/model failure is a typed `{ outcome: "failure", ... }` result. Abort, timeout, turn-limit, spawn, protocol, preparation, and callback failures reject with `EphemeralSubagentError` and a stable `code`. A terminal response at `maxTurns` succeeds; an attempted continuation rejects with `turn_limit`, accumulated `usage`, and bounded `output`. The executor supplies the same turn/maximum-runtime budget to the existing child Role tool extension, which steers the fixed convergence warning before another model turn once at each 80% threshold, combines thresholds first due together, and uses no timer or extra turn. Assistant `output` and `stderr` are bounded, and `usage` contains aggregate child usage when Pi supplies it.
 
 ### Activity callbacks
 

package/extensions/config.ts

@@ -11,6 +11,7 @@ export interface SubagentTimeoutConfig {
 
 export interface SubagentConfig {
 	maxSubagents?: number;
+	maxTurns?: number;
 	timeout?: SubagentTimeoutConfig;
 }
 
@@ -66,16 +67,18 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 	const problems: string[] = [];
 	const config: SubagentConfig = {};
 	for (const key of Object.keys(record)) {
-		if (key !== "maxSubagents" && key !== "timeout") {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected maxSubagents, timeout`);
+		if (key !== "maxSubagents" && key !== "maxTurns" && key !== "timeout") {
+			problems.push(`unknown config key ${JSON.stringify(key)}; expected maxSubagents, maxTurns, timeout`);
 		}
 	}
 
-	if (record.maxSubagents !== undefined) {
-		if (typeof record.maxSubagents === "number" && Number.isSafeInteger(record.maxSubagents) && record.maxSubagents >= 1) {
-			config.maxSubagents = record.maxSubagents;
+	for (const key of ["maxSubagents", "maxTurns"] as const) {
+		const value = record[key];
+		if (value === undefined) continue;
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) {
+			config[key] = value;
 		} else {
-			problems.push(`maxSubagents must be a safe integer >= 1, got ${JSON.stringify(record.maxSubagents)}`);
+			problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
 		}
 	}
 

package/extensions/delegate-flow.ts

@@ -795,8 +795,8 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		description: "Run 1–8 independent Implementers in isolated Unit Worktrees, validate and serially fast-forward each tip, with exact review only for units that declare a judgment criterion.",
 		promptSnippet: "Run a deterministic parallel-implementation, serial-verification Flow",
 		promptGuidelines: [
-			"Use delegate_flow only for cohesive units expected to commute; combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
-			"Each unit must include explicit bounded requirements and its authoritative direct command/argument validation gate. Add review only for an explicit judgment that validation cannot establish.",
+			"Use delegate_flow only for cohesive units expected to commute: split independent outcomes into units, sequence dependent work outside delegate_flow, and never divide one invariant across multiple units. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
+			"Each delegate_flow unit must own one concrete outcome with one focused validation story: include explicit bounded requirements and its authoritative direct command/argument validation gate. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Add review only for an explicit judgment that validation cannot establish.",
 			"If a Flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance; modelClass may replace that one repair's current class.",
 		],
 		parameters: DelegateFlowSchema,

package/extensions/role-tools.ts

@@ -1,7 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CHILD_EXCLUDED_TOOL_NAMES, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
+import { CHILD_EXCLUDED_TOOL_NAMES, EXECUTION_BUDGET_ENV, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
 
 const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
+const WARNING_RATIO = 0.8;
+const WARNING_MESSAGE_TYPE = "pi-subagent-execution-budget";
 
 function configuredTools(value: unknown): string[] {
 	if (typeof value !== "string") throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
@@ -17,6 +19,35 @@ function configuredTools(value: unknown): string[] {
 	return [...new Set(parsed.map((name) => name.trim()))];
 }
 
+function executionBudget(value: string | undefined): { maxTurns: number; maxMs: number; startedAt: number } | undefined {
+	if (value === undefined) return;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	const budget = parsed as Record<string, unknown>;
+	if (Object.keys(budget).length !== 3 || !("maxTurns" in budget) || !("maxMs" in budget) || !("startedAt" in budget)
+		|| !Number.isSafeInteger(budget.maxTurns) || (budget.maxTurns as number) < 1
+		|| typeof budget.maxMs !== "number" || !Number.isFinite(budget.maxMs) || budget.maxMs <= 0
+		|| !Number.isSafeInteger(budget.startedAt) || (budget.startedAt as number) < 0) {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	return { maxTurns: budget.maxTurns as number, maxMs: budget.maxMs, startedAt: budget.startedAt as number };
+}
+
+function expectsAnotherTurn(message: unknown): boolean {
+	if (!message || typeof message !== "object" || Array.isArray(message)) return false;
+	const record = message as Record<string, unknown>;
+	return record.role === "assistant" && Array.isArray(record.content)
+		&& record.content.some((part) => part && typeof part === "object" && !Array.isArray(part)
+			&& (part as Record<string, unknown>).type === "toolCall");
+}
+
 export default function roleTools(pi: ExtensionAPI): void {
 	pi.registerFlag(ROLE_TOOL_POLICY_FLAG, {
 		description: "Internal Pi Subagent Role tool policy",
@@ -36,4 +67,29 @@ export default function roleTools(pi: ExtensionAPI): void {
 			throw new Error(`Subagent requested unavailable tools: ${unavailable.join(", ")}. Check spelling and load the provider extension that registers them.`);
 		}
 	});
+
+	const budget = executionBudget(process.env[EXECUTION_BUDGET_ENV]);
+	if (!budget) return;
+	const warningTurn = Math.ceil(budget.maxTurns * WARNING_RATIO);
+	let completedTurns = 0;
+	let turnWarningSent = false;
+	let runtimeWarningSent = false;
+	pi.on("turn_end", (event) => {
+		completedTurns += 1;
+		if (!expectsAnotherTurn(event.message)) return;
+		const elapsedMs = Math.max(0, Date.now() - budget.startedAt);
+		const turnWarningDue = !turnWarningSent && completedTurns >= warningTurn;
+		const runtimeWarningDue = !runtimeWarningSent && elapsedMs >= budget.maxMs * WARNING_RATIO;
+		if (!turnWarningDue && !runtimeWarningDue) return;
+		if (turnWarningDue) turnWarningSent = true;
+		if (runtimeWarningDue) runtimeWarningSent = true;
+		const remainingTurns = Math.max(0, budget.maxTurns - completedTurns);
+		const remainingMinutes = Math.max(0, Math.ceil((budget.maxMs - elapsedMs) / 60_000));
+		const maxMinutes = budget.maxMs / 60_000;
+		pi.sendMessage({
+			customType: WARNING_MESSAGE_TYPE,
+			content: `**Execution budget warning:** ${remainingTurns} of ${budget.maxTurns} turns and approximately ${remainingMinutes} of ${maxMinutes} minutes remain before forced termination.\nConverge now: stop expanding scope, complete the highest-priority required work, perform only essential validation, and return a concise final result. If completion is impossible, follow your role’s recovery requirements and report the blocker and exact remaining work. This warning does not change your role, scope, or permissions.`,
+			display: true,
+		}, { deliverAs: "steer", triggerTurn: false });
+	});
 }

package/extensions/subagent.ts

@@ -18,6 +18,7 @@ import {
 	createEphemeralSubagentExecutor,
 	DELEGATE_TASK,
 	createRoleLaunch,
+	DEFAULT_MAX_TURNS,
 	EphemeralSubagentError,
 	finalizeChildWorktree,
 	formatDuration,
@@ -331,7 +332,11 @@ export default function subagentExtension(
 	// Explicit policy argument (tests/embedders) wins; otherwise resolve from
 	// config file over defaults.
 	const timeoutPolicy: TimeoutPolicy = overrideTimeoutPolicy ?? resolveTimeoutPolicy(loadedConfig.config.timeout);
-	const executor = createEphemeralSubagentExecutor({ maxConcurrency: maxActiveSubagents, timeout: timeoutPolicy });
+	const executor = createEphemeralSubagentExecutor({
+		maxConcurrency: maxActiveSubagents,
+		maxTurns: loadedConfig.config.maxTurns ?? DEFAULT_MAX_TURNS,
+		timeout: timeoutPolicy,
+	});
 	// Background children outlive the launching tool call, so they get their own
 	// abort signal: tied to the session, not to the turn that started them.
 	const backgroundTasks = new Map<string, { controller: AbortController; settled: Promise<void> }>();
@@ -602,8 +607,8 @@ export default function subagentExtension(
 		description: `Delegate one selected single, parallel, or chain workflow of bounded tasks to isolated Pi Subagents. Roles: ${roleSummary()}.`,
 		promptSnippet: "Delegate one bounded single, parallel, or chain workflow to isolated roles",
 		promptGuidelines: [
-			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output.",
-			"Every delegate_task entry must state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; never pass the parent request unchanged.",
+			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; split independent, commuting outcomes into parallel entries, sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
+			"Every delegate_task entry must own one concrete outcome with one focused validation story: state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; if the affected flow or scope is not yet known, perform bounded read-only discovery first; never pass the parent request unchanged.",
 			"For each delegate_task entry, populate model and thinking only for an explicit user override; otherwise choose only modelClass: fast normally, or balanced upfront for obviously complex work. This is Main policy, not runtime enforcement.",
 			"Parallel delegate_task entries must own non-overlapping files. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.",
 			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -39,9 +39,9 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.3",
-    "@earendil-works/pi-coding-agent": "^0.84.3",
-    "@earendil-works/pi-tui": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "^1.3.15"
   },
   "repository": {

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -11,9 +11,9 @@ You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do
 
 Before slicing, identify applicable repository prohibitions. If the request or plan conflicts with them, stop and resolve the conflict before delegation. Copy them into every affected task and into `review` when automated validation cannot establish compliance; never replace repository policy with generic preservation or migration assumptions. When compatibility is disallowed, require deletion of replaced paths and forbid legacy readers, aliases, adapters, dual schemas, deprecation paths, and compatibility fallbacks.
 
-Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute; combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Dependent work remains outside Flow, in one task or ordinary caller-controlled sequencing.
+Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute: split independent outcomes into units, combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants, and never divide one invariant across multiple units. Dependent work remains outside Flow; sequence it in one task or ordinary caller-controlled sequencing.
 
-Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array. Do not pass the parent request unchanged. Use `modelClass: "fast"` normally; use `"balanced"` upfront only for obviously complex work. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
+Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array; each delegation must own one concrete outcome with one focused validation story. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Do not pass the parent request unchanged. Use `modelClass: "fast"` normally; use `"balanced"` upfront only for obviously complex work. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
 
 ## Runtime Flow