@wichayutdew/pi-workflows 3.5.0 → 3.7.0

package/dist/index.js

@@ -695,6 +695,7 @@ function parseWorkflowStep(value, stepId, path, errors) {
     "title",
     "prompt",
     "agent",
+    "maxToolCalls",
     "permissions",
     "requires",
     "transitions",
@@ -707,6 +708,10 @@ function parseWorkflowStep(value, stepId, path, errors) {
     pattern: AGENT_PROFILE_NAME_PATTERN
   });
   const agent = agentName ? { name: agentName } : undefined;
+  const maxToolCalls = value.maxToolCalls === undefined ? undefined : readInteger(value.maxToolCalls, 1, `${path}.maxToolCalls`, errors, {
+    min: 1,
+    max: 1e5
+  });
   const permissions = parsePermissions(value.permissions, `${path}.permissions`, errors);
   const requires = parseRequirements(value.requires, permissions, `${path}.requires`, errors);
   const transitions = parseTransitions(value.transitions, `${path}.transitions`, errors);
@@ -726,6 +731,13 @@ function parseWorkflowStep(value, stepId, path, errors) {
       errors.push(`${path}.transitions: artifact-contract retry requires a "retry" transition`);
     }
   }
+  if (agent && maxToolCalls !== undefined) {
+    if (!Object.hasOwn(transitions, "handoff")) {
+      errors.push(`${path}.transitions: maxToolCalls requires a "handoff" transition`);
+    } else if (transitions.handoff !== stepId) {
+      errors.push(`${path}.transitions: handoff transition must target "${stepId}"`);
+    }
+  }
   if (workspace) {
     workspace.bindOn.forEach((outcome) => {
       if (!Object.hasOwn(transitions, outcome)) {
@@ -739,6 +751,7 @@ function parseWorkflowStep(value, stepId, path, errors) {
     title,
     prompt,
     ...agent ? { agent } : {},
+    ...maxToolCalls === undefined ? {} : { maxToolCalls },
     permissions,
     requires,
     transitions,
@@ -2609,6 +2622,22 @@ var RESULT_KEYS = new Set([
 var isObject = (value) => {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 };
+function validateNonSuccessSummary(outcome, summary) {
+  if (outcome === "blocked") {
+    const isActionable = /^# Blocked:\s+.+/m.test(summary) && /^\s*\*\*Action:\*\*\s+.+/m.test(summary) && /^\s*\*\*Next:\*\*\s+.+/m.test(summary);
+    if (!isActionable) {
+      throw new Error("blocked summary must identify the missing user prerequisite and next action");
+    }
+  }
+  if (outcome === "retry") {
+    const describesTransientFailure = /\btransient\b/i.test(summary);
+    const hasSafeRetryCondition = /\b(safe (retry|to retry)|retry (when|after|once))\b/i.test(summary);
+    const requestsUserInput = /\b(provide|confirm|choose|approve|decide)\b/i.test(summary);
+    if (!/^# Retry:\s+.+/m.test(summary) || !describesTransientFailure || !hasSafeRetryCondition || requestsUserInput) {
+      throw new Error("retry summary must identify a transient failure and safe retry condition");
+    }
+  }
+}
 function parseResultWorkspace(value, outcome, policy) {
   const requiresWorkspace = policy.workspace?.bindOn.includes(outcome) === true;
   if (!requiresWorkspace) {
@@ -2663,6 +2692,7 @@ function parseWorkflowStepResult(value, policy) {
   if (summary.length > policy.summaryMaxChars) {
     throw new Error(`workflow step summary exceeds ${policy.summaryMaxChars} characters`);
   }
+  validateNonSuccessSummary(value.outcome, summary);
   if (value.artifact !== undefined && typeof value.artifact !== "string") {
     throw new Error("workflow step artifact must be a string");
   }
@@ -6053,6 +6083,7 @@ var resolveStep = (workflow, run) => {
   return step;
 };
 var RESUME_INPUT_PLACEHOLDER = /\{\{\s*resume\.input\s*\}\}/;
+var WORKFLOW_INPUT_PLACEHOLDER = /\{\{\s*workflow\.input\s*\}\}/;
 var renderStepPrompt = ({
   workflow,
   run,
@@ -6094,6 +6125,7 @@ function buildStepTask(options) {
   const isDelegated = execution === "delegated";
   const promptTemplate = workflow.prompts[run.currentStepId] ?? "";
   const prompt = renderStepPrompt({ workflow, run, step, execution });
+  const showWorkflowInput = WORKFLOW_INPUT_PLACEHOLDER.test(promptTemplate);
   const handoff = currentStepHandoff(run);
   const contract = createStepContract({ workflow, run, step });
   const completionTool = isDelegated ? "structured_output" : "workflow_complete_step";
@@ -6113,6 +6145,7 @@ function buildStepTask(options) {
     ...step.agent ? ["## Role prompt", "", rolePrompt(step.agent.name), ""] : [],
     prompt,
     "",
+    ...showWorkflowInput ? ["## Original workflow request", "", run.input || "(none supplied)", ""] : [],
     ...isDelegated ? buildDelegatedHandoffSection(handoff) : [],
     ...buildRestartWorkspaceSection(run.restartWorkspaceCwd),
     ...buildResumeInputSection(run, RESUME_INPUT_PLACEHOLDER.test(promptTemplate)),
@@ -6393,6 +6426,10 @@ var POLICY_KEYS = new Set([
   "outcomes",
   "pauseOutcomes",
   "summaryMaxChars",
+  "maxToolCalls",
+  "handoffReserve",
+  "totalToolCalls",
+  "handoffOutcome",
   "gateSubmitOutcome",
   "workspace"
 ]);
@@ -6411,6 +6448,29 @@ var rejectUnknownProperties = (value) => {
     throw new Error(`child policy has unknown property "${unknownKey}"`);
   }
 };
+var parseToolBudget = (value) => {
+  const fields2 = [
+    value.maxToolCalls,
+    value.handoffReserve,
+    value.totalToolCalls
+  ];
+  if (fields2.every((field) => field === undefined))
+    return {};
+  if (fields2.some((field) => field === undefined)) {
+    throw new Error("child policy tool budget fields must be provided together");
+  }
+  const [maxToolCalls, handoffReserve, totalToolCalls] = fields2;
+  if (typeof maxToolCalls !== "number" || !Number.isInteger(maxToolCalls) || maxToolCalls < 1 || maxToolCalls > 1e5) {
+    throw new Error("child policy maxToolCalls is invalid");
+  }
+  if (handoffReserve !== 2) {
+    throw new Error("child policy handoffReserve is invalid");
+  }
+  if (typeof totalToolCalls !== "number" || !Number.isInteger(totalToolCalls) || totalToolCalls !== maxToolCalls + handoffReserve) {
+    throw new Error("child policy totalToolCalls is invalid");
+  }
+  return { maxToolCalls, handoffReserve, totalToolCalls };
+};
 var parseIdentityAndPaths = (value, environment) => {
   const requestId = requiredString(value, "requestId");
   const agent = requiredString(value, "agent");
@@ -6465,9 +6525,28 @@ var parseChildPolicy = (value, environment = DEFAULT_CHILD_POLICY_ENVIRONMENT) =
   if (!isRecord11(value))
     throw new Error("child policy must be an object");
   rejectUnknownProperties(value);
+  const sections = parseChildPolicySections(value);
+  const toolBudget = parseToolBudget(value);
+  const handoffOutcome = value.handoffOutcome;
+  if (handoffOutcome !== undefined) {
+    if (typeof handoffOutcome !== "string" || handoffOutcome !== "handoff") {
+      throw new Error("child policy handoffOutcome is invalid");
+    }
+    if (toolBudget.maxToolCalls === undefined) {
+      throw new Error("child policy handoffOutcome requires a tool budget");
+    }
+    if (!sections.outcomes.includes(handoffOutcome)) {
+      throw new Error("child policy handoffOutcome must be an allowed outcome");
+    }
+  }
+  if (toolBudget.maxToolCalls !== undefined && handoffOutcome === undefined) {
+    throw new Error("child policy tool budget requires handoffOutcome");
+  }
   return {
     ...parseIdentityAndPaths(value, environment),
-    ...parseChildPolicySections(value)
+    ...sections,
+    ...toolBudget,
+    ...handoffOutcome ? { handoffOutcome } : {}
   };
 };
 
@@ -6564,6 +6643,7 @@ var parseDelegatedStepResult = (value, policy) => {
   }
 };
 // src/harness/delegation-plan.ts
+var HANDOFF_RESERVE = 2;
 function createDelegationPlan(input, dependencies) {
   const { workflow, run, step, latestContext } = input;
   const agent = step.agent?.name;
@@ -6658,6 +6738,12 @@ function createDelegationPlan(input, dependencies) {
   const workspace = dependencies.createDelegationWorkspace();
   const outcomes = allowedOutcomes(workflow, run);
   const outcomeSet = new Set(outcomes);
+  const toolBudget = step.maxToolCalls === undefined ? {} : {
+    maxToolCalls: step.maxToolCalls,
+    handoffReserve: HANDOFF_RESERVE,
+    totalToolCalls: step.maxToolCalls + HANDOFF_RESERVE,
+    handoffOutcome: "handoff"
+  };
   const policyDigest = digest({
     version: 1,
     requestId,
@@ -6670,6 +6756,7 @@ function createDelegationPlan(input, dependencies) {
     resultPath: workspace.resultPath,
     permissions: step.permissions,
     outcomes,
+    ...toolBudget,
     ...step.workspace ? { workspace: step.workspace } : {}
   });
   const policy = {
@@ -6689,6 +6776,8 @@ function createDelegationPlan(input, dependencies) {
     outcomes,
     pauseOutcomes: Object.entries(step.transitions).filter(([outcome, target]) => target === "$pause" && outcomeSet.has(outcome)).map(([outcome]) => outcome),
     summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...toolBudget,
+    ...step.maxToolCalls === undefined ? {} : { handoffOutcome: "handoff" },
     ...step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {},
     ...step.workspace ? { workspace: structuredClone(step.workspace) } : {}
   };
@@ -7951,6 +8040,45 @@ var COMPLETION_REPAIR_PROMPT = [
   "Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields."
 ].join(`
 `);
+var toolBudgetWarningPrompt = ({
+  productiveCalls,
+  productiveRemaining,
+  handoffReserve
+}) => [
+  "Tool-call budget warning.",
+  `Productive calls used: ${productiveCalls}.`,
+  `Productive calls remaining: ${productiveRemaining}.`,
+  `Handoff reserve: ${handoffReserve} calls.`,
+  "Begin preparing a compact handoff now."
+].join(`
+`);
+var TOOL_BUDGET_HANDOFF_PROMPT = [
+  "The productive tool-call budget is exhausted.",
+  "Work tools are locked; do not execute further work.",
+  "Call `structured_output` exactly once, alone, with a detailed configured result if you can complete now.",
+  "If you settle without a result, the extension persists an `handoff` result for a fresh child."
+].join(`
+`);
+var toolBudgetHandoffResult = (policy, productiveCalls) => {
+  if (policy.handoffOutcome !== "handoff") {
+    throw new Error("tool-budget handoff requires a configured handoff outcome");
+  }
+  return {
+    version: 1,
+    policyDigest: policy.policyDigest,
+    outcome: policy.handoffOutcome,
+    summary: [
+      "# Handoff: Productive tool-call budget exhausted.",
+      "",
+      `- Completed work: Productive calls completed: ${productiveCalls}.`,
+      "- Current state: Work tools are locked; no further productive tool calls ran.",
+      "- Remaining work: A fresh child must inspect the previous handoff and continue this same step.",
+      "- Blocker: The configured productive tool-call budget is exhausted.",
+      "**Next:** Start a fresh delegated attempt for this step using the persisted handoff."
+    ].join(`
+`)
+  };
+};
 var needsCompletionRepair = ({
   policy,
   dependencies
@@ -8035,11 +8163,25 @@ var childSystemPrompt = (policy) => {
     "",
     "The parent workflow harness owns orchestration and state transitions.",
     "Perform only this delegated step. Its child-side tool policy is enforced.",
+    "Do not launch subagents while executing this declarative workflow step.",
+    "Use `blocked` only when progress requires user-provided information, a decision, authority, credentials, or approval.",
+    "Use `retry` only for a transient failure that can be retried without new user input.",
+    "Do not open a skill unless this step YAML lists that skill.",
     "When finished, call `structured_output` exactly once and as the only tool call in that message.",
     "Pass the workflow result as its `value`: outcome, summary, optional artifact, and workspace only when required below.",
     `Valid outcomes: ${policy.outcomes.join(", ")}`,
     `Pause outcomes: ${policy.pauseOutcomes.join(", ") || "(none)"}`,
     `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...policy.maxToolCalls === undefined ? [] : [
+      "",
+      "## Tool-call budget",
+      `Productive tool-call budget: ${policy.maxToolCalls} calls.`,
+      `Handoff reserve: ${policy.handoffReserve} calls.`,
+      `Total tool-call budget: ${policy.totalToolCalls} calls.`,
+      "At 2 productive calls remaining, prepare a concise handoff with completed work, current state, remaining work, and any blocker.",
+      "Work tools are locked when the productive budget is exhausted.",
+      "If the child settles without a result after exhaustion, the extension writes the configured `handoff` structured result."
+    ],
     ...policy.gateSubmitOutcome ? [
       `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`
     ] : [],
@@ -8060,7 +8202,9 @@ var INITIAL_STATE = {
   policyError: undefined,
   invalidCompletionCalls: new Set,
   effectiveTools: new Set,
-  repairRequested: false
+  productiveToolCallIds: new Set,
+  repairRequested: false,
+  runtimeMode: "working"
 };
 var errorMessage2 = (error) => error instanceof Error ? error.message : String(error);
 var invalidPolicyInput = (pi, policyError, images) => {
@@ -8127,7 +8271,9 @@ var registerSubagentChildRuntime = (pi, options = {}) => {
         activePolicy: extracted.policy,
         policyError: undefined,
         effectiveTools,
-        repairRequested: false
+        productiveToolCallIds: new Set,
+        repairRequested: false,
+        runtimeMode: "working"
       };
     } catch (error) {
       const policyError = errorMessage2(error);
@@ -8160,11 +8306,67 @@ ${childSystemPrompt(state.activePolicy)}`
   pi.on("turn_start", () => {
     state = { ...state, invalidCompletionCalls: new Set };
   });
+  pi.on("tool_execution_end", (event) => {
+    const policy = state.activePolicy;
+    const handoffReserve = policy?.handoffReserve;
+    if (!policy || policy.maxToolCalls === undefined || handoffReserve === undefined || event.toolName === CHILD_COMPLETION_TOOL || state.runtimeMode === "handoff" || state.productiveToolCallIds.has(event.toolCallId)) {
+      return;
+    }
+    const productiveToolCallIds = new Set(state.productiveToolCallIds);
+    productiveToolCallIds.add(event.toolCallId);
+    const productiveCalls = productiveToolCallIds.size;
+    if (productiveCalls >= policy.maxToolCalls) {
+      state = {
+        ...state,
+        effectiveTools: new Set,
+        productiveToolCallIds,
+        runtimeMode: "handoff"
+      };
+      try {
+        writeChildResult({
+          policy,
+          result: toolBudgetHandoffResult(policy, productiveCalls),
+          dependencies
+        });
+        pi.setActiveTools([]);
+      } catch {
+        state = {
+          ...state,
+          effectiveTools: new Set([CHILD_COMPLETION_TOOL])
+        };
+        pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+        pi.sendUserMessage(TOOL_BUDGET_HANDOFF_PROMPT, {
+          deliverAs: "followUp"
+        });
+      }
+      return;
+    }
+    state = { ...state, productiveToolCallIds };
+    const productiveRemaining = policy.maxToolCalls - productiveCalls;
+    if (productiveRemaining <= handoffReserve) {
+      pi.sendUserMessage(toolBudgetWarningPrompt({
+        productiveCalls,
+        productiveRemaining,
+        handoffReserve
+      }), { deliverAs: "followUp" });
+    }
+  });
   pi.on("agent_settled", () => {
     const policy = state.activePolicy;
-    if (!policy || state.repairRequested || !needsCompletionRepair({ policy, dependencies })) {
+    if (!policy || state.repairRequested)
       return;
+    if (state.runtimeMode === "handoff" && needsCompletionRepair({ policy, dependencies })) {
+      try {
+        writeChildResult({
+          policy,
+          result: toolBudgetHandoffResult(policy, state.productiveToolCallIds.size),
+          dependencies
+        });
+        return;
+      } catch {}
     }
+    if (!needsCompletionRepair({ policy, dependencies }))
+      return;
     state = {
       ...state,
       repairRequested: true,
@@ -8223,6 +8425,12 @@ ${childSystemPrompt(state.activePolicy)}`
         };
       }
     }
+    if (state.runtimeMode === "handoff") {
+      return {
+        block: true,
+        reason: "Productive tool-call budget is exhausted; the extension-owned handoff is already persisted"
+      };
+    }
     if (CHILD_COORDINATION_TOOLS.has(event.toolName)) {
       return {
         block: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/schemas/workflow.schema.json

@@ -669,6 +669,11 @@
         "agent": {
           "$ref": "#/$defs/subagentRuntimeName"
         },
+        "maxToolCalls": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000
+        },
         "permissions": {
           "$ref": "#/$defs/permissions"
         },

package/src/config/types.ts

@@ -87,6 +87,7 @@ export type WorkflowStep = {
   readonly prompt: PromptSpec;
   /** Optional workflow-owned role prompt for this main-agent step. */
   readonly agent?: StepAgent;
+  readonly maxToolCalls?: number;
   readonly permissions: StepPermissions;
   readonly requires: StepRequirements;
   readonly transitions: Readonly<Record<string, StepTarget>>;

package/src/config/validation/step.ts

@@ -358,6 +358,7 @@ export function parseWorkflowStep(
       'title',
       'prompt',
       'agent',
+      'maxToolCalls',
       'permissions',
       'requires',
       'transitions',
@@ -382,6 +383,13 @@ export function parseWorkflowStep(
   const agent: StepAgent | undefined = agentName
     ? { name: agentName }
     : undefined;
+  const maxToolCalls =
+    value.maxToolCalls === undefined
+      ? undefined
+      : readInteger(value.maxToolCalls, 1, `${path}.maxToolCalls`, errors, {
+          min: 1,
+          max: 100_000,
+        });
   const permissions = parsePermissions(
     value.permissions,
     `${path}.permissions`,
@@ -430,6 +438,17 @@ export function parseWorkflowStep(
       );
     }
   }
+  if (agent && maxToolCalls !== undefined) {
+    if (!Object.hasOwn(transitions, 'handoff')) {
+      errors.push(
+        `${path}.transitions: maxToolCalls requires a "handoff" transition`,
+      );
+    } else if (transitions.handoff !== stepId) {
+      errors.push(
+        `${path}.transitions: handoff transition must target "${stepId}"`,
+      );
+    }
+  }
   if (workspace) {
     workspace.bindOn.forEach((outcome) => {
       if (!Object.hasOwn(transitions, outcome)) {
@@ -445,6 +464,7 @@ export function parseWorkflowStep(
     title,
     prompt,
     ...(agent ? { agent } : {}),
+    ...(maxToolCalls === undefined ? {} : { maxToolCalls }),
     permissions,
     requires,
     transitions,

package/src/harness/delegation-plan.ts

@@ -13,6 +13,8 @@ import { buildDelegatedStepTask } from '../prompt.ts';
 import type { WorkflowHarnessDependencies } from './dependencies.ts';
 import type { ActiveDelegation } from './types.ts';
 
+const HANDOFF_RESERVE = 2;
+
 type DelegationPlanInput = {
   workflow: LoadedWorkflow;
   run: WorkflowRun;
@@ -156,6 +158,15 @@ export function createDelegationPlan(
   const workspace = dependencies.createDelegationWorkspace();
   const outcomes = allowedOutcomes(workflow, run);
   const outcomeSet = new Set(outcomes);
+  const toolBudget =
+    step.maxToolCalls === undefined
+      ? {}
+      : {
+          maxToolCalls: step.maxToolCalls,
+          handoffReserve: HANDOFF_RESERVE,
+          totalToolCalls: step.maxToolCalls + HANDOFF_RESERVE,
+          handoffOutcome: 'handoff',
+        };
   const policyDigest = digest({
     version: 1,
     requestId,
@@ -168,6 +179,7 @@ export function createDelegationPlan(
     resultPath: workspace.resultPath,
     permissions: step.permissions,
     outcomes,
+    ...toolBudget,
     ...(step.workspace ? { workspace: step.workspace } : {}),
   });
   const policy: ChildStepPolicy = {
@@ -191,6 +203,8 @@ export function createDelegationPlan(
       )
       .map(([outcome]) => outcome),
     summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...toolBudget,
+    ...(step.maxToolCalls === undefined ? {} : { handoffOutcome: 'handoff' }),
     ...(step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}),
     ...(step.workspace ? { workspace: structuredClone(step.workspace) } : {}),
   };

package/src/integrations/subagents/child-policy-types.ts

@@ -22,6 +22,14 @@ export type ChildStepPolicy = {
   /** Outcomes that pause instead of advancing to another workflow step. */
   readonly pauseOutcomes: ReadonlyArray<string>;
   readonly summaryMaxChars: number;
+  /** Productive calls available before the mandatory handoff reserve. */
+  readonly maxToolCalls?: number;
+  /** Calls reserved for the child to hand off after productive work. */
+  readonly handoffReserve?: number;
+  /** Productive calls plus the mandatory handoff reserve. */
+  readonly totalToolCalls?: number;
+  /** Extension-owned outcome persisted when an exhausted child settles without a result. */
+  readonly handoffOutcome?: string;
   readonly gateSubmitOutcome?: string;
   readonly workspace?: StepWorkspaceBinding;
 };

package/src/integrations/subagents/child-policy-validation.ts

@@ -28,6 +28,10 @@ const POLICY_KEYS: ReadonlySet<string> = new Set([
   'outcomes',
   'pauseOutcomes',
   'summaryMaxChars',
+  'maxToolCalls',
+  'handoffReserve',
+  'totalToolCalls',
+  'handoffOutcome',
   'gateSubmitOutcome',
   'workspace',
 ]);
@@ -75,6 +79,48 @@ const rejectUnknownProperties = (
   }
 };
 
+type ToolBudget = Pick<
+  ChildStepPolicy,
+  'maxToolCalls' | 'handoffReserve' | 'totalToolCalls'
+>;
+
+const parseToolBudget = (
+  value: Readonly<Record<string, unknown>>,
+): ToolBudget => {
+  const fields = [
+    value.maxToolCalls,
+    value.handoffReserve,
+    value.totalToolCalls,
+  ];
+  if (fields.every((field) => field === undefined)) return {};
+  if (fields.some((field) => field === undefined)) {
+    throw new Error(
+      'child policy tool budget fields must be provided together',
+    );
+  }
+
+  const [maxToolCalls, handoffReserve, totalToolCalls] = fields;
+  if (
+    typeof maxToolCalls !== 'number' ||
+    !Number.isInteger(maxToolCalls) ||
+    maxToolCalls < 1 ||
+    maxToolCalls > 100_000
+  ) {
+    throw new Error('child policy maxToolCalls is invalid');
+  }
+  if (handoffReserve !== 2) {
+    throw new Error('child policy handoffReserve is invalid');
+  }
+  if (
+    typeof totalToolCalls !== 'number' ||
+    !Number.isInteger(totalToolCalls) ||
+    totalToolCalls !== maxToolCalls + handoffReserve
+  ) {
+    throw new Error('child policy totalToolCalls is invalid');
+  }
+  return { maxToolCalls, handoffReserve, totalToolCalls };
+};
+
 type IdentityAndPaths = Pick<
   ChildStepPolicy,
   | 'version'
@@ -161,8 +207,27 @@ export const parseChildPolicy = (
   if (!isRecord(value)) throw new Error('child policy must be an object');
 
   rejectUnknownProperties(value);
+  const sections = parseChildPolicySections(value);
+  const toolBudget = parseToolBudget(value);
+  const handoffOutcome = value.handoffOutcome;
+  if (handoffOutcome !== undefined) {
+    if (typeof handoffOutcome !== 'string' || handoffOutcome !== 'handoff') {
+      throw new Error('child policy handoffOutcome is invalid');
+    }
+    if (toolBudget.maxToolCalls === undefined) {
+      throw new Error('child policy handoffOutcome requires a tool budget');
+    }
+    if (!sections.outcomes.includes(handoffOutcome)) {
+      throw new Error('child policy handoffOutcome must be an allowed outcome');
+    }
+  }
+  if (toolBudget.maxToolCalls !== undefined && handoffOutcome === undefined) {
+    throw new Error('child policy tool budget requires handoffOutcome');
+  }
   return {
     ...parseIdentityAndPaths(value, environment),
-    ...parseChildPolicySections(value),
+    ...sections,
+    ...toolBudget,
+    ...(handoffOutcome ? { handoffOutcome } : {}),
   };
 };

package/src/integrations/subagents/child-runtime-policy.ts

@@ -29,11 +29,27 @@ export const childSystemPrompt = (policy: ChildStepPolicy): string => {
     '',
     'The parent workflow harness owns orchestration and state transitions.',
     'Perform only this delegated step. Its child-side tool policy is enforced.',
+    'Do not launch subagents while executing this declarative workflow step.',
+    'Use `blocked` only when progress requires user-provided information, a decision, authority, credentials, or approval.',
+    'Use `retry` only for a transient failure that can be retried without new user input.',
+    'Do not open a skill unless this step YAML lists that skill.',
     'When finished, call `structured_output` exactly once and as the only tool call in that message.',
     'Pass the workflow result as its `value`: outcome, summary, optional artifact, and workspace only when required below.',
     `Valid outcomes: ${policy.outcomes.join(', ')}`,
     `Pause outcomes: ${policy.pauseOutcomes.join(', ') || '(none)'}`,
     `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...(policy.maxToolCalls === undefined
+      ? []
+      : [
+          '',
+          '## Tool-call budget',
+          `Productive tool-call budget: ${policy.maxToolCalls} calls.`,
+          `Handoff reserve: ${policy.handoffReserve} calls.`,
+          `Total tool-call budget: ${policy.totalToolCalls} calls.`,
+          'At 2 productive calls remaining, prepare a concise handoff with completed work, current state, remaining work, and any blocker.',
+          'Work tools are locked when the productive budget is exhausted.',
+          'If the child settles without a result after exhaustion, the extension writes the configured `handoff` structured result.',
+        ]),
     ...(policy.gateSubmitOutcome
       ? [
           `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`,

package/src/integrations/subagents/child-runtime-repair.ts

@@ -1,3 +1,4 @@
+import type { WorkflowStepResult } from '../../runtime/step-result.ts';
 import type { ChildStepPolicy } from './child-policy-types.ts';
 import type { SubagentChildRuntimeDependencies } from './child-runtime-types.ts';
 
@@ -7,6 +8,56 @@ export const COMPLETION_REPAIR_PROMPT = [
   'Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields.',
 ].join('\n');
 
+export const toolBudgetWarningPrompt = ({
+  productiveCalls,
+  productiveRemaining,
+  handoffReserve,
+}: {
+  readonly productiveCalls: number;
+  readonly productiveRemaining: number;
+  readonly handoffReserve: number;
+}): string =>
+  [
+    'Tool-call budget warning.',
+    `Productive calls used: ${productiveCalls}.`,
+    `Productive calls remaining: ${productiveRemaining}.`,
+    `Handoff reserve: ${handoffReserve} calls.`,
+    'Begin preparing a compact handoff now.',
+  ].join('\n');
+
+export const TOOL_BUDGET_HANDOFF_PROMPT = [
+  'The productive tool-call budget is exhausted.',
+  'Work tools are locked; do not execute further work.',
+  'Call `structured_output` exactly once, alone, with a detailed configured result if you can complete now.',
+  'If you settle without a result, the extension persists an `handoff` result for a fresh child.',
+].join('\n');
+
+/** Builds the only extension-owned result allowed after productive budget exhaustion. */
+export const toolBudgetHandoffResult = (
+  policy: ChildStepPolicy,
+  productiveCalls: number,
+): WorkflowStepResult => {
+  if (policy.handoffOutcome !== 'handoff') {
+    throw new Error(
+      'tool-budget handoff requires a configured handoff outcome',
+    );
+  }
+  return {
+    version: 1,
+    policyDigest: policy.policyDigest,
+    outcome: policy.handoffOutcome,
+    summary: [
+      '# Handoff: Productive tool-call budget exhausted.',
+      '',
+      `- Completed work: Productive calls completed: ${productiveCalls}.`,
+      '- Current state: Work tools are locked; no further productive tool calls ran.',
+      '- Remaining work: A fresh child must inspect the previous handoff and continue this same step.',
+      '- Blocker: The configured productive tool-call budget is exhausted.',
+      '**Next:** Start a fresh delegated attempt for this step using the persisted handoff.',
+    ].join('\n'),
+  };
+};
+
 /** Returns whether a same-child completion repair may be requested safely. */
 export const needsCompletionRepair = ({
   policy,

package/src/integrations/subagents/child-runtime.ts

@@ -16,6 +16,9 @@ import { DEFAULT_CHILD_RUNTIME_DEPENDENCIES } from './child-runtime-dependencies
 import {
   COMPLETION_REPAIR_PROMPT,
   needsCompletionRepair,
+  TOOL_BUDGET_HANDOFF_PROMPT,
+  toolBudgetHandoffResult,
+  toolBudgetWarningPrompt,
 } from './child-runtime-repair.ts';
 import {
   verifyChildCapability,
@@ -43,7 +46,9 @@ type ChildRuntimeState = {
   readonly policyError: string | undefined;
   readonly invalidCompletionCalls: ReadonlySet<string>;
   readonly effectiveTools: ReadonlySet<string>;
+  readonly productiveToolCallIds: ReadonlySet<string>;
   readonly repairRequested: boolean;
+  readonly runtimeMode: 'working' | 'handoff';
 };
 
 const INITIAL_STATE: ChildRuntimeState = {
@@ -51,7 +56,9 @@ const INITIAL_STATE: ChildRuntimeState = {
   policyError: undefined,
   invalidCompletionCalls: new Set(),
   effectiveTools: new Set(),
+  productiveToolCallIds: new Set(),
   repairRequested: false,
+  runtimeMode: 'working',
 };
 
 const errorMessage = (error: unknown): string =>
@@ -148,7 +155,9 @@ export const registerSubagentChildRuntime = (
         activePolicy: extracted.policy,
         policyError: undefined,
         effectiveTools,
+        productiveToolCallIds: new Set(),
         repairRequested: false,
+        runtimeMode: 'working',
       };
     } catch (error) {
       const policyError = errorMessage(error);
@@ -182,15 +191,87 @@ export const registerSubagentChildRuntime = (
     state = { ...state, invalidCompletionCalls: new Set() };
   });
 
-  pi.on('agent_settled', () => {
+  pi.on('tool_execution_end', (event) => {
     const policy = state.activePolicy;
+    const handoffReserve = policy?.handoffReserve;
     if (
       !policy ||
-      state.repairRequested ||
-      !needsCompletionRepair({ policy, dependencies })
+      policy.maxToolCalls === undefined ||
+      handoffReserve === undefined ||
+      event.toolName === CHILD_COMPLETION_TOOL ||
+      state.runtimeMode === 'handoff' ||
+      state.productiveToolCallIds.has(event.toolCallId)
     ) {
       return;
     }
+
+    const productiveToolCallIds = new Set(state.productiveToolCallIds);
+    productiveToolCallIds.add(event.toolCallId);
+    const productiveCalls = productiveToolCallIds.size;
+    if (productiveCalls >= policy.maxToolCalls) {
+      state = {
+        ...state,
+        effectiveTools: new Set(),
+        productiveToolCallIds,
+        runtimeMode: 'handoff',
+      };
+      try {
+        writeChildResult({
+          policy,
+          result: toolBudgetHandoffResult(policy, productiveCalls),
+          dependencies,
+        });
+        pi.setActiveTools([]);
+      } catch {
+        state = {
+          ...state,
+          effectiveTools: new Set([CHILD_COMPLETION_TOOL]),
+        };
+        pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+        pi.sendUserMessage(TOOL_BUDGET_HANDOFF_PROMPT, {
+          deliverAs: 'followUp',
+        });
+      }
+      return;
+    }
+
+    state = { ...state, productiveToolCallIds };
+    const productiveRemaining = policy.maxToolCalls - productiveCalls;
+    if (productiveRemaining <= handoffReserve) {
+      pi.sendUserMessage(
+        toolBudgetWarningPrompt({
+          productiveCalls,
+          productiveRemaining,
+          handoffReserve,
+        }),
+        { deliverAs: 'followUp' },
+      );
+    }
+  });
+
+  pi.on('agent_settled', () => {
+    const policy = state.activePolicy;
+    if (!policy || state.repairRequested) return;
+    if (
+      state.runtimeMode === 'handoff' &&
+      needsCompletionRepair({ policy, dependencies })
+    ) {
+      try {
+        writeChildResult({
+          policy,
+          result: toolBudgetHandoffResult(
+            policy,
+            state.productiveToolCallIds.size,
+          ),
+          dependencies,
+        });
+        return;
+      } catch {
+        // Preserve the normal completion-repair path so the parent gets the
+        // correlated result failure if the protected write cannot be made.
+      }
+    }
+    if (!needsCompletionRepair({ policy, dependencies })) return;
     state = {
       ...state,
       repairRequested: true,
@@ -252,6 +333,13 @@ export const registerSubagentChildRuntime = (
         };
       }
     }
+    if (state.runtimeMode === 'handoff') {
+      return {
+        block: true,
+        reason:
+          'Productive tool-call budget is exhausted; the extension-owned handoff is already persisted',
+      };
+    }
     if (CHILD_COORDINATION_TOOLS.has(event.toolName)) {
       return {
         block: true,

package/src/prompt/step-task.ts

@@ -51,6 +51,7 @@ type RenderStepPromptOptions = {
 };
 
 const RESUME_INPUT_PLACEHOLDER = /\{\{\s*resume\.input\s*\}\}/;
+const WORKFLOW_INPUT_PLACEHOLDER = /\{\{\s*workflow\.input\s*\}\}/;
 
 const renderStepPrompt = ({
   workflow,
@@ -110,6 +111,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
   const isDelegated = execution === 'delegated';
   const promptTemplate = workflow.prompts[run.currentStepId] ?? '';
   const prompt = renderStepPrompt({ workflow, run, step, execution });
+  const showWorkflowInput = WORKFLOW_INPUT_PLACEHOLDER.test(promptTemplate);
   const handoff = currentStepHandoff(run);
   const contract = createStepContract({ workflow, run, step });
   const completionTool = isDelegated
@@ -135,6 +137,9 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
       : []),
     prompt,
     '',
+    ...(showWorkflowInput
+      ? ['## Original workflow request', '', run.input || '(none supplied)', '']
+      : []),
     ...(isDelegated ? buildDelegatedHandoffSection(handoff) : []),
     ...buildRestartWorkspaceSection(run.restartWorkspaceCwd),
     ...buildResumeInputSection(

package/src/runtime/step-result.ts

@@ -45,6 +45,37 @@ const isObject = (value: unknown): value is Record<string, unknown> => {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 };
 
+function validateNonSuccessSummary(outcome: string, summary: string): void {
+  if (outcome === 'blocked') {
+    const isActionable =
+      /^# Blocked:\s+.+/m.test(summary) &&
+      /^\s*\*\*Action:\*\*\s+.+/m.test(summary) &&
+      /^\s*\*\*Next:\*\*\s+.+/m.test(summary);
+    if (!isActionable) {
+      throw new Error(
+        'blocked summary must identify the missing user prerequisite and next action',
+      );
+    }
+  }
+  if (outcome === 'retry') {
+    const describesTransientFailure = /\btransient\b/i.test(summary);
+    const hasSafeRetryCondition =
+      /\b(safe (retry|to retry)|retry (when|after|once))\b/i.test(summary);
+    const requestsUserInput =
+      /\b(provide|confirm|choose|approve|decide)\b/i.test(summary);
+    if (
+      !/^# Retry:\s+.+/m.test(summary) ||
+      !describesTransientFailure ||
+      !hasSafeRetryCondition ||
+      requestsUserInput
+    ) {
+      throw new Error(
+        'retry summary must identify a transient failure and safe retry condition',
+      );
+    }
+  }
+}
+
 function parseResultWorkspace(
   value: unknown,
   outcome: string,
@@ -131,6 +162,7 @@ export function parseWorkflowStepResult(
       `workflow step summary exceeds ${policy.summaryMaxChars} characters`,
     );
   }
+  validateNonSuccessSummary(value.outcome, summary);
   if (value.artifact !== undefined && typeof value.artifact !== 'string') {
     throw new Error('workflow step artifact must be a string');
   }