@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/registration/context-commands.ts

@@ -1,7 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { stageContextDelivery } from "../context/context-delivery.ts";
+import { semanticCompactionCancelled } from "../session/system-prompt.ts";
+import { WORKFLOW_IDS, resolveWorkflowId, type WorkflowId } from "../workflows/webui-workflow.ts";
 
 type ExtensionContext = any;
+const WORKFLOW_USAGE = WORKFLOW_IDS.join("|");
+
+export function parsePreflightWorkflow(raw: string): WorkflowId {
+  const first = String(raw ?? "").trim().split(/\s+/)[0];
+  return resolveWorkflowId(first) ?? "task";
+}
 
 export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
@@ -225,17 +233,27 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
       `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
       `editRecovery: ${report.metrics.editRecoveryContextCount}/${report.metrics.editRecoveryFailures} failures returned context; ${report.metrics.editRecoverySuppressedFailures} suppressed; ${report.metrics.editRecoveryEstimatedTokens} estimated tokens; classification coverage ${formatPercent(report.metrics.editRecoveryFailureEvidenceCoverage)}`,
       `taskEfficiency: ${taskEfficiency ? `${taskEfficiency.solver.route}; verify=${taskEfficiency.verification.attempts}; outcome=${taskEfficiency.outcome.task}` : "no active task"}`,
+      ...(taskEfficiency ? [`taskUsage: ${taskEfficiency.usageAccounting.status}; observed SDK tokens=${formatCount(taskEfficiency.exactUsage.tokens)}; billed cost=unknown; requests=${taskEfficiency.usageAccounting.requests}`] : []),
       ...report.recommendations.map((recommendation) => `- ${recommendation}`)
     ].join("\n"), { ...report, taskEfficiency });
   }
 
-  function parsePreflightWorkflow(raw: string): string {
-    return raw.match(/\b(?:scout|be-to-fe|review|plan|platform-improve|task)\b/i)?.[0]?.toLowerCase() ?? "task";
-  }
-
   function compactCurrentSession(ctx: ExtensionContext): void {
     const sessionId = ctx.sessionManager.getSessionId();
     const instructions = semanticCompactionInstructions(ctx.cwd, sessionId);
+    if (semanticCompactionCancelled(instructions)) {
+      telemetry(ctx, {
+        event: "compaction_cancelled",
+        mode: "semantic",
+        reason: "lossless-task-truth-exceeds-carry-target",
+        hasTaskContract: Boolean(compactSessionTask(ctx.cwd, sessionId))
+      });
+      ctx.ui.notify("Piagent kept the current context because compacting it would lose required task details.", "warning");
+      emitRuntimeMessage(ctx, "piagent-context-compaction-cancelled", instructions, {
+        reason: "lossless-task-truth-exceeds-carry-target"
+      });
+      return;
+    }
     telemetry(ctx, {
       event: "compaction_requested",
       mode: "semantic",
@@ -314,8 +332,8 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
         "pack: /context pack <task or symbol>",
         "impact: /context impact [changed files]",
         "efficiency: /context efficiency",
-        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
-        "compact: /context compact [task|scout|be-to-fe]",
+        `preflight: /context preflight [${WORKFLOW_USAGE}]`,
+        `compact: /context compact [${WORKFLOW_USAGE}]`,
         "legacy: /piagent-context | /context-index | /task-preflight"
       ].join("\n"));
       return;
@@ -366,8 +384,8 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
         "pack: /context pack <task or symbol>",
         "impact: /context impact [changed files]",
         "efficiency: /context efficiency",
-        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
-        "compact: /context compact [task|scout|be-to-fe]",
+        `preflight: /context preflight [${WORKFLOW_USAGE}]`,
+        `compact: /context compact [${WORKFLOW_USAGE}]`,
         "legacy: /piagent-context | /context-index | /task-preflight"
       ].join("\n"));
       return;
@@ -428,10 +446,10 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
           content: [
             `mode: ${orchestration.defaultMode}`,
             `helpersMode: ${helpersMode()}`,
-            `subagents: bounded read-only scout/planning/review; max ${orchestration.maxConcurrentSubagents}`,
+            `helpers: max ${orchestration.maxConcurrentSubagents} fresh read-only total; requires >=30% projected net token saving`,
             `lenses: ${orchestration.defaultReviewLenses.join(", ")}`,
             `fieldGuide: ${orchestration.fieldGuide.enabled ? `${fieldGuidePath} (${fieldGuideExists ? "exists" : "missing"})` : "off"}`,
-            "writer: single writer by default; parallel writers need explicit approval + isolation"
+            "writer: parent only; helper workers and retries are disabled"
           ].join("\n"),
           display: true,
           details: {

package/packages/piagent-core/runtime/registration/knowledge-tools.ts

@@ -11,11 +11,11 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
   registerPiagentTool(pi, {
     name: "piagent_orchestration_policy",
     label: "Piagent Orchestration Policy",
-    description: "Return solo-first subagent, review lens, model-role, and Field Guide policy for the current project.",
-    promptSnippet: "Use this before planning medium/large tasks so orchestration stays single-agent-first and token-aware.",
+    description: "Return parent-direct helper limits, review lenses, model-role, and Field Guide policy for the current project.",
+    promptSnippet: "Use this before planning medium/large tasks so the parent stays direct and helper use remains a measured token optimization.",
     promptGuidelines: [
-      "Default to the parent agent plus bounded subagents only when they reduce context risk or improve review quality.",
-      "Use review lenses instead of spawning a broad swarm.",
+      "Default to the parent model working directly; review quality alone does not justify another model run.",
+      "Use at most one fresh read-only helper only with two independent lanes and at least 30% projected total token savings; never delegate implementation or retry a deterministic failure.",
       "Treat Field Guide memory as advisory and verify it against current repository files."
     ],
     parameters: Type.Object({
@@ -45,7 +45,9 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           path: fieldGuidePath,
           exists: fieldGuideExists
         },
-        stance: "single-agent-first; subagents are opt-in tools for bounded scout, planning, and review"
+        helperBudget: "1-readonly-total/0-retries/0-writers",
+        minimumProjectedNetSaving: 0.3,
+        stance: "parent-direct; one fresh read-only helper only when runtime-measured net token savings justify it"
       };
       const text = params.detail === "full"
         ? JSON.stringify(payload, null, 2)
@@ -53,6 +55,8 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           `mode: ${payload.defaultMode}`,
           `maxConcurrentSubagents: ${payload.maxConcurrentSubagents}`,
           `helpersMode: ${payload.helpersMode}`,
+          `helperBudget: ${payload.helperBudget}`,
+          `minimumProjectedNetSaving: ${Math.round(payload.minimumProjectedNetSaving * 100)}%`,
           `reviewLenses: ${payload.defaultReviewLenses.join(", ")}`,
           `fieldGuide: ${payload.fieldGuide.enabled ? `${payload.fieldGuide.path} (${payload.fieldGuide.exists ? "exists" : "missing"})` : "off"}`,
           `fieldGuidePolicy: ${payload.fieldGuide.writePolicy}, maxLines=${payload.fieldGuide.maxLines}`,

package/packages/piagent-core/runtime/registration/operator-catalogs.ts

@@ -1,3 +1,5 @@
+import { WORKFLOW_IDS, WORKFLOW_OPTIONS } from "../workflows/webui-workflow.ts";
+
 export const WORKFLOW_COMMAND_EXCLUSIONS = Object.freeze([
   "implement",
   "audit",
@@ -15,16 +17,9 @@ export const ONBOARDING_COMMAND_ACTIONS = Object.freeze([
   "help"
 ]);
 
-export const FRESH_COMMAND_ACTIONS = Object.freeze([
-  "task",
-  "scout",
-  "be-to-fe",
-  "help"
-]);
+export const FRESH_COMMAND_ACTIONS = Object.freeze([...WORKFLOW_IDS, "help"]);
 
 export const FRESH_COMMAND_HELP = Object.freeze([
   "namespace: /fresh",
-  "/fresh task <request>",
-  "/fresh scout <read-only request>",
-  "/fresh be-to-fe <BE spec/change + FE outcome>"
+  ...WORKFLOW_OPTIONS.map((option) => `/fresh ${option.id} ${option.argumentHint}`)
 ]);

package/packages/piagent-core/runtime/registration/operator-request-intake.ts

@@ -0,0 +1,49 @@
+import { OPERATOR_REQUEST_MAX_CHARS } from "../../extensions/task-state.js";
+
+type SessionContext = {
+  sessionManager: {
+    getBranch?: () => unknown;
+    getEntries?: () => unknown;
+  };
+};
+
+function userMessageText(message: unknown): string {
+  if (!message || typeof message !== "object" || (message as Record<string, unknown>).role !== "user") return "";
+  const content = (message as Record<string, unknown>).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  // The host stores the exact operator prose in the first text block. Later
+  // text blocks may contain extracted attachment bodies and must not be copied
+  // into private task truth as if the operator typed them.
+  const first = content.find((block) => block && typeof block === "object"
+    && (block as Record<string, unknown>).type === "text"
+    && typeof (block as Record<string, unknown>).text === "string") as Record<string, unknown> | undefined;
+  return typeof first?.text === "string" ? first.text : "";
+}
+
+export function latestOperatorRequest(ctx: SessionContext): string | undefined {
+  let entries: unknown[] = [];
+  try {
+    const branch = ctx.sessionManager.getBranch?.();
+    entries = Array.isArray(branch) ? branch : [];
+    if (entries.length === 0) {
+      const all = ctx.sessionManager.getEntries?.();
+      entries = Array.isArray(all) ? all : [];
+    }
+  } catch {
+    return undefined;
+  }
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index] as Record<string, any> | undefined;
+    if (entry?.type !== "message") continue;
+    const text = userMessageText(entry.message);
+    if (text.trim()) return text;
+  }
+  return undefined;
+}
+
+export function boundedOperatorRequest(value: unknown, redactText: (value: string) => string): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const redacted = redactText(value);
+  return Array.from(redacted).length <= OPERATOR_REQUEST_MAX_CHARS ? redacted : undefined;
+}

package/packages/piagent-core/runtime/registration/policy-tools.ts

@@ -1,11 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { stageContextDelivery } from "../context/context-delivery.ts";
 import { formatContextEfficiencyReport } from "../context/context-efficiency-format.ts";
+import { WORKFLOW_IDS } from "../workflows/webui-workflow.ts";
+import { registerSessionWaitTool } from "./session-wait-tool.ts";
 
 type PiagentToolGroup = any;
 type TechStackManifest = any;
 
-
 export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
     PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups, activeSessionTask,
@@ -20,6 +21,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
     resolvePermissionProfile, resolveRuntimePolicy, retrievalKey, runtimeState, searchContextIndexV2,
     techStackPath, telemetry, toolRegistryConfig, verifierCommandInstructions
   } = deps;
+  registerSessionWaitTool(pi, Type);
   registerPiagentTool(pi, {
     name: "piagent_tools",
     label: "Piagent Tool Loader",
@@ -30,7 +32,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       "When recovery is necessary, load only the smallest group that resolves the reported missing evidence."
     ],
     parameters: Type.Object({
-      groups: Type.Array(StringEnum(["intake", "governance", "task", "recovery", "policy", "retrieval", "knowledge", "onboarding", "usage"] as const), { minItems: 1 })
+      groups: Type.Array(StringEnum(["intake", "governance", "task", "waiting", "recovery", "policy", "retrieval", "source", "knowledge", "onboarding", "usage"] as const), { minItems: 1 })
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const groups = [...new Set(params.groups)] as PiagentToolGroup[];
@@ -429,8 +431,8 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
   registerPiagentTool(pi, {
     name: "piagent_task_gate_check",
     label: "Piagent Task Gate Check",
-    description: "Check whether a governed task has enough context, verify evidence, and trace before claiming done.",
-    promptSnippet: "Use this before final on source-changing tasks.",
+    description: "Check whether a governed task has enough context, current-tree exact verifier evidence, and trace before claiming done or rerunning verification.",
+    promptSnippet: "Use before final and before repeating an exact verifier; run only commands listed as missing for the current tree.",
     parameters: Type.Object({
       taskId: Type.String({ minLength: 1 }),
       changedFiles: Type.Optional(Type.Array(Type.String()))
@@ -451,7 +453,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
         ...verifierCommandInstructions(result.missingVerifyCommands),
         `warnings: ${result.warnings.join("; ") || "none"}`
       ].join("\n");
-      return { content: [{ type: "text", text }], details: { ...result, task: projected } };
+      return { content: [{ type: "text", text }], details: { ...result, task: projected ? { taskId: projected.taskId, taskRunId: projected.taskRunId } : undefined } };
     }
   });
 
@@ -481,7 +483,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       "Do not paste mandatory-flow boilerplate into the task request; use platform workflow commands instead."
     ],
     parameters: Type.Object({
-      workflow: Type.Optional(StringEnum(["task", "scout", "be-to-fe", "review", "plan", "platform-improve"] as const)),
+      workflow: Type.Optional(StringEnum(WORKFLOW_IDS)),
       inputChars: Type.Optional(Type.Number({ minimum: 0 }))
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/packages/piagent-core/runtime/registration/session-commands.ts

@@ -1,7 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WORKFLOW_IDS, resolveWorkflowId } from "../workflows/webui-workflow.ts";
 
 type ExtensionContext = any;
 type TaskContract = any;
+const WORKFLOW_USAGE = WORKFLOW_IDS.join("|");
 
 export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
@@ -89,8 +91,8 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         "namespace: /usage",
         "live: /usage live",
         "history: /usage history",
-        "preflight: /usage preflight [task|scout|be-to-fe]",
-        "compact: /usage compact [task|scout|be-to-fe]",
+        `preflight: /usage preflight [${WORKFLOW_USAGE}]`,
+        `compact: /usage compact [${WORKFLOW_USAGE}]`,
         "logs: /usage logs",
         "efficiency: /usage efficiency",
         "native exact session: /session",
@@ -186,8 +188,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         { value: "current", label: "Current session", description: "Name, id, file, model", recommended: true },
         { value: "name", label: "Set name", description: "Use Pi native /name <task name>" },
         { value: "resume", label: "Resume help", description: "Commands for continuing old sessions" },
-        { value: "fresh-task", label: "Fresh task", description: "Use /fresh task <request>" },
-        { value: "fresh-scout", label: "Fresh scout", description: "Use /fresh scout <request>" },
+        { value: "fresh", label: "Fresh workflow", description: "Use /fresh <workflow> <request>" },
         { value: "usage", label: "Usage", description: "Current context/session usage" },
         { value: "help", label: "Help", description: "Show typed forms" }
       ], "current");
@@ -207,7 +208,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         "session helpers:",
         "current: /usage live or Pi native /session",
         "name: Pi native /name <task/session name>",
-        "fresh: /fresh task|scout|be-to-fe <request>",
+        `fresh: /fresh ${WORKFLOW_USAGE} <request>`,
         "resume: Pi native /resume or /session",
         "legacy: /piagent-session | /setname | /fresh-task | /fresh-scout | /fresh-be-to-fe"
       ].join("\n"));
@@ -231,8 +232,9 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
     }
     if (["fresh", "new"].includes(action)) {
       const next = commandArgs(rest);
-      const workflow = next.action === "be-to-fe" ? "be-to-fe" : next.action === "scout" ? "scout" : "task";
-      await startFreshWorkflow(workflow, next.rest, ctx);
+      const workflow = resolveWorkflowId(next.action);
+      const request = workflow ? next.rest : [next.action, next.rest].filter(Boolean).join(" ");
+      await startFreshWorkflow(workflow ?? "task", request, ctx);
       return;
     }
     if (["fresh-task", "task"].includes(action)) {
@@ -334,7 +336,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
       const approvals = feature ? [feature.externalAction ? "external-action" : "", feature.destructiveAction ? "destructive-action" : "", feature.permissionExpansion ? "permission-expansion" : ""].filter(Boolean) : [];
       const modelRoute = feature ? await evaluateModelRoute?.(ctx, feature, snapshot) : undefined;
       const retrievalRoute = feature ? await evaluateRetrievalRoute?.(ctx, feature) : undefined;
-      return { runtime: snapshot, modelRoute: modelRoute?.status === "ok" ? modelRoute.decision : null, retrievalRoute: retrievalRoute ?? null, scope: task?.scope ?? [], protectedPaths: effectiveProtectedPaths(policy, profile).readProtectedPaths, activeToolGroups: pi.getActiveTools(), helperMode: helpersMode(), helperBudget: "2-concurrent/3-total", executionBackend: "host", executionBoundary: "host execution is not a sandbox", approvals, blockers: feature?.protectedTarget ? ["protected-target"] : [], controlMode: evaluation.status === "ok" && evaluation.decision.mode === "shadow" ? "shadow" : resolveRuntimePolicy(profile).finalGate === "enforce" ? "enforce" : "assist" };
+      return { runtime: snapshot, modelRoute: modelRoute?.status === "ok" ? modelRoute.decision : null, retrievalRoute: retrievalRoute ?? null, scope: task?.scope ?? [], protectedPaths: effectiveProtectedPaths(policy, profile).readProtectedPaths, activeToolGroups: pi.getActiveTools(), helperMode: helpersMode(), helperBudget: "1-readonly-total/0-retries/0-writers", executionBackend: "host", executionBoundary: "host execution is not a sandbox", approvals, blockers: feature?.protectedTarget ? ["protected-target"] : [], controlMode: evaluation.status === "ok" && evaluation.decision.mode === "shadow" ? "shadow" : resolveRuntimePolicy(profile).finalGate === "enforce" ? "enforce" : "assist" };
     }
   });
 

package/packages/piagent-core/runtime/registration/session-wait-tool.ts

@@ -0,0 +1,54 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerPiagentTool } from "./extension-registration.ts";
+import { MAX_SESSION_WAIT_SECONDS, SESSION_WAIT_ENTRY, SessionWaitRuntime } from "../tools/session-wait.ts";
+
+/** Reuse the host session journal; pending waits never schedule work on resume. */
+export function registerSessionWaitTool(pi: ExtensionAPI, Type: any): void {
+  const waits = new SessionWaitRuntime();
+  const key = (ctx: ExtensionContext) => `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  for (const event of ["session_before_switch", "session_before_fork", "session_before_tree", "session_shutdown"] as const) {
+    pi.on(event, async (_event: unknown, ctx: ExtensionContext) => { waits.interrupt(key(ctx)); });
+  }
+  registerPiagentTool(pi, {
+    name: "piagent_wait",
+    label: "Wait until the next check",
+    description: "Wait 1–3600 seconds within this open session without polling or calling a model. Use when the next useful check is later. No background scheduling, condition monitoring, command execution, or completion evidence. Cancel to interrupt.",
+    promptSnippet: "For a future check, wait once until it is useful; avoid repeated unchanged status checks.",
+    promptGuidelines: [
+      "Use a process/event wait tool when it can wake on completion; otherwise choose the next useful check time within the task deadline. Call this tool alone so cancellation can stop its batch.",
+      "Do independent work first. Keep the next check explicit; waiting never completes a task or proves an external action succeeded.",
+      "This requires an open running session. After interruption or restart, reconcile pending work before deciding to wait again; never replay uncertain external actions."
+    ],
+    parameters: Type.Object({
+      seconds: Type.Number({ minimum: 1, maximum: MAX_SESSION_WAIT_SECONDS, multipleOf: 1 }),
+      nextCheck: Type.String({ minLength: 1, maxLength: 240, description: "The specific observation to make when the wait ends, not a command to execute automatically." })
+    }),
+    async execute(toolCallId: string, params: { seconds: number; nextCheck: string }, signal: AbortSignal | undefined,
+      _onUpdate: unknown, ctx: ExtensionContext) {
+      if (!Number.isInteger(params.seconds) || params.seconds < 1 || params.seconds > MAX_SESSION_WAIT_SECONDS
+        || typeof params.nextCheck !== "string" || !params.nextCheck.trim() || params.nextCheck.length > 240) {
+        throw new Error("Use a bounded wait of 1–3600 seconds and a nonempty next check of at most 240 characters.");
+      }
+      const sessionId = ctx.sessionManager.getSessionId();
+      const prior = ctx.sessionManager.getBranch().some((entry: any) => entry.type === "custom"
+        && entry.customType === SESSION_WAIT_ENTRY && entry.data?.toolCallId === toolCallId);
+      if (prior) throw new Error("This wait call is already journaled. Reconcile its result; do not replay it after resume.");
+      if (signal?.aborted) throw new Error("Wait interrupted before starting; no follow-up was scheduled.");
+      const startedAt = new Date().toISOString();
+      const identity = { toolCallId, sessionId, startedAt, seconds: params.seconds };
+      pi.appendEntry(SESSION_WAIT_ENTRY, { ...identity, outcome: "pending" });
+      const result = await waits.wait(key(ctx), params.seconds, signal);
+      // Never append a receipt to a different session after a switch.
+      if (ctx.sessionManager.getSessionId() === sessionId) {
+        pi.appendEntry(SESSION_WAIT_ENTRY, { ...identity, ...result });
+      }
+      return {
+        terminate: result.outcome === "interrupted",
+        content: [{ type: "text", text: result.outcome === "elapsed"
+          ? `Wait elapsed. Next check: ${params.nextCheck}. No condition was checked; task completion and external outcomes remain unverified.`
+          : `Wait interrupted. Pending next check: ${params.nextCheck}. No follow-up was scheduled; reconcile current state before continuing.` }],
+        details: { ...identity, ...result, conditionChecked: false, followUpScheduled: false }
+      };
+    }
+  });
+}

package/packages/piagent-core/runtime/registration/task-completion-tools.ts

@@ -1,4 +1,8 @@
+import { retainFocusedVerification } from "../../extensions/acceptance-focused-verification.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { completionPreparationCurrent } from "../verification/completion-preparation.ts";
+import { apiBaselineCriterionEvidence as apiBaselineEvidence } from "../verification/acceptance-api-baseline.js";
+import { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 import { durableContextEvidenceEntries, isRuntimeOwnedContextEvidenceEntry } from "../../extensions/context-evidence.js";
 import { mergeObservedTaskContext } from "../../extensions/task-contract-view.js";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
@@ -9,6 +13,9 @@ import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
 
 type TaskContract = any;
 
+function taskErrorDetails(task: TaskContract, reasonCode: string): Record<string, unknown> {
+  return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt };
+}
 
 export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
@@ -17,7 +24,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
     compactTaskDetails, contextBudgetConfig, evaluateTaskGate, findMatchingObservedBashResult, loadProfileFromContext,
     normalizeRelative, nowIso, observedBashLedgerPath, policy, readObservedBashResults,
     readTask, recordCompletionAudit, recordVerificationCheckpoint, redactForStorage, redactText, runtimeState,
-    refreshAcceptanceReceipt, registerPiagentTool, resolveRuntimePolicy, runtimeLifecycleMode, semanticRepairCompletionBlock, taskChangedFileEvidence,
+    refreshAcceptanceReceipt, registerPiagentTool, resolveRuntimePolicy, runtimeLifecycleMode, semanticRepairCompletionBlock, taskAcceptanceEvidenceFiles, taskChangedFileEvidence,
     uniqueStrings, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, writeTask
   } = deps;
   registerPiagentTool(pi, {
@@ -41,7 +48,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; context evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; context evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       const activeIdentity = runtimeState.taskIdentity(ctx);
       if (!activeIdentity || activeIdentity.taskId !== task.taskId || activeIdentity.taskRunId !== task.taskRunId) {
@@ -127,7 +134,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; verify evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; verify evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
 
       const observedEntries = [
@@ -171,16 +178,19 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           matchedProfileCommand,
           workingTreeDigest
         });
-        task.verifyEvidence = task.verifyEvidence.slice(-100);
+        task.verifyEvidence = policy?.finalGate?.acceptanceProofMode === "diagnostic"
+          ? retainFocusedVerification(task.verifyEvidence, workingTreeDigest, currentWorkspaceRevisionDigest(ctx.cwd))
+          : task.verifyEvidence.slice(-100);
       }
-      const hasChanges = taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected.length > 0;
-      const allPassing = matchedProfileCommand && hasChanges && allVerifyCommandsPassCurrentTree(task, workingTreeDigest);
-      if (matchedProfileCommand && hasChanges) {
+      const taskLocalDelta = taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected;
+      const verificationCanSettleSourceTask = taskLocalDelta.length > 0 || task.mutationPolicy === "allowed";
+      const allPassing = matchedProfileCommand && verificationCanSettleSourceTask && allVerifyCommandsPassCurrentTree(task, workingTreeDigest, currentWorkspaceRevisionDigest(ctx.cwd));
+      if (matchedProfileCommand && verificationCanSettleSourceTask) {
         applyRuntimeLifecycleObservation(task, allPassing ? "verification-complete" : "verification-pending", nowIso());
       }
       const acceptance = refreshAcceptanceReceipt(task, {
-        cwd: ctx.cwd,
-        changedFiles: taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected,
+        cwd: ctx.cwd, apiBaselineEvidence,
+        changedFiles: taskAcceptanceEvidenceFiles(ctx.cwd, task, currentDigests, taskLocalDelta),
         currentWorkingTreeDigest: workingTreeDigest
       });
       task.acceptanceReceipt = acceptance.task.acceptanceReceipt;
@@ -239,7 +249,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; memory evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; memory evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
 
       const safeFiles = params.files.map((file) => ({
@@ -257,7 +267,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
 
       return {
         content: [{ type: "text", text: `Memory citations recorded for ${task.taskId}: ${params.files.length} file(s)` }],
-        details: task
+        details: compactTaskDetails(task)
       };
     }
   });
@@ -284,13 +294,13 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; its final trace was not replaced.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; its final trace was not replaced.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       if (params.outcome !== "completed" && !params.friction?.trim() && !task.failureReason?.trim()) {
-        return { content: [{ type: "text", text: `Trace ${params.outcome} requires a concrete friction/reason so the next attempt does not repeat the same work.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Trace ${params.outcome} requires a concrete friction/reason so the next attempt does not repeat the same work.` }], details: taskErrorDetails(task, "trace-friction-required"), isError: true };
       }
       if (params.outcome === "failed" && !params.failedAt && !task.failedAt) {
-        return { content: [{ type: "text", text: "A failed trace requires failedAt to identify the lifecycle phase." }], details: task, isError: true };
+        return { content: [{ type: "text", text: "A failed trace requires failedAt to identify the lifecycle phase." }], details: taskErrorDetails(task, "trace-failure-phase-required"), isError: true };
       }
 
       const rawChangedFiles = params.changedFiles ?? task.changedFiles;
@@ -301,6 +311,9 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           isError: true
         };
       }
+      if (params.outcome === "completed" && !completionPreparationCurrent(await deps.prepareIndependentAcceptance?.(ctx, task))) {
+        return { content: [{ type: "text", text: "Trace refused: independent verification stopped with the session." }], isError: true };
+      }
       const finalFileDigests = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
       let nextTask: TaskContract = {
         ...task,
@@ -318,8 +331,8 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         }
       };
       nextTask = refreshAcceptanceReceipt(nextTask, {
-        cwd: ctx.cwd,
-        changedFiles: nextTask.changedFiles,
+        cwd: ctx.cwd, apiBaselineEvidence,
+        changedFiles: taskAcceptanceEvidenceFiles(ctx.cwd, nextTask, finalFileDigests, nextTask.changedFiles),
         currentWorkingTreeDigest: workingTreeEvidenceDigest(finalFileDigests)
       }).task as TaskContract;
       let gate = evaluateTaskGate(ctx.cwd, nextTask, policy, {
@@ -331,7 +344,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         ? semanticRepairCompletionBlock?.(ctx.cwd, nextTask.taskRunId)
         : undefined;
       if (semanticBlock) gate = { ...gate, decision: "fail", missing: [...new Set([...gate.missing, semanticBlock])] };
-      if (params.outcome === "completed" && (semanticBlock || (runtime.finalGate === "enforce" && gate.decision === "fail"))) {
+      if (params.outcome === "completed" && (semanticBlock || ((runtime.finalGate === "enforce" || gate.acceptanceProof?.mode === "diagnostic") && gate.decision === "fail"))) {
         const blockedTrace = {
           taskId: nextTask.taskId,
           taskRunId: nextTask.taskRunId,
@@ -363,11 +376,15 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
               ...verifierCommandInstructions(gate.missingVerifyCommands)
             ].join("\n")
           }],
-          details: { gate, task: nextTask },
+          details: { gate, task: taskErrorDetails(nextTask, "completion-gate-blocked") },
           isError: true
         };
       }
 
+      if (gate.acceptanceProof?.mode === "diagnostic" && gate.acceptanceProof.pendingCriterionIds.length > 0) {
+        nextTask.trace.notes = [nextTask.trace.notes,
+          `Diagnostic acceptance: ${gate.acceptanceProof.pendingCriterionIds.length} criteria remain unproved; no quality claim.`].filter(Boolean).join("\n");
+      }
       let handoffPreview: any;
       try {
         handoffPreview = buildHandoffProjection(ctx.cwd, nextTask, {
@@ -395,6 +412,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         taskRunId: nextTask.taskRunId,
         sessionId: nextTask.sessionId,
         event: "trace_record",
+        ...(gate.acceptanceProof?.mode === "diagnostic" ? { acceptanceProof: gate.acceptanceProof } : {}),
         outcome: params.outcome,
         changedFiles: nextTask.changedFiles,
         friction: nextTask.trace.friction,
@@ -409,6 +427,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         phase: params.failedAt ?? "review",
         evidence: {
           outcome: params.outcome,
+          ...(gate.acceptanceProof?.mode === "diagnostic" ? { acceptanceProof: gate.acceptanceProof } : {}),
           changedFiles: written.changedFiles,
           failedAt: written.failedAt,
           ruledOut: written.ruledOut
@@ -425,8 +444,8 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
       }
 
       return {
-        content: [{ type: "text", text: `Trace recorded for ${nextTask.taskId}: ${params.outcome}${gate.decision === "fail" ? ` (gate warning: missing ${gate.missing.join(", ")})` : ""}` }],
-        details: { task: written, gate, completionReceipt: buildCompletionReceiptView(written, { cwd: ctx.cwd, gate }) }
+        content: [{ type: "text", text: `Trace recorded for ${nextTask.taskId}: ${params.outcome}${gate.acceptanceProof?.mode === "diagnostic" && gate.acceptanceProof.pendingCriterionIds.length > 0 ? " (diagnostic acceptance; no quality claim)" : ""}${gate.decision === "fail" ? ` (gate warning: missing ${gate.missing.join(", ")})` : ""}` }],
+        details: { task: compactTaskDetails(written), gate, completionReceipt: buildCompletionReceiptView(written, { cwd: ctx.cwd, gate }) }
       };
     }
   });