@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/inspection/webui-snapshot.ts

@@ -8,6 +8,8 @@ import { workingTreeEvidenceDigest, workingTreeSnapshotUsesCurrentAlgorithm } fr
 import { inspectTaskContinuationBudget } from "../recovery/continuation-budget.ts";
 import { readHandoffProjection } from "../recovery/handoff-projection.ts";
 import type { ActivityInspectorEvent, CurrentActivity } from "../product/activity-inspector.ts";
+import { recoveredToolCalls } from "./activity-recovery.ts";
+import { classifyToolFailure, handledToolFailure } from "./tool-failure-classification.ts";
 import { projectCriteriaFileVerifier, type CriteriaLinkProjection } from "./criteria-links.ts";
 import { collectSourceChangeViews, type SourceChangeDocument, type WebUiIdentity } from "./source-change-projection.ts";
 
@@ -82,6 +84,60 @@ function scopedEvents(events: ActivityInspectorEvent[], sessionId: string, task?
   return [...deduped.values()].sort((left, right) => String(left.recordedAt).localeCompare(String(right.recordedAt))).slice(-2_000);
 }
 
+type CanonicalToolResult = { content: unknown; isError: boolean; toolName: string; recordedAt?: string };
+
+function canonicalToolEvidence(sessionEntries: unknown[]): {
+  inputs: Map<string, unknown>;
+  results: Map<string, CanonicalToolResult>;
+} {
+  const inputs = new Map<string, unknown>(), results = new Map<string, CanonicalToolResult>();
+  for (const entry of sessionEntries) {
+    if (!entry || typeof entry !== "object" || (entry as any).type !== "message") continue;
+    const message = (entry as any).message;
+    if (message?.role === "assistant" && Array.isArray(message.content)) {
+      for (const block of message.content) if (block?.type === "toolCall" && typeof block.id === "string") inputs.set(block.id, block.arguments);
+    }
+    if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
+      const recordedAt = TIMESTAMP.test(String((entry as any).timestamp ?? message.timestamp ?? ""))
+        ? String((entry as any).timestamp ?? message.timestamp) : undefined;
+      results.set(message.toolCallId, { content: message.content, isError: message.isError === true,
+        toolName: typeof message.toolName === "string" ? message.toolName : "", recordedAt });
+    }
+  }
+  return { inputs, results };
+}
+
+function reconciledToolResults(events: ActivityInspectorEvent[], evidence: ReturnType<typeof canonicalToolEvidence>): ActivityInspectorEvent[] {
+  const resultIds = new Set(events.filter((event) => event.event === "tool_result" && event.toolCallId).map((event) => event.toolCallId as string));
+  const reconciled = events.map((event) => {
+    if (event.event !== "tool_result" || !event.toolCallId) return event;
+    const raw = evidence.results.get(event.toolCallId);
+    if (!raw) return event;
+    const reasonCode = classifyToolFailure(raw.toolName || event.toolName, raw.isError, raw.content, evidence.inputs.get(event.toolCallId));
+    if (!event.isError) {
+      // A newer explicit success remains authoritative over an older canonical
+      // hard error. The exception is a provider-level helper soft failure:
+      // legacy telemetry could only see `isError=false`, while the canonical
+      // result proves that no useful child actually ran.
+      if (raw.isError || !["helper-dispatch-rejected", "helper-insufficient-evidence"].includes(String(reasonCode))) return event;
+      return { ...event, isError: true, reasonCode };
+    }
+    return reasonCode ? { ...event, reasonCode } : event;
+  });
+  for (const call of events) {
+    if (call.event !== "tool_call" || !call.toolCallId || resultIds.has(call.toolCallId)) continue;
+    const raw = evidence.results.get(call.toolCallId);
+    if (!raw) continue;
+    const reasonCode = classifyToolFailure(raw.toolName || call.toolName, raw.isError, raw.content, evidence.inputs.get(call.toolCallId));
+    const effectiveError = raw.isError || Boolean(reasonCode && !handledToolFailure(reasonCode));
+    reconciled.push({ activityId: `canonical-result:${call.toolCallId}`, event: "tool_result",
+      recordedAt: raw.recordedAt ?? call.recordedAt, sessionId: call.sessionId, taskRunId: call.taskRunId,
+      toolCallId: call.toolCallId, toolName: raw.toolName || call.toolName, isError: effectiveError,
+      ...(reasonCode ? { reasonCode } : {}) });
+  }
+  return reconciled.sort((left, right) => String(left.recordedAt ?? "").localeCompare(String(right.recordedAt ?? "")));
+}
+
 function sourceSummary(document: SourceChangeDocument | null, view: "task" | "working-tree" | "staged") {
   if (!document || document.availability.state === "unavailable") return {
     view, base: view === "task" ? "task-baseline" : "HEAD", state: "unavailable", revision: null,
@@ -109,21 +165,26 @@ function sourceSummary(document: SourceChangeDocument | null, view: "task" | "wo
 function activityProjection(events: ActivityInspectorEvent[], current: CurrentActivity[]) {
   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 recoveries = recoveredToolCalls(events);
   const calls = events.filter((event) => event.event === "tool_call").slice(-200);
   const projected = calls.map((call) => {
     const result = results.get(call.toolCallId), decision = decisions.get(call.toolCallId);
     const blocked = decision?.decision === "blocked";
-    const failed = !blocked && Boolean(result && (result.isError === true || (typeof result.exitCode === "number" && result.exitCode !== 0)));
-    const state = blocked ? "blocked" : !result ? "running" : failed ? "failed" : "passed";
+    const handled = Boolean(result && handledToolFailure(result.reasonCode));
+    const failed = !blocked && !handled && Boolean(result && (result.isError === true || (typeof result.exitCode === "number" && result.exitCode !== 0)));
+    const recovery = call.toolCallId ? recoveries.get(call.toolCallId) : undefined;
+    const state = blocked ? "blocked" : !result ? "running" : failed && !recovery ? "failed" : "passed";
     const toolName = display(call.toolName ?? "unknown", 80).replace(/[^A-Za-z0-9._:@~-]/g, "-") || "unknown";
     const rawId = String(call.toolCallId ?? call.activityId ?? `${call.recordedAt}:${toolName}`);
     const command = display(call.command ?? call.targetPath ?? toolName, 65_536);
     return {
       activityRef: token("activity", [rawId, call.recordedAt]), kind: ["bash", "shell", "exec"].includes(toolName) ? "command" : "tool", state,
-      label: display(state === "running" ? `${toolName} running` : `${toolName} ${state}`, 500), preview: command,
+      label: display(recovery ? `${toolName} recovered` : handled ? `${toolName} warning` : state === "running" ? `${toolName} running` : `${toolName} ${state}`, 500), preview: command,
       toolCallId: token("tool", rawId), toolName, commandDigest: call.command ? `sha256:${hash(call.command)}` : null,
-      logRef: null, exitCode: typeof result?.exitCode === "number" ? result.exitCode : null, exitCodeExact: result?.exitCodeExact === true,
-      startedAt: timestamp(call.recordedAt), finishedAt: result || blocked ? timestamp(result?.recordedAt ?? decision?.recordedAt, timestamp(call.recordedAt)) : null
+      logRef: null, exitCode: recovery?.exitCode ?? (typeof result?.exitCode === "number" ? result.exitCode : null),
+      exitCodeExact: recovery?.exitCodeExact ?? (result?.exitCodeExact === true),
+      startedAt: timestamp(call.recordedAt), finishedAt: recovery ? timestamp(recovery.recoveredAt, timestamp(call.recordedAt))
+        : result || blocked ? timestamp(result?.recordedAt ?? decision?.recordedAt, timestamp(call.recordedAt)) : null
     };
   });
   const callIds = new Set(calls.map((call) => String(call.toolCallId ?? "")));
@@ -274,12 +335,15 @@ export async function buildWebUiInspectionProjection(input: {
   const taskRevision = input.task ? webUiTaskRevision(input.task) : null;
   const views = await collectSourceChangeViews({ cwd: input.cwd, identity, generatedAt, taskRevision,
     isProtectedPath: (_root, repoPath) => Boolean(matchesProtectedPath(repoPath, effectiveProtectedPaths)) });
-  const events = scopedEvents(input.events ?? [], input.sessionId, input.task);
+  const canonicalEvidence = canonicalToolEvidence(input.sessionEntries ?? []);
+  const events = reconciledToolResults(scopedEvents(input.events ?? [], input.sessionId, input.task), canonicalEvidence);
   const linked = projectCriteriaFileVerifier({ cwd: input.cwd, task: input.task, sourceViews: views, currentSnapshot,
     protectedPaths: input.protectedPaths, events, at: new Date(generatedAt) });
   const sourceChanges = { task: sourceSummary(linked.sourceViews.task, "task"), workingTree: sourceSummary(linked.sourceViews.workingTree, "working-tree"), staged: sourceSummary(linked.sourceViews.staged, "staged") };
   const currentDigest = workingTreeSnapshotUsesCurrentAlgorithm(currentSnapshot) ? workingTreeEvidenceDigest(currentSnapshot) : null;
-  const current = input.current ?? [], controlState = input.task?.trace.outcome === "pending" ? "active" as const : "terminal" as const;
+  const current = (input.current ?? []).filter((item) => (item.status ?? "running") !== "running" || !canonicalEvidence.results.has(item.toolCallId));
+  const runningCurrent = current.find((item) => (item.status ?? "running") === "running");
+  const controlState = input.task?.trace.outcome === "pending" ? "active" as const : "terminal" as const;
   const context = contextProjection(input.contextUsage, generatedAt), usageFacts = usage(input.sessionEntries ?? []);
   const eventCursor = input.eventCursor ?? token("event-cursor", events.map((event) => event.activityId ?? [event.event, event.toolCallId, event.recordedAt]));
   const runtimeRevision = token("runtime-rev", [taskRevision, sourceChanges.workingTree.revision, sourceChanges.staged.revision, eventCursor, current]);
@@ -300,8 +364,8 @@ export async function buildWebUiInspectionProjection(input: {
     capabilities: capabilities(identity, generatedAt, input.resyncRequired === true, input.eventReplay),
     session: {
       connectionState: input.resyncRequired ? "resync-required" : "connected", connectionReason: input.resyncRequired ? "event-replay-gap" : null, displayName: input.task?.sessionName ?? null,
-      operation: current.some((item) => (item.status ?? "running") === "running")
-        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: "tool", evidence: "derived", reasonCode: null }, startedAt: timestamp(current[0]?.startedAt, generatedAt), settledAt: null, reasonCode: null }
+      operation: runningCurrent
+        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: "tool", evidence: "derived", reasonCode: null }, startedAt: timestamp(runningCurrent.startedAt, generatedAt), settledAt: null, reasonCode: null }
         : { liveness: "idle", operationRef: null, hostPhase: { state: "known", value: "idle", evidence: "derived", reasonCode: null }, startedAt: null, settledAt: null, reasonCode: null },
       controlState: input.task ? controlState : "active", taskOutcome: input.task?.trace.outcome ?? null, approvalState: approvals.state,
       verificationState: linked.verification.state, permissionProfile: { state: "unavailable", value: null, evidence: null, reasonCode: "permission-profile-not-projected" },

package/packages/piagent-core/runtime/model/authenticated-catalog.ts

@@ -50,14 +50,22 @@ function positiveInteger(value: unknown): number | null {
   return Number.isInteger(value) && Number(value) > 0 && Number(value) <= 10_000_000 ? Number(value) : null;
 }
 
-function thinkingLevels(value: unknown): string[] | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const levels = Object.entries(value)
-    .filter(([, mapped]) => mapped !== null && mapped !== false)
-    .map(([level]) => text(level))
-    .filter(Boolean)
-    .sort();
-  return levels.length > 0 ? [...new Set(levels)].slice(0, 16) : [];
+const PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+function thinkingLevels(value: ModelLike): string[] | null {
+  if (typeof value.reasoning !== "boolean") return null;
+  if (!value.reasoning) return ["off"];
+  const mapping = value.thinkingLevelMap && typeof value.thinkingLevelMap === "object" && !Array.isArray(value.thinkingLevelMap)
+    ? value.thinkingLevelMap as Record<string, unknown>
+    : {};
+  // Match Pi's getSupportedThinkingLevels semantics. Reasoning models support
+  // the standard host levels through `high` unless a model explicitly marks a
+  // level null. `xhigh` and `max` are opt-in capabilities.
+  return PI_THINKING_LEVELS.filter((level) => {
+    const mapped = mapping[level];
+    if (mapped === null) return false;
+    return level === "xhigh" || level === "max" ? mapped !== undefined : true;
+  });
 }
 
 function boundedModel(value: ModelLike): AuthenticatedModelCatalogEntry | undefined {
@@ -71,7 +79,7 @@ function boundedModel(value: ModelLike): AuthenticatedModelCatalogEntry | undefi
     contextWindow: positiveInteger(value.contextWindow),
     reasoning: typeof value.reasoning === "boolean" ? value.reasoning : null,
     imageInput: input ? input.includes("image") : null,
-    supportedThinkingLevels: thinkingLevels(value.thinkingLevelMap)
+    supportedThinkingLevels: thinkingLevels(value)
   };
 }
 

package/packages/piagent-core/runtime/model/openai-codex-reasoning.ts

@@ -0,0 +1,83 @@
+type ProviderPayload = Record<string, unknown>;
+
+const GPT56_CODEX_MODEL = /^gpt-5\.6-(?:luna|sol|terra)$/;
+const PROVIDER_EFFORT_BY_HOST_LEVEL: Readonly<Record<string, string>> = Object.freeze({
+  off: "none",
+  minimal: "low",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max"
+});
+
+export type OpenAiCodexReasoningNormalization = {
+  payload: unknown;
+  applicable: boolean;
+  changed: boolean;
+  hostThinkingLevel: string;
+  expectedProviderEffort: string | null;
+  providerEffort: string | null;
+  reasonCode: "not-applicable" | "observed" | "off-normalized-to-none" | "minimal-normalized-to-low" | "provider-effort-normalized";
+};
+
+function record(value: unknown): ProviderPayload | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as ProviderPayload : null;
+}
+
+function effortFromPayload(payload: ProviderPayload): string | null {
+  const reasoning = record(payload.reasoning);
+  return typeof reasoning?.effort === "string" ? reasoning.effort : null;
+}
+
+/**
+ * Compatibility bridge for the pinned Pi host's OpenAI Codex serializer.
+ *
+ * Pi names the provider's `none` effort `off`. Pi 0.84.1 currently drops
+ * `off` before its request builder, which omits the reasoning object and lets
+ * GPT-5.6 use its server default. Enforce the same-model/effort invariant for
+ * every host level, while keeping the correction deliberately narrow to the
+ * three authenticated GPT-5.6 Codex models whose capability map we audit.
+ */
+export function normalizeOpenAiCodexReasoningPayload(input: {
+  payload: unknown;
+  provider: unknown;
+  modelId: unknown;
+  hostThinkingLevel: unknown;
+}): OpenAiCodexReasoningNormalization {
+  const provider = String(input.provider ?? "");
+  const modelId = String(input.modelId ?? "");
+  const hostThinkingLevel = String(input.hostThinkingLevel ?? "");
+  const payload = record(input.payload);
+  const expectedProviderEffort = PROVIDER_EFFORT_BY_HOST_LEVEL[hostThinkingLevel] ?? null;
+  const applicable = provider === "openai-codex" && GPT56_CODEX_MODEL.test(modelId)
+    && payload !== null && payload.model === modelId && expectedProviderEffort !== null;
+  if (!applicable || !payload) {
+    return { payload: input.payload, applicable: false, changed: false, hostThinkingLevel,
+      expectedProviderEffort, providerEffort: payload ? effortFromPayload(payload) : null, reasonCode: "not-applicable" };
+  }
+
+  const currentEffort = effortFromPayload(payload);
+  if (currentEffort === expectedProviderEffort) {
+    return { payload: input.payload, applicable: true, changed: false, hostThinkingLevel,
+      expectedProviderEffort, providerEffort: currentEffort, reasonCode: "observed" };
+  }
+
+  const currentReasoning = record(payload.reasoning) ?? {};
+  const normalizedReasoning = {
+    ...currentReasoning,
+    effort: expectedProviderEffort,
+    ...(typeof currentReasoning.summary === "string" ? {} : { summary: "auto" })
+  };
+  return {
+    payload: { ...payload, reasoning: normalizedReasoning },
+    applicable: true,
+    changed: true,
+    hostThinkingLevel,
+    expectedProviderEffort,
+    providerEffort: expectedProviderEffort,
+    reasonCode: hostThinkingLevel === "off" ? "off-normalized-to-none"
+      : hostThinkingLevel === "minimal" ? "minimal-normalized-to-low"
+        : "provider-effort-normalized"
+  };
+}

package/packages/piagent-core/runtime/model/provider-wire-fingerprint.ts

@@ -0,0 +1,238 @@
+import crypto from "node:crypto";
+
+type JsonRecord = Record<string, unknown>;
+type BoundReason = "instructions-unavailable" | "instructions-too-large" | "tools-invalid" | "tools-too-large"
+  | "input-invalid" | "input-too-large" | "deferred-tools-invalid" | "deferred-tools-too-large"
+  | "surface-too-deep" | "surface-too-large" | "surface-not-json" | "surface-cyclic";
+
+const MAX_INSTRUCTIONS_CHARS = 1_000_000;
+const MAX_TOOLS = 512;
+const MAX_INPUT_ITEMS = 4_096;
+const MAX_SURFACE_DEPTH = 32;
+const MAX_SURFACE_NODES = 50_000;
+const MAX_SURFACE_STRING_CHARS = 2_000_000;
+const MAX_CONTAINER_ITEMS = 4_096;
+const PUBLIC_ID = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const CONTROL_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+export type ProviderWireFingerprint = {
+  applicable: boolean;
+  state: "known" | "unavailable";
+  reasonCode: BoundReason | "not-applicable" | null;
+  modelId: string | null;
+  instructionsHash: string | null;
+  baseInstructionsHash: string | null;
+  instructionNormalization: "host-relocation-v1" | "none" | null;
+  instructionChars: number | null;
+  orderedToolSurfaceHash: string | null;
+  toolCount: number | null;
+  deferredToolSurfaceHash: string | null;
+  deferredToolCount: number | null;
+  deferredToolBatchCount: number | null;
+  reasoningEffort: string | null;
+  textVerbosity: string | null;
+  toolChoiceKind: string | null;
+  toolChoiceHash: string | null;
+  requestPrefixFingerprint: string | null;
+};
+
+class SurfaceBoundError extends Error {
+  readonly reasonCode: BoundReason;
+  constructor(reasonCode: BoundReason) { super(reasonCode); this.reasonCode = reasonCode; }
+}
+
+function record(value: unknown): JsonRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as JsonRecord : null;
+}
+
+function hash(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function control(value: unknown): string | null {
+  return typeof value === "string" && CONTROL_VALUE.test(value) ? value : null;
+}
+
+function canonicalJson(value: unknown): string {
+  const budget = { nodes: 0, stringChars: 0, active: new WeakSet<object>() };
+  const visit = (item: unknown, depth: number, inArray: boolean): unknown => {
+    budget.nodes += 1;
+    if (budget.nodes > MAX_SURFACE_NODES) throw new SurfaceBoundError("surface-too-large");
+    if (depth > MAX_SURFACE_DEPTH) throw new SurfaceBoundError("surface-too-deep");
+    if (item === null || typeof item === "boolean") return item;
+    if (typeof item === "string") {
+      budget.stringChars += item.length;
+      if (budget.stringChars > MAX_SURFACE_STRING_CHARS) throw new SurfaceBoundError("surface-too-large");
+      return item;
+    }
+    if (typeof item === "number") return Number.isFinite(item) ? item : null;
+    if (["undefined", "function", "symbol"].includes(typeof item)) return inArray ? null : undefined;
+    if (typeof item === "bigint" || typeof item !== "object") throw new SurfaceBoundError("surface-not-json");
+    if (budget.active.has(item)) throw new SurfaceBoundError("surface-cyclic");
+    budget.active.add(item);
+    try {
+      if (Array.isArray(item)) {
+        if (item.length > MAX_CONTAINER_ITEMS) throw new SurfaceBoundError("surface-too-large");
+        return item.map((entry) => visit(entry, depth + 1, true));
+      }
+      const entries = Object.entries(item as JsonRecord)
+        .filter(([, entry]) => !["undefined", "function", "symbol"].includes(typeof entry));
+      if (entries.length > MAX_CONTAINER_ITEMS) throw new SurfaceBoundError("surface-too-large");
+      entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+      const output: JsonRecord = {};
+      for (const [key, entry] of entries) {
+        budget.stringChars += key.length;
+        if (budget.stringChars > MAX_SURFACE_STRING_CHARS) throw new SurfaceBoundError("surface-too-large");
+        output[key] = visit(entry, depth + 1, false);
+      }
+      return output;
+    } finally {
+      budget.active.delete(item);
+    }
+  };
+  return JSON.stringify(visit(value, 0, false));
+}
+
+function unavailable(modelId: string, reasonCode: BoundReason): ProviderWireFingerprint {
+  return { applicable: true, state: "unavailable", reasonCode, modelId, instructionsHash: null,
+    baseInstructionsHash: null, instructionNormalization: null, instructionChars: null,
+    orderedToolSurfaceHash: null, toolCount: null, deferredToolSurfaceHash: null, deferredToolCount: null,
+    deferredToolBatchCount: null, reasoningEffort: null, textVerbosity: null, toolChoiceKind: null,
+    toolChoiceHash: null, requestPrefixFingerprint: null };
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function boundedHostPaths(value: unknown): string[] {
+  if (typeof value !== "string" || value.length === 0 || value.length > 32_768 || value.includes("\0")) return [];
+  if (/^[\\/]+$/.test(value) || /^[A-Za-z]:[\\/]?$/.test(value)) return [];
+  const native = value.replace(/[\\/]+$/, "");
+  const slash = native.replace(/\\/g, "/");
+  return [...new Set([native, slash].filter(Boolean))];
+}
+
+function normalizeSkillLocations(instructions: string, platformRoot: unknown): string {
+  const roots = boundedHostPaths(platformRoot);
+  if (roots.length === 0) return instructions;
+  const startTag = "<available_skills>";
+  const endTag = "</available_skills>";
+  let cursor = 0;
+  let output = "";
+  while (cursor < instructions.length) {
+    const start = instructions.indexOf(startTag, cursor);
+    if (start < 0) return output + instructions.slice(cursor);
+    const endStart = instructions.indexOf(endTag, start + startTag.length);
+    if (endStart < 0) return output + instructions.slice(cursor);
+    const end = endStart + endTag.length;
+    let section = instructions.slice(start, end);
+    for (const root of roots) {
+      const locationPrefix = `<location>${xmlEscape(root)}`;
+      section = section
+        .replaceAll(`${locationPrefix}/`, "<location>[PIAGENT_PLATFORM_ROOT]/")
+        .replaceAll(`${locationPrefix}\\`, "<location>[PIAGENT_PLATFORM_ROOT]/")
+        .replaceAll(`${locationPrefix}</location>`, "<location>[PIAGENT_PLATFORM_ROOT]</location>");
+    }
+    output += instructions.slice(cursor, start) + section;
+    cursor = end;
+  }
+  return output;
+}
+
+function normalizeHostOwnedRelocation(instructions: string, workingDirectory: unknown, platformRoot: unknown): {
+  value: string;
+  mode: "host-relocation-v1" | "none";
+} {
+  const cwdVariants = boundedHostPaths(workingDirectory);
+  let value = normalizeSkillLocations(instructions, platformRoot);
+  for (const cwd of cwdVariants) {
+    const cwdLine = `Current working directory: ${cwd}`;
+    if (value.endsWith(cwdLine)) {
+      value = `${value.slice(0, -cwdLine.length)}Current working directory: [PIAGENT_PROJECT_ROOT]`;
+    }
+    value = value
+      .replaceAll(`<project_instructions path="${cwd}">`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]">')
+      .replaceAll(`<project_instructions path="${cwd}/`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]/')
+      .replaceAll(`<project_instructions path="${cwd}\\`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]/');
+  }
+  return value === instructions
+    ? { value, mode: "none" }
+    : { value, mode: "host-relocation-v1" };
+}
+
+export function buildOpenAiCodexWireFingerprint(input: {
+  payload: unknown;
+  provider: unknown;
+  modelId: unknown;
+  workingDirectory?: unknown;
+  platformRoot?: unknown;
+}): ProviderWireFingerprint {
+  const payload = record(input.payload);
+  const provider = typeof input.provider === "string" ? input.provider : "";
+  const modelId = typeof input.modelId === "string" && PUBLIC_ID.test(input.modelId) ? input.modelId : "";
+  if (provider !== "openai-codex" || !payload || !modelId || payload.model !== modelId) {
+    return { ...unavailable("", "surface-not-json"), applicable: false, state: "unavailable",
+      reasonCode: "not-applicable", modelId: null };
+  }
+  if (typeof payload.instructions !== "string") return unavailable(modelId, "instructions-unavailable");
+  if (payload.instructions.length > MAX_INSTRUCTIONS_CHARS) return unavailable(modelId, "instructions-too-large");
+  const tools = payload.tools === undefined ? [] : payload.tools;
+  if (!Array.isArray(tools)) return unavailable(modelId, "tools-invalid");
+  if (tools.length > MAX_TOOLS) return unavailable(modelId, "tools-too-large");
+  const requestInput = payload.input === undefined ? [] : payload.input;
+  if (!Array.isArray(requestInput)) return unavailable(modelId, "input-invalid");
+  if (requestInput.length > MAX_INPUT_ITEMS) return unavailable(modelId, "input-too-large");
+
+  const deferredBatches: Array<{ inputIndex: number; tools: unknown[] }> = [];
+  let deferredToolCount = 0;
+  for (let index = 0; index < requestInput.length; index += 1) {
+    const item = record(requestInput[index]);
+    if (item?.type !== "tool_search_output") continue;
+    if (!Array.isArray(item.tools)) return unavailable(modelId, "deferred-tools-invalid");
+    deferredToolCount += item.tools.length;
+    if (deferredToolCount > MAX_TOOLS) return unavailable(modelId, "deferred-tools-too-large");
+    deferredBatches.push({ inputIndex: index, tools: item.tools });
+  }
+
+  try {
+    const instructionsHash = hash(payload.instructions);
+    const normalizedInstructions = normalizeHostOwnedRelocation(payload.instructions, input.workingDirectory, input.platformRoot);
+    const baseInstructionsHash = hash(normalizedInstructions.value);
+    // Object keys are canonicalized because their order is semantic noise;
+    // arrays are preserved so changing provider-visible tool order is detected.
+    const orderedToolSurfaceHash = hash(canonicalJson(tools));
+    const deferredToolSurfaceHash = hash(canonicalJson(deferredBatches));
+    const toolChoice = payload.tool_choice ?? null;
+    const toolChoiceHash = hash(canonicalJson(toolChoice));
+    const reasoningEffort = control(record(payload.reasoning)?.effort);
+    const textVerbosity = control(record(payload.text)?.verbosity);
+    const toolChoiceKind = typeof toolChoice === "string" ? control(toolChoice) : record(toolChoice) ? "structured" : "none";
+    const requestPrefixFingerprint = hash(JSON.stringify({
+      schemaVersion: 1,
+      modelId,
+      instructionsHash,
+      baseInstructionsHash,
+      orderedToolSurfaceHash,
+      toolCount: tools.length,
+      deferredToolSurfaceHash,
+      deferredToolCount,
+      deferredToolBatchCount: deferredBatches.length,
+      reasoningEffort,
+      textVerbosity,
+      toolChoiceHash
+    }));
+    return { applicable: true, state: "known", reasonCode: null, modelId, instructionsHash,
+      baseInstructionsHash, instructionNormalization: normalizedInstructions.mode,
+      instructionChars: payload.instructions.length, orderedToolSurfaceHash, toolCount: tools.length,
+      deferredToolSurfaceHash, deferredToolCount, deferredToolBatchCount: deferredBatches.length,
+      reasoningEffort, textVerbosity, toolChoiceKind, toolChoiceHash, requestPrefixFingerprint };
+  } catch (error) {
+    return unavailable(modelId, error instanceof SurfaceBoundError ? error.reasonCode : "surface-not-json");
+  }
+}

package/packages/piagent-core/runtime/orchestration/helper-lifecycle.ts

@@ -5,18 +5,19 @@ import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
 import type { SolverDecision, TaskFeatures } from "../solver/solver-types.ts";
 import { bindRole, type RoleBinding } from "./role-binder.ts";
 import { AUTOMATIC_OWNED_WORK_CEILINGS, OwnedWorkBudgetController } from "./owned-work-budget.ts";
+import { assessMinimalDelegation, type MinimalDelegationEvidence } from "./minimal-delegation-policy.ts";
 import { createHelperRequest, defaultRolePolicy, type HelperRequest, type HelperRole } from "./role-policy.ts";
 
 export const HELPERS_MODE_VALUES = Object.freeze(["off", "recommend", "on"] as const);
 export type HelpersMode = typeof HELPERS_MODE_VALUES[number];
-export type HelperDecision = { mode: HelpersMode; action: "solo" | "recommend" | "dispatch" | "unavailable" | "blocked"; role: HelperRole | null; reasonCodes: string[]; binding: RoleBinding | null; request: HelperRequest | null };
+export type HelperDecision = { mode: HelpersMode; action: "solo" | "recommend" | "dispatch" | "unavailable" | "blocked"; role: HelperRole | null; reasonCodes: string[]; projectedSavingsRatio: number | null; binding: RoleBinding | null; request: HelperRequest | null };
 export type HelperDispatchResult = { status: "succeeded" | "failed" | "timeout" | "cancelled"; calls: number; tokens: number; output: string; summary?: string };
-export type HelperUsageReceipt = { role: HelperRole; disposition: string; reasonCodes: string[]; requestRef: string; outputDigest: string | null; summary: string | null; mergeOwner: "parent" | null; calls: number; tokens: number; helperUsed: boolean };
+export type HelperUsageReceipt = { role: HelperRole; disposition: string; decision: "dispatch" | "skip"; reasonCodes: string[]; projectedSavingsRatio: number | null; requestRef: string; outputDigest: string | null; summary: string | null; mergeOwner: "parent" | null; calls: number; tokens: number; helperUsed: boolean };
 type DispatchAdapter = (request: HelperRequest, signal: AbortSignal) => Promise<HelperDispatchResult>;
 type DispatchOptions = { timeoutMs?: number };
 
 function digest(value: unknown): string { return crypto.createHash("sha256").update(String(value ?? "")).digest("hex"); }
-export function helpersMode(value = process.env.PIAGENT_HELPERS_MODE): HelpersMode { return HELPERS_MODE_VALUES.includes(value as HelpersMode) ? value as HelpersMode : "recommend"; }
+export function helpersMode(value = process.env.PIAGENT_HELPERS_MODE): HelpersMode { return HELPERS_MODE_VALUES.includes(value as HelpersMode) ? value as HelpersMode : "off"; }
 
 export function selectHelperRole(input: { features: TaskFeatures; solver: SolverDecision; confidence?: string; conflictingEvidence?: boolean; repeatedSourceFailure?: boolean; independentReviewUseful?: boolean }): { role: HelperRole | null; reasons: string[] } {
   if (input.features.riskLane === "tiny") return { role: null, reasons: ["tiny-task-solo"] };
@@ -31,20 +32,23 @@ export class HelperLifecycleRuntime {
   readonly #budgets: OwnedWorkBudgetController;
   readonly #active = new Map<string, Set<AbortController>>();
   constructor(budgets = new OwnedWorkBudgetController()) { this.#budgets = budgets; }
-  decide(input: { mode: HelpersMode; objective: string; taskId: string; taskRunId: string; sessionId: string; taskScope: string[]; parentAllowedTools: string[]; features: TaskFeatures; solver: SolverDecision; runtime: RuntimeModelSnapshot; catalog: AuthenticatedModelCatalog; confidence?: string; conflictingEvidence?: boolean; repeatedSourceFailure?: boolean; independentReviewUseful?: boolean }): HelperDecision {
-    if (input.mode === "off") return { mode: input.mode, action: "solo", role: null, reasonCodes: ["helpers-off"], binding: null, request: null };
-    const selection = selectHelperRole(input); if (!selection.role) return { mode: input.mode, action: "solo", role: null, reasonCodes: selection.reasons, binding: null, request: null };
+  decide(input: { mode: HelpersMode; objective: string; taskId: string; taskRunId: string; sessionId: string; taskScope: string[]; parentAllowedTools: string[]; features: TaskFeatures; solver: SolverDecision; runtime: RuntimeModelSnapshot; catalog: AuthenticatedModelCatalog; delegationEvidence?: MinimalDelegationEvidence; confidence?: string; conflictingEvidence?: boolean; repeatedSourceFailure?: boolean; independentReviewUseful?: boolean }): HelperDecision {
+    if (input.mode === "off") return { mode: input.mode, action: "solo", role: null, reasonCodes: ["helpers-off", "parent-direct-default"], projectedSavingsRatio: null, binding: null, request: null };
+    const selection = selectHelperRole(input); if (!selection.role) return { mode: input.mode, action: "solo", role: null, reasonCodes: selection.reasons, projectedSavingsRatio: null, binding: null, request: null };
+    const delegation = assessMinimalDelegation(input.delegationEvidence);
+    if (!delegation.eligible) return { mode: input.mode, action: "solo", role: null, reasonCodes: [...selection.reasons, ...delegation.reasonCodes], projectedSavingsRatio: delegation.projectedSavingsRatio, binding: null, request: null };
     const policy = defaultRolePolicy(selection.role, input.taskScope);
     const binding = bindRole({ policy, features: input.features, solver: input.solver, runtime: input.runtime, catalog: input.catalog, helperBudgetAvailable: true });
-    if (binding.disposition !== "recommended") return { mode: input.mode, action: "unavailable", role: selection.role, reasonCodes: [...selection.reasons, ...binding.reasonCodes], binding, request: null };
+    if (binding.disposition !== "recommended") return { mode: input.mode, action: "unavailable", role: selection.role, reasonCodes: [...selection.reasons, ...delegation.reasonCodes, ...binding.reasonCodes], projectedSavingsRatio: delegation.projectedSavingsRatio, binding, request: null };
     const request = createHelperRequest({ policy, objective: input.objective, taskId: input.taskId, taskRunId: input.taskRunId, sessionId: input.sessionId, parentReadScope: input.taskScope, parentWriteScope: input.taskScope, parentAllowedTools: input.parentAllowedTools, requestedReadScope: input.taskScope, requestedWriteScope: [], model: { provider: binding.provider as string, modelId: binding.modelId as string, effort: binding.effort as string, source: binding.mappingVersion }, singleWriterOwnership: null });
     const action = input.mode === "recommend" ? "recommend" : policy.authority === "read-only" ? "dispatch" : "blocked";
-    return { mode: input.mode, action, role: selection.role, reasonCodes: action === "blocked" ? [...selection.reasons, "automatic-worker-disabled"] : selection.reasons, binding, request };
+    const reasonCodes = [...selection.reasons, ...delegation.reasonCodes];
+    return { mode: input.mode, action, role: selection.role, reasonCodes: action === "blocked" ? [...reasonCodes, "automatic-worker-disabled"] : reasonCodes, projectedSavingsRatio: delegation.projectedSavingsRatio, binding, request };
   }
   async dispatch(cwd: string, decision: HelperDecision, adapter: DispatchAdapter, options: DispatchOptions = {}): Promise<HelperUsageReceipt> {
-    if (decision.action !== "dispatch" || !decision.request || !decision.role) return { role: decision.role ?? "scout", disposition: decision.action, reasonCodes: decision.reasonCodes, requestRef: "none", outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
+    if (decision.action !== "dispatch" || !decision.request || !decision.role) return { role: decision.role ?? "scout", disposition: decision.action, decision: "skip", reasonCodes: decision.reasonCodes, projectedSavingsRatio: decision.projectedSavingsRatio, requestRef: "none", outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
     const reservation = this.#budgets.reserve(cwd, decision.request, undefined, AUTOMATIC_OWNED_WORK_CEILINGS);
-    if (reservation.decision !== "reserved" || !reservation.reservationId) return { role: decision.role, disposition: reservation.reason, reasonCodes: [...decision.reasonCodes, reservation.reason], requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
+    if (reservation.decision !== "reserved" || !reservation.reservationId) return { role: decision.role, disposition: reservation.reason, decision: "skip", reasonCodes: [...decision.reasonCodes, reservation.reason], projectedSavingsRatio: decision.projectedSavingsRatio, requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls: 0, tokens: 0, helperUsed: false };
     const controller = new AbortController(), active = this.#active.get(decision.request.taskRunId) ?? new Set<AbortController>();
     active.add(controller); this.#active.set(decision.request.taskRunId, active);
     const ceilingMs = decision.request.ceilings.timeSeconds * 1000;
@@ -66,10 +70,10 @@ export class HelperLifecycleRuntime {
     const released = this.#budgets.release(cwd, decision.request, reservation.reservationId, terminal, { calls: result.calls, tokens: result.tokens, output: result.output });
     const calls = Math.min(Math.max(0, Number(result.calls) || 0), decision.request.ceilings.calls + 1);
     const tokens = Math.min(Math.max(0, Number(result.tokens) || 0), decision.request.contextBudget + 1);
-    if (!released.accepted) return { role: decision.role, disposition: released.status === "cancelled" ? "cancelled" : "stale-result", reasonCodes: [...decision.reasonCodes, released.reason], requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls, tokens, helperUsed: true };
+    if (!released.accepted) return { role: decision.role, disposition: released.status === "cancelled" ? "cancelled" : "stale-result", decision: "dispatch", reasonCodes: [...decision.reasonCodes, released.reason], projectedSavingsRatio: decision.projectedSavingsRatio, requestRef: decision.request.deduplicationKey, outputDigest: null, summary: null, mergeOwner: null, calls, tokens, helperUsed: true };
     const withinBudget = released.reason === "released", succeeded = result.status === "succeeded" && withinBudget;
     const summary = succeeded && typeof result.summary === "string" ? redactSensitiveText(result.summary).text.replace(/\s+/g, " ").trim().slice(0, 1000) || null : null;
-    return { role: decision.role, disposition: withinBudget ? result.status : "budget-exceeded", reasonCodes: withinBudget ? decision.reasonCodes : [...decision.reasonCodes, released.reason], requestRef: decision.request.deduplicationKey, outputDigest: succeeded && result.output ? digest(result.output) : null, summary, mergeOwner: summary ? "parent" : null, calls, tokens, helperUsed: true };
+    return { role: decision.role, disposition: withinBudget ? result.status : "budget-exceeded", decision: "dispatch", reasonCodes: withinBudget ? decision.reasonCodes : [...decision.reasonCodes, released.reason], projectedSavingsRatio: decision.projectedSavingsRatio, requestRef: decision.request.deduplicationKey, outputDigest: succeeded && result.output ? digest(result.output) : null, summary, mergeOwner: summary ? "parent" : null, calls, tokens, helperUsed: true };
   }
   cancelTask(cwd: string, decision: HelperDecision, now = new Date().toISOString()): number {
     if (!decision.request) return 0;

package/packages/piagent-core/runtime/orchestration/minimal-delegation-policy.ts

@@ -0,0 +1,71 @@
+export const MINIMAL_DELEGATION_POLICY_VERSION = "minimal-delegation-v1" as const;
+
+export const MINIMAL_DELEGATION_LIMITS = Object.freeze({
+  maxConcurrentHelpers: 1,
+  maxTotalHelpers: 1,
+  maxRetries: 0,
+  maxHelperCalls: 8,
+  maxTransferTokens: 2_048,
+  minimumProjectedSavingsRatio: 0.3
+});
+
+export type MinimalDelegationEvidence = {
+  source: "runtime-estimate";
+  independentWorkstreams: string[];
+  canRunWithoutParentOutput: boolean;
+  estimatedSoloTokens: number;
+  estimatedTotalTokensWithHelper: number;
+  transferTokens: number;
+  inheritedParentTokens: number;
+  retryOfDeterministicFailure: boolean;
+};
+
+export type MinimalDelegationAssessment = {
+  eligible: boolean;
+  projectedSavingsRatio: number | null;
+  reasonCodes: string[];
+};
+
+function boundedInteger(value: unknown, minimum: number, maximum: number): value is number {
+  return Number.isInteger(value) && Number(value) >= minimum && Number(value) <= maximum;
+}
+
+function validWorkstreams(value: unknown): value is string[] {
+  return Array.isArray(value)
+    && value.length >= 2
+    && value.length <= 8
+    && new Set(value).size === value.length
+    && value.every((item) => typeof item === "string" && /^[a-z0-9][a-z0-9:._/-]{0,127}$/i.test(item));
+}
+
+/**
+ * Helpers are an optimization, not a default reasoning layer. A helper is only
+ * eligible when the runtime can show two genuinely independent lanes, a fresh
+ * minimal handoff, and at least 30% projected token savings after merge cost.
+ * The estimate is advisory, while the one-helper ledger below is enforcing.
+ */
+export function assessMinimalDelegation(evidence?: MinimalDelegationEvidence): MinimalDelegationAssessment {
+  if (!evidence) return { eligible: false, projectedSavingsRatio: null, reasonCodes: ["delegation-evidence-missing", "parent-direct-default"] };
+
+  const reasons: string[] = [];
+  if (evidence.source !== "runtime-estimate") reasons.push("delegation-estimate-not-runtime-owned");
+  if (!validWorkstreams(evidence.independentWorkstreams)) reasons.push("independent-workstreams-not-proven");
+  if (evidence.canRunWithoutParentOutput !== true) reasons.push("helper-depends-on-parent-output");
+  if (!boundedInteger(evidence.estimatedSoloTokens, 1, 100_000_000)
+    || !boundedInteger(evidence.estimatedTotalTokensWithHelper, 1, 100_000_000)) reasons.push("delegation-token-estimate-invalid");
+  if (!boundedInteger(evidence.transferTokens, 0, MINIMAL_DELEGATION_LIMITS.maxTransferTokens)) reasons.push("helper-context-transfer-too-large");
+  if (evidence.inheritedParentTokens !== 0) reasons.push("parent-history-inheritance-forbidden");
+  if (evidence.retryOfDeterministicFailure !== false) reasons.push("deterministic-helper-retry-forbidden");
+
+  const projectedSavingsRatio = boundedInteger(evidence.estimatedSoloTokens, 1, 100_000_000)
+    && boundedInteger(evidence.estimatedTotalTokensWithHelper, 1, 100_000_000)
+    ? (evidence.estimatedSoloTokens - evidence.estimatedTotalTokensWithHelper) / evidence.estimatedSoloTokens
+    : null;
+  if (projectedSavingsRatio === null || projectedSavingsRatio < MINIMAL_DELEGATION_LIMITS.minimumProjectedSavingsRatio) {
+    reasons.push("projected-token-savings-below-30pct");
+  }
+
+  return reasons.length
+    ? { eligible: false, projectedSavingsRatio, reasonCodes: [...new Set(reasons), "parent-direct-default"] }
+    : { eligible: true, projectedSavingsRatio, reasonCodes: ["independent-workstreams-proven", "projected-token-savings-at-least-30pct", "isolated-minimal-context"] };
+}