@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/recovery/task-evidence-coverage-refresh.ts

@@ -0,0 +1,217 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { readTaskJournal } from "../../extensions/task-journal.js";
+import {
+  directChildGitEvidenceRoots,
+  normalizedGitPath
+} from "../../extensions/workspace-evidence-roots.js";
+import {
+  workingTreeSnapshot,
+  workingTreeSnapshotHasUnavailableEvidence
+} from "../../extensions/task-state.js";
+import { workingTreeEvidenceDigest } from "../../extensions/working-tree-digest.js";
+import { readMutationProvenance } from "../inspection/mutation-provenance-store.ts";
+import { readTaskBaselineManifest } from "../inspection/source-evidence-store.ts";
+
+// Some filesystems expose timestamps at coarse granularity. Requiring a clear
+// pre-task gap prevents a file created in the same timestamp bucket as task
+// startup from being mistaken for legacy baseline state.
+const LEGACY_EVIDENCE_TIMESTAMP_SAFETY_MS = 2_000;
+
+export type TaskEvidenceCoverageRefresh = {
+  task: TaskContract;
+  refreshed: boolean;
+  reason: string;
+  addedPaths: string[];
+  retainedMutationPaths: string[];
+  ambiguousPaths: string[];
+  previousBaselineDigest: string;
+  nextBaselineDigest: string;
+};
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? [...new Set(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+      .map((item) => normalizedGitPath(item).replace(/\/$/, "")))]
+    : [];
+}
+
+function decodedMutationPath(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 8192 || !/^[A-Za-z0-9_-]*$/.test(value)) return undefined;
+  try {
+    const decoded = Buffer.from(value, "base64url").toString("utf8");
+    const normalized = normalizedGitPath(decoded);
+    return normalized && normalized !== "." && normalized !== ".." && !normalized.startsWith("../")
+      ? normalized
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function journalMutationPaths(cwd: string, taskRunId: string): { paths: string[]; corruptions: string[] } {
+  const journal = readTaskJournal(cwd, { taskRunId });
+  const paths: string[] = [];
+  for (const event of journal.events) {
+    if (event.eventType !== "checkpoint" || event.taskRunId !== taskRunId) continue;
+    const evidence = event.data?.evidence;
+    if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) continue;
+    paths.push(...strings((evidence as Record<string, unknown>).files));
+    paths.push(...strings((evidence as Record<string, unknown>).targetPaths));
+  }
+  return { paths: [...new Set(paths)].sort(), corruptions: journal.corruptions };
+}
+
+function provenanceMutationPaths(cwd: string, taskRunId: string): { paths: string[]; corruptions: string[] } {
+  const provenance = readMutationProvenance(cwd, taskRunId);
+  const paths = provenance.records.flatMap((record) => record.changes
+    .map((change) => decodedMutationPath(change.repoPathBase64))
+    .filter((item): item is string => Boolean(item)));
+  return { paths: [...new Set(paths)].sort(), corruptions: provenance.corruptions };
+}
+
+function isLegacyLooseHiddenPath(file: string, childGitPrefixes: string[]): boolean {
+  const normalized = normalizedGitPath(file);
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) return false;
+  if (childGitPrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`))) return false;
+  return normalized.split("/").some((segment) => segment.startsWith(".") && segment.length > 1);
+}
+
+function fileStatePredatesTask(cwd: string, file: string, createdAt: string): boolean {
+  const taskStartedAt = Date.parse(createdAt);
+  if (!Number.isFinite(taskStartedAt)) return false;
+  const absolute = path.resolve(cwd, file);
+  const relative = path.relative(cwd, absolute);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false;
+
+  // The legacy inventory has no content digest for this path. Metadata that is
+  // older than the task is the only local positive evidence that the exact file
+  // state existed before task execution. A symlink, unreadable component, zero
+  // timestamp, or any task-time ctime/mtime remains an ordinary task delta.
+  let current = cwd;
+  try {
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+      current = path.join(current, segment);
+      const component = fs.lstatSync(current);
+      if (component.isSymbolicLink()) return false;
+    }
+    const stat = fs.lstatSync(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink()) return false;
+    const timestamps = [stat.birthtimeMs, stat.ctimeMs, stat.mtimeMs];
+    const latestSafeTimestamp = taskStartedAt - LEGACY_EVIDENCE_TIMESTAMP_SAFETY_MS;
+    return timestamps.every((value) => Number.isFinite(value) && value > 0 && value <= latestSafeTimestamp);
+  } catch {
+    return false;
+  }
+}
+
+function manifestProvenBaselinePaths(
+  cwd: string,
+  task: TaskContract,
+  previousBaseline: Record<string, string>,
+  current: Record<string, string>,
+  candidates: string[]
+): string[] {
+  if (candidates.length === 0) return [];
+  try {
+    const manifest = readTaskBaselineManifest(cwd, task.taskRunId);
+    if (!manifest || manifest.taskId !== task.taskId || manifest.taskRunId !== task.taskRunId) return [];
+    const expanded = { ...previousBaseline };
+    for (const file of candidates) expanded[file] = current[file];
+    return workingTreeEvidenceDigest(expanded) === manifest.baselineTreeDigest ? candidates : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reconcile the one coverage gap introduced when parent-workspace evidence
+ * began including hidden project source. Only paths the legacy collector could
+ * not see are adopted, and any path with durable mutation evidence remains a
+ * real task delta. Existing baseline entries are never rewritten.
+ */
+export function refreshLegacyHiddenWorkspaceEvidenceCoverage(
+  cwd: string,
+  task: TaskContract
+): TaskEvidenceCoverageRefresh {
+  const previousBaseline = task.baselineFileDigests ?? {};
+  const previousBaselineDigest = workingTreeEvidenceDigest(previousBaseline);
+  const unchanged = (
+    reason: string,
+    retainedMutationPaths: string[] = [],
+    ambiguousPaths: string[] = []
+  ): TaskEvidenceCoverageRefresh => ({
+    task,
+    refreshed: false,
+    reason,
+    addedPaths: [],
+    retainedMutationPaths,
+    ambiguousPaths,
+    previousBaselineDigest,
+    nextBaselineDigest: previousBaselineDigest
+  });
+
+  if (task.trace.outcome !== "pending" || task.changeMode !== "source-change") return unchanged("task-not-refreshable");
+  if (!previousBaseline || typeof previousBaseline !== "object" || Array.isArray(previousBaseline)) return unchanged("baseline-unavailable");
+  const childGitPrefixes = directChildGitEvidenceRoots(cwd).map((root) => normalizedGitPath(root.prefix)).filter(Boolean);
+  if (childGitPrefixes.length === 0) return unchanged("not-parent-multi-repo-workspace");
+
+  const current = workingTreeSnapshot(cwd) as Record<string, string>;
+  if (workingTreeSnapshotHasUnavailableEvidence(current)) return unchanged("current-evidence-unavailable");
+  const candidates = Object.keys(current)
+    .filter((file) => previousBaseline[file] === undefined && isLegacyLooseHiddenPath(file, childGitPrefixes))
+    .sort();
+  if (candidates.length === 0) return unchanged("coverage-current");
+
+  const journal = journalMutationPaths(cwd, task.taskRunId);
+  const provenance = provenanceMutationPaths(cwd, task.taskRunId);
+  if (journal.corruptions.length > 0 || provenance.corruptions.length > 0) {
+    return unchanged("mutation-evidence-unavailable");
+  }
+  const mutated = new Set([
+    ...strings(task.observedChangedFiles),
+    ...strings(task.changedFiles),
+    ...journal.paths,
+    ...provenance.paths
+  ]);
+  const retainedMutationPaths = candidates.filter((file) => mutated.has(file));
+  const unclaimedCandidates = candidates.filter((file) => !mutated.has(file));
+  // A current, integrity-validated baseline manifest is stronger than file
+  // timestamps: if adding the currently observed missing paths reconstructs
+  // its exact task-start tree digest, none of those paths changed after start.
+  // Legacy manifests that did not cover the paths simply fail this equality
+  // and retain the conservative timestamp fallback.
+  const manifestProven = new Set(manifestProvenBaselinePaths(cwd, task, previousBaseline, current, unclaimedCandidates));
+  const addedPaths = unclaimedCandidates.filter((file) => manifestProven.has(file) || fileStatePredatesTask(cwd, file, task.createdAt));
+  const added = new Set(addedPaths);
+  const ambiguousPaths = unclaimedCandidates.filter((file) => !added.has(file));
+  if (addedPaths.length === 0) {
+    return unchanged(
+      ambiguousPaths.length > 0 ? "coverage-candidates-ambiguous" : "coverage-candidates-have-mutation-evidence",
+      retainedMutationPaths,
+      ambiguousPaths
+    );
+  }
+
+  const baselineFileDigests = { ...previousBaseline };
+  for (const file of addedPaths) baselineFileDigests[file] = current[file];
+  const refreshed: TaskContract = {
+    ...task,
+    baselineChangedFiles: Object.keys(baselineFileDigests).sort(),
+    baselineFileDigests
+  };
+  return {
+    task: refreshed,
+    refreshed: true,
+    reason: ambiguousPaths.length > 0
+      ? "legacy-hidden-workspace-coverage-partially-expanded"
+      : "legacy-hidden-workspace-coverage-expanded",
+    addedPaths,
+    retainedMutationPaths,
+    ambiguousPaths,
+    previousBaselineDigest,
+    nextBaselineDigest: workingTreeEvidenceDigest(baselineFileDigests)
+  };
+}

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

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stageContextDelivery } from "../context/context-delivery.ts";
+import { semanticCompactionCancelled } from "../session/system-prompt.ts";
 
 type ExtensionContext = any;
 
@@ -10,7 +12,7 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     contextIndexV2Status, crypto, emitRuntimeMessage, ensureContextIndexV2, estimateContextTokens,
     formatContextPreflight,
     formatCount, formatPercent, fs, helpersMode, loadProfileFromContext, memoryHandbookPath,
-    policy, projectFilePath, resolveMemorySettings, resolveOrchestrationPolicy, searchContextIndex,
+    policy, projectFilePath, resolveMemorySettings, resolveOrchestrationPolicy, retrievalKey, runtimeState, searchContextIndex,
     searchContextIndexV2, selectRuntimeAction, semanticCompactionInstructions, telemetry
   } = deps;
   function emitContextIndexSearch(ctx: ExtensionContext, query: string): void {
@@ -123,6 +125,7 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     });
     telemetry(ctx, {
       event: "context_pack",
+      turnId: runtimeState.currentTurn(ctx)?.turnId,
       queryHash: pack.queryHash,
       confidence: pack.confidence,
       candidates: pack.candidates,
@@ -131,12 +134,65 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
       selectedPaths: pack.selected.map((item) => item.path),
       source: "command"
     });
+    const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId());
+    const deliveryId = task?.trace?.outcome === "pending" && pack.selected.length > 0 ? crypto.randomUUID() : undefined;
+    if (deliveryId) {
+      stageContextDelivery(ctx, {
+        deliveryId,
+        taskRunId: task.taskRunId,
+        turnId: runtimeState.currentTurn(ctx)?.turnId,
+        entries: pack.selected.map((item) => ({
+          path: item.path,
+          reason: "Runtime confirmed delivery of a /context pack message."
+        })),
+        pack: {
+          retrievalKey: retrievalKey(ctx, query),
+          queryHash: pack.queryHash,
+          confidence: pack.confidence,
+          estimatedTokens: pack.estimatedTokens,
+          paths: pack.selected.map((item) => item.path)
+        },
+        injection: {
+          source: "context-command",
+          queryHash: pack.queryHash,
+          confidence: pack.confidence,
+          estimatedTokens: pack.estimatedTokens,
+          selectedItems: pack.selected.map((item) => ({
+            path: item.path,
+            estimatedTokens: item.estimatedTokens,
+            sources: item.sources,
+            links: item.links,
+            fileContentHash: item.fileContentHash,
+            ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+            payloadHash: item.payloadHash,
+            representation: item.representation,
+            ranges: item.ranges,
+            generation: item.generation,
+            sensitiveContentRedacted: item.sensitiveContentRedacted
+          }))
+        }
+      }, { state: runtimeState, telemetry });
+    }
     emitRuntimeMessage(ctx, "piagent-context-pack-v2", pack.text, {
       queryHash: pack.queryHash,
       confidence: pack.confidence,
       estimatedTokens: pack.estimatedTokens,
       paths: pack.selected.map((item) => item.path),
-      finderRecommended: pack.finderRecommended
+      selectedItems: pack.selected.map((item) => ({
+        path: item.path,
+        estimatedTokens: item.estimatedTokens,
+        sources: item.sources,
+        links: item.links,
+        fileContentHash: item.fileContentHash,
+        ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+        payloadHash: item.payloadHash,
+        representation: item.representation,
+        ranges: item.ranges,
+        generation: item.generation,
+        sensitiveContentRedacted: item.sensitiveContentRedacted
+      })),
+      finderRecommended: pack.finderRecommended,
+      contextDelivery: deliveryId ? { schemaVersion: 1, deliveryId } : undefined
     });
   }
 
@@ -156,13 +212,19 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     const report = buildContextEfficiencyReport(ctx.cwd);
     const task = activeSessionTask(ctx);
     const taskEfficiency = task ? buildTaskEfficiencyMetrics(ctx.cwd, task) : null;
+    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})`;
     emitRuntimeMessage(ctx, "piagent-context-efficiency", [
-      `contextWasteScore: ${report.metrics.contextWasteScore}/100 (lower is better)`,
+      `contextWasteScore: ${wasteScore}`,
       `activeTools: ${report.metrics.averageActiveTools}`,
-      `toolSchemaShare: ${formatPercent(report.metrics.toolSchemaShare)}`,
-      `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.readCalls}`,
+      `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)}`,
       `taskEfficiency: ${taskEfficiency ? `${taskEfficiency.solver.route}; verify=${taskEfficiency.verification.attempts}; outcome=${taskEfficiency.outcome.task}` : "no active task"}`,
       ...report.recommendations.map((recommendation) => `- ${recommendation}`)
     ].join("\n"), { ...report, taskEfficiency });
@@ -175,6 +237,19 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
   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",
@@ -367,10 +442,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-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,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stageContextDelivery } from "../context/context-delivery.ts";
+import { formatContextEfficiencyReport } from "../context/context-efficiency-format.ts";
 
 type PiagentToolGroup = any;
 type TechStackManifest = any;
@@ -6,7 +8,7 @@ type TechStackManifest = any;
 
 export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
-    PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups,
+    PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups, activeSessionTask,
     buildContextEfficiencyReport, buildContextIndexStatus, buildContextIndexV2, buildContextPack, buildContextPreflight,
     buildTestImpact, buildUsageSnapshot, candidateFileBudget, contextBudgetConfig, contextIndexExcludePatterns,
     contextIndexV2Status, crypto, dynamicToolsEnabled, effectiveProtectedPaths, ensureContextIndexV2,
@@ -28,7 +30,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", "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[];
@@ -142,7 +144,48 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
           limit: 18,
           excludePatterns
         });
-        result = { ...pack, text: undefined, status };
+        telemetry(ctx, { event: "context_pack", turnId: runtimeState.currentTurn(ctx)?.turnId, source: "context-tool", queryHash: pack.queryHash, confidence: pack.confidence, candidates: pack.candidates, selected: pack.selected.length, estimatedTokens: pack.estimatedTokens, selectedPaths: pack.selected.map((item) => item.path) });
+        const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId());
+        const deliveryId = task?.trace?.outcome === "pending" && pack.selected.length > 0 ? crypto.randomUUID() : undefined;
+        if (deliveryId) {
+          const packRetrievalKey = retrievalKey(ctx, params.query);
+          stageContextDelivery(ctx, {
+            deliveryId,
+            taskRunId: task.taskRunId,
+            turnId: runtimeState.currentTurn(ctx)?.turnId,
+            entries: pack.selected.map((item) => ({
+              path: item.path,
+              reason: "Runtime confirmed delivery of an explicit Context Engine tool pack."
+            })),
+            pack: {
+              retrievalKey: packRetrievalKey,
+              queryHash: pack.queryHash,
+              confidence: pack.confidence,
+              estimatedTokens: pack.estimatedTokens,
+              paths: pack.selected.map((item) => item.path)
+            },
+            injection: {
+              source: "context-tool",
+              queryHash: pack.queryHash,
+              confidence: pack.confidence,
+              estimatedTokens: pack.estimatedTokens,
+              selectedItems: pack.selected.map((item) => ({
+                path: item.path,
+                estimatedTokens: item.estimatedTokens,
+                sources: item.sources,
+                links: item.links,
+                fileContentHash: item.fileContentHash,
+                ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+                payloadHash: item.payloadHash,
+                representation: item.representation,
+                ranges: item.ranges,
+                generation: item.generation,
+                sensitiveContentRedacted: item.sensitiveContentRedacted
+              }))
+            }
+          }, { state: runtimeState, telemetry });
+        }
+        result = { ...pack, text: undefined, status, contextDelivery: deliveryId ? { schemaVersion: 1, deliveryId } : undefined };
         text = pack.text;
       } else if (params.action === "impact") {
         await ensureContextIndexV2(ctx.cwd, { excludePatterns, rebuildMissing: false });
@@ -156,15 +199,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       } else {
         result = buildContextEfficiencyReport(ctx.cwd);
         const report = result as ReturnType<typeof buildContextEfficiencyReport>;
-        text = [
-          `contextWasteScore: ${report.metrics.contextWasteScore}/100 (lower is better)`,
-          `activeTools: ${report.metrics.averageActiveTools}`,
-          `toolSchemaShare: ${formatPercent(report.metrics.toolSchemaShare)}`,
-          `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.readCalls}`,
-          `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
-          `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
-          ...report.recommendations.map((recommendation) => `- ${recommendation}`)
-        ].join("\n");
+        text = formatContextEfficiencyReport(report, formatPercent);
       }
       telemetry(ctx, {
         event: "context_engine_action",
@@ -394,8 +429,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()))
@@ -416,7 +451,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 } };
     }
   });
 

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

@@ -334,7 +334,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" };
     }
   });