@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/extensions/task-state.js

@@ -1,7 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
 import { appendTaskJournalEvent, readTaskJournal } from "./task-journal.js";
 import {
@@ -28,12 +27,25 @@ import {
   unavailableWorkingTreeHash,
   versionWorkingTreeHash
 } from "./working-tree-digest.js";
+import {
+  directChildGitEvidenceRoots,
+  gitEvidenceRootDetails,
+  gitEvidenceRoots,
+  gitOutput,
+  isGitWorkingTree,
+  nonGitWorkspaceFileDetails,
+  nonGitWorkspaceFiles,
+  normalizedGitPath,
+  pathWithinNonGitWorkspaceEvidenceRoot,
+  prefixedGitPath
+} from "./workspace-evidence-roots.js";
+export { isGitWorkingTree } from "./workspace-evidence-roots.js";
 
 export const TASK_CONTRACT_SCHEMA_VERSION = 2; export const DEFAULT_MAX_TASK_ATTEMPTS = 3;
 const TASK_OUTCOMES = ["pending", "completed", "blocked", "partial", "failed"], TERMINAL_TASK_OUTCOMES = new Set(["completed", "blocked", "partial", "failed"]);
 const REVIEW_LENSES = ["correctness", "tests", "scope", "security", "docs", "release", "package"];
 const TASK_CONTRACT_FIELDS = new Set([
-  "schemaVersion", "taskRunId", "taskId", "sessionId", "sessionName", "changeMode", "attempt", "maxAttempts",
+  "schemaVersion", "taskRunId", "taskId", "sessionId", "sessionName", "changeMode", "mutationPolicy", "attempt", "maxAttempts",
   "previousAttempts", "summary", "riskLane", "intakeMode", "expectedOutput", "acceptanceCriteria", "criterionGraph", "scope", "outOfScope",
   "protectedPaths", "requiredContext", "contextManifest", "memoryCitations", "mcpCapabilities", "verifyGroup",
   "verifyCommands", "workPlan", "reviewLenses", "orchestration", "acceptanceReceipt", "authoritySnapshot", "workingTreeDigestAlgorithm", "workingTreeDigestMigration", "baselineChangedFiles", "baselineFileDigests",
@@ -47,14 +59,6 @@ const ORCHESTRATION_FIELDS = new Set(["mode", "subagents", "reason", "fieldGuide
 const MODEL_ROLE_FIELDS = new Set(["planner", "worker", "reviewer", "watchdog"]);
 const VERIFY_EVIDENCE_FIELDS = new Set(["command", "exitCode", "summary", "recordedAt", "observed", "observedAt", "isError", "matchedProfileCommand", "preWorkingTreeDigest", "workingTreeDigest"]);
 const TRACE_FIELDS = new Set(["outcome", "friction", "notes", "recordedAt"]);
-const WORKSPACE_EVIDENCE_MAX_FILES = 2000;
-const WORKSPACE_EVIDENCE_SKIP_NAMES = new Set([
-  ".git", ".hg", ".svn", ".pi", "node_modules", "dist", "build", ".next", "coverage"
-]);
-const WORKSPACE_EVIDENCE_PRIORITY_NAMES = new Map([
-  ["plans", 0]
-]);
-
 export function safeTaskId(value) {
   const normalized = String(value ?? "")
     .trim()
@@ -198,6 +202,8 @@ export function taskContractValidationErrors(input) {
   }
   if (input.failedAt !== undefined && !["research", "plan", "execute", "verify", "review"].includes(input.failedAt)) errors.push("failedAt is invalid");
   if (!["source-change", "read-only"].includes(input.changeMode)) errors.push("changeMode is invalid");
+  if (input.mutationPolicy !== undefined && !["required", "forbidden"].includes(input.mutationPolicy)) errors.push("mutationPolicy is invalid");
+  if (input.changeMode === "read-only" && input.mutationPolicy === "required") errors.push("read-only tasks cannot require mutation");
   if (!["tiny", "normal", "high-risk"].includes(input.riskLane)) errors.push("riskLane is invalid");
   if (input.intakeMode !== undefined && !["model", "runtime"].includes(input.intakeMode)) errors.push("intakeMode is invalid");
   errors.push(...taskDigestContractValidationErrors(input));
@@ -227,6 +233,7 @@ export function taskContractValidationErrors(input) {
   }
   if (Array.isArray(input.acceptanceCriteria) && input.acceptanceCriteria.length === 0) errors.push("acceptanceCriteria must not be empty");
   if (Array.isArray(input.scope) && input.scope.length === 0) errors.push("scope must not be empty");
+  if (Array.isArray(input.scope) && input.scope.length > 2000) errors.push("scope must contain at most 2000 entries");
   if (Array.isArray(input.previousAttempts) && input.previousAttempts.length > 10) errors.push("previousAttempts must contain at most 10 entries");
   if (Array.isArray(input.workPlan) && input.workPlan.length > 12) errors.push("workPlan must contain at most 12 entries");
   if (Array.isArray(input.reviewLenses)) {
@@ -390,6 +397,7 @@ export function normalizeTaskContract(input, options = {}) {
     sessionId,
     sessionName: String(input.sessionName ?? options.sessionName ?? "").trim() || undefined,
     changeMode: input.changeMode === "read-only" ? "read-only" : "source-change",
+    mutationPolicy: input.changeMode === "read-only" || input.mutationPolicy === "forbidden" ? "forbidden" : "required",
     attempt: positiveInteger(input.attempt, 1, 100),
     maxAttempts: positiveInteger(input.maxAttempts, DEFAULT_MAX_TASK_ATTEMPTS, 10),
     previousAttempts: Array.isArray(input.previousAttempts) ? input.previousAttempts.slice(-10).map((item) => pickFields(item, PREVIOUS_ATTEMPT_FIELDS)) : [],
@@ -576,13 +584,6 @@ export function summarizeAttempt(task) {
   };
 }
 
-function gitOutput(cwd, args, options = {}) {
-  return execFileSync("git", ["-C", cwd, ...args], {
-    encoding: options.encoding ?? "utf8",
-    maxBuffer: options.maxBuffer ?? 16 * 1024 * 1024,
-    stdio: ["ignore", "pipe", "ignore"]
-  });
-}
 function gitHasHead(cwd) {
   try {
     gitOutput(cwd, ["rev-parse", "--verify", "HEAD"]);
@@ -591,20 +592,6 @@ function gitHasHead(cwd) {
     return false;
   }
 }
-export function isGitWorkingTree(cwd) {
-  try {
-    return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
-  } catch {
-    return false;
-  }
-}
-function normalizedGitPath(value) {
-  return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
-}
-function prefixedGitPath(prefix, file) {
-  const normalized = normalizedGitPath(file);
-  return prefix ? `${prefix}/${normalized}` : normalized;
-}
 
 function workingTreeFilesForGitRoot(cwd, observeRename) {
   if (!isGitWorkingTree(cwd)) return [];
@@ -615,90 +602,8 @@ function workingTreeFilesForGitRoot(cwd, observeRename) {
   return [...new Set([...changed, ...untracked].map(normalizedGitPath).filter((item) => item && !item.startsWith(".pi/piagent-state/")))].sort();
 }
 
-function directChildGitEvidenceRoots(cwd) {
-  const roots = [];
-  let entries;
-  try {
-    entries = fs.readdirSync(cwd, { withFileTypes: true });
-  } catch {
-    return roots;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
-    const child = path.join(cwd, entry.name);
-    try {
-      if (fs.lstatSync(child).isSymbolicLink()) continue;
-      if (!isGitWorkingTree(child)) continue;
-      const topLevel = gitOutput(child, ["rev-parse", "--show-toplevel"]).trim();
-      if (fs.realpathSync(topLevel) !== fs.realpathSync(child)) continue;
-      roots.push({ cwd: child, prefix: normalizedGitPath(entry.name) });
-    } catch {
-      // Ignore unreadable or non-standard child folders; source-change start
-      // only needs at least one reliable evidence root.
-    }
-  }
-  return roots.sort((left, right) => left.prefix.localeCompare(right.prefix));
-}
-
-function gitEvidenceRoots(cwd) {
-  if (isGitWorkingTree(cwd)) return [{ cwd, prefix: "" }];
-  return directChildGitEvidenceRoots(cwd);
-}
-
-function nonGitWorkspaceFiles(cwd, gitRootPrefixes) {
-  const files = [];
-  const gitRoots = new Set(gitRootPrefixes.filter(Boolean));
-  function orderedEntries(entries) {
-    return [...entries].sort((left, right) => {
-      const leftPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(left.name.toLowerCase()) ?? 10;
-      const rightPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(right.name.toLowerCase()) ?? 10;
-      if (leftPriority !== rightPriority) return leftPriority - rightPriority;
-      return left.name.localeCompare(right.name, "en-US");
-    });
-  }
-  function visit(directory, relativeDirectory) {
-    if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) return;
-    let entries;
-    try {
-      entries = fs.readdirSync(directory, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of orderedEntries(entries)) {
-      if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) return;
-      if (WORKSPACE_EVIDENCE_SKIP_NAMES.has(entry.name)) continue;
-      const relative = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
-      const topSegment = relative.split("/")[0];
-      if (gitRoots.has(topSegment)) continue;
-      const absolute = path.join(directory, entry.name);
-      try {
-        if (fs.lstatSync(absolute).isSymbolicLink()) continue;
-      } catch {
-        continue;
-      }
-      if (entry.isDirectory()) {
-        visit(absolute, relative);
-      } else if (entry.isFile()) {
-        files.push(normalizedGitPath(relative));
-      }
-    }
-  }
-  visit(cwd, "");
-  return files.sort();
-}
-
 function nonGitWorkspaceFileDigest(cwd, file, protectedProjectPath = null) { return streamedWorkingTreeFileDigest(cwd, file, false, protectedProjectPath); }
 
-function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
-  const topSegment = candidate.split("/")[0];
-  return Boolean(
-    topSegment
-    && !WORKSPACE_EVIDENCE_SKIP_NAMES.has(topSegment)
-    && !topSegment.startsWith(".")
-    && !gitRootPrefixes.includes(topSegment)
-  );
-}
-
 export function hasGitEvidenceRoot(cwd) {
   return gitEvidenceRoots(cwd).length > 0;
 }
@@ -739,35 +644,36 @@ export function workingTreeFiles(cwd) {
     return [];
   }
 }
-
-export function repositoryFileManifest(cwd, maxFiles = 10_000) {
-  const limit = Number.isInteger(maxFiles) ? Math.max(1, Math.min(50_000, maxFiles)) : 10_000;
-  const files = [];
+export function repositoryFileManifestDetails(cwd, maxFiles = 10_000) {
+  const limit = Number.isInteger(maxFiles) ? Math.max(1, Math.min(50_000, maxFiles)) : 10_000, files = new Set();
   try {
-    for (const root of gitEvidenceRoots(cwd)) {
-      const listed = gitOutput(root.cwd, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"])
-        .split("\0")
-        .filter(Boolean);
+    const rootDetails = gitEvidenceRootDetails(cwd), roots = rootDetails.roots;
+    const add = (candidate) => {
+      if (!candidate || candidate.startsWith(".pi/") || candidate.startsWith(".git/") || candidate.split("/").includes("node_modules")
+        || /(?:^|\/)\.env(?:\.|$)/i.test(candidate) || /(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i.test(candidate)) return true;
+      files.add(candidate);
+      return files.size <= limit;
+    };
+    for (const root of roots) {
+      const listed = gitOutput(root.cwd, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
       for (const file of listed) {
         const candidate = prefixedGitPath(root.prefix, file);
-        if (
-          !candidate
-          || candidate.startsWith(".pi/")
-          || candidate.startsWith(".git/")
-          || candidate.split("/").includes("node_modules")
-          || /(?:^|\/)\.env(?:\.|$)/i.test(candidate)
-          || /(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i.test(candidate)
-        ) continue;
-        files.push(candidate);
-        if (files.length >= limit) return [...new Set(files)].sort();
+        if (!add(candidate)) return { files: [...files].slice(0, limit).sort(), complete: false, candidateCount: files.size };
       }
     }
+    if (!isGitWorkingTree(cwd) && roots.length > 0) {
+      const looseDetails = nonGitWorkspaceFileDetails(cwd, roots.map((root) => root.prefix));
+      const looseFiles = looseDetails.files;
+      for (const file of looseFiles) if (!add(file)) return { files: [...files].slice(0, limit).sort(), complete: false, candidateCount: files.size };
+      if (!looseDetails.complete) return { files: [...files].sort(), complete: false, candidateCount: files.size };
+    }
+    if (!rootDetails.complete) return { files: [...files].sort(), complete: false, candidateCount: files.size };
   } catch {
-    return [];
+    return { files: [], complete: false, candidateCount: 0 };
   }
-  return [...new Set(files)].sort();
+  return { files: [...files].sort(), complete: true, candidateCount: files.size };
 }
-
+export function repositoryFileManifest(cwd, maxFiles = 10_000) { return repositoryFileManifestDetails(cwd, maxFiles).files; }
 function changedPathsFromNameStatus(output, observeRename) {
   const fields = String(output ?? "").split("\0").filter(Boolean);
   const files = [];

package/packages/piagent-core/extensions/verification-intelligence.js

@@ -295,7 +295,9 @@ export function selectVerificationPlan(profile, requestedGroup, changeMode, cwd,
         const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
         const scripts = manifest.scripts && typeof manifest.scripts === "object" ? manifest.scripts : {};
         const selected = ["type-check", "typecheck", "lint", "test"].filter((name) => typeof scripts[name] === "string");
-        if (selected.length > 0) commands = selected.map((name) => name === "test" ? "npm test" : `npm run ${name}`);
+        if (selected.length > 0) {
+          commands = [selected.map((name) => name === "test" ? "npm test" : `npm run ${name}`).join(" && ")];
+        }
       }
     } catch {
       // Preserve the profile's fail-closed verifier when package metadata is absent or invalid.

package/packages/piagent-core/extensions/workspace-evidence-roots.js

@@ -0,0 +1,157 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const WORKSPACE_EVIDENCE_MAX_FILES = 2000;
+const WORKSPACE_EVIDENCE_SKIP_NAMES = new Set([
+  ".git", ".hg", ".svn", ".pi", "node_modules", "dist", "build", ".next", "coverage"
+]);
+const WORKSPACE_EVIDENCE_PRIORITY_NAMES = new Map([["plans", 0]]);
+
+function hiddenWorkspaceEvidenceSegment(value) {
+  return String(value ?? "").startsWith(".");
+}
+
+export function gitOutput(cwd, args, options = {}) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: options.encoding ?? "utf8",
+    maxBuffer: options.maxBuffer ?? 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+}
+
+export function isGitWorkingTree(cwd) {
+  try {
+    return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+  } catch {
+    return false;
+  }
+}
+
+export function normalizedGitPath(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
+}
+
+export function prefixedGitPath(prefix, file) {
+  const normalized = normalizedGitPath(file);
+  return prefix ? `${prefix}/${normalized}` : normalized;
+}
+
+function directChildGitEvidenceRootDetails(cwd) {
+  const roots = [];
+  let complete = true;
+  let entries;
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return { roots, complete: false };
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const child = path.join(cwd, entry.name);
+    try {
+      if (fs.lstatSync(child).isSymbolicLink()) continue;
+      let gitMarker;
+      try {
+        gitMarker = fs.lstatSync(path.join(child, ".git"));
+      } catch (error) {
+        if (error?.code === "ENOENT") continue;
+        complete = false;
+        continue;
+      }
+      if (!gitMarker.isDirectory() && !gitMarker.isFile()) {
+        complete = false;
+        continue;
+      }
+      if (!isGitWorkingTree(child)) {
+        complete = false;
+        continue;
+      }
+      const topLevel = gitOutput(child, ["rev-parse", "--show-toplevel"]).trim();
+      if (fs.realpathSync(topLevel) !== fs.realpathSync(child)) {
+        complete = false;
+        continue;
+      }
+      roots.push({ cwd: child, prefix: normalizedGitPath(entry.name) });
+    } catch {
+      complete = false;
+    }
+  }
+  return { roots: roots.sort((left, right) => left.prefix.localeCompare(right.prefix)), complete };
+}
+
+export function directChildGitEvidenceRoots(cwd) {
+  return directChildGitEvidenceRootDetails(cwd).roots;
+}
+
+export function gitEvidenceRootDetails(cwd) {
+  if (isGitWorkingTree(cwd)) return { roots: [{ cwd, prefix: "" }], complete: true };
+  return directChildGitEvidenceRootDetails(cwd);
+}
+
+export function gitEvidenceRoots(cwd) {
+  return gitEvidenceRootDetails(cwd).roots;
+}
+
+export function nonGitWorkspaceFileDetails(cwd, gitRootPrefixes) {
+  const files = [];
+  let complete = true;
+  const gitRoots = new Set(gitRootPrefixes.filter(Boolean));
+  const orderedEntries = (entries) => [...entries].sort((left, right) => {
+    const leftPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(left.name.toLowerCase()) ?? 10;
+    const rightPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(right.name.toLowerCase()) ?? 10;
+    return leftPriority - rightPriority || left.name.localeCompare(right.name, "en-US");
+  });
+  function visit(directory, relativeDirectory) {
+    if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) {
+      complete = false;
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      complete = false;
+      return;
+    }
+    for (const entry of orderedEntries(entries)) {
+      if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) {
+        complete = false;
+        return;
+      }
+      // Loose files beside nested repositories are not governed by either
+      // repository's ignore/trust policy. Keep hidden editor, agent, cloud,
+      // credential, and cache state out of both manifests and change evidence
+      // instead of attempting to maintain an incomplete name blacklist.
+      if (WORKSPACE_EVIDENCE_SKIP_NAMES.has(entry.name) || hiddenWorkspaceEvidenceSegment(entry.name)) continue;
+      const relative = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      if (gitRoots.has(relative.split("/")[0])) continue;
+      const absolute = path.join(directory, entry.name);
+      try {
+        if (fs.lstatSync(absolute).isSymbolicLink()) continue;
+      } catch {
+        complete = false;
+        continue;
+      }
+      if (entry.isDirectory()) visit(absolute, relative);
+      else if (entry.isFile()) files.push(normalizedGitPath(relative));
+    }
+  }
+  visit(cwd, "");
+  return { files: files.sort(), complete };
+}
+
+export function nonGitWorkspaceFiles(cwd, gitRootPrefixes) {
+  return nonGitWorkspaceFileDetails(cwd, gitRootPrefixes).files;
+}
+
+export function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
+  const segments = candidate.split("/").filter(Boolean);
+  const topSegment = segments[0];
+  return Boolean(
+    topSegment
+    && !WORKSPACE_EVIDENCE_SKIP_NAMES.has(topSegment)
+    && !segments.some(hiddenWorkspaceEvidenceSegment)
+    && !gitRootPrefixes.includes(topSegment)
+  );
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/policies/base-policy.json

@@ -107,6 +107,7 @@
   },
   "contextBudget": {
     "defaultMode": "enforce",
+    "contextDeltaShadow": "sample",
     "maxContextFileChars": 50000,
     "maxMemoryFileChars": 20000,
     "maxManifestFiles": 80,
@@ -155,6 +156,7 @@
       "ls": ["filesystem-readonly"],
       "write": ["filesystem-write"],
       "edit": ["filesystem-write"],
+      "apply_patch": ["filesystem-write"],
       "browser": ["browser"],
       "github": ["github"]
     }

package/packages/piagent-core/runtime/context/context-delivery.ts

@@ -0,0 +1,103 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import type { PendingContextDelivery, RuntimeSessionState, ObservedTaskContext } from "../session/runtime-state.ts";
+
+export type ContextDeliveryConfirmationDependencies = {
+  state: RuntimeSessionState;
+  maxManifestFiles: number;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  flushObservedTaskContext: (
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    pendingContext: ObservedTaskContext[],
+    maxManifestFiles: number,
+    event: string
+  ) => TaskContract | undefined;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+export function contextDeliveryIdFromDetails(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+  const rawDelivery = (details as { contextDelivery?: unknown }).contextDelivery;
+  if (!rawDelivery || typeof rawDelivery !== "object" || Array.isArray(rawDelivery)) return undefined;
+  const deliveryId = (rawDelivery as { deliveryId?: unknown }).deliveryId;
+  return typeof deliveryId === "string" && deliveryId.length > 0 && deliveryId.length <= 200
+    ? deliveryId
+    : undefined;
+}
+
+export function confirmContextDelivery(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  deliveryId: string,
+  dependencies: ContextDeliveryConfirmationDependencies
+): TaskContract | undefined {
+  const delivery = dependencies.state.takeContextDelivery(ctx, deliveryId);
+  if (!delivery) return undefined;
+  const task = dependencies.activeTask(ctx);
+  if (!task || task.trace.outcome !== "pending" || task.taskRunId !== delivery.taskRunId) {
+    dependencies.telemetry(ctx, { event: "context_delivery_rejected", deliveryId, reason: "task-identity-mismatch" });
+    return undefined;
+  }
+  for (const entry of delivery.entries) {
+    dependencies.state.rememberObservedContext(ctx, entry);
+    dependencies.state.rememberQualifiedContextEvidence(ctx, delivery.taskRunId, entry);
+  }
+  const written = dependencies.flushObservedTaskContext(
+    pi,
+    ctx,
+    dependencies.state.qualifiedContextEvidence(ctx, delivery.taskRunId),
+    dependencies.maxManifestFiles,
+    "context_delivery_confirmed"
+  );
+  if (!written || written.taskRunId !== delivery.taskRunId) return undefined;
+  if (delivery.pack) {
+    const { retrievalKey, ...pack } = delivery.pack;
+    dependencies.state.rememberInjectedContextPack(ctx, retrievalKey, pack);
+  }
+  dependencies.telemetry(ctx, {
+    event: "context_delivery_confirmed",
+    deliveryId,
+    turnId: delivery.turnId,
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    selectedPaths: delivery.entries.map((entry) => entry.path),
+    selected: delivery.entries.length
+  });
+  if (delivery.injection) dependencies.telemetry(ctx, {
+    event: "context_pack_injected",
+    injectionId: deliveryId,
+    turnId: delivery.turnId,
+    ...delivery.injection,
+    selectedPaths: delivery.injection.selectedItems.map((item) => item.path)
+  });
+  return written;
+}
+
+export function stageContextDelivery(
+  ctx: ExtensionContext,
+  delivery: PendingContextDelivery,
+  dependencies: Pick<ContextDeliveryConfirmationDependencies, "state" | "telemetry">
+): void {
+  dependencies.state.stageContextDelivery(ctx, delivery);
+  if (!delivery.injection) return;
+  dependencies.telemetry(ctx, {
+    event: "context_pack_offered",
+    deliveryId: delivery.deliveryId,
+    turnId: delivery.turnId,
+    ...delivery.injection,
+    selectedPaths: delivery.injection.selectedItems.map((item) => item.path)
+  });
+}
+
+export function confirmContextDeliveryFromToolResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  event: { details?: unknown; isError?: boolean },
+  dependencies: ContextDeliveryConfirmationDependencies
+): TaskContract | undefined {
+  if (event.isError === true) return undefined;
+  const deliveryId = contextDeliveryIdFromDetails(event.details);
+  return deliveryId ? confirmContextDelivery(pi, ctx, deliveryId, dependencies) : undefined;
+}

package/packages/piagent-core/runtime/context/context-delta-shadow.ts

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { buildContextPack, ensureContextIndexV2 } from "../../extensions/context-engine.js";
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
+import type { TaskContract } from "../../extensions/guard-types.js";
+
+export type ContextDeltaShadowMode = "off" | "sample" | "on";
+
+type ShadowInput = {
+  ctx: ExtensionContext;
+  query: string;
+  turnId: string;
+  task: TaskContract;
+  mode: ContextDeltaShadowMode;
+  protectedTarget: boolean;
+  excludePatterns: string[];
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+function sampled(taskRunId: string, query: string): boolean {
+  const byte = crypto.createHash("sha256").update(`${taskRunId}\0${query}`).digest()[0];
+  return byte < 64;
+}
+
+export async function measureContextDeltaShadow(input: ShadowInput): Promise<void> {
+  if (input.mode === "off" || input.protectedTarget || (input.mode === "sample" && !sampled(input.task.taskRunId, input.query))) return;
+  const usage = input.ctx.getContextUsage();
+  if (usage && Number(usage.percent ?? 0) >= 80) return;
+  try {
+    const { status } = await ensureContextIndexV2(input.ctx.cwd, { excludePatterns: input.excludePatterns, rebuildMissing: false });
+    if (!status.exists || status.stale) return;
+    const pack = await buildContextPack(input.ctx.cwd, input.query, {
+      budgetTokens: 1_200,
+      includeCode: false,
+      limit: 10,
+      excludePatterns: input.excludePatterns
+    });
+    const manifested = new Set(durableContextEvidenceEntries(input.task).map((entry) => entry.path));
+    const duplicateItems = pack.selected.filter((item) => manifested.has(item.path));
+    input.telemetry(input.ctx, {
+      event: "context_delta_shadow",
+      turnId: input.turnId,
+      queryHash: pack.queryHash,
+      candidatePaths: pack.selected.map((item) => item.path),
+      pathsAlreadyManifested: duplicateItems.map((item) => item.path),
+      candidateTokens: pack.selected.reduce((sum, item) => sum + item.estimatedTokens, 0),
+      duplicateCandidateTokens: duplicateItems.reduce((sum, item) => sum + item.estimatedTokens, 0)
+    });
+  } catch (error) {
+    input.telemetry(input.ctx, { event: "context_delta_shadow", turnId: input.turnId, skipped: "error", error: error instanceof Error ? error.message : String(error) });
+  }
+}

package/packages/piagent-core/runtime/context/context-efficiency-format.ts

@@ -0,0 +1,47 @@
+type ContextEfficiencyReport = {
+  metrics: {
+    contextWasteScore: number | null;
+    contextWasteScoreEstimate: number;
+    contextWasteScoreEvidenceCoverage: number;
+    averageActiveTools: number;
+    toolSchemaPrefixShare: number;
+    toolSchemaToSystemRatio: number;
+    duplicateReads: number;
+    comparableReadCalls: number;
+    readCalls: number;
+    readEvidenceCoverage: number;
+    contextFallbackRereads: number;
+    contextSelections: number;
+    duplicateOutputRate: number;
+    lowConfidencePacks: number;
+    editRecoveryContextCount: number;
+    editRecoveryFailures: number;
+    editRecoverySuppressedFailures: number;
+    editRecoveryEstimatedTokens: number;
+    editRecoveryFailureEvidenceCoverage: number;
+  };
+  coverage: { wasteScore: { status: string } };
+  sample: { contextPacks: number };
+  recommendations: string[];
+};
+
+export function formatContextEfficiencyReport(
+  report: ContextEfficiencyReport,
+  formatPercent: (value: number) => string
+): string {
+  const wasteScore = report.metrics.contextWasteScore === null
+    ? `unavailable (diagnostic estimate ${report.metrics.contextWasteScoreEstimate}/100; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`
+    : `${report.metrics.contextWasteScore}/100 (lower is better; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`;
+  return [
+    `contextWasteScore: ${wasteScore}`,
+    `activeTools: ${report.metrics.averageActiveTools}`,
+    `toolSchemaPrefixShare: ${formatPercent(report.metrics.toolSchemaPrefixShare)}`,
+    `toolSchemaToSystemRatio: ${report.metrics.toolSchemaToSystemRatio}`,
+    `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.comparableReadCalls} comparable (${report.metrics.readCalls} observed; coverage ${formatPercent(report.metrics.readEvidenceCoverage)})`,
+    `fallbackRereads: ${report.metrics.contextFallbackRereads}/${report.metrics.contextSelections}`,
+    `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
+    `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)}`,
+    ...report.recommendations.map((recommendation) => `- ${recommendation}`)
+  ].join("\n");
+}