@piagent/platform 1.5.4 → 1.6.0

package/packages/piagent-core/runtime/hooks/agent-start-hook.ts

@@ -7,7 +7,10 @@ import {
   ensureContextIndexV2,
   estimateContextTokens
 } from "../../extensions/context-engine.js";
-import { buildSelectedContextPack } from "../../extensions/criterion-context-pack.js";
+import {
+  buildSelectedContextPack,
+  composeCriterionContextEntries
+} from "../../extensions/criterion-context-pack.js";
 import { matchesProtectedPath } from "../../extensions/policy-core.js";
 import { selectRepositoryMemoryFacts } from "../../extensions/repository-memory.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
@@ -15,9 +18,12 @@ import {
   contextPlanAcceptsConfidence,
   planAdaptiveContext
 } from "../context/adaptive-planner.ts";
+import { stageContextDelivery } from "../context/context-delivery.ts";
+import { measureContextDeltaShadow, type ContextDeltaShadowMode } from "../context/context-delta-shadow.ts";
+import { buildPrefixTelemetry } from "../context/prefix-telemetry.ts";
+import { formatRepositoryMemoryHints } from "../context/repository-memory-hints.ts";
 import { modelCapabilityFromContext } from "../model/capabilities.ts";
 import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
-import { runtimeModelSnapshotDigest } from "../model/runtime-snapshot.ts";
 import type { ModelRouteEvaluation } from "../model/model-route-runtime.ts";
 import { buildTaskResumeContext } from "../recovery/resume-state.ts";
 import { planRetrievalRoute } from "../context/retrieval-route-policy.ts";
@@ -25,7 +31,7 @@ import type { SolverShadowEvaluation } from "../solver/solver-shadow.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncOptions, TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 import { trajectoryRecommendationRef } from "../trajectory/trajectory-runtime.ts";
-import { RuntimeSessionState } from "../session/runtime-state.ts";
+import { RuntimeSessionState, type ContextInjectionItem } from "../session/runtime-state.ts";
 import {
   compactManagedProjectInstructions,
   rewriteLegacyProjectInstructions
@@ -37,16 +43,20 @@ import {
   automaticTaskIntakeMode
 } from "../workflows/task-intake.ts";
 import { CONTEXT_PACK_MAX_TOKENS } from "../runtime-limits.ts";
+import { modelRouteTelemetry, runtimeSnapshotTelemetry, solverShadowTelemetry } from "./agent-prompt-telemetry.ts";
 
 type RuntimeIntakeResult = {
   started: boolean;
   text: string;
   task?: TaskContract;
+  plannedContext?: Array<{ path: string; reason: string }>;
+  plannedContextComplete?: boolean;
 };
 
 type AgentStartHookDependencies = {
   state: RuntimeSessionState;
   autoContextEnabled: boolean;
+  contextDeltaShadowMode: ContextDeltaShadowMode;
   activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
   readProtectedPaths: (ctx: ExtensionContext) => string[];
   contextExcludePatterns: (ctx: ExtensionContext) => string[];
@@ -71,36 +81,18 @@ type AgentStartHookDependencies = {
   telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
 };
 
-function formatRepositoryMemoryHints(candidates: Array<{
-  record: { id?: string; fact: string; citations: Array<{ path: string }> };
-  matchedTerms: string[];
-}>, budgetTokens: number): { text: string; ids: string[] } {
-  if (budgetTokens < 80 || candidates.length === 0) return { text: "", ids: [] };
-  const lines = [
-    "[Piagent repository memory: advisory only]",
-    "Verify every hint against the cited current file before relying on it."
-  ];
-  const ids: string[] = [];
-  for (const candidate of candidates) {
-    const paths = candidate.record.citations.slice(0, 4).map((citation) => citation.path).join(", ");
-    const line = `- ${candidate.record.fact.slice(0, 320)} [sources: ${paths}]`;
-    const proposed = [...lines, line].join("\n");
-    if (estimateContextTokens(proposed) > budgetTokens) break;
-    lines.push(line);
-    if (candidate.record.id) ids.push(candidate.record.id);
-  }
-  return ids.length > 0 ? { text: lines.join("\n"), ids } : { text: "", ids: [] };
-}
-
 export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStartHookDependencies): void {
   pi.on("before_agent_start", async (event, ctx) => {
     const projectInstructions = rewriteLegacyProjectInstructions(event.systemPrompt);
     const query = looksLikeGovernedBoilerplate(event.prompt) ? extractTaskRequest(event.prompt) : event.prompt.trim();
     const signal = classifyContextTask(query);
+    const turn = dependencies.state.currentTurn(ctx, signal.promptHash) ?? dependencies.state.beginTurn(ctx, signal.promptHash);
     const readProtectedPaths = dependencies.readProtectedPaths(ctx);
+    const protectedTarget = signal.paths.some((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
     const protectedOnlyTarget = signal.paths.length > 0
       && signal.paths.every((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
-    const activeTask = dependencies.activeTask(ctx);
+    const sessionTask = dependencies.activeTask(ctx);
+    const activeTask = sessionTask?.trace.outcome === "pending" ? sessionTask : undefined;
     const runtimeIntakeMode = !activeTask ? automaticTaskIntakeMode(query, readProtectedPaths) : undefined;
     const runtimeIntake = Boolean(runtimeIntakeMode);
     const compactMode = protectedOnlyTarget
@@ -122,10 +114,10 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       .map((tool) => ({
         name: tool.name,
         description: tool.description,
-        parameters: tool.parameters,
-        promptGuidelines: tool.promptGuidelines
+        parameters: tool.parameters
       }));
-    const toolSchemaTokens = estimateContextTokens(JSON.stringify(toolMetadata));
+    const prefix = buildPrefixTelemetry(effectiveSystemPrompt, toolMetadata);
+    const toolSchemaTokens = estimateContextTokens(prefix.canonicalToolSurface);
     const systemPromptTokens = estimateContextTokens(effectiveSystemPrompt);
     const autoPackUseful = activeTask?.trace.outcome !== "pending"
       && (runtimeIntake || signal.paths.length === 0);
@@ -154,6 +146,7 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
     if (activeTask) observeTrajectorySync(ctx, dependencies.syncTrajectory?.(ctx, activeTask, { sourceHook: "agent-start", recommendationRef }), dependencies.telemetry);
     dependencies.telemetry(ctx, {
       event: "agent_prompt",
+      turnId: turn.turnId,
       promptHash: signal.promptHash,
       promptChars: signal.promptChars,
       workflow: signal.workflow,
@@ -162,56 +155,16 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       activePiagentTools: [...active].filter((toolName) => PIAGENT_TOOL_NAMES.has(toolName)).length,
       toolSchemaTokens,
       systemPromptTokens,
-      systemPromptHash: crypto.createHash("sha256").update(effectiveSystemPrompt).digest("hex"),
+      systemPromptHash: prefix.systemPromptHash,
+      toolSchemaHash: prefix.toolSchemaHash,
+      prefixSurfaceHash: prefix.prefixSurfaceHash,
+      taskRunId: activeTask?.taskRunId,
       legacyProjectInstructionsRewritten: projectInstructions.rewritten,
       managedInstructionsCompacted: compactedInstructions.compacted,
       contextUsage: ctx.getContextUsage(),
-      runtimeSnapshot: runtimeSnapshot
-        ? {
-            schemaVersion: runtimeSnapshot.schemaVersion,
-            digest: runtimeModelSnapshotDigest(runtimeSnapshot),
-            provider: runtimeSnapshot.provider,
-            modelId: runtimeSnapshot.modelId,
-            contextWindow: runtimeSnapshot.contextWindow,
-            requestedThinkingLevel: runtimeSnapshot.requestedThinkingLevel,
-            effectiveThinkingLevel: runtimeSnapshot.effectiveThinkingLevel,
-            warningCount: runtimeSnapshot.warnings.length
-          }
-        : undefined,
-      solverShadow: solverShadow?.status === "ok"
-        ? {
-            mode: solverShadow.decision.mode,
-            route: solverShadow.decision.route,
-            featureHash: solverShadow.features.featureHash,
-            reasonCodes: solverShadow.decision.reasonCodes,
-            confidence: solverShadow.decision.confidence,
-            reused: solverShadow.reused,
-            persisted: solverShadow.persisted,
-            durationMs: solverShadow.durationMs,
-            warnings: solverShadow.warnings
-          }
-        : solverShadow,
-      modelRoute: modelRoute?.status === "ok"
-        ? {
-            mode: modelRoute.decision.mode,
-            objective: modelRoute.decision.objective,
-            capabilityBand: modelRoute.decision.capabilityBand,
-            safetyFloor: modelRoute.decision.safetyFloor,
-            disposition: modelRoute.decision.disposition,
-            selectionSource: modelRoute.decision.selectionSource,
-            provider: modelRoute.decision.provider,
-            modelId: modelRoute.decision.modelId,
-            effort: modelRoute.decision.effort,
-            downgradeSteps: modelRoute.decision.downgradeSteps,
-            enforced: modelRoute.decision.enforced,
-            decisionDigest: modelRoute.decision.decisionDigest,
-            reasonCodes: modelRoute.decision.reasonCodes,
-            reused: modelRoute.reused,
-            persisted: modelRoute.persisted,
-            durationMs: modelRoute.durationMs,
-            warnings: modelRoute.warnings
-          }
-        : modelRoute
+      runtimeSnapshot: runtimeSnapshotTelemetry(runtimeSnapshot),
+      solverShadow: solverShadowTelemetry(solverShadow),
+      modelRoute: modelRouteTelemetry(modelRoute)
     });
 
     const finishAgentStart = async (contextMessage?: {
@@ -225,36 +178,133 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       const intake = await dependencies.startAutomaticTask(query, ctx);
       if (intake?.task) observeTrajectorySync(ctx, dependencies.syncTrajectory?.(ctx, intake.task, { sourceHook: "agent-start", recommendationRef }), dependencies.telemetry);
       if (!selectedContext && !intake) return systemPromptUpdate;
-      const criterionContext = !selectedContext && intake?.task?.criterionGraph?.mode === "criterion-graph"
-        ? buildSelectedContextPack(ctx.cwd, intake.task.contextManifest.filter((entry) => /^criterion-/.test(entry.reason)), {
-            budgetTokens: CONTEXT_PACK_MAX_TOKENS, limit: 6, excludePatterns: readProtectedPaths
+      const discoveryItems = selectedContext?.customType === "piagent-context-pack-v2" && Array.isArray(selectedContext.details.selectedItems)
+        ? selectedContext.details.selectedItems as Array<Record<string, unknown>>
+        : [];
+      const discoveryPlan = selectedContext?.customType === "piagent-context-pack-v2"
+        && selectedContext.details.contextPlan && typeof selectedContext.details.contextPlan === "object"
+        ? selectedContext.details.contextPlan as { budgetTokens?: unknown; limit?: unknown }
+        : undefined;
+      const fallbackBudget = signal.paths.length === 0 ? 680 : signal.lane === "tiny" ? 420 : 560;
+      const criterionBudget = Number.isFinite(Number(discoveryPlan?.budgetTokens))
+        ? Math.max(100, Math.min(CONTEXT_PACK_MAX_TOKENS, Math.trunc(Number(discoveryPlan?.budgetTokens))))
+        : fallbackBudget;
+      const criterionLimit = Number.isFinite(Number(discoveryPlan?.limit))
+        ? Math.max(1, Math.min(6, Math.trunc(Number(discoveryPlan?.limit))))
+        : signal.paths.length > 0 ? 3 : 4;
+      const criterionMode = dependencies.autoContextEnabled && intake?.task?.criterionGraph?.mode === "criterion-graph";
+      const criterionEntries = intake?.task?.criterionGraph?.mode === "criterion-graph"
+        ? composeCriterionContextEntries({
+            explicitPaths: signal.paths,
+            criteria: intake.task.acceptanceCriteria,
+            plannedEntries: intake.plannedContext ?? [],
+            plannedSelectionComplete: intake.plannedContextComplete === true,
+            retrievedItems: discoveryItems
+          }, { limit: criterionLimit })
+        : [];
+      const criterionContext = criterionMode
+        ? buildSelectedContextPack(ctx.cwd, criterionEntries, {
+            budgetTokens: criterionBudget,
+            limit: criterionLimit,
+            focusText: [query, ...intake.task.acceptanceCriteria].join("\n"),
+            excludePatterns: dependencies.contextExcludePatterns(ctx)
           })
         : undefined;
-      if (criterionContext?.selected.length) dependencies.telemetry(ctx, {
-        event: "criterion_context_pack", selected: criterionContext.selected.length,
-        estimatedTokens: criterionContext.estimatedTokens, selectedPaths: criterionContext.selected.map((entry) => entry.path)
+      const criterionReasonCode = !dependencies.autoContextEnabled
+        ? "auto-context-disabled"
+        : intake?.task?.criterionGraph?.mode !== "criterion-graph"
+          ? "criterion-graph-unavailable"
+          : criterionEntries.length === 0
+            ? "no-candidates"
+            : !criterionContext?.selected.length ? "no-readable-selection" : "selected";
+      if (intake?.task) dependencies.telemetry(ctx, {
+        event: "criterion_context_pack", turnId: turn.turnId, selected: criterionContext?.selected.length ?? 0,
+        candidates: criterionEntries.length,
+        budgetTokens: criterionBudget,
+        estimatedTokens: criterionContext?.estimatedTokens ?? 0,
+        reasonCode: criterionReasonCode,
+        selectedPaths: criterionContext?.selected.map((entry) => entry.path) ?? []
       });
-      const content = [selectedContext?.content, intake?.text, criterionContext?.text].filter(Boolean).join("\n\n");
+      const composedContext = criterionContext?.selected.length ? criterionContext : undefined;
+      const deliveredSelectedContext = criterionMode ? undefined : selectedContext;
+      const content = [deliveredSelectedContext?.content, intake?.text, composedContext?.text].filter(Boolean).join("\n\n");
+      const deliveryTask = intake?.task ?? activeTask;
+      const selectedPackPaths = deliveredSelectedContext?.customType === "piagent-context-pack-v2" && Array.isArray(deliveredSelectedContext.details.paths)
+        ? deliveredSelectedContext.details.paths.filter((value): value is string => typeof value === "string")
+        : [];
+      const criterionPaths = composedContext?.selected.map((entry) => entry.path) ?? [];
+      const selectedPackItems = (deliveredSelectedContext?.details.selectedItems as ContextInjectionItem[] | undefined)
+        ?? selectedPackPaths.map((path) => ({ path, estimatedTokens: 0 }));
+      const injectionItems: ContextInjectionItem[] = composedContext?.selected ?? selectedPackItems;
+      const deliveryEntries = new Map<string, { path: string; reason: string }>();
+      for (const filePath of selectedPackPaths) {
+        deliveryEntries.set(filePath, {
+          path: filePath,
+          reason: "Runtime confirmed delivery of a bounded Context Engine navigation pack."
+        });
+      }
+      for (const filePath of criterionPaths) {
+        deliveryEntries.set(filePath, {
+          path: filePath,
+          reason: "Runtime confirmed delivery of criterion-selected context."
+        });
+      }
+      const deliveryId = deliveryTask && deliveryEntries.size > 0 ? crypto.randomUUID() : undefined;
+      if (deliveryTask && deliveryId) {
+        const retrievalKey = typeof deliveredSelectedContext?.details.retrievalKey === "string" ? deliveredSelectedContext.details.retrievalKey : undefined;
+        stageContextDelivery(ctx, {
+          deliveryId,
+          taskRunId: deliveryTask.taskRunId,
+          turnId: turn.turnId,
+          entries: [...deliveryEntries.values()],
+          pack: retrievalKey
+            ? {
+                retrievalKey,
+                queryHash: String(deliveredSelectedContext?.details.queryHash ?? ""),
+                confidence: String(deliveredSelectedContext?.details.confidence ?? "unknown"),
+                estimatedTokens: Number(deliveredSelectedContext?.details.estimatedTokens ?? 0),
+                paths: selectedPackPaths
+              }
+            : undefined,
+          injection: {
+            source: composedContext ? "criterion-pack" : deliveredSelectedContext?.customType === "piagent-context-pack-v2" ? "auto-pack" : "criterion-seed",
+            queryHash: String(deliveredSelectedContext?.details.queryHash ?? signal.promptHash),
+            confidence: String(deliveredSelectedContext?.details.confidence ?? (criterionPaths.length > 0 ? "high" : "unknown")),
+            estimatedTokens: Number(deliveredSelectedContext?.details.estimatedTokens ?? composedContext?.estimatedTokens ?? 0),
+            selectedItems: injectionItems
+          }
+        }, { state: dependencies.state, telemetry: dependencies.telemetry });
+      }
       return {
         ...(systemPromptUpdate ?? {}),
         message: {
-          customType: selectedContext?.customType ?? "piagent-runtime-task-intake",
+          customType: deliveredSelectedContext?.customType ?? "piagent-runtime-task-intake",
           content,
           display: false,
           details: {
-            ...(selectedContext?.details ?? {}),
+            ...(deliveredSelectedContext?.details ?? {}),
+            ...(composedContext ? {
+              schemaVersion: 1,
+              queryHash: signal.promptHash,
+              estimatedTokens: composedContext.estimatedTokens,
+              paths: composedContext.selected.map((entry) => entry.path),
+              selectedItems: composedContext.selected
+            } : {}),
+            contextDelivery: deliveryId ? { schemaVersion: 1, deliveryId } : undefined,
             runtimeTask: intake?.task
               ? {
                   taskId: intake.task.taskId,
                   taskRunId: intake.task.taskRunId,
+                  changeMode: intake.task.changeMode,
+                  mutationPolicy: intake.task.mutationPolicy,
                   scope: intake.task.scope,
                   verifyCommands: intake.task.verifyCommands,
                   criterionGraph: intake.task.criterionGraph ? { mode: intake.task.criterionGraph.mode, graphDigest: intake.task.criterionGraph.graphDigest, nodes: intake.task.criterionGraph.nodes.length } : null,
                   intakeMode: intake.task.intakeMode
                 }
               : undefined,
-            criterionContext: criterionContext?.selected.length ? {
-              paths: criterionContext.selected.map((entry) => entry.path), estimatedTokens: criterionContext.estimatedTokens
+            criterionContext: composedContext ? {
+              paths: composedContext.selected.map((entry) => entry.path), estimatedTokens: composedContext.estimatedTokens
             } : undefined,
             runtimeIntakeStarted: intake?.started ?? false
           }
@@ -263,6 +313,9 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
     };
 
     const packKey = dependencies.promptPackKey(ctx, signal.promptHash);
+    if (!autoPackUseful && activeTask?.trace.outcome === "pending" && query.length >= 20 && signal.workflow !== "usage" && dependencies.autoContextEnabled) {
+      await measureContextDeltaShadow({ ctx, query, turnId: turn.turnId, task: activeTask, mode: dependencies.contextDeltaShadowMode, protectedTarget, excludePatterns: dependencies.contextExcludePatterns(ctx), telemetry: dependencies.telemetry });
+    }
     if (
       query.length < 20
       || signal.workflow === "usage"
@@ -304,6 +357,7 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       if (!status.exists || status.stale) {
         dependencies.telemetry(ctx, {
           event: "context_pack",
+          turnId: turn.turnId,
           queryHash: signal.promptHash,
           confidence: "none",
           candidates: 0,
@@ -348,6 +402,7 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       });
       dependencies.telemetry(ctx, {
         event: "context_pack",
+        turnId: turn.turnId,
         queryHash: pack.queryHash,
         confidence: pack.confidence,
         candidates: pack.candidates,
@@ -379,10 +434,12 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
       }
       if (!contextPlanAcceptsConfidence(plan, pack.confidence) || pack.selected.length === 0) return finishAgentStart();
       const memoryBudgetTokens = Math.max(0, plan.budgetTokens - pack.estimatedTokens);
-      const memoryHints = formatRepositoryMemoryHints(
-        selectRepositoryMemoryFacts(ctx.cwd, query, { limit: 2, excludePatterns }),
-        memoryBudgetTokens
-      );
+      const memoryHints = runtimeIntake
+        ? { text: "", ids: [] }
+        : formatRepositoryMemoryHints(
+            selectRepositoryMemoryFacts(ctx.cwd, query, { limit: 2, excludePatterns }),
+            memoryBudgetTokens
+          );
       dependencies.telemetry(ctx, {
         event: "repository_memory_selected",
         queryHash: signal.promptHash,
@@ -392,27 +449,29 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
         estimatedTokens: estimateContextTokens(memoryHints.text),
         planReceipt: plan.receipt
       });
-      dependencies.state.rememberInjectedContextPack(ctx, dependencies.retrievalKey(ctx, query), {
-        queryHash: pack.queryHash,
-        confidence: pack.confidence,
-        estimatedTokens: pack.estimatedTokens,
-        paths: pack.selected.map((item) => item.path)
-      });
-      for (const selected of pack.selected) {
-        dependencies.state.rememberObservedContext(ctx, {
-          path: selected.path,
-          reason: "Runtime injected a bounded Context Engine navigation pack."
-        });
-      }
       return finishAgentStart({
         customType: "piagent-context-pack-v2",
         content: [pack.text, memoryHints.text].filter(Boolean).join("\n\n"),
         details: {
           schemaVersion: 2,
           queryHash: pack.queryHash,
+          retrievalKey: dependencies.retrievalKey(ctx, query),
           confidence: pack.confidence,
           estimatedTokens: pack.estimatedTokens,
           paths: pack.selected.map((item) => item.path),
+          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
+          })),
           repositoryMemoryIds: memoryHints.ids,
           currentSnapshot: plan.currentSnapshot,
           contextPlan: plan
@@ -421,6 +480,7 @@ export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStar
     } catch (error) {
       dependencies.telemetry(ctx, {
         event: "context_pack",
+        turnId: turn.turnId,
         queryHash: signal.promptHash,
         confidence: "none",
         candidates: 0,

package/packages/piagent-core/runtime/hooks/completion-hook.ts

@@ -6,6 +6,7 @@ import {
   acceptanceCriticalRecoveryProjection,
   applyAcceptanceRecoveryProvenance
 } from "../../extensions/acceptance-receipt.js";
+import { hasDurableContextEvidence } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
 import { runtimeLifecycleMode, workingTreeEvidenceDigest } from "../../extensions/task-lifecycle.js";
 import { recordCompletionAudit } from "../../extensions/task-runtime-audit.js";
@@ -18,8 +19,7 @@ import {
   looksLikeCompletionClaim,
   looksLikeIncompleteHandoff
 } from "../session/message-signals.ts";
-import { RuntimeSessionState } from "../session/runtime-state.ts";
-import type { ObservedTaskContext } from "../session/runtime-state.ts";
+import { RuntimeSessionState, type ObservedTaskContext } from "../session/runtime-state.ts";
 import type { RecoveryDecision } from "../recovery/recovery-policy.ts";
 import { buildHandoffProjection, handoffProjectionPath, writeHandoffProjection } from "../recovery/handoff-projection.ts";
 import { evaluateExactFinalOutputContract } from "../quality/exact-output-contract.ts";
@@ -177,7 +177,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
     let task = flushObservedTaskContext(
       pi,
       ctx,
-      state.observedContext(ctx),
+      state.qualifiedTaskContext(ctx),
       maxManifestFiles,
       "context_observed_before_handoff"
     ) ?? activeTask(ctx);
@@ -187,7 +187,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
     const completionClaim = looksLikeCompletionClaim(text);
     const incompleteHandoff = looksLikeIncompleteHandoff(text);
     if (task.trace.outcome !== "pending") return;
-    const readOnlyEvidenceObserved = task.changeMode === "read-only" && task.contextManifest.length > 0;
+    const readOnlyEvidenceObserved = (task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && hasDurableContextEvidence(task);
     const latestExactVerifier = latestObservedVerification(task.verifyEvidence.filter((evidence) => evidence.matchedProfileCommand === true));
     const potentiallyFinalEvidence = task.observedChangedFiles.length > 0
       || latestExactVerifier?.exitCode === 0
@@ -298,7 +298,6 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         projected = withRecoveryProvenance(ctx, projected, projectedGate, currentDigests, null);
         task = writeTask(ctx.cwd, projected);
         observeTrajectorySync(ctx, syncTrajectory?.(ctx, task, { sourceHook: "completion" }), telemetry);
-        state.cacheTaskIdentity(ctx, task);
         state.clearPerformanceReview(task.taskRunId);
         state.clearObservedContext(ctx);
         activateBaseTools(ctx);
@@ -387,7 +386,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
             ...verifierInstructions(gate.missingVerifyCommands),
             "Do not broaden task scope, repeat a failed hypothesis, expand permission, or perform an external action."
           ]
-        : selectedRecovery.reasonCodes.includes("unknown-diagnostic-pass") || task.changeMode === "read-only"
+        : selectedRecovery.reasonCodes.includes("unknown-diagnostic-pass") || task.changeMode === "read-only" || task.mutationPolicy === "forbidden"
         ? [
             ...(gate.missingVerifyCommands.length > 0
               ? ["Run only the missing exact verifier commands against the current working tree.", ...verifierInstructions(gate.missingVerifyCommands)]

package/packages/piagent-core/runtime/hooks/input-hook.ts

@@ -11,6 +11,7 @@ import { buildHandoffProjection, writeHandoffProjection } from "../recovery/hand
 import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
 import { activeTaskToolGroups, toolGroupsForPrompt } from "../tools/tool-groups.ts";
 import type { PiagentToolGroup } from "../tools/tool-groups.ts";
+import type { RuntimeSessionState } from "../session/runtime-state.ts";
 import {
   buildFreshCommand,
   chooseFreshWorkflow,
@@ -26,6 +27,7 @@ import {
 } from "../workflows/task-intake.ts";
 
 type InputHookDependencies = {
+  state: RuntimeSessionState;
   boilerplateCollapseChars: number;
   activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
   authorityPolicy: (ctx: ExtensionContext, task: TaskContract) => AuthorityResumeDecision;
@@ -44,7 +46,14 @@ export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDepen
     }
 
     const taskSignal = classifyContextTask(text);
-    const activeTask = dependencies.activeTask(ctx);
+    const sessionTask = dependencies.activeTask(ctx);
+    if (sessionTask && sessionTask.trace.outcome !== "pending") dependencies.state.clearTaskBoundary(ctx, sessionTask.taskRunId);
+    else if (!sessionTask) {
+      const cachedTask = dependencies.state.taskIdentity(ctx);
+      if (cachedTask) dependencies.state.clearTaskBoundary(ctx, cachedTask.taskRunId);
+    }
+    const activeTask = sessionTask?.trace.outcome === "pending" ? sessionTask : undefined;
+    const turn = dependencies.state.beginTurn(ctx, taskSignal.promptHash);
     const authorityPolicy = activeTask?.trace.outcome === "pending" ? dependencies.authorityPolicy(ctx, activeTask) : undefined;
     let authorityHandoffReady = false;
     if (activeTask && authorityPolicy?.disposition === "new-attempt-required") {
@@ -79,6 +88,7 @@ export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDepen
       : promptGroups);
     dependencies.telemetry(ctx, {
       event: "user_input",
+      turnId: turn.turnId,
       source: event.source,
       promptHash: taskSignal.promptHash,
       promptChars: taskSignal.promptChars,

package/packages/piagent-core/runtime/hooks/session-hooks.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { TaskContract } from "../../extensions/guard-types.js";
 import { RuntimeSessionState } from "../session/runtime-state.ts";
 import type { ObservedTaskContext } from "../session/runtime-state.ts";
+import { confirmContextDelivery, contextDeliveryIdFromDetails } from "../context/context-delivery.ts";
 
 type TelemetryWriter = (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
 
@@ -39,6 +40,20 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
     flushObservedTaskContext
   } = dependencies;
 
+  pi.on("message_start", async (event, ctx) => {
+    const message = event.message as unknown as { role?: unknown; details?: unknown };
+    if (message.role !== "custom") return;
+    const deliveryId = contextDeliveryIdFromDetails(message.details);
+    if (!deliveryId) return;
+    confirmContextDelivery(pi, ctx, deliveryId, {
+      state,
+      maxManifestFiles,
+      activeTask: (deliveryContext) => activeTask(deliveryContext.cwd, deliveryContext.sessionManager.getSessionId()),
+      flushObservedTaskContext,
+      telemetry
+    });
+  });
+
   pi.on("session_info_changed", async (event, ctx) => {
     const sessionId = ctx.sessionManager.getSessionId();
     const task = activeTask(ctx.cwd, sessionId);
@@ -58,6 +73,7 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
 
   pi.on("turn_end", async (event, ctx) => {
     const message = event.message as unknown as { usage?: unknown; stopReason?: unknown; role?: unknown };
+    const task = activeTask(ctx.cwd, ctx.sessionManager.getSessionId());
     telemetry(ctx, {
       event: "turn_end",
       turnIndex: event.turnIndex,
@@ -65,9 +81,13 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
       role: message.role,
       stopReason: message.stopReason,
       usage: message.usage,
-      contextUsage: ctx.getContextUsage()
+      contextUsage: ctx.getContextUsage(),
+      taskId: task?.taskId,
+      taskRunId: task?.taskRunId,
+      taskOutcome: task?.trace.outcome
     });
     dependencies.onTurnEnd?.(ctx);
+    if (task && task.trace.outcome !== "pending") state.clearTaskBoundary(ctx, task.taskRunId);
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
@@ -96,7 +116,7 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
     flushObservedTaskContext(
       pi,
       ctx,
-      state.observedContext(ctx),
+      state.qualifiedTaskContext(ctx),
       maxManifestFiles,
       "context_observed_before_shutdown"
     );

package/packages/piagent-core/runtime/hooks/session-start-hook.ts

@@ -139,8 +139,9 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
       dependencies.bindTask(ctx.cwd, sessionId, sessionName, resumedTask);
     }
     if (resumedTask?.workingTreeDigestMigration && resumedTask.workingTreeDigestMigration.status !== "refreshed") dependencies.state.clearDigestMigrationState(ctx, resumedTask.taskRunId, resumedTask.taskId);
-    dependencies.state.cacheTaskIdentity(ctx, resumedTask);
-    const resumeState = resumedTask ? dependencies.inspectResume(ctx.cwd, resumedTask, sessionId) : undefined;
+    if (resumedTask?.trace.outcome === "pending") dependencies.state.cacheTaskIdentity(ctx, resumedTask);
+    else dependencies.state.clearSession(ctx);
+    const resumeState = resumedTask?.trace.outcome === "pending" ? dependencies.inspectResume(ctx.cwd, resumedTask, sessionId) : undefined;
     if (resumeState) dependencies.state.rememberResumeState(resumeState);
     if (resumedTask && resumeState?.enforcementSafe) observeTrajectorySync(ctx, dependencies.syncTrajectory?.(ctx, resumedTask), dependencies.telemetry);
     let taskRecovery: Record<string, unknown> | undefined;
@@ -217,6 +218,10 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
     }
     dependencies.telemetry(ctx, {
       event: "session_start",
+      // Benchmark and efficiency projections must be able to distinguish a
+      // genuine zero-recovery session from telemetry produced before this
+      // receipt/result protocol existed.
+      editRecoveryContextTelemetryVersion: 1,
       activeTools: pi.getActiveTools().length,
       index: engineStatus,
       taskMigration: migration,