@piagent/platform 1.6.0 → 1.7.1

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

@@ -21,6 +21,8 @@ import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
 import { toolResultCaptureRoot } from "../session/tool-result-compaction.ts";
 import { ensureTaskAuthorityResumePolicy } from "../policy/authority-resume-policy.ts";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
+import { refreshPristineRuntimeTaskVerification } from "../recovery/pristine-task-policy-refresh.ts";
+import { refreshLegacyHiddenWorkspaceEvidenceCoverage } from "../recovery/task-evidence-coverage-refresh.ts";
 import { activeTaskToolGroups } from "../tools/tool-groups.ts";
 import type { PiagentToolGroup } from "../tools/tool-groups.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
@@ -29,6 +31,20 @@ import type { ResumeState } from "../recovery/resume-state.ts";
 
 type SessionTaskReference = { taskId?: string; taskRunId?: string };
 
+type SessionStartIdentity = { cwd: string; sessionId: string };
+
+function sessionContextMatches(ctx: ExtensionContext, identity: SessionStartIdentity): boolean {
+  try {
+    return ctx.cwd === identity.cwd && ctx.sessionManager.getSessionId() === identity.sessionId;
+  } catch {
+    // Pi invalidates every session-bound ctx getter after a replacement or
+    // reload. A stale startup hook belongs to the outgoing runtime; the new
+    // runtime receives its own session_start event and must be the only one to
+    // publish startup telemetry or bind post-start surfaces.
+    return false;
+  }
+}
+
 type SessionStartHookDependencies = {
   state: RuntimeSessionState;
   loadProfile: (ctx: ExtensionContext) => ProjectProfile;
@@ -40,6 +56,7 @@ type SessionStartHookDependencies = {
   resolveTaskAny: (cwd: string, reference: string) => TaskContract | undefined;
   bindTask: (cwd: string, sessionId: string, sessionName: string | undefined, task: TaskContract) => unknown;
   writeTask: (cwd: string, task: TaskContract) => TaskContract;
+  appendTrace: (cwd: string, payload: Record<string, unknown>) => void;
   capabilityState: (ctx: ExtensionContext) => { ok: boolean; reason?: string; repinned?: string };
   permissionProfile: (ctx: ExtensionContext, profile: ProjectProfile) => { mode: string; warning?: string };
   legacyProjectWarning: (cwd: string) => string | undefined;
@@ -63,6 +80,7 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
     if (!hasOperatorSessionName(operatorSessionName)) pi.setSessionName(`pi:${name}`);
 
     const sessionId = ctx.sessionManager.getSessionId();
+    const sessionIdentity = { cwd: ctx.cwd, sessionId };
     const sessionName = currentSessionName(ctx);
     const taskReference = dependencies.taskReference(ctx);
     const activeTaskRunId = readSessionTaskBinding(ctx.cwd, sessionId)?.activeTaskRunId ?? taskReference?.taskRunId;
@@ -138,6 +156,103 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
       resumedTask = dependencies.writeTask(ctx.cwd, resumedTask);
       dependencies.bindTask(ctx.cwd, sessionId, sessionName, resumedTask);
     }
+    const capabilityState = dependencies.capabilityState(ctx);
+    if (resumedTask?.trace.outcome === "pending"
+      && authorityPolicy?.disposition === "resume-pinned"
+      && capabilityState.ok) {
+      // Re-read from the durable session binding immediately before the
+      // synchronous pristine-tree check and write. This prevents an earlier
+      // session-start projection from overwriting newer same-process task
+      // evidence or work-plan state.
+      const latestTask = dependencies.activeTask(ctx.cwd, sessionId);
+      if (latestTask?.taskRunId === resumedTask.taskRunId) {
+        resumedTask = latestTask;
+        let refreshTask = latestTask;
+        // Coverage reconciliation must precede resume inspection. Otherwise a
+        // path newly visible to the evidence collector looks like a task delta
+        // and can incorrectly block a valid dirty-task resume.
+        const coverage = refreshLegacyHiddenWorkspaceEvidenceCoverage(ctx.cwd, refreshTask);
+        if (coverage.refreshed) {
+          try {
+            resumedTask = dependencies.writeTask(ctx.cwd, coverage.task);
+            refreshTask = resumedTask;
+            try {
+              dependencies.appendTrace(ctx.cwd, {
+                event: "task_evidence_coverage_expanded",
+                taskId: resumedTask.taskId,
+                taskRunId: resumedTask.taskRunId,
+                sessionId,
+                sessionName,
+                reason: coverage.reason,
+                addedPathCount: coverage.addedPaths.length,
+                addedPathExamples: coverage.addedPaths.slice(0, 20),
+                retainedMutationPathCount: coverage.retainedMutationPaths.length,
+                retainedMutationPathExamples: coverage.retainedMutationPaths.slice(0, 20),
+                ambiguousPathCount: coverage.ambiguousPaths.length,
+                ambiguousPathExamples: coverage.ambiguousPaths.slice(0, 20),
+                previousBaselineDigest: coverage.previousBaselineDigest,
+                nextBaselineDigest: coverage.nextBaselineDigest
+              });
+            } catch (error) {
+              try {
+                ctx.ui.notify(`Piagent expanded legacy task evidence coverage, but its auxiliary trace could not be written: ${error instanceof Error ? error.message : String(error)}`, "warning");
+              } catch {
+                // UI availability is not part of the durable coverage commit.
+              }
+            }
+          } catch (error) {
+            try {
+              ctx.ui.notify(`Piagent kept the existing task baseline because its evidence-coverage refresh could not be persisted: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            } catch {
+              // Continue startup with the last durably readable task.
+            }
+            refreshTask = dependencies.activeTask(ctx.cwd, sessionId) ?? latestTask;
+            resumedTask = refreshTask;
+          }
+        }
+        const refreshResume = dependencies.inspectResume(ctx.cwd, refreshTask, sessionId);
+        const refreshAllowed = refreshResume.enforcementSafe
+          && refreshResume.decision !== "blocked"
+          && refreshResume.decision !== "paused";
+        if (refreshAllowed) {
+          const refresh = refreshPristineRuntimeTaskVerification(ctx.cwd, refreshTask, profile);
+          if (refresh.refreshed) {
+            try {
+              resumedTask = dependencies.writeTask(ctx.cwd, refresh.task);
+              try {
+                dependencies.appendTrace(ctx.cwd, {
+                  event: "task_pristine_verifier_refreshed",
+                  taskId: resumedTask.taskId,
+                  taskRunId: resumedTask.taskRunId,
+                  sessionId,
+                  sessionName,
+                  reason: refresh.reason,
+                  verifyGroup: refresh.verifyGroup,
+                  previousCommands: refresh.previousCommands,
+                  verifyCommands: refresh.nextCommands
+                });
+              } catch (error) {
+                // The contract write and its task journal entry are already
+                // durable. An auxiliary trace/notice failure must not abort
+                // session startup or roll the task back to stale commands.
+                try {
+                  ctx.ui.notify(`Piagent refreshed the task verifier, but its auxiliary trace could not be written: ${error instanceof Error ? error.message : String(error)}`, "warning");
+                } catch {
+                  // UI availability is not part of the durable refresh commit.
+                }
+              }
+            } catch (error) {
+              try {
+                ctx.ui.notify(`Piagent kept the existing task verifier because its pristine refresh could not be persisted: ${error instanceof Error ? error.message : String(error)}`, "warning");
+              } catch {
+                // Continue startup with the last durably readable task.
+              }
+              resumedTask = dependencies.activeTask(ctx.cwd, sessionId) ?? refreshTask;
+            }
+          }
+        }
+      }
+    }
     if (resumedTask?.workingTreeDigestMigration && resumedTask.workingTreeDigestMigration.status !== "refreshed") dependencies.state.clearDigestMigrationState(ctx, resumedTask.taskRunId, resumedTask.taskId);
     if (resumedTask?.trace.outcome === "pending") dependencies.state.cacheTaskIdentity(ctx, resumedTask);
     else dependencies.state.clearSession(ctx);
@@ -180,11 +295,10 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
       : " (run /onboard to select a profile)";
     const snapshot = buildUsageSnapshot(ctx, String(pi.getThinkingLevel()));
     const preflight = buildContextPreflight(snapshot, "task", 0);
-    const capabilityState = dependencies.capabilityState(ctx);
     const permissionProfile = dependencies.permissionProfile(ctx, profile);
     const executionBackend = resolveExecutionBackend();
     const contextHint = preflight.recommendation === "fresh-session"
-      ? " Context is high; use /fresh task or /fresh scout for new work."
+      ? " Context is high; use /fresh <workflow> for new work (/fresh help lists every workflow)."
       : preflight.recommendation === "compact"
         ? " Context is warm; run /task-preflight before large work."
         : "";
@@ -209,6 +323,11 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
     if (updateNotice) ctx.ui.notify(updateNotice, "info");
 
     let engineStatus: unknown;
+    // Capture ExtensionAPI state before the first await. Pi invalidates the
+    // captured `pi` object as soon as a concurrent session replacement/reload
+    // wins; consulting it after context-index I/O would then surface a noisy
+    // extension failure even though the replacement session is healthy.
+    const activeToolCount = pi.getActiveTools().length;
     try {
       engineStatus = await contextIndexV2Status(ctx.cwd, {
         excludePatterns: dependencies.contextExcludePatterns(profile)
@@ -216,22 +335,34 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
     } catch (error) {
       engineStatus = { exists: false, error: error instanceof Error ? error.message : String(error) };
     }
-    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,
-      taskId: resumedTask?.taskId,
-      taskRunId: resumedTask?.taskRunId,
-      captureRetention,
-      taskJournalRetention,
-      taskRecovery,
-      executionBackend
-    });
-    await dependencies.afterStart?.(ctx);
+    if (!sessionContextMatches(ctx, sessionIdentity)) return;
+    try {
+      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: activeToolCount,
+        index: engineStatus,
+        taskMigration: migration,
+        taskId: resumedTask?.taskId,
+        taskRunId: resumedTask?.taskRunId,
+        captureRetention,
+        taskJournalRetention,
+        taskRecovery,
+        executionBackend
+      });
+    } catch (error) {
+      if (!sessionContextMatches(ctx, sessionIdentity)) return;
+      throw error;
+    }
+    if (!sessionContextMatches(ctx, sessionIdentity)) return;
+    try {
+      await dependencies.afterStart?.(ctx);
+    } catch (error) {
+      if (!sessionContextMatches(ctx, sessionIdentity)) return;
+      throw error;
+    }
   });
 }

package/packages/piagent-core/runtime/hooks/tool-result-hook.ts

@@ -1,35 +1,37 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-
 import { estimateContextTokens, toolResultFingerprint } from "../../extensions/context-engine.js";
 import { matchesProtectedPath } from "../../extensions/policy-core.js";
 import { changedSnapshotFiles, taskDeltaFilesFromSnapshot } from "../../extensions/task-contract-view.js";
 import { classifyVerificationFailure } from "../../extensions/verification-intelligence.js";
-import { redactForStorage, redactSensitiveText } from "../../extensions/redaction-core.js";
+import { redactForStorage } from "../../extensions/redaction-core.js";
 import { appendObservedBashResult, hashEvidenceCommand, observedBashResultFromToolResultEvent } from "../../extensions/runtime-evidence.js";
-import { workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence } from "../../extensions/task-state.js";
-import { workingTreeObservation } from "../../extensions/working-tree-digest.js";
+import { workingTreeSnapshotHasUnavailableEvidence } from "../../extensions/task-state.js";
+import { captureWorkspaceVerificationSnapshot } from "../../extensions/workspace-verification-snapshot.js";
 import { recordObservedContextEvidence } from "../context/context-evidence-qualification.ts";
 import { confirmContextDeliveryFromToolResult, type ContextDeliveryConfirmationDependencies } from "../context/context-delivery.ts";
 import { recordMutationResult } from "../inspection/mutation-provenance-recorder.ts";
-import { classifyToolFailure } from "../inspection/tool-failure-classification.ts";
+import { classifyToolFailure, handledToolFailure } from "../inspection/tool-failure-classification.ts";
+import { classifyDirectSubagentResult, type DirectSubagentResult } from "../orchestration/subagent-tool-policy.ts";
 import { boundedGitDiffReview } from "../quality/performance-assurance.ts";
 import { currentFileContentDigests } from "../quality/model-mutation-proof.ts";
 import { boundedPerformanceReviewResultText } from "../quality/performance-review-evidence.ts";
 import { buildEditRecoveryContext, type EditRecoveryContext } from "../recovery/edit-recovery-context.ts";
 import { EditRecoveryDeliveryState } from "../recovery/edit-recovery-delivery.ts";
+import { RetrievalEvidenceRuntime } from "../session/retrieval-evidence-runtime.ts";
 import { attachToolResultCompactionDetails, compactToolResultDetails, compactToolResultTextContent, type ToolResultCaptureSummary } from "../session/tool-result-compaction.ts";
 import type { ObservedTaskContext } from "../session/runtime-state.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 import { filterGrepProtectedContent, filterProtectedPathListContent } from "./tool-result-content-guards.ts";
-import { patchLineStats } from "./tool-result-metadata.ts";
+import { editVerificationMarker, patchLineStats } from "./tool-result-metadata.ts";
+import { handledNavigationToolResult } from "./tool-result-navigation.ts";
+import { attachRetrievalCheckpoint, observeRetrievalResult } from "./tool-result-retrieval.ts";
+import { appendToolResultText, boundedToolResultText, countChangedStringLeaves, isPlainRecord, numericExitCode, redactToolResultTextContent, successfulToolResult } from "./tool-result-value-helpers.ts";
 
 export { filterGrepProtectedContent, filterProtectedPathListContent };
 type ToolResultEvent = { toolCallId?: string; toolName: string; input?: unknown; content?: unknown; details?: unknown; isError?: boolean; usage?: unknown };
 type ObservedBashResult = NonNullable<ReturnType<typeof observedBashResultFromToolResultEvent>>;
 type ObservedVerificationResult = ObservedBashResult & { outputText?: string };
-type WorkingTreeObservation = ReturnType<typeof workingTreeObservation>;
-
 type ToolResultHookDependencies = ContextDeliveryConfirmationDependencies & {
   readProtectedPaths: (ctx: ExtensionContext) => string[];
   recordObservedBash: (observed: ObservedBashResult) => void;
@@ -46,15 +48,15 @@ type ToolResultHookDependencies = ContextDeliveryConfirmationDependencies & {
     event: ToolResultEvent,
     pendingContext: ObservedTaskContext[],
     maxManifestFiles: number,
-    shellSnapshotBefore?: Record<string, string>, eventTree?: WorkingTreeObservation
+    shellSnapshotBefore?: Record<string, string>, eventTree?: ReturnType<typeof captureWorkspaceVerificationSnapshot>
   ) => unknown;
   recordObservedTaskVerification: (
     pi: ExtensionAPI,
     ctx: ExtensionContext,
     observed: ObservedVerificationResult,
     pendingContext: ObservedTaskContext[],
-    maxManifestFiles: number, shellSnapshotBefore?: Record<string, string>, eventTree?: WorkingTreeObservation,
-    readProtectedPaths?: string[]
+    maxManifestFiles: number, shellSnapshotBefore?: Record<string, string>, eventTree?: ReturnType<typeof captureWorkspaceVerificationSnapshot>,
+    readProtectedPaths?: string[], preWorkspaceRevisionDigest?: string
   ) => unknown;
   extractLikelyPath: (cwd: string, input: Record<string, unknown>) => string | undefined;
   mutationTargets: (cwd: string, toolName: string, input: Record<string, unknown>) => string[];
@@ -62,6 +64,11 @@ type ToolResultHookDependencies = ContextDeliveryConfirmationDependencies & {
   telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
   activity?: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
   now: () => string;
+  observeEditFreshness?: (
+    ctx: ExtensionContext,
+    event: ToolResultEvent,
+    metadata: { taskRunId?: string; successful: boolean; targetPath?: string; mutationTargets: string[] }
+  ) => void;
   completeSemanticRepair?: (
     ctx: ExtensionContext,
     event: ToolResultEvent,
@@ -75,79 +82,24 @@ type ToolResultHookDependencies = ContextDeliveryConfirmationDependencies & {
     }
   ) => TrajectorySyncResult | undefined;
   syncTrajectory?: (ctx: ExtensionContext, contextObserved: boolean) => TrajectorySyncResult | undefined;
+  recordSubagentResult?: (
+    ctx: ExtensionContext,
+    event: ToolResultEvent,
+    result: DirectSubagentResult
+  ) => void;
 };
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-function numericExitCode(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isInteger(value)) return value;
-  if (typeof value === "string" && /^-?\d+$/.test(value.trim())) return Number.parseInt(value, 10);
-  return undefined;
-}
-
-function successfulToolResult(event: ToolResultEvent): boolean {
-  if (event.isError === true) return false;
-  const details = isPlainRecord(event.details) ? event.details : {};
-  const exitCode = numericExitCode(details.exitCode ?? details.status);
-  return exitCode === undefined || exitCode === 0;
-}
-
-function boundedToolResultText(content: unknown): string {
-  const text = typeof content === "string"
-    ? content
-    : Array.isArray(content)
-      ? content
-          .filter((block) => block && typeof block === "object" && (block as { type?: unknown }).type === "text")
-          .map((block) => String((block as { text?: unknown }).text ?? ""))
-          .join("\n")
-      : "";
-  return text.slice(-20_000);
-}
-
-function countChangedStringLeaves(before: unknown, after: unknown): number {
-  if (typeof before === "string" && typeof after === "string") return before === after ? 0 : 1;
-  if (Array.isArray(before) && Array.isArray(after)) {
-    return before.reduce((total, item, index) => total + countChangedStringLeaves(item, after[index]), 0);
-  }
-  if (!before || !after || typeof before !== "object" || typeof after !== "object") return 0;
-  return Object.entries(before as Record<string, unknown>).reduce(
-    (total, [key, value]) => total + countChangedStringLeaves(value, (after as Record<string, unknown>)[key]),
-    0
-  );
-}
-
-function redactToolResultTextContent(content: unknown): { content: unknown; redacted: number } {
-  if (!Array.isArray(content)) return { content, redacted: 0 };
-  let redacted = 0;
-  const safeContent = content.map((block) => {
-    if (!block || typeof block !== "object") return block;
-    const typed = block as { type?: unknown; text?: unknown };
-    if (typed.type !== "text" || typeof typed.text !== "string") return block;
-    const safeText = redactSensitiveText(typed.text);
-    if (!safeText.redacted) return block;
-    redacted += 1;
-    return { ...block, text: safeText.text };
-  });
-  return { content: safeContent, redacted };
-}
-
-function appendToolResultText(content: unknown, text: string): unknown[] {
-  const block = { type: "text", text };
-  if (Array.isArray(content)) return [...content, block];
-  if (typeof content === "string" && content) return [{ type: "text", text: content }, block];
-  return [block];
-}
-
 export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResultHookDependencies): void {
   const editRecoveryDelivery = new EditRecoveryDeliveryState();
+  const retrievalEvidence = new RetrievalEvidenceRuntime();
   pi.on("session_compact", async (_event, ctx) => editRecoveryDelivery.advanceEpoch(ctx));
-  pi.on("session_shutdown", async (_event, ctx) => editRecoveryDelivery.clearSession(ctx));
+  pi.on("session_shutdown", async (_event, ctx) => {
+    editRecoveryDelivery.clearSession(ctx);
+    retrievalEvidence.clearSession(ctx);
+  });
   pi.on("tool_result", async (event, ctx) => {
     confirmContextDeliveryFromToolResult(pi, ctx, event, dependencies);
+    const currentTurnId = dependencies.state.currentTurn?.(ctx)?.turnId;
     const taskIdentity = dependencies.state.taskIdentity(ctx);
     const resultToolCallId = event.toolCallId ?? toolResultFingerprint(event.toolName, event.input, []).key;
     const readProtectedPaths = dependencies.readProtectedPaths(ctx);
@@ -168,13 +120,24 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     const observedContextEntry = dependencies.observedTaskContext(ctx.cwd, event, readProtectedPaths);
     recordObservedContextEvidence(ctx, observedContextEntry, taskIdentity, dependencies);
     const pendingContext = dependencies.state.qualifiedTaskContext(ctx);
-    const shellSnapshotBefore = dependencies.isShellTool(event.toolName)
-      ? dependencies.state.consumeShellMutationSnapshot(ctx, event.toolName, event.input)
+    const shellVerificationBefore = dependencies.isShellTool(event.toolName)
+      ? dependencies.state.consumeShellVerificationSnapshot(ctx, event.toolName, event.input, resultToolCallId)
       : undefined;
+    const shellSnapshotBefore = shellVerificationBefore?.snapshot as Record<string, string> | undefined;
     const currentTask = dependencies.activeTask(ctx);
+    const subagentResult = classifyDirectSubagentResult({
+      toolName: event.toolName,
+      toolInput: event.input,
+      content: event.content,
+      details: event.details,
+      isError: event.isError
+    });
+    if (subagentResult) dependencies.recordSubagentResult?.(ctx, event, subagentResult);
+    const effectiveToolError = event.isError === true || subagentResult?.failed === true;
     const eventTree = currentTask
-      ? workingTreeObservation(workingTreeSnapshot(ctx.cwd) as Record<string, string>)
+      ? captureWorkspaceVerificationSnapshot(ctx.cwd)
       : undefined;
+    dependencies.state.projectVerification.observe(ctx, currentTask, event, shellVerificationBefore, eventTree);
     dependencies.recordObservedTaskChanges(pi, ctx, event, pendingContext, dependencies.maxManifestFiles, shellSnapshotBefore, eventTree);
     if (observed) {
       dependencies.recordObservedTaskVerification(
@@ -182,7 +145,7 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
         ctx,
         { ...observed, toolCallId: observed.toolCallId ?? resultToolCallId, outputText: boundedToolResultText(event.content) },
         pendingContext,
-        dependencies.maxManifestFiles, shellSnapshotBefore, eventTree, readProtectedPaths
+        dependencies.maxManifestFiles, shellSnapshotBefore, eventTree, readProtectedPaths, shellVerificationBefore?.workspaceRevisionDigest ?? undefined
       );
     }
 
@@ -224,11 +187,12 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       }
     }
     const outputText = boundedToolResultText(event.content);
-    const failureReasonCode = classifyToolFailure(event.toolName, event.isError === true, event.content, event.input);
+    const toolFailureReasonCode = classifyToolFailure(event.toolName, effectiveToolError, event.content, event.input);
+    const failureReasonCode = subagentResult?.reasonCode ?? toolFailureReasonCode;
     const performanceReviewOutputText = boundedPerformanceReviewResultText(event.content);
     const observedExitCode = observed?.exitCode
       ?? numericExitCode(isPlainRecord(event.details) ? event.details.exitCode ?? event.details.status : undefined)
-      ?? (event.isError === true ? 1 : 0);
+      ?? (effectiveToolError ? 1 : 0);
     const failure = observedExitCode === 0
       ? undefined
       : classifyVerificationFailure(outputText, observedExitCode);
@@ -282,6 +246,7 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     const successfulDirectMutation = successfulToolResult(event)
       && directMutationTool;
     const shellTreeChanged = shellChangedPaths.length > 0;
+    if (successfulDirectMutation || shellTreeChanged) retrievalEvidence.invalidateAfterMutation(ctx, currentTurnId);
     if (taskIdentity && currentTreeDigest && (reviewCandidate || existingCredit || successfulDirectMutation || shellSnapshotBefore)) {
       if (shellTreeChanged || directMutationResult.changedPaths.length > 0) {
         dependencies.state.invalidatePerformanceReviewCredit(taskIdentity.taskRunId);
@@ -313,7 +278,50 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     let resultDetails: unknown = event.details;
     let resultChanged = false;
     let editRecovery: EditRecoveryContext | undefined;
+    if (subagentResult) {
+      const classification = {
+        schemaVersion: 1,
+        spawned: subagentResult.spawned,
+        failed: subagentResult.failed,
+        reasonCode: subagentResult.reasonCode,
+        disposition: subagentResult.disposition,
+        role: subagentResult.role,
+        requestRef: subagentResult.requestRef,
+        calls: subagentResult.calls,
+        tokens: subagentResult.tokens
+      };
+      resultDetails = isPlainRecord(resultDetails)
+        ? { ...resultDetails, piagentSubagentOutcome: classification }
+        : { ...(resultDetails === undefined ? {} : { value: resultDetails }), piagentSubagentOutcome: classification };
+      if (subagentResult.failed) {
+        resultContent = appendToolResultText(
+          resultContent,
+          `[Piagent helper outcome: failed (${subagentResult.reasonCode ?? "helper-run-failed"}). Treat this result as insufficient evidence; continue in the parent and do not retry the helper.]`
+        );
+      }
+      resultChanged = true;
+    }
     const resultTarget = dependencies.extractLikelyPath(ctx.cwd, isPlainRecord(event.input) ? event.input : {});
+    const handledNavigationFailure = effectiveToolError && handledToolFailure(toolFailureReasonCode, normalizedToolName);
+    if (handledNavigationFailure) {
+      const navigation = handledNavigationToolResult({
+        toolName: normalizedToolName,
+        reasonCode: String(toolFailureReasonCode),
+        targetPath: resultTarget,
+        content: resultContent,
+        details: resultDetails,
+        redactText: dependencies.redactText
+      });
+      resultContent = navigation.content;
+      resultDetails = navigation.details;
+      resultChanged = true;
+    }
+    dependencies.observeEditFreshness?.(ctx, event, {
+      taskRunId: taskIdentity?.taskRunId,
+      successful: successfulToolResult(event),
+      targetPath: resultTarget,
+      mutationTargets: directMutationTargets
+    });
     if (event.toolName === "grep") {
       const filtered = filterGrepProtectedContent(resultContent, readProtectedPaths);
       if (filtered.changed) {
@@ -340,7 +348,7 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     const recovery = buildEditRecoveryContext({
       cwd: ctx.cwd,
       targetPath: resultTarget,
-      reasonCode: failureReasonCode,
+      reasonCode: toolFailureReasonCode,
       protectedPaths: readProtectedPaths
     });
     if (recovery) {
@@ -391,7 +399,10 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       outputHash: fingerprint.outputHash,
       recordedAt: dependencies.now()
     });
-    if (repeated && ["read", "grep", "find", "ls"].includes(event.toolName) && fingerprint.outputChars > 0) {
+    const retrievalCheckpoint = observeRetrievalResult({ runtime: retrievalEvidence, ctx, turnId: currentTurnId,
+      observation: { toolName: normalizedToolName, callFingerprint: fingerprint.key, outputHash: fingerprint.outputHash,
+        target: resultTarget, deterministicMiss: handledNavigationFailure, nonEvidenceFailure: effectiveToolError } });
+    if (repeated && ["read", "grep", "find", "ls", "subagent"].includes(event.toolName) && fingerprint.outputChars > 0) {
       resultContent = [{
         type: "text",
         text: `[Piagent delta: unchanged ${event.toolName} result; ${fingerprint.outputChars} chars / ${fingerprint.outputLines} lines match the previous identical call.]`
@@ -408,7 +419,6 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
         : { value: resultDetails, piagentDelta: delta };
       resultChanged = true;
     }
-
     const captureCache = new Map<string, ToolResultCaptureSummary>();
     const compactedContent = compactToolResultTextContent(ctx.cwd, event, ctx, resultContent, captureCache);
     const compactionCaptures = [...compactedContent.captures];
@@ -433,6 +443,13 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       resultContent = appendToolResultText(resultContent, editRecovery.text);
       resultChanged = true;
     }
+    const checkpointResult = attachRetrievalCheckpoint({ checkpoint: retrievalCheckpoint, content: resultContent,
+      details: resultDetails, ctx, turnId: currentTurnId, telemetry: dependencies.telemetry });
+    if (checkpointResult.changed) {
+      resultContent = checkpointResult.content;
+      resultDetails = checkpointResult.details;
+      resultChanged = true;
+    }
 
     const resultFingerprintId = event.toolCallId ?? fingerprint.key;
     const record = dependencies.activity ?? dependencies.telemetry;
@@ -441,10 +458,10 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       .map((filePath) => dependencies.redactText(filePath))
       .sort();
     const lineStats = patchLineStats(event.details);
-    const editRecoveryFailure = ["edit-anchor-not-unique", "edit-anchor-stale"].includes(String(failureReasonCode));
+    const editRecoveryFailure = ["edit-anchor-not-unique", "edit-anchor-stale"].includes(String(toolFailureReasonCode));
     record(ctx, {
-      activityId: `result:${resultFingerprintId}`,
-      event: "tool_result",
+      activityId: `result:${resultFingerprintId}`, event: "tool_result",
+      ...editVerificationMarker(taskIdentity, eventTree, successfulToolResult(event), changedPaths),
       recordedAt: dependencies.now(),
       toolCallId: resultFingerprintId,
       toolName: event.toolName,
@@ -458,8 +475,10 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       compacted: compactionCaptures.length > 0,
       compactedCaptures: compactionCaptures.length,
       sensitiveValuesRedacted,
-      isError: event.isError,
+      isError: effectiveToolError,
       reasonCode: failureReasonCode,
+      handledFailure: handledNavigationFailure || undefined,
+      retrievalCheckpoint: retrievalCheckpoint?.reason,
       // An explicit false is evidence too: it proves that every classified
       // edit-anchor failure passed through the recovery policy even when the
       // target was too large, private, protected, or otherwise ineligible.
@@ -474,8 +493,8 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
 
     if (resultChanged) {
       return resultDetails === undefined
-        ? { content: resultContent }
-        : { content: resultContent, details: resultDetails };
+        ? { content: resultContent, ...(handledNavigationFailure ? { isError: false } : {}) }
+        : { content: resultContent, details: resultDetails, ...(handledNavigationFailure ? { isError: false } : {}) };
     }
   });
 }

package/packages/piagent-core/runtime/hooks/tool-result-metadata.ts

@@ -11,3 +11,12 @@ export function patchLineStats(details: unknown): { additions?: number; deletion
   }
   return { additions, deletions };
 }
+
+export function editVerificationMarker(identity: { taskId: string; taskRunId: string } | undefined,
+  tree: { proofCapable: boolean; digest: string; workspaceRevisionDigest: string | null } | undefined,
+  successful: boolean, changedPaths: string[]) {
+  return { taskUsageVersion: 1, taskId: identity?.taskId, taskRunId: identity?.taskRunId,
+    mutationObserved: successful && changedPaths.length > 0 && tree?.proofCapable === true,
+    postWorkingTreeDigest: tree?.proofCapable ? tree.digest : null,
+    postWorkspaceRevisionDigest: tree?.proofCapable ? tree.workspaceRevisionDigest : null };
+}

package/packages/piagent-core/runtime/hooks/tool-result-navigation.ts

@@ -0,0 +1,36 @@
+import { appendToolResultText, isPlainRecord } from "./tool-result-value-helpers.ts";
+
+function handledNavigationText(reasonCode: string): string {
+  const guidance = reasonCode === "target-is-directory"
+    ? "List the directory once and choose a child"
+    : "Discover from one confirmed parent";
+  return `[Piagent navigation: ${reasonCode} — handled negative evidence, not a runtime failure. ${guidance}; do not retry this call.]`;
+}
+
+export function handledNavigationToolResult(input: {
+  toolName: string;
+  reasonCode: string;
+  targetPath?: string;
+  content: unknown;
+  details: unknown;
+  redactText: (value: string) => string;
+}): { content: unknown; details: unknown } {
+  const targetPath = input.targetPath
+    ? input.redactText(input.targetPath).replace(/\s+/g, " ").trim().slice(0, 1_024) || undefined
+    : undefined;
+  const navigation = {
+    schemaVersion: 1,
+    handled: true,
+    reasonCode: input.reasonCode,
+    targetPath,
+    retryExactCall: false
+  };
+  const text = handledNavigationText(input.reasonCode);
+  const content = ["read", "grep", "find", "ls"].includes(input.toolName)
+    ? [{ type: "text", text }]
+    : appendToolResultText(input.content, text);
+  const details = isPlainRecord(input.details)
+    ? { ...input.details, piagentNavigation: navigation }
+    : { ...(input.details === undefined ? {} : { value: input.details }), piagentNavigation: navigation };
+  return { content, details };
+}