@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/orchestration/owned-work-budget.ts

@@ -7,12 +7,12 @@ import type { HelperRequest, HelperRole } from "./role-policy.ts";
 import { validateHelperRequest } from "./role-policy.ts";
 
 export const OWNED_WORK_BUDGET_VERSION = "owned-work-budget-v1" as const;
-// `maxRepairPasses` is declared for the repair lane, which reserves no helper
-// role here, so this mechanism never reads it. It is named rather than removed
-// because the repair lane is bounded elsewhere; nothing in this file enforces it.
+// Keep the complete ceiling shape for persisted/operator projections, but clamp
+// every caller to one read-only helper and zero retries/writers below.
 export type OwnedWorkCeilings = Readonly<{ maxConcurrentHelpers: number; maxTotalHelpers: number; maxScoutPasses: number; maxPlannerPasses: number; maxReviewPasses: number; maxOracleCalls: number; maxRepairPasses: number; maxWriters: number }>;
-export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 2, maxTotalHelpers: 3, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 1, maxWriters: 1 });
-export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ ...DEFAULT_OWNED_WORK_CEILINGS, maxConcurrentHelpers: 1, maxTotalHelpers: 1 });
+export const ABSOLUTE_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 1, maxTotalHelpers: 1, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 0, maxWriters: 0 });
+export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = ABSOLUTE_OWNED_WORK_CEILINGS;
+export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = ABSOLUTE_OWNED_WORK_CEILINGS;
 const LOCK_WAIT_MS = 5;
 const LOCK_WAIT_CEILING_MS = 250;
 const STALE_LOCK_MS = 30_000;
@@ -29,16 +29,6 @@ function statePath(cwd: string, taskRunId: string): string { return path.join(cw
 function lockPath(cwd: string, taskRunId: string): string { return `${statePath(cwd, taskRunId)}.lock`; }
 function empty(request: HelperRequest, now: string): BudgetState { return { version: OWNED_WORK_BUDGET_VERSION, taskId: request.taskId, taskRunId: request.taskRunId, terminal: false, reservations: [], updatedAt: now }; }
 function active(state: BudgetState): OwnedWorkReservation[] { return state.reservations.filter((item) => item.status === "active"); }
-// The per-role ceiling, read from the ceilings the caller passed rather than
-// from constants written here. These limits were real but fixed at one apiece,
-// so `OwnedWorkCeilings` advertised six numbers that nothing ever read: a
-// profile could raise `maxScoutPasses` and be silently ignored, while the two
-// neighbouring fields in the same object did take effect. Half-honoured
-// configuration is worse than none, because the half that works teaches the
-// reader to trust the half that does not.
-//
-// Every default is one, so this changes no behaviour under the shipped
-// ceilings; it makes the object mean what it says.
 function roleLimit(role: HelperRole, ceilings: OwnedWorkCeilings): number {
   switch (role) {
     case "scout": case "retriever": case "researcher": return ceilings.maxScoutPasses;
@@ -51,6 +41,19 @@ function roleLimit(role: HelperRole, ceilings: OwnedWorkCeilings): number {
   }
 }
 
+function effectiveCeilings(requested: OwnedWorkCeilings): OwnedWorkCeilings {
+  return {
+    maxConcurrentHelpers: Math.min(requested.maxConcurrentHelpers, ABSOLUTE_OWNED_WORK_CEILINGS.maxConcurrentHelpers),
+    maxTotalHelpers: Math.min(requested.maxTotalHelpers, ABSOLUTE_OWNED_WORK_CEILINGS.maxTotalHelpers),
+    maxScoutPasses: Math.min(requested.maxScoutPasses, ABSOLUTE_OWNED_WORK_CEILINGS.maxScoutPasses),
+    maxPlannerPasses: Math.min(requested.maxPlannerPasses, ABSOLUTE_OWNED_WORK_CEILINGS.maxPlannerPasses),
+    maxReviewPasses: Math.min(requested.maxReviewPasses, ABSOLUTE_OWNED_WORK_CEILINGS.maxReviewPasses),
+    maxOracleCalls: Math.min(requested.maxOracleCalls, ABSOLUTE_OWNED_WORK_CEILINGS.maxOracleCalls),
+    maxRepairPasses: 0,
+    maxWriters: 0
+  };
+}
+
 function read(cwd: string, request: HelperRequest, now: string): BudgetState {
   const target = statePath(cwd, request.taskRunId); if (!fs.existsSync(target)) return empty(request, now);
   const resolved = resolveLocalStatePath(cwd, target, { label: "Helper budget state", kind: "file" });
@@ -153,14 +156,19 @@ export function inspectOwnedWorkBudget(cwd: string, taskId: string, taskRunId: s
 export class OwnedWorkBudgetController {
   reserve(cwd: string, requestInput: HelperRequest, now = new Date().toISOString(), ceilings: OwnedWorkCeilings = DEFAULT_OWNED_WORK_CEILINGS): { decision: "reserved" | "duplicate" | "blocked"; reason: string; reservationId: string | null; recoveredOrphans: number } {
     const request = validateHelperRequest(structuredClone(requestInput));
+    const limits = effectiveCeilings(ceilings);
     return withLock(cwd, request.taskRunId, () => {
       const state = read(cwd, request, now); const recoveredOrphans = recoverOrphans(state, now);
-      if (state.terminal) return { decision: "blocked", reason: "parent-task-terminal", reservationId: null, recoveredOrphans };
+      const settle = (result: { decision: "reserved" | "duplicate" | "blocked"; reason: string; reservationId: string | null; recoveredOrphans: number }) => {
+        if (recoveredOrphans > 0) { state.updatedAt = now; write(cwd, state); }
+        return result;
+      };
+      if (state.terminal) return settle({ decision: "blocked", reason: "parent-task-terminal", reservationId: null, recoveredOrphans });
       const duplicate = state.reservations.find((item) => item.deduplicationKey === request.deduplicationKey && ["active", "succeeded"].includes(item.status));
-      if (duplicate) return { decision: "duplicate", reason: "equivalent-helper-already-owned", reservationId: duplicate.id, recoveredOrphans };
-      if (active(state).length >= ceilings.maxConcurrentHelpers || state.reservations.length >= ceilings.maxTotalHelpers) return { decision: "blocked", reason: "helper-budget-exhausted", reservationId: null, recoveredOrphans };
-      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role, ceilings)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
-      if (request.authority === "single-writer" && active(state).some((item) => item.authority === "single-writer")) return { decision: "blocked", reason: "single-writer-already-owned", reservationId: null, recoveredOrphans };
+      if (duplicate) return settle({ decision: "duplicate", reason: "equivalent-helper-already-owned", reservationId: duplicate.id, recoveredOrphans });
+      if (active(state).length >= limits.maxConcurrentHelpers || state.reservations.length >= limits.maxTotalHelpers) return settle({ decision: "blocked", reason: "helper-budget-exhausted", reservationId: null, recoveredOrphans });
+      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role, limits)) return settle({ decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans });
+      if (request.authority === "single-writer" && active(state).some((item) => item.authority === "single-writer")) return settle({ decision: "blocked", reason: "single-writer-already-owned", reservationId: null, recoveredOrphans });
       const id = digest(`${request.taskRunId}:${request.deduplicationKey}:${state.reservations.length}`).slice(0, 32);
       state.reservations.push({ id, deduplicationKey: request.deduplicationKey, role: request.role, authority: request.authority, status: "active", reservedAt: now, expiresAt: new Date(Date.parse(now) + request.ceilings.timeSeconds * 1000).toISOString(), completedAt: null, usageRef: null });
       state.updatedAt = now; write(cwd, state); return { decision: "reserved", reason: "budget-reserved", reservationId: id, recoveredOrphans };

package/packages/piagent-core/runtime/orchestration/role-policy.ts

@@ -3,7 +3,7 @@ import { globMatchesPath, normalizePathCandidate } from "../../extensions/policy
 
 export const ROLE_POLICY_SCHEMA_VERSION = 1 as const;
 export const ROLE_POLICY_VERSION = "role-policy-v1" as const;
-export const HELPER_REQUEST_SCHEMA_VERSION = 1 as const;
+export const HELPER_REQUEST_SCHEMA_VERSION = 2 as const;
 export const HELPER_ROLES = Object.freeze(["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"] as const);
 export type HelperRole = typeof HELPER_ROLES[number];
 export type HelperAuthority = "read-only" | "single-writer";
@@ -15,12 +15,13 @@ export type RolePolicy = {
   outputSchema: string; stoppingRule: string; approvalRestrictions: string[];
 };
 export type HelperRequest = {
-  schemaVersion: 1; policyVersion: typeof ROLE_POLICY_VERSION; role: HelperRole; objectiveHash: string; objectiveText: string;
+  schemaVersion: 2; policyVersion: typeof ROLE_POLICY_VERSION; role: HelperRole; objectiveHash: string; objectiveText: string;
   taskId: string; taskRunId: string; sessionHash: string; authority: HelperAuthority; readScope: string[]; writeScope: string[];
   allowedTools: string[]; model: { provider: string; modelId: string; effort: string; source: string } | null;
   contextBudget: number; ceilings: { timeSeconds: number; calls: number; retries: number }; outputSchema: string;
   stoppingRule: string; approvalRestrictions: string[]; parentAuthorityDigest: string; singleWriterOwnership: string | null;
   deduplicationKey: string;
+  contextTransfer: { mode: "isolated-minimal"; inheritParentHistory: false; maxSeedTokens: number; estimatedSeedTokens: number };
 };
 
 const READ_TOOLS = ["read", "grep", "find", "ls"];
@@ -28,7 +29,7 @@ const MUTATION_TOOLS = new Set(["edit", "write", "apply_patch", "bash", "contact
 const HASH = /^[a-f0-9]{64}$/;
 const REF = /^[a-z0-9][a-z0-9:._/-]{0,255}$/i;
 const ROLE_FIELDS = new Set(["schemaVersion", "policyVersion", "role", "authority", "enabledByDefault", "readScope", "writeScope", "allowedTools", "modelSelectionSource", "effortSelectionSource", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions"]);
-const REQUEST_FIELDS = new Set(["schemaVersion", "policyVersion", "role", "objectiveHash", "objectiveText", "taskId", "taskRunId", "sessionHash", "authority", "readScope", "writeScope", "allowedTools", "model", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions", "parentAuthorityDigest", "singleWriterOwnership", "deduplicationKey"]);
+const REQUEST_FIELDS = new Set(["schemaVersion", "policyVersion", "role", "objectiveHash", "objectiveText", "taskId", "taskRunId", "sessionHash", "authority", "readScope", "writeScope", "allowedTools", "model", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions", "parentAuthorityDigest", "singleWriterOwnership", "deduplicationKey", "contextTransfer"]);
 
 function object(value: unknown): Record<string, any> | undefined { return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : undefined; }
 function exact(value: Record<string, any>, fields: Set<string>, label: string): string[] { return [...Object.keys(value).filter((field) => !fields.has(field)).map((field) => `${label} unknown field: ${field}`), ...[...fields].filter((field) => !(field in value)).map((field) => `${label} missing field: ${field}`)]; }
@@ -36,6 +37,15 @@ function strings(value: unknown, max: number, itemMax = 300): value is string[]
 function ceilings(value: unknown): boolean { const item = object(value); return Boolean(item && exact(item, new Set(["timeSeconds", "calls", "retries"]), "ceilings").length === 0 && Number.isInteger(item.timeSeconds) && item.timeSeconds >= 1 && item.timeSeconds <= 3600 && Number.isInteger(item.calls) && item.calls >= 1 && item.calls <= 100 && Number.isInteger(item.retries) && item.retries >= 0 && item.retries <= 3); }
 function digest(value: unknown): string { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
 function boundedObjective(value: unknown): string { return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, 1000); }
+function estimatedSeedTokens(value: Record<string, any>): number {
+  const seed = {
+    schemaVersion: value.schemaVersion, policyVersion: value.policyVersion, role: value.role, objectiveText: value.objectiveText,
+    taskId: value.taskId, taskRunId: value.taskRunId, authority: value.authority, readScope: value.readScope, writeScope: value.writeScope,
+    allowedTools: value.allowedTools, model: value.model, contextBudget: value.contextBudget, ceilings: value.ceilings,
+    outputSchema: value.outputSchema, stoppingRule: value.stoppingRule, approvalRestrictions: value.approvalRestrictions
+  };
+  return Math.ceil(JSON.stringify(seed).length / 4);
+}
 function safeScopePattern(value: string): boolean {
   const normalized = normalizePathCandidate(value);
   return Boolean(normalized && !/^\/|^[A-Za-z]:\//.test(normalized) && !normalized.split("/").some((part) => part === "." || part === "..") && !/[?\[\]{}\0]/.test(normalized));
@@ -69,7 +79,7 @@ export function validateRolePolicy(input: unknown): RolePolicy { const errors =
 export function helperRequestValidationErrors(input: unknown): string[] {
   const value = object(input); if (!value) return ["helper request must be an object"];
   const errors = exact(value, REQUEST_FIELDS, "helper request");
-  if (value.schemaVersion !== 1 || value.policyVersion !== ROLE_POLICY_VERSION || !HELPER_ROLES.includes(value.role) || !HASH.test(String(value.objectiveHash)) || !HASH.test(String(value.sessionHash)) || !HASH.test(String(value.parentAuthorityDigest)) || !HASH.test(String(value.deduplicationKey))) errors.push("helper identity/digests are invalid");
+  if (value.schemaVersion !== 2 || value.policyVersion !== ROLE_POLICY_VERSION || !HELPER_ROLES.includes(value.role) || !HASH.test(String(value.objectiveHash)) || !HASH.test(String(value.sessionHash)) || !HASH.test(String(value.parentAuthorityDigest)) || !HASH.test(String(value.deduplicationKey))) errors.push("helper identity/digests are invalid");
   if (typeof value.objectiveText !== "string" || value.objectiveText.length < 3 || value.objectiveText.length > 1000 || !REF.test(String(value.taskId)) || !REF.test(String(value.taskRunId))) errors.push("helper objective/task identity is invalid");
   if (!["read-only", "single-writer"].includes(value.authority) || !strings(value.readScope, 100) || !strings(value.writeScope, 100) || !value.readScope.every(safeScopePattern) || !value.writeScope.every(safeScopePattern) || !strings(value.allowedTools, 32) || !strings(value.approvalRestrictions, 16)) errors.push("helper authority collections are invalid");
   if (value.authority === "read-only" && (value.writeScope.length > 0 || value.allowedTools.some((tool: string) => MUTATION_TOOLS.has(tool)))) errors.push("read-only helper cannot mutate");
@@ -79,6 +89,12 @@ export function helperRequestValidationErrors(input: unknown): string[] {
   if (typeof value.outputSchema !== "string" || value.outputSchema.length > 200 || typeof value.stoppingRule !== "string" || value.stoppingRule.length > 500) errors.push("helper output/stopping contract is invalid");
   const model = value.model === null ? null : object(value.model);
   if (value.model !== null && (!model || exact(model, new Set(["provider", "modelId", "effort", "source"]), "model").length || ![model.provider, model.modelId, model.effort, model.source].every((item) => typeof item === "string" && item.length > 0 && item.length <= 160))) errors.push("helper model binding is invalid");
+  const contextTransfer = object(value.contextTransfer);
+  if (!contextTransfer || exact(contextTransfer, new Set(["mode", "inheritParentHistory", "maxSeedTokens", "estimatedSeedTokens"]), "context transfer").length
+    || contextTransfer.mode !== "isolated-minimal" || contextTransfer.inheritParentHistory !== false
+    || !Number.isInteger(contextTransfer.maxSeedTokens) || contextTransfer.maxSeedTokens < 256 || contextTransfer.maxSeedTokens > 2048
+    || !Number.isInteger(contextTransfer.estimatedSeedTokens) || contextTransfer.estimatedSeedTokens !== estimatedSeedTokens(value)
+    || contextTransfer.estimatedSeedTokens > contextTransfer.maxSeedTokens) errors.push("helper context transfer must be isolated and minimal");
   return errors;
 }
 export function validateHelperRequest(input: unknown): HelperRequest { const errors = helperRequestValidationErrors(input); if (errors.length) throw new Error(errors.join("; ")); return input as HelperRequest; }
@@ -87,9 +103,9 @@ export function defaultRolePolicy(role: HelperRole, scope: string[] = ["**"]): R
   const readOnly = role !== "worker";
   const policy: RolePolicy = {
     schemaVersion: 1, policyVersion: ROLE_POLICY_VERSION, role, authority: readOnly ? "read-only" : "single-writer",
-    enabledByDefault: readOnly, readScope: [...scope], writeScope: [], allowedTools: readOnly ? [...READ_TOOLS] : [...READ_TOOLS, "bash", "edit", "write", "contact_supervisor"],
-    modelSelectionSource: "runtime-catalog", effortSelectionSource: "runtime-snapshot", contextBudget: role === "oracle" ? 12000 : role === "reviewer" ? 9000 : 6000,
-    ceilings: { timeSeconds: role === "oracle" ? 900 : 600, calls: role === "retriever" ? 20 : 40, retries: 0 },
+    enabledByDefault: false, readScope: [...scope], writeScope: [], allowedTools: readOnly ? [...READ_TOOLS] : [...READ_TOOLS, "bash", "edit", "write", "apply_patch", "contact_supervisor"],
+    modelSelectionSource: "runtime-catalog", effortSelectionSource: "runtime-snapshot", contextBudget: role === "oracle" ? 8000 : role === "reviewer" || role === "planner" ? 6000 : 4000,
+    ceilings: { timeSeconds: 300, calls: 8, retries: 0 },
     outputSchema: `${role}-result-v1`, stoppingRule: "Stop when the bounded objective is answered or evidence is insufficient; return uncertainty.",
     approvalRestrictions: ["no-external-write", "no-destructive-action", "no-permission-expansion"]
   };
@@ -103,11 +119,13 @@ export function createHelperRequest(input: { policy: RolePolicy; objective: stri
   if (policy.allowedTools.some((tool) => !input.parentAllowedTools.includes(tool))) throw new Error("helper request cannot broaden parent tools");
   const authority = policy.authority;
   const request: HelperRequest = {
-    schemaVersion: 1, policyVersion: ROLE_POLICY_VERSION, role: policy.role, objectiveHash: digest(objectiveText), objectiveText,
+    schemaVersion: 2, policyVersion: ROLE_POLICY_VERSION, role: policy.role, objectiveHash: digest(objectiveText), objectiveText,
     taskId: input.taskId, taskRunId: input.taskRunId, sessionHash: digest(input.sessionId), authority, readScope: [...readScope], writeScope: [...writeScope], allowedTools: [...policy.allowedTools],
     model: input.model ?? null, contextBudget: policy.contextBudget, ceilings: { ...policy.ceilings }, outputSchema: policy.outputSchema, stoppingRule: policy.stoppingRule,
     approvalRestrictions: [...policy.approvalRestrictions], parentAuthorityDigest: digest({ read: input.parentReadScope, write: input.parentWriteScope, tools: input.parentAllowedTools }),
-    singleWriterOwnership: input.singleWriterOwnership ?? null, deduplicationKey: digest({ role: policy.role, objective: objectiveText, readScope, writeScope })
+    singleWriterOwnership: input.singleWriterOwnership ?? null, deduplicationKey: digest({ role: policy.role, objective: objectiveText, readScope, writeScope }),
+    contextTransfer: { mode: "isolated-minimal", inheritParentHistory: false, maxSeedTokens: 2048, estimatedSeedTokens: 0 }
   };
+  request.contextTransfer.estimatedSeedTokens = estimatedSeedTokens(request);
   return validateHelperRequest(request);
 }

package/packages/piagent-core/runtime/orchestration/subagent-tool-policy.ts

@@ -0,0 +1,329 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { taskAuthorityMode } from "../policy/task-authority-runtime.ts";
+import { MINIMAL_DELEGATION_LIMITS } from "./minimal-delegation-policy.ts";
+
+const SUBAGENT_TOOL = /(?:^|[_-])subagents?(?:[_-]|$)/i;
+const NON_DISPATCH_ACTIONS = new Set(["cancel", "kill", "list", "status", "stop", "wait"]);
+const READ_ONLY_AGENTS = new Set([
+  "piagent-oracle",
+  "piagent-planner",
+  "piagent-reviewer",
+  "piagent-scout"
+]);
+const URL = /\bhttps?:\/\/[^\s<>)\]}]+/i;
+const PROVIDED_SOURCE = /\b(?:provided|supplied|attached|pasted)\s+(?:evidence|source|text)|\busing only (?:the )?(?:evidence|source|text) below|\bdo not (?:fetch|open|retrieve)|\bn[oộ]i dung (?:đ[aã] )?(?:cung c[aấ]p|d[aá]n|đ[ií]nh k[eè]m)/i;
+
+type PlainRecord = Record<string, unknown>;
+
+export type DirectSubagentDispatchPreflight = {
+  applicable: boolean;
+  dispatch: boolean;
+  allowed: boolean;
+  reasonCode: string | null;
+  reason: string | null;
+  role: string | null;
+  requestCount: number;
+};
+
+export type DirectSubagentResult = {
+  applicable: boolean;
+  spawned: boolean;
+  failed: boolean;
+  reasonCode: string | null;
+  disposition: string;
+  role: "retriever" | "scout" | "planner" | "worker" | "reviewer" | "oracle" | "researcher";
+  requestRef: string;
+  outputDigest: string | null;
+  calls: number;
+  tokens: number;
+};
+
+type DirectSubagentTaskPersistence = {
+  now: () => string;
+  persist: (task: TaskContract) => TaskContract;
+  trace: (payload: Record<string, unknown>) => void;
+  sessionTrace?: (payload: Record<string, unknown>) => void;
+};
+
+export function taskHelperUsageMode(task: TaskContract): "off" | "recommend" | "on" {
+  const boundMode = taskAuthorityMode(task, "CAP-14");
+  return boundMode === "on" || boundMode === "recommend" ? boundMode : "off";
+}
+
+export function reserveDirectSubagentDispatch(
+  task: TaskContract | undefined,
+  toolCallId: string,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending" || task.orchestration?.subagents !== "not-used") return task;
+  task.orchestration = {
+    ...(task.orchestration ?? {
+      mode: "solo-first" as const,
+      subagents: "not-used" as const,
+      reason: "Parent works directly by default."
+    }),
+    subagents: "optional",
+    reason: "One bounded read-only helper dispatch is authorized and awaiting a durable result."
+  };
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  persistence.trace({
+    event: "helper_dispatch_reserved",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId
+  });
+  return written;
+}
+
+export function recordDirectSubagentResult(
+  task: TaskContract | undefined,
+  event: { toolCallId?: string; toolName: string },
+  result: DirectSubagentResult,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending") return task;
+  const existingUsage = task.acceptanceReceipt?.helperUsage;
+  const helper = {
+    role: result.role,
+    disposition: result.disposition,
+    requestRef: result.requestRef,
+    outputDigest: result.outputDigest,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  const helpers = result.spawned
+    ? [...(existingUsage?.helpers ?? []).filter((item) => item.requestRef !== result.requestRef), helper].slice(-3)
+    : existingUsage?.helpers ?? [];
+  const used = helpers.length > 0 || existingUsage?.used === true;
+  const reasonCodes = [...new Set([
+    ...(existingUsage?.reasonCodes ?? []),
+    result.reasonCode ?? (result.spawned ? "helper-result-accepted" : "helper-dispatch-rejected")
+  ])].slice(-16);
+  if (task.acceptanceReceipt) {
+    task.acceptanceReceipt.helperUsage = {
+      mode: taskHelperUsageMode(task),
+      used,
+      decision: result.spawned ? "dispatch" : "skip",
+      projectedSavingsRatio: existingUsage?.projectedSavingsRatio ?? null,
+      reasonCodes,
+      helpers,
+      recordedAt: persistence.now()
+    };
+  }
+  if (task.orchestration) {
+    task.orchestration.subagents = used ? "used" : "not-used";
+    task.orchestration.reason = result.spawned
+      ? `A bounded read-only helper ran with disposition ${result.disposition}; its digest-only usage is recorded in the acceptance receipt.`
+      : `Helper dispatch did not start (${result.reasonCode ?? "helper-dispatch-rejected"}); the parent remains the sole execution owner.`;
+  }
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  const trace = {
+    event: "helper_result_recorded",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId: event.toolCallId,
+    toolName: event.toolName,
+    spawned: result.spawned,
+    disposition: result.disposition,
+    reasonCode: result.reasonCode,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  persistence.trace(trace);
+  persistence.sessionTrace?.(trace);
+  return written;
+}
+
+function record(value: unknown): PlainRecord {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as PlainRecord : {};
+}
+
+function finiteInteger(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.trunc(value))
+    : fallback;
+}
+
+function helperRole(value: unknown): DirectSubagentResult["role"] {
+  const normalized = String(value ?? "").trim().toLowerCase().replace(/^piagent-/, "");
+  return ["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"].includes(normalized)
+    ? normalized as DirectSubagentResult["role"]
+    : "scout";
+}
+
+function dispatchRequests(input: PlainRecord): PlainRecord[] {
+  if (Array.isArray(input.tasks)) {
+    return input.tasks.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+      .map((item) => ({ ...input, ...item, tasks: undefined }));
+  }
+  return typeof input.agent === "string" && input.agent.trim() ? [input] : [];
+}
+
+function boundedNumber(input: PlainRecord, nestedField: string, field: string): number | undefined {
+  const nested = record(input[nestedField]);
+  const value = nested[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function sameProjectRoot(currentCwd: string, requested: unknown): boolean {
+  if (typeof requested !== "string" || !requested.trim()) return true;
+  return path.resolve(currentCwd) === path.resolve(currentCwd, requested);
+}
+
+function blocked(reasonCode: string, reason: string, role: string | null, requestCount: number): DirectSubagentDispatchPreflight {
+  return { applicable: true, dispatch: true, allowed: false, reasonCode, reason, role, requestCount };
+}
+
+/**
+ * The optional pi-subagents tool is a second execution backend. It must not be
+ * able to bypass the task-bound CAP-14 snapshot merely because the model knows
+ * the tool name. This preflight is deliberately conservative: one fresh,
+ * read-only, locally capable helper, with the same hard ceilings as Piagent's
+ * owned helper runtime.
+ */
+export function evaluateDirectSubagentDispatch(input: {
+  toolName: string;
+  toolInput: unknown;
+  cwd: string;
+  helpersMode: "off" | "recommend" | "on";
+  taskPending: boolean;
+  dispatchAuthority: boolean;
+  durableSubagentState?: "not-used" | "optional" | "used";
+}): DirectSubagentDispatchPreflight {
+  if (!SUBAGENT_TOOL.test(input.toolName)) {
+    return { applicable: false, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  const toolInput = record(input.toolInput);
+  const requests = dispatchRequests(toolInput);
+  const action = String(toolInput.action ?? "").trim().toLowerCase();
+  if (requests.length === 0 && NON_DISPATCH_ACTIONS.has(action)) {
+    return { applicable: true, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  if (requests.length === 0) return blocked("helper-dispatch-shape-invalid", "Subagent dispatch requires exactly one named read-only helper.", null, 0);
+  const role = String(requests[0].agent ?? "").trim();
+  if (requests.length !== 1) return blocked("helper-count-exceeds-one", `Piagent permits at most one helper for the entire task; ${requests.length} were requested.`, role || null, requests.length);
+  if (!input.taskPending) return blocked("helper-task-authority-missing", "A pending session-bound task is required before helper dispatch.", role || null, 1);
+  if (input.helpersMode !== "on" || !input.dispatchAuthority) {
+    return blocked("helper-dispatch-authority-disabled", "Task-bound helper authority is not on; continue in the parent model.", role || null, 1);
+  }
+  if (input.durableSubagentState === "optional" || input.durableSubagentState === "used") {
+    return blocked("helper-retry-forbidden", "This task already reserved or used its one helper; helper retries are disabled.", role || null, 1);
+  }
+  if (role === "piagent-worker" || !READ_ONLY_AGENTS.has(role)) {
+    return blocked("automatic-helper-role-disabled", `Automatic helper ${role || "(unknown)"} is not an enabled read-only Piagent role.`, role || null, 1);
+  }
+  const request = requests[0];
+  if (request.context !== undefined && request.context !== "fresh") {
+    return blocked("helper-parent-history-forbidden", "Helpers must use fresh isolated context and cannot fork the parent transcript.", role, 1);
+  }
+  if (!sameProjectRoot(input.cwd, request.cwd)) {
+    return blocked("helper-cwd-outside-project", "Helper cwd must remain the current project root.", role, 1);
+  }
+  const timeoutMs = typeof request.timeoutMs === "number" ? request.timeoutMs : undefined;
+  if (timeoutMs === undefined) {
+    return blocked("helper-time-budget-missing", "Helper dispatch requires an explicit timeoutMs no greater than 300 seconds.", role, 1);
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs > 300_000 || timeoutMs < 1) {
+    return blocked("helper-time-budget-exceeded", "Helper timeout must be between 1 ms and the 300 second Piagent ceiling.", role, 1);
+  }
+  const maxTurns = boundedNumber(request, "turnBudget", "maxTurns");
+  if (maxTurns === undefined) {
+    return blocked("helper-turn-budget-missing", "Helper dispatch requires an explicit turnBudget.maxTurns no greater than 8.", role, 1);
+  }
+  if (maxTurns < 1 || maxTurns > 8) {
+    return blocked("helper-turn-budget-exceeded", "Helper maxTurns exceeds the bounded 8-turn ceiling.", role, 1);
+  }
+  const hardCalls = boundedNumber(request, "toolBudget", "hard");
+  if (hardCalls === undefined) {
+    return blocked("helper-call-budget-missing", `Helper dispatch requires an explicit toolBudget.hard no greater than ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}.`, role, 1);
+  }
+  if (hardCalls < 1 || hardCalls > MINIMAL_DELEGATION_LIMITS.maxHelperCalls) {
+    return blocked("helper-call-budget-exceeded", `Helper hard tool budget exceeds the ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}-call ceiling.`, role, 1);
+  }
+  const objective = String(request.task ?? "").trim();
+  if (!objective) return blocked("helper-objective-missing", "Helper dispatch requires a bounded objective.", role, 1);
+  if (URL.test(objective) && !PROVIDED_SOURCE.test(objective)) {
+    return blocked("helper-source-access-unavailable", "The selected helper has local read tools only and cannot retrieve the remote URL; inspect it in the parent or provide a local checkout/evidence bundle.", role, 1);
+  }
+  return { applicable: true, dispatch: true, allowed: true, reasonCode: null, reason: null, role, requestCount: 1 };
+}
+
+function textContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
+    .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n");
+}
+
+function childAcceptanceFailed(result: PlainRecord): boolean {
+  const acceptance = record(result.acceptance);
+  const report = record(acceptance.childReport);
+  const criteria = Array.isArray(report.criteriaSatisfied) ? report.criteriaSatisfied : [];
+  return criteria.some((item) => record(item).status === "not-satisfied")
+    || ["failed", "rejected", "not-satisfied"].includes(String(acceptance.status ?? "").toLowerCase());
+}
+
+function totalUsage(details: PlainRecord, results: PlainRecord[]): number {
+  const aggregate = record(details.totalChildUsage);
+  const sources = Object.keys(aggregate).length > 0 ? [aggregate] : results.map((result) => record(result.usage));
+  return Math.min(100_000_000, sources.reduce((total, usage) => total
+    + finiteInteger(usage.input)
+    + finiteInteger(usage.output)
+    + finiteInteger(usage.cacheRead)
+    + finiteInteger(usage.cacheWrite), 0));
+}
+
+/** Convert a pi-subagents provider result into fail-closed, digest-only truth. */
+export function classifyDirectSubagentResult(input: {
+  toolName: string;
+  toolInput: unknown;
+  content: unknown;
+  details: unknown;
+  isError?: boolean;
+}): DirectSubagentResult | undefined {
+  if (!SUBAGENT_TOOL.test(input.toolName)) return undefined;
+  const toolInput = record(input.toolInput);
+  if (dispatchRequests(toolInput).length === 0) return undefined;
+  const details = record(input.details);
+  const results = Array.isArray(details.results)
+    ? details.results.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+    : [];
+  const spawned = results.length > 0 || typeof details.runId === "string" && details.runId.length > 0;
+  const resultFailures = results.some((result) => finiteInteger(result.exitCode) !== 0 || childAcceptanceFailed(result));
+  const content = textContent(input.content);
+  const insufficientEvidence = results.some(childAcceptanceFailed)
+    || /\bscope inspected:\s*none\b|\bno source (?:content|evidence) (?:was|could be) (?:accessible|collected)|\bcriteria?[^\n]{0,80}not-satisfied\b/i.test(content);
+  const failed = input.isError === true || !spawned || resultFailures || insufficientEvidence;
+  const reasonCode = input.isError === true
+    ? "helper-tool-error"
+    : !spawned
+      ? "helper-dispatch-rejected"
+      : insufficientEvidence
+        ? "helper-insufficient-evidence"
+        : resultFailures
+          ? "helper-run-failed"
+          : null;
+  const firstResult = results[0] ?? {};
+  const agent = firstResult.agent ?? dispatchRequests(toolInput)[0]?.agent;
+  const finalOutput = results.map((result) => String(result.finalOutput ?? "")).filter(Boolean).join("\n");
+  const calls = Math.min(100, results.reduce((total, result) => total + finiteInteger(result.toolCount), 0));
+  return {
+    applicable: true,
+    spawned,
+    failed,
+    reasonCode,
+    disposition: failed ? reasonCode ?? "failed" : "succeeded",
+    role: helperRole(agent),
+    requestRef: crypto.createHash("sha256").update(JSON.stringify(toolInput)).digest("hex"),
+    outputDigest: !failed && finalOutput ? crypto.createHash("sha256").update(finalOutput).digest("hex") : null,
+    calls,
+    tokens: totalUsage(details, results)
+  };
+}

package/packages/piagent-core/runtime/policy/block-remedy.ts

@@ -43,10 +43,6 @@ const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
     match: /outside resolved filesystem scope/i,
     remedy: "Work inside the project, or widen the filesystem scope in the active profile and reapply it."
   },
-  {
-    match: /cannot mutate paths outside its declared scope|semantic repair must stay inside its declared task scope/i,
-    remedy: "Start a new attempt with `piagent_task_start` listing this path in the scope; a running task cannot widen its own."
-  },
   {
     match: /Task Implementation Contract is required/i,
     remedy: "Call `piagent_task_start` once with explicit project-relative scope, then retry."

package/packages/piagent-core/runtime/product/activity-inspector.ts

@@ -3,6 +3,8 @@ import {
   buildWebUiInspectionProjection,
   type WebUiInspectionProjection
 } from "../inspection/webui-snapshot.ts";
+import { recoveredToolCalls } from "../inspection/activity-recovery.ts";
+import { handledToolFailure } from "../inspection/tool-failure-classification.ts";
 
 export const ACTIVITY_INSPECTOR_VERSION = "activity-inspector-v2" as const;
 
@@ -18,6 +20,7 @@ export type ActivityInspectorEvent = {
   command?: string;
   decision?: string;
   reason?: string;
+  reasonCode?: string;
   warningKind?: string;
   isError?: boolean;
   exitCode?: number;
@@ -46,13 +49,15 @@ function isTestPath(file: string): boolean { return /(^|\/)(?:test|tests|spec|__
 function failedToolResult(event: ActivityInspectorEvent): boolean { return event.isError === true || (typeof event.exitCode === "number" && event.exitCode !== 0); }
 
 function commandProjection(events: ActivityInspectorEvent[]) {
+  const recoveries = recoveredToolCalls(events);
   const calls = events.filter((event) => event.event === "tool_call" && ["bash", "shell", "exec"].includes(String(event.toolName)));
   const results = new Map(events.filter((event) => event.event === "tool_result").map((event) => [event.toolCallId, event]));
   const decisions = new Map(events.filter((event) => event.event === "tool_decision").map((event) => [event.toolCallId, event]));
   const entries = calls.map((call) => {
     const decision = decisions.get(call.toolCallId), result = results.get(call.toolCallId);
     const blocked = decision?.decision === "blocked";
-    const failed = !blocked && Boolean(result && failedToolResult(result));
+    const recovered = Boolean(call.toolCallId && recoveries.has(call.toolCallId));
+    const failed = !blocked && !recovered && !handledToolFailure(result?.reasonCode) && Boolean(result && failedToolResult(result));
     return { toolCallId: call.toolCallId ?? "unknown", command: call.command ?? "[redacted or unavailable]",
       status: blocked ? "blocked" : !result ? "running" : failed ? "failed" : "passed",
       exitCode: result?.exitCode ?? null, exitCodeExact: result?.exitCodeExact === true,
@@ -121,7 +126,7 @@ export async function buildActivityInspector(input: {
       phase: snapshot.session.operation.hostPhase.state === "known" && snapshot.session.operation.hostPhase.value !== "idle" ? snapshot.session.operation.hostPhase.value : null,
       outcome: snapshot.task?.outcome ?? "idle", running: snapshot.activity.running.length, current: input.current ?? [] },
     criteria: snapshot.task?.criteria ?? [], sourceChanges: snapshot.sourceChanges, files,
-    tools: { calls: calls.length, results: results.length, failed: results.filter(failedToolResult).length,
+    tools: { calls: calls.length, results: results.length, failed: results.filter((event) => failedToolResult(event) && !handledToolFailure(event.reasonCode)).length,
       blocked: events.filter((event) => event.event === "tool_decision" && event.decision === "blocked").length, byName,
       perToolTokens: null, perToolTokensReason: "Pi reports model usage by response/turn; built-in tool calls do not carry attributable model-token totals." },
     commands, safety,

package/packages/piagent-core/runtime/product/efficiency-metrics.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import { readSolverShadowEvents } from "../solver/solver-shadow.ts";
 import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
@@ -52,8 +53,9 @@ export function buildTaskEfficiencyMetrics(
   const decision = solverEvent?.decision;
   const helperUsage = task.acceptanceReceipt?.helperUsage;
   const provenance = task.acceptanceReceipt?.provenance;
+  const contextEvidence = durableContextEvidenceEntries(task);
   const relevantEvent = trajectory.events.find((event) => event.cause === "context-observed");
-  const relevantFileMs = relevantEvent && task.contextManifest.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
+  const relevantFileMs = relevantEvent && contextEvidence.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
   const recommendedTools = decision?.toolGroups ?? [];
   const activeTools = [...new Set(input.activeToolGroups ?? [])].sort();
   const exactUsage = input.exactUsage && (input.exactUsage.tokens !== null || input.exactUsage.cost !== null)
@@ -83,7 +85,7 @@ export function buildTaskEfficiencyMetrics(
     },
     context: {
       requiredFiles: task.requiredContext.length,
-      manifestedFiles: task.contextManifest.length,
+      manifestedFiles: contextEvidence.length,
       memoryCitations: task.memoryCitations.length,
       recommendedBudget: decision?.context.budgetBand ?? "unknown",
       timeToRelevantFileMs: relevantFileMs,
@@ -110,6 +112,9 @@ export function buildTaskEfficiencyMetrics(
     helpers: {
       mode: helperUsage?.mode ?? "unknown",
       used: helperUsage?.used ?? false,
+      decision: helperUsage?.decision ?? (helperUsage?.used ? "dispatch" : "skip"),
+      projectedSavingsRatio: helperUsage?.projectedSavingsRatio ?? null,
+      reasonCodes: helperUsage?.reasonCodes ?? ["parent-direct-default"],
       entries: (helperUsage?.helpers ?? []).map((item) => ({
         role: item.role,
         model: null,