@henryqw/pi-subagent 15.1.0 → 15.1.2

package/CONTEXT.md

@@ -23,7 +23,8 @@ 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. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns` is a safe integer >= 1; default 50) 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. When Role launches, including `delegate_task` and each `delegate_flow` Implementer or Reviewer launch, reach a continuing penultimate `turn_end`, they reserve the final allowed turn for a response-only handoff: after its tools, they disable every tool and steer one structured final report. With `maxTurns` set to 1, they disable tools during `session_start`, and the sole provider turn is the response-only handoff. Its fixed decision packet is the default, but exact output required by the assigned task or Role takes precedence and is returned alone. A terminal penultimate response gets no handoff. This does not extend the executor limit. Raw `createEphemeralSubagentExecutor` launches do not guarantee a handoff, and timeout, provider, or child-process failures can prevent one. Before the final boundary, the 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/config.json` (`maxTurns` is a safe integer >= 1 and defaults to 50; `timeout.idleMinutes`/`maxMinutes` default to 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` is a safe integer >= 1; default 50), attempted continuation after the optional token handoff, 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. Optional `maxTokens` is a safe integer >= 1 with an unlimited default. It is one global executor default applied independently to every `delegate_task` child and every Flow Implementer, Reviewer, and repair child; it is neither a shared pool nor a per-call or environment option. Token accounting sums each completed assistant response's `Usage.totalTokens` once, matching the executor's aggregate `Usage`. A terminal response crossing the limit succeeds. A continuing crossing turn and its tools finish, then exactly one extra response turn is permitted. Further continuation rejects with typed `token_limit`, aggregate usage, and bounded last assistant output. This permits a crossing turn plus the final response to overshoot; it is not an exact hard cap. Raw executor launches enforce the extra-turn window but do not guarantee tools are disabled.
+- Every Role launch installs the shared tool policy. On a continuing token crossing, or the continuing penultimate `maxTurns` turn, the policy waits for `turn_end`, disables every tool, and steers one structured final report. This covers `delegate_task` and each Flow launch. With `maxTurns` set to 1, tools are disabled during `session_start`, and the sole provider turn is the response-only handoff. The fixed decision packet is the default, but exact task or Role output takes precedence and is returned alone. Terminal boundary responses get no handoff. Before the final boundary, the policy steers the fixed convergence warning once at each 80% threshold for completed turns, aggregate tokens when configured, and maximum runtime. It combines thresholds first due together and starts no timer or extra warning turn. Timeout, provider, or child-process failures can prevent a handoff. 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/config.json` (`maxTurns` defaults to 50; `maxTokens` defaults to unlimited; `timeout.idleMinutes`/`maxMinutes` default to 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/config.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
 - 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

@@ -80,6 +80,15 @@ See the [orchestration guide](./docs/orchestration.md) for full delegation, tran
 
 The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation.
 
+Before delegating:
+
+- Find concrete outcomes that can ship on their own.
+- Split only those outcomes. Give each one owner and a focused check.
+- Run independent work in parallel.
+- Prefer parallel delegation when at least two outcomes are independent.
+- For naturally multi-part work, roughly three to five useful units can help.
+- This is a guide, not a quota. Never create units just to reach it.
+
 Its ordinary review loop is optional. Use it only when the caller or repository policy explicitly requires judgment review.
 
 - Call `delegate_task` with `role: "reviewer"` to select the effective `reviewer` Role.
@@ -92,7 +101,11 @@ Flow is separate. It owns exact review evidence, exact `PASS` approval, validati
 
 ## Flow
 
-Flow requires a clean Main worktree on an attached branch with a committed `HEAD`. Use it only for independent Git changes that can merge in any order. Do not split units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
+Flow requires a clean Main worktree on an attached branch with a committed `HEAD`. Use it only for independent Git changes that can merge in any order.
+
+Keep work together or run it in order when a split divides an invariant or adds coordination. Do not split units with overlapping mutable ownership. Do not split units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
+
+One Implementer launch must plausibly finish before the configured maximum runtime. Cohesion is not enough when work has several preservable, separately verifiable milestones. Split oversized dependent work into serial one-unit Flows after each milestone integrates. Units in one Flow stay independent and commuting.
 
 ```text
 delegate_flow({ units: [{ id, name, task, modelClass?, validation: [{ command, args }], review? }] })
@@ -128,22 +141,29 @@ pi-subagent owns `~/.pi/agent/config/pi-subagent/config.json`. It is optional. A
 | --- | --- | --- | --- |
 | `maxSubagents` | Sets the maximum number of active child processes. | Safe integer of at least 1. | `5` |
 | `maxTurns` | Sets the hard provider-turn limit for each child. | Safe integer of at least 1. | `50` |
-| `timeout.idleMinutes` | Sets the idle timeout for a child. | Positive minutes. | `10` |
-| `timeout.maxMinutes` | Sets the maximum runtime for a child. | Positive minutes greater than `idleMinutes`. | `30` |
+| `maxTokens` | Sets the token limit for each child. | Safe integer of at least 1. | Unlimited |
+| `timeout.idleMinutes` | Sets the idle timeout for a child. | Positive minutes; minutes × 60,000 ≤ 2,147,483,647 ms | `10` |
+| `timeout.maxMinutes` | Sets the maximum runtime for a child. | Positive minutes greater than `idleMinutes`; minutes × 60,000 ≤ 2,147,483,647 ms | `30` |
+
+`maxTokens` applies separately to every child. This includes `delegate_task` and each Flow Implementer, Reviewer, and repair launch. It is not a shared pool or per-call option. Set it only in this file.
+
+Pi adds each completed assistant response's `Usage.totalTokens` once. This matches the executor's aggregate `Usage`. At 80%, a Role receives one convergence warning.
+
+A terminal response that crosses `maxTokens` succeeds. A continuing crossing turn completes its tools. Pi then disables tools and allows one response-only handoff. That handoff can overshoot the limit, so `maxTokens` is not an exact cap. Further continuation rejects with `token_limit`, aggregate `Usage`, and bounded last output.
 
 Excess children wait FIFO without using a child timeout. A terminal response on turn 50 succeeds; an attempted continuation rejects with `turn_limit`.
 
 ### Final response handoff
 
-When a Role launch reaches a continuing penultimate turn, Pi reserves the final allowed turn for a response-only handoff. This includes `delegate_task` and every Implementer or Reviewer launch within `delegate_flow`.
+Role launches reserve a response-only handoff at a continuing `maxTokens` crossing or the penultimate `maxTurns` turn. This includes `delegate_task` and every Implementer or Reviewer launch within `delegate_flow`.
 
 With `maxTurns` set to 1, Pi disables tools at startup. The sole provider turn is the response-only handoff.
 
-Pi waits for the penultimate turn's tools. It then disables all tools and requests a final report. The final allowed provider request has no tools. A terminal penultimate response gets no handoff.
+Pi waits for the current turn's tools. It then disables all tools and requests a final report. A terminal boundary response gets no handoff.
 
-The fixed decision packet asks for Status (completed, blocked, or incomplete), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence. The child returns only that output, such as a Flow Reviewer's exact `PASS` or caller-required structured output. It reserves a turn within the existing hard limit; it never adds a model turn. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
+The fixed decision packet asks for Status (completed, blocked, or incomplete), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence. The child returns only that output, such as a Flow Reviewer's exact `PASS` or caller-required structured output. The handoff stays within `maxTurns`, but it is the one allowed turn after a token crossing. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
 
-A raw `createEphemeralSubagentExecutor` launch does not guarantee this handoff. A timeout, provider failure, or child-process failure can end a Role launch before handoff.
+A raw `createEphemeralSubagentExecutor` launch can enforce the extra-turn window. It cannot guarantee disabled tools or the final handoff. A timeout, provider failure, or child-process failure can also end a Role launch before handoff.
 
 Malformed or unreadable JSON, a non-object root, unknown keys, and invalid values produce one warning. Invalid settings use defaults while valid settings still apply. If the effective maximum is not greater than the idle timeout, both timeout settings use defaults. The file is never rewritten.
 

package/dist/ephemeral.d.ts

@@ -2,6 +2,12 @@ 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 EphemeralSubagentExecutionBudget {
+    maxTurns: number;
+    maxMs: number;
+    startedAt: number;
+    maxTokens?: number;
+}
 export interface EphemeralSubagentTimeout {
     idleMs: number;
     maxMs: number;
@@ -9,6 +15,7 @@ export interface EphemeralSubagentTimeout {
 export interface EphemeralSubagentExecutorOptions {
     maxConcurrency: number;
     maxTurns?: number;
+    maxTokens?: number;
     timeout: EphemeralSubagentTimeout;
 }
 export type EphemeralSubagentActivityEvent = {
@@ -47,7 +54,7 @@ export type EphemeralSubagentResult = (EphemeralSubagentResultBase & {
 }) | (EphemeralSubagentResultBase & {
     outcome: "failure";
 });
-export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "turn_limit" | "spawn" | "protocol" | "prepare" | "callback";
+export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "turn_limit" | "token_limit" | "spawn" | "protocol" | "prepare" | "callback";
 export declare class EphemeralSubagentError extends Error {
     name: string;
     readonly code: EphemeralSubagentErrorCode;

package/dist/ephemeral.js

@@ -70,6 +70,9 @@ function validateOptions(options) {
     if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
         throw new RangeError("maxTurns must be a safe integer >= 1.");
     }
+    if (options.maxTokens !== undefined && (!Number.isSafeInteger(options.maxTokens) || options.maxTokens < 1)) {
+        throw new RangeError("maxTokens must be a safe integer >= 1.");
+    }
     if (!options.timeout || typeof options.timeout !== "object")
         throw new TypeError("timeout is required.");
     const timeout = {
@@ -78,7 +81,12 @@ function validateOptions(options) {
     };
     if (timeout.maxMs <= timeout.idleMs)
         throw new RangeError("timeout.maxMs must be greater than timeout.idleMs.");
-    return { maxConcurrency: options.maxConcurrency, maxTurns, timeout };
+    return {
+        maxConcurrency: options.maxConcurrency,
+        maxTurns,
+        ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
+        timeout,
+    };
 }
 function abortError(signal, cause = signal?.reason, usage) {
     return new EphemeralSubagentError("aborted", "Subagent was aborted.", cause, usage);
@@ -378,12 +386,18 @@ async function runPi(prepared, input, budget, invocation) {
         const maxDeadline = startedAt + timeoutPolicy.maxMs;
         let child;
         try {
+            const executionBudget = {
+                maxTurns: budget.maxTurns,
+                maxMs: timeoutPolicy.maxMs,
+                startedAt,
+                ...(budget.maxTokens === undefined ? {} : { maxTokens: budget.maxTokens }),
+            };
             child = spawn(invocation.command, args, {
                 cwd: prepared.cwd,
                 env: {
                     ...process.env,
                     ...prepared.launch.env,
-                    [EXECUTION_BUDGET_ENV]: JSON.stringify({ maxTurns: budget.maxTurns, maxMs: timeoutPolicy.maxMs, startedAt }),
+                    [EXECUTION_BUDGET_ENV]: JSON.stringify(executionBudget),
                 },
                 shell: false,
                 stdio: ["ignore", "pipe", "pipe"],
@@ -411,6 +425,8 @@ async function runPi(prepared, input, budget, invocation) {
         let protocolError;
         let aborted = false;
         let turnLimited = false;
+        let tokenBudget = "within";
+        const tokenLimited = () => tokenBudget === "limited";
         let startedTurns = 0;
         let lastEventAt = startedAt;
         let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline);
@@ -498,6 +514,11 @@ async function runPi(prepared, input, budget, invocation) {
                 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 (tokenLimited()) {
+                const summary = `Subagent reached its maximum token limit of ${budget.maxTokens}.`;
+                const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
+                reject(new EphemeralSubagentError("token_limit", message, new Error(message), accumulatedUsage(), output));
+            }
             else if (protocolError) {
                 reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
             }
@@ -558,7 +579,7 @@ async function runPi(prepared, input, budget, invocation) {
             deadlineTimer.unref();
         };
         const observeEvent = () => {
-            if (callbackFailure || aborted || timedOutAfterMs !== undefined || childExited)
+            if (callbackFailure || aborted || timedOutAfterMs !== undefined || turnLimited || tokenLimited() || childExited)
                 return;
             const now = Date.now();
             if (now >= deadline) {
@@ -568,8 +589,31 @@ async function runPi(prepared, input, budget, invocation) {
             lastEventAt = now;
             scheduleDeadline();
         };
+        const advanceTokenBudget = (event) => {
+            switch (tokenBudget) {
+                case "within":
+                    if (event === "turn_end" && budget.maxTokens !== undefined && completedTokens >= budget.maxTokens) {
+                        tokenBudget = "crossed";
+                    }
+                    return false;
+                case "crossed":
+                    if (event === "turn_start")
+                        tokenBudget = "final_turn";
+                    return false;
+                case "final_turn":
+                    if (event === "turn_start") {
+                        if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                            tokenBudget = "limited";
+                        stop(true);
+                        return true;
+                    }
+                    return false;
+                case "limited":
+                    return true;
+            }
+        };
         const processLine = (line) => {
-            if (turnLimited || !line.trim())
+            if (turnLimited || tokenLimited() || !line.trim())
                 return;
             let event;
             try {
@@ -584,12 +628,18 @@ async function runPi(prepared, input, budget, 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 === "turn_start") {
+                if (++startedTurns > budget.maxTurns) {
+                    if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                        turnLimited = true;
+                    stop(true);
+                    return;
+                }
+                if (advanceTokenBudget("turn_start"))
+                    return;
             }
+            if (record.type === "turn_end")
+                advanceTokenBudget("turn_end");
             if (record.type === "message_start") {
                 partial.prefix = "";
                 partial.totalBytes = 0;
@@ -714,7 +764,7 @@ async function runPi(prepared, input, budget, invocation) {
         };
         onStdoutData = (data) => {
             armPostExitIdleDeadline();
-            if (callbackFailure || protocolError || turnLimited)
+            if (callbackFailure || protocolError || turnLimited || tokenLimited())
                 return;
             let offset = 0;
             while (offset < data.length) {
@@ -755,7 +805,7 @@ async function runPi(prepared, input, budget, invocation) {
                         invokeCallback("onActivity", input.onActivity, activity);
                     }
                 }
-                if (callbackFailure || turnLimited)
+                if (callbackFailure || turnLimited || tokenLimited())
                     return;
                 lineParts = [];
                 lineBytes = 0;
@@ -795,13 +845,13 @@ async function runPi(prepared, input, budget, invocation) {
             killTimer.unref();
         }
         const abort = () => {
-            if (timedOutAfterMs !== undefined || turnLimited || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || tokenLimited() || childExited)
                 return;
             aborted = true;
             stop();
         };
         function timeout(afterMs, reason) {
-            if (timedOutAfterMs !== undefined || turnLimited || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || tokenLimited() || 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 AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.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 { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutionBudget, 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/docs/orchestration.md

@@ -144,13 +144,15 @@ Role Skill names resolve through Main's effective Pi Skill registry at launch. M
 
 ### Role final-turn handoff
 
-Role launches made by `createRoleLaunch` reserve the final allowed turn for a response-only handoff. This includes `delegate_task` and every Implementer or Reviewer launch from `delegate_flow`. A raw `createEphemeralSubagentExecutor` launch does not guarantee a handoff.
+Role launches made by `createRoleLaunch` reserve a response-only handoff at either boundary. They use the penultimate `maxTurns` turn or a continuing `maxTokens` crossing. This includes `delegate_task` and every Flow Implementer, Reviewer, and repair launch.
 
 With `maxTurns` set to 1, Pi disables tools during `session_start`. The sole provider turn is the response-only handoff.
 
-After a continuing penultimate turn, Pi completes its tools. It then disables every active tool and queues one structured final handoff. The final allowed provider request has no tools. A terminal penultimate response gets no handoff.
+After a continuing boundary turn, Pi completes its tools. It then disables every active tool and queues one structured final handoff. A terminal boundary response succeeds without a handoff. If the child continues after the token handoff, the executor rejects with `token_limit`.
 
-The handoff requests a fixed Markdown decision packet with Status (`completed`, `blocked`, or `incomplete`), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence, and the child replies only with it. This preserves a Flow Reviewer's exact `PASS` and caller-required structured output. It reserves a turn inside the executor's existing hard limit. It never adds a model turn. A timeout, provider failure, or child-process failure can end a Role launch before handoff. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
+The handoff requests a fixed Markdown decision packet with Status (`completed`, `blocked`, or `incomplete`), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence, and the child replies only with it. This preserves a Flow Reviewer's exact `PASS` and caller-required structured output. The handoff remains inside `maxTurns`, but it is the one permitted response after crossing `maxTokens`. A timeout, provider failure, or child-process failure can end a Role launch before handoff. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
+
+A raw `createEphemeralSubagentExecutor` launch enforces the token extra-turn window. It does not guarantee disabled tools or the handoff message. Only Role launches install that policy.
 
 ## Public Role and executor API
 
@@ -181,11 +183,14 @@ A loaded `Role` contains `name`, `description`, required normalized `tools`, `ex
 const executorOptions = {
   maxConcurrency: 4,
   maxTurns: 50,
+  maxTokens: 100_000, // optional; omitted means unlimited
   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` and `maxTurns` must be safe integers >= 1. `idleMs` and `maxMs` must be positive. `maxMs` must exceed `idleMs`. Omitted `maxTurns` defaults to 50.
+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`, and configured `maxTokens` must be safe integers >= 1. `idleMs` and `maxMs` must be positive. `maxMs` must exceed `idleMs`. Omitted `maxTurns` defaults to 50. Omitted `maxTokens` is unlimited.
+
+One executor applies `maxTokens` independently to every `run`; it is not a shared pool. `run` has no token override. The built-in extension reads its global value only from `config/pi-subagent/config.json`.
 
 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.
 
@@ -214,6 +219,7 @@ export function createRunRole(pi) {
   const executor = createEphemeralSubagentExecutor({
     maxConcurrency: 4,
     maxTurns: 50,
+    maxTokens: 100_000,
     timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
   });
 
@@ -267,7 +273,11 @@ 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, 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 passes its turn and runtime budget through the child environment. On a Role launch, its tool policy 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.
+`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, token-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`.
+
+Token accounting adds each completed assistant response's `Usage.totalTokens` once. It uses the same aggregate `usage` returned by the executor. A terminal response crossing `maxTokens` succeeds. A continuing crossing response and its tools finish before one final response turn. That turn may overshoot the configured value. Further continuation rejects with `token_limit`, aggregate `usage`, and bounded last assistant `output`.
+
+The executor passes its turn, token, and runtime budget through its internal child protocol. On a Role launch, its tool policy sends one convergence warning at each 80% threshold. It combines thresholds first due together and uses no timer or extra warning 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;
+	maxTokens?: number;
 	timeout?: SubagentTimeoutConfig;
 }
 
@@ -31,6 +32,7 @@ const positive = (value: unknown): value is number =>
 // every child immediately instead of applying the configured deadline.
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
+const INTEGER_FIELDS = ["maxSubagents", "maxTurns", "maxTokens"] as const;
 const TIMEOUT_FIELDS = ["idleMinutes", "maxMinutes"] as const;
 
 /** Return the canonical default JSON path for pi-subagent's config home. */
@@ -45,26 +47,18 @@ function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfi
 	const problems: string[] = [];
 	const config: SubagentConfig = {};
 	for (const key of Object.keys(record)) {
-		if (key !== "maxSubagents" && key !== "maxTurns" && key !== "timeout") {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected maxSubagents, maxTurns, timeout`);
+		if (![...INTEGER_FIELDS, "timeout"].includes(key as typeof INTEGER_FIELDS[number] | "timeout")) {
+			problems.push(`unknown config key ${JSON.stringify(key)}; expected ${INTEGER_FIELDS.join(", ")}, timeout`);
 		}
 	}
 
-	const maxSubagents = record.maxSubagents;
-	if (maxSubagents !== undefined) {
-		if (typeof maxSubagents === "number" && Number.isSafeInteger(maxSubagents) && maxSubagents >= 1) {
-			config.maxSubagents = maxSubagents;
+	for (const key of INTEGER_FIELDS) {
+		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(maxSubagents)}`);
-		}
-	}
-
-	const maxTurns = record.maxTurns;
-	if (maxTurns !== undefined) {
-		if (typeof maxTurns === "number" && Number.isSafeInteger(maxTurns) && maxTurns >= 1) {
-			config.maxTurns = maxTurns;
-		} else {
-			problems.push(`maxTurns must be a safe integer >= 1, got ${JSON.stringify(maxTurns)}`);
+			problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
 		}
 	}
 

package/extensions/delegate-flow.ts

@@ -770,7 +770,7 @@ 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: 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.",
+			"Use delegate_flow only for cohesive units expected to commute: make independent commuting outcomes separate units rather than combining them merely to reduce Implementer count; sequence dependent work outside delegate_flow. On naturally multi-part work, actively look for roughly 3–5 useful units, but never manufacture units, split one invariant across multiple units, assign overlapping mutable ownership, or use a quota. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
 			`${TASK_NAME_CONTRACT.promptGuidance} 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.`,
 			`For each delegate_flow unit, ${MODEL_CLASS_GUIDANCE}`,
 			"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.",

package/extensions/role-tools.ts

@@ -1,5 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CHILD_EXCLUDED_TOOL_NAMES, EXECUTION_BUDGET_ENV, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
+import {
+	CHILD_EXCLUDED_TOOL_NAMES,
+	EXECUTION_BUDGET_ENV,
+	ROLE_TOOL_POLICY_FLAG,
+	type EphemeralSubagentExecutionBudget,
+} from "@henryqw/pi-subagent";
 
 const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
 const WARNING_RATIO = 0.8;
@@ -24,7 +29,7 @@ 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 {
+function executionBudget(value: string | undefined): EphemeralSubagentExecutionBudget | undefined {
 	if (value === undefined) return;
 	let parsed: unknown;
 	try {
@@ -36,13 +41,22 @@ function executionBudget(value: string | undefined): { maxTurns: number; maxMs:
 		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)
+	const maxTokensValid = budget.maxTokens === undefined
+		|| Number.isSafeInteger(budget.maxTokens) && (budget.maxTokens as number) >= 1;
+	if (Object.keys(budget).some((key) => !["maxTurns", "maxMs", "startedAt", "maxTokens"].includes(key))
+		|| !("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) {
+		|| !Number.isSafeInteger(budget.startedAt) || (budget.startedAt as number) < 0
+		|| !maxTokensValid) {
 		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 };
+	return {
+		maxTurns: budget.maxTurns as number,
+		maxMs: budget.maxMs,
+		startedAt: budget.startedAt as number,
+		...(budget.maxTokens === undefined ? {} : { maxTokens: budget.maxTokens as number }),
+	};
 }
 
 function expectsAnotherTurn(message: unknown): boolean {
@@ -53,6 +67,18 @@ function expectsAnotherTurn(message: unknown): boolean {
 			&& (part as Record<string, unknown>).type === "toolCall");
 }
 
+function messageTokens(message: unknown): number | undefined {
+	if (!message || typeof message !== "object" || Array.isArray(message)) return;
+	const usage = (message as Record<string, unknown>).usage;
+	if (!usage || typeof usage !== "object" || Array.isArray(usage)) return;
+	const totalTokens = (usage as Record<string, unknown>).totalTokens;
+	return typeof totalTokens === "number" && Number.isFinite(totalTokens) && totalTokens >= 0 ? totalTokens : undefined;
+}
+
+function joinBudgetParts(parts: string[]): string {
+	return `${parts.slice(0, -1).join(", ")}${parts.length > 2 ? "," : ""} and ${parts.at(-1)}`;
+}
+
 export default function roleTools(pi: ExtensionAPI): void {
 	pi.registerFlag(ROLE_TOOL_POLICY_FLAG, {
 		description: "Internal Pi Subagent Role tool policy",
@@ -82,30 +108,48 @@ export default function roleTools(pi: ExtensionAPI): void {
 
 	if (!budget) return;
 	const warningTurn = Math.ceil(budget.maxTurns * WARNING_RATIO);
+	const warningTokens = budget.maxTokens === undefined ? undefined : Math.ceil(budget.maxTokens * WARNING_RATIO);
 	let completedTurns = 0;
+	let completedTokens = 0;
+	let currentTokens = 0;
 	let turnWarningSent = false;
+	let tokenWarningSent = false;
 	let runtimeWarningSent = false;
+	pi.on("message_update", (event) => {
+		currentTokens = messageTokens(event.message) ?? currentTokens;
+	});
 	pi.on("turn_end", (event) => {
 		completedTurns += 1;
-		if (!expectsAnotherTurn(event.message) || handoffSent) return;
-		if (completedTurns === budget.maxTurns - 1) {
+		completedTokens += messageTokens(event.message) ?? currentTokens;
+		currentTokens = 0;
+		const continuing = expectsAnotherTurn(event.message);
+		const tokenBudgetCrossed = budget.maxTokens !== undefined && completedTokens >= budget.maxTokens;
+		if (!handoffSent && (continuing && completedTurns === budget.maxTurns - 1 || tokenBudgetCrossed)) {
 			pi.setActiveTools([]);
 			pi.sendMessage(FINAL_HANDOFF_MESSAGE, { deliverAs: "steer", triggerTurn: false });
 			handoffSent = true;
 			return;
 		}
+		if (!continuing || handoffSent) return;
 		const elapsedMs = Math.max(0, Date.now() - budget.startedAt);
 		const turnWarningDue = !turnWarningSent && completedTurns >= warningTurn;
+		const tokenWarningDue = warningTokens !== undefined && !tokenWarningSent && completedTokens >= warningTokens;
 		const runtimeWarningDue = !runtimeWarningSent && elapsedMs >= budget.maxMs * WARNING_RATIO;
-		if (!turnWarningDue && !runtimeWarningDue) return;
+		if (!turnWarningDue && !tokenWarningDue && !runtimeWarningDue) return;
 		if (turnWarningDue) turnWarningSent = true;
+		if (tokenWarningDue) tokenWarningSent = 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;
+		const parts = [
+			`${remainingTurns} of ${budget.maxTurns} turns`,
+			...(budget.maxTokens === undefined ? [] : [`${Math.max(0, budget.maxTokens - completedTokens)} of ${budget.maxTokens} tokens`]),
+			`approximately ${remainingMinutes} of ${maxMinutes} minutes`,
+		];
 		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.`,
+			content: `**Execution budget warning:** ${joinBudgetParts(parts)} 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

@@ -301,6 +301,7 @@ export default function subagentExtension(
 	const executor = createEphemeralSubagentExecutor({
 		maxConcurrency: maxActiveSubagents,
 		maxTurns: loadedConfig.config.maxTurns ?? DEFAULT_MAX_TURNS,
+		maxTokens: loadedConfig.config.maxTokens,
 		timeout: timeoutPolicy,
 	});
 	// Background children outlive the launching tool call, so they get their own
@@ -595,10 +596,10 @@ 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+name+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.",
-			`${TASK_NAME_CONTRACT.promptGuidance} 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.`,
+			"Call delegate_task with exactly one mode: role+name+task in single mode for one atomic task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; prefer parallel mode whenever at least two independent outcomes exist and each is independently deliverable and independently verifiable; do not combine independent outcomes merely to reduce child count. Sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
+			`${TASK_NAME_CONTRACT.promptGuidance} 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 naturally multi-part delegate_task work, you may look for roughly 3–5 useful entries, but do not manufacture entries or enforce a quota.`,
 			`For each delegate_task entry, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
-			"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.",
+			"Parallel mutating delegate_task entries must own non-overlapping files and changes. Read-only delegate_task entries may inspect overlapping sources when their questions and deliverables differ. Keep integration and cross-cutting decisions in Main.",
 			"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.",
 		],
 		parameters: WorkflowSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "15.1.0",
+  "version": "15.1.2",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

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

@@ -11,7 +11,9 @@ You are Main, the planner/orchestrator: slice work and choose `delegate_flow` or
 
 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: 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.
+Run a concise decomposition pass. Identify independently deliverable concrete outcomes. Maximize safe parallelism at those boundaries: give each outcome focused validation and clear ownership, and parallelize commuting work. Prefer parallel delegation when at least two independent outcomes exist. For naturally multi-part work, roughly 3–5 useful units is a guide, not a quota. Never manufacture units.
+
+Before selecting a Flow unit, require that one Implementer launch can plausibly finish before the configured maximum runtime. Cohesion alone is not enough when work has multiple preservable, separately verifiable milestones. Use `delegate_flow` for independent units expected to commute. Keep work together or sequence it when splitting would divide an invariant, overlap mutable ownership, or create coordination. Combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Units inside one Flow remain independent and commuting. Dependent work remains outside Flow. Split oversized dependent work into serial one-unit Flows after each milestone integrates; otherwise 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. Each task packet must name the neighboring behavior that must stay unchanged. Include the exact test name or error when known CI evidence exists. Never claim a validation command matches unknown CI.
 
@@ -29,13 +31,13 @@ A successful Flow owns integration and cleanup. A blocked outcome is repairable
 delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit.", modelClass: "balanced" })
 ```
 
-Make the guidance specific to the reported implementation, validation, or review failure. Omit `modelClass` to retain an explicit blocked-unit class or otherwise use each frozen Role's default; supply it only to replace both defaults for that one repair. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution.
+Make the guidance specific to the reported implementation, validation, or review failure. Omit `modelClass` to retain an explicit blocked-unit class or otherwise use each frozen Role's default; supply it only to replace both defaults for that one repair. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect each exact retained path reported by the runtime directly, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. Do not run `git worktree list` merely to rediscover a retained path.
 
 A cleanup warning does not undo successful integration. Report a cleanup warning from a successful Flow as-is. Do not investigate it unless the user asks or cleanup is part of acceptance.
 
 ## Ordinary delegation
 
-Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Choose `modelClass` according to the delegation tool's guidance. A direct `model` replaces only the selected route's model. The route keeps its thinking level. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.
+Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Choose `modelClass` according to the delegation tool's guidance. A direct `model` replaces only the selected route's model. The route keeps its thinking level. Keep integration and cross-cutting decisions in Main.
 
 ### Optional evidence loop for implementation