@piagent/platform 1.5.5 → 1.6.1

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

@@ -1,35 +1,38 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { toolResultFingerprint } from "../../extensions/context-engine.js";
-import type { TaskContract } from "../../extensions/guard-types.ts";
+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 { 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 { 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 { attachToolResultCompactionDetails, compactToolResultDetails, compactToolResultTextContent, type ToolResultCaptureSummary } from "../session/tool-result-compaction.ts";
-import { RuntimeSessionState, type ObservedTaskContext } from "../session/runtime-state.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 { 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 = {
-  state: RuntimeSessionState;
-  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
-  maxManifestFiles: number;
+type ToolResultHookDependencies = ContextDeliveryConfirmationDependencies & {
   readProtectedPaths: (ctx: ExtensionContext) => string[];
   recordObservedBash: (observed: ObservedBashResult) => void;
   observedBashLedgerPath: (cwd: string) => string;
@@ -61,6 +64,11 @@ type ToolResultHookDependencies = {
   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,
@@ -69,164 +77,24 @@ type ToolResultHookDependencies = {
       success: boolean;
       exitCode: number;
       currentWorkingTreeDigest: string;
-      changedPaths: string[];
+      changedPaths: string[]; authoredChangedPaths: string[];
       retryableFailure: boolean; correctiveFailure: boolean;
     }
   ) => TrajectorySyncResult | undefined;
   syncTrajectory?: (ctx: ExtensionContext, contextObserved: boolean) => TrajectorySyncResult | undefined;
+  recordSubagentResult?: (
+    ctx: ExtensionContext,
+    event: ToolResultEvent,
+    result: DirectSubagentResult
+  ) => void;
 };
 
-function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
-  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
-  let raw = candidate.trim();
-  try {
-    raw = decodeURIComponent(raw);
-  } catch {
-    return undefined;
-  }
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
-    if (!raw.toLowerCase().startsWith("file://")) return undefined;
-    try {
-      raw = fileURLToPath(raw);
-    } catch {
-      return undefined;
-    }
-  }
-  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
-  return path.relative(cwd, absolute).split(path.sep).join("/");
-}
-
-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 filterTextBlocks(
-  content: unknown,
-  blocked: (line: string) => boolean,
-  emptyText: string,
-  noticeText: (count: number) => string
-): { changed: boolean; content?: unknown; redactedLines: number } {
-  if (!Array.isArray(content)) return { changed: false, redactedLines: 0 };
-  let changed = false;
-  let redactedLines = 0;
-  const filtered = content.map((block) => {
-    if (!block || typeof block !== "object") return block;
-    const text = (block as { type?: unknown; text?: unknown }).text;
-    if ((block as { type?: unknown }).type !== "text" || typeof text !== "string") return block;
-    const kept: string[] = [];
-    let blockRedactedLines = 0;
-    for (const line of text.split(/\r?\n/)) {
-      if (blocked(line)) {
-        changed = true;
-        redactedLines += 1;
-        blockRedactedLines += 1;
-      } else {
-        kept.push(line);
-      }
-    }
-    if (blockRedactedLines === 0) return block;
-    const notice = noticeText(blockRedactedLines);
-    const nextText = kept.join("\n").trim().length > 0
-      ? `${kept.join("\n")}\n${notice}`
-      : `${emptyText}\n${notice}`;
-    return { ...block, text: nextText };
-  });
-  return { changed, content: filtered, redactedLines };
-}
-
-export function filterGrepProtectedContent(content: unknown, protectedPatterns: string[]) {
-  return filterTextBlocks(
-    content,
-    (line) => {
-      const linePath = line.match(/^(.+?)(?::\d+:|-\d+-)/)?.[1];
-      return Boolean(linePath && matchesProtectedPath(linePath, protectedPatterns));
-    },
-    "No matches found in non-protected paths.",
-    (count) => `[Piagent Pi guard redacted ${count} protected grep line${count === 1 ? "" : "s"}.]`
-  );
-}
-
-export function filterProtectedPathListContent(
-  cwd: string,
-  content: unknown,
-  protectedPatterns: string[],
-  basePath: string,
-  toolName: string
-) {
-  return filterTextBlocks(
-    content,
-    (line) => {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("[") || trimmed.startsWith("No ") || trimmed === "(empty directory)") return false;
-      const entry = trimmed.replace(/[\\/]+$/, "");
-      const candidates = new Set<string>();
-      const direct = normalizeRelative(cwd, entry);
-      const underBase = normalizeRelative(cwd, path.posix.join(basePath || ".", entry));
-      if (direct !== undefined) candidates.add(direct);
-      if (underBase !== undefined) candidates.add(underBase);
-      return [...candidates].some((candidate) => matchesProtectedPath(candidate, protectedPatterns));
-    },
-    "No entries found in non-protected paths.",
-    (count) => `[Piagent Pi guard redacted ${count} protected ${toolName} line${count === 1 ? "" : "s"}.]`
-  );
-}
-
 export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResultHookDependencies): void {
+  const editRecoveryDelivery = new EditRecoveryDeliveryState();
+  pi.on("session_compact", async (_event, ctx) => editRecoveryDelivery.advanceEpoch(ctx));
+  pi.on("session_shutdown", async (_event, ctx) => editRecoveryDelivery.clearSession(ctx));
   pi.on("tool_result", async (event, ctx) => {
+    confirmContextDeliveryFromToolResult(pi, ctx, event, dependencies);
     const taskIdentity = dependencies.state.taskIdentity(ctx);
     const resultToolCallId = event.toolCallId ?? toolResultFingerprint(event.toolName, event.input, []).key;
     const readProtectedPaths = dependencies.readProtectedPaths(ctx);
@@ -245,12 +113,21 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     }
 
     const observedContextEntry = dependencies.observedTaskContext(ctx.cwd, event, readProtectedPaths);
-    if (observedContextEntry) dependencies.state.rememberObservedContext(ctx, observedContextEntry);
-    const pendingContext = dependencies.state.observedContext(ctx);
+    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)
       : 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>)
       : undefined;
@@ -303,10 +180,12 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       }
     }
     const outputText = boundedToolResultText(event.content);
+    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);
@@ -326,6 +205,7 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
           exitCode: observedExitCode,
           currentWorkingTreeDigest: currentTreeDigest,
           changedPaths: [...new Set([...directMutationResult.changedPaths, ...shellChangedPaths])].sort(),
+          authoredChangedPaths: Object.keys(directMutationResult.recordedDigests).sort(),
           retryableFailure: failure?.retryable === true, correctiveFailure: failure?.sourceMutationPermission === "eligible-in-scope" && failure?.confidence === "high"
         })
       : undefined;
@@ -389,6 +269,37 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     let resultContent: unknown = event.content;
     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 : {});
+    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) {
@@ -412,6 +323,44 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       }
     }
 
+    const recovery = buildEditRecoveryContext({
+      cwd: ctx.cwd,
+      targetPath: resultTarget,
+      reasonCode: toolFailureReasonCode,
+      protectedPaths: readProtectedPaths
+    });
+    if (recovery) {
+      if (editRecoveryDelivery.reserve(ctx, taskIdentity?.taskRunId ?? "", recovery.key)) {
+        editRecovery = recovery;
+        const injectedChars = recovery.text.length;
+        const injectedEstimatedTokens = estimateContextTokens(recovery.text);
+        const recoveryDetails = {
+          schemaVersion: 1,
+          targetPath: dependencies.redactText(recovery.targetPath),
+          contentHash: recovery.contentHash,
+          originalChars: recovery.originalChars,
+          injectedChars,
+          injectedEstimatedTokens,
+          sensitiveContentRedacted: recovery.redacted
+        };
+        resultDetails = isPlainRecord(resultDetails)
+          ? { ...resultDetails, piagentEditRecovery: recoveryDetails }
+          : { ...(resultDetails === undefined ? {} : { value: resultDetails }), piagentEditRecovery: recoveryDetails };
+        resultChanged = true;
+        dependencies.telemetry(ctx, {
+          event: "edit_recovery_context",
+          toolCallId: resultToolCallId,
+          taskRunId: taskIdentity?.taskRunId,
+          targetPath: dependencies.redactText(recovery.targetPath),
+          contentHash: recovery.contentHash,
+          originalChars: recovery.originalChars,
+          injectedChars,
+          injectedEstimatedTokens,
+          sensitiveContentRedacted: recovery.redacted
+        });
+      }
+    }
+
     const safeContent = redactToolResultTextContent(resultContent);
     const safeDetails = redactForStorage(resultDetails);
     const sensitiveValuesRedacted = safeContent.redacted + countChangedStringLeaves(resultDetails, safeDetails);
@@ -428,7 +377,7 @@ 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) {
+    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.]`
@@ -463,11 +412,22 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     if (compactionCaptures.length > 0) {
       resultDetails = attachToolResultCompactionDetails(resultDetails, compactionCaptures);
     }
+    // Compact the original error independently, then append the already bounded
+    // and sanitized recovery snapshot. Otherwise a small but line-dense file can
+    // be compacted into a preview and cease to be a complete one-shot recovery.
+    if (editRecovery) {
+      resultContent = appendToolResultText(resultContent, editRecovery.text);
+      resultChanged = true;
+    }
 
     const resultFingerprintId = event.toolCallId ?? fingerprint.key;
     const record = dependencies.activity ?? dependencies.telemetry;
-    const resultTarget = dependencies.extractLikelyPath(ctx.cwd, isPlainRecord(event.input) ? event.input : {});
+    const changedPaths = [...new Set([...directMutationResult.changedPaths, ...shellChangedPaths])]
+      .filter((filePath) => !matchesProtectedPath(filePath, readProtectedPaths))
+      .map((filePath) => dependencies.redactText(filePath))
+      .sort();
     const lineStats = patchLineStats(event.details);
+    const editRecoveryFailure = ["edit-anchor-not-unique", "edit-anchor-stale"].includes(String(toolFailureReasonCode));
     record(ctx, {
       activityId: `result:${resultFingerprintId}`,
       event: "tool_result",
@@ -475,6 +435,7 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       toolCallId: resultFingerprintId,
       toolName: event.toolName,
       targetPath: resultTarget ? dependencies.redactText(resultTarget) : undefined,
+      changedPaths: changedPaths.length > 0 ? changedPaths : undefined,
       inputHash: fingerprint.inputHash,
       outputHash: fingerprint.outputHash,
       outputChars: fingerprint.outputChars,
@@ -483,7 +444,14 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       compacted: compactionCaptures.length > 0,
       compactedCaptures: compactionCaptures.length,
       sensitiveValuesRedacted,
-      isError: event.isError,
+      isError: effectiveToolError,
+      reasonCode: failureReasonCode,
+      // 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.
+      editRecoveryContext: editRecoveryFailure ? Boolean(editRecovery) : undefined,
+      editRecoveryInjectedChars: editRecovery?.text.length,
+      editRecoveryEstimatedTokens: editRecovery ? estimateContextTokens(editRecovery.text) : undefined,
       exitCode: observed?.exitCode ?? (dependencies.isShellTool(event.toolName) ? event.isError ? 1 : 0 : undefined),
       exitCodeExact: observed?.exitCode !== undefined,
       ...lineStats,

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

@@ -0,0 +1,66 @@
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+
+export 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;
+}
+
+export 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;
+}
+
+export function successfulToolResult(event: { isError?: boolean; details?: unknown }): 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;
+}
+
+export 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);
+}
+
+export 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
+  );
+}
+
+export 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 };
+}
+
+export 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];
+}

package/packages/piagent-core/runtime/inspection/activity-event-adapter.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../extensions/redaction-core.js";
 import type { ActivityInspectorEvent } from "../product/activity-inspector.ts";
+import { handledToolFailure } from "./tool-failure-classification.ts";
 import type { RuntimeEventDraft, RuntimeEventRevision } from "./runtime-event-store.ts";
 
 export type RuntimeEventIdentity = {
@@ -52,7 +53,8 @@ export function adaptActivityTelemetryEvent(input: ActivityEventAdapterInput): R
   const operationRef = hasOperation ? opaque("operation", input.identity.agentOperationId) : null;
   const toolCallRef = hasOperation ? opaque("tool", rawToolCall) : null;
   const activityType = hasOperation ? "tool" : ["bash", "shell", "exec"].includes(toolName) ? "command" : "other";
-  const failed = eventName === "tool_result" && (event.isError === true || typeof event.exitCode === "number" && event.exitCode !== 0);
+  const resultFailure = eventName === "tool_result" && (event.isError === true || typeof event.exitCode === "number" && event.exitCode !== 0);
+  const failed = resultFailure && !handledToolFailure(event.reasonCode);
   const blocked = eventName === "tool_decision";
   // `tool_call` is emitted before policy authorization. Calling it "started"
   // made the Dashboard claim a command was running while it was still waiting
@@ -64,7 +66,7 @@ export function adaptActivityTelemetryEvent(input: ActivityEventAdapterInput): R
   const preview = safeText(previewValue, 4000);
   const storedRedactions = typeof event.sensitiveValuesRedacted === "number" && Number.isInteger(event.sensitiveValuesRedacted)
     ? Math.max(0, Math.min(10_000, event.sensitiveValuesRedacted)) : 0;
-  const reasonCode = blocked ? "policy-blocked" : failed ? "tool-result-failed" : null;
+  const reasonCode = blocked ? "policy-blocked" : resultFailure ? safeText(event.reasonCode ?? "tool-result-failed", 80).text || "tool-result-failed" : null;
   return {
     ...base(input.identity, input.revision, observedAt), agentOperationId: operationRef, toolCallId: toolCallRef,
     kind, evidence: "derived",

package/packages/piagent-core/runtime/inspection/activity-recovery.ts

@@ -0,0 +1,104 @@
+import type { ActivityInspectorEvent } from "../product/activity-inspector.ts";
+
+const RECOVERY_WINDOW_MS = 15 * 60 * 1_000;
+const SHELL_TOOLS = new Set(["bash", "shell", "exec", "command"]);
+const MUTATION_TOOLS = /(?:^|[._-])(?:apply[_-]?patch|edit|write|create[_-]?file|replace)(?:$|[._-])/i;
+
+export type ActivityRecovery = {
+  recoveredAt: string;
+  recoveryToolCallId: string;
+  recoveryToolName: string;
+  exitCode: number | null;
+  exitCodeExact: boolean;
+};
+
+function resultFailed(event: ActivityInspectorEvent | undefined): boolean {
+  return Boolean(event && (event.isError === true || typeof event.exitCode === "number" && event.exitCode !== 0));
+}
+
+function time(value: unknown): number {
+  const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
+function normalized(value: unknown): string {
+  return typeof value === "string" ? value.replaceAll("\\", "/").replace(/\s+/g, " ").trim() : "";
+}
+
+function family(toolName: unknown): "read" | "mutation" | "shell" | "other" {
+  const value = String(toolName ?? "").toLowerCase();
+  if (SHELL_TOOLS.has(value)) return "shell";
+  if (MUTATION_TOOLS.test(value)) return "mutation";
+  if (/(?:^|[._-])(?:read|document[_-]?read)(?:$|[._-])/.test(value)) return "read";
+  return "other";
+}
+
+function likelyCorrectedReadTarget(failed: ActivityInspectorEvent, candidate: ActivityInspectorEvent): boolean {
+  if (family(failed.toolName) !== "read" || family(candidate.toolName) !== "read") return false;
+  const failedPath = normalized(failed.targetPath).toLowerCase();
+  const candidatePath = normalized(candidate.targetPath).toLowerCase();
+  const failedSlash = failedPath.lastIndexOf("/"), candidateSlash = candidatePath.lastIndexOf("/");
+  if (!failedPath || !candidatePath || failedPath.slice(0, failedSlash) !== candidatePath.slice(0, candidateSlash)) return false;
+  const failedName = failedPath.slice(failedSlash + 1), candidateName = candidatePath.slice(candidateSlash + 1);
+  const failedExtension = failedName.includes(".") ? failedName.slice(failedName.lastIndexOf(".")) : "";
+  const candidateExtension = candidateName.includes(".") ? candidateName.slice(candidateName.lastIndexOf(".")) : "";
+  if (failedExtension !== candidateExtension) return false;
+  const tokens = (value: string) => new Set(value.slice(0, value.length - failedExtension.length).split(/[^a-z0-9]+/).filter(Boolean));
+  const failedTokens = tokens(failedName), candidateTokens = tokens(candidateName);
+  const overlap = [...failedTokens].filter((token) => candidateTokens.has(token)).length;
+  return overlap >= 2 && overlap === Math.min(failedTokens.size, candidateTokens.size);
+}
+
+function sameLogicalTarget(failed: ActivityInspectorEvent, candidate: ActivityInspectorEvent): boolean {
+  const failedPath = normalized(failed.targetPath), candidatePath = normalized(candidate.targetPath);
+  if (failedPath && candidatePath && failedPath === candidatePath) {
+    const failedFamily = family(failed.toolName), candidateFamily = family(candidate.toolName);
+    return failedFamily === candidateFamily || failedFamily === "read" && candidateFamily === "mutation";
+  }
+  const failedCommand = normalized(failed.command), candidateCommand = normalized(candidate.command);
+  return Boolean(failedCommand && candidateCommand && failedCommand === candidateCommand
+    && family(failed.toolName) === "shell" && family(candidate.toolName) === "shell");
+}
+
+export function recoveredToolCalls(events: readonly ActivityInspectorEvent[]): ReadonlyMap<string, ActivityRecovery> {
+  const results = new Map<string, { event: ActivityInspectorEvent; order: number }>();
+  for (let order = 0; order < events.length; order += 1) {
+    const event = events[order];
+    if (event?.event === "tool_result" && event.toolCallId) results.set(event.toolCallId, { event, order });
+  }
+  const segments = new Map<number, number>();
+  let segment = 0;
+  for (let order = 0; order < events.length; order += 1) {
+    if (events[order]?.event === "user_input") segment += 1;
+    segments.set(order, segment);
+  }
+  const calls = events.map((event, order) => ({ event, order }))
+    .filter((entry) => entry.event?.event === "tool_call" && Boolean(entry.event.toolCallId));
+  const recovered = new Map<string, ActivityRecovery>();
+  for (let failedCallIndex = 0; failedCallIndex < calls.length; failedCallIndex += 1) {
+    const failedCall = calls[failedCallIndex];
+    const failedResult = results.get(failedCall.event.toolCallId!);
+    if (!failedResult || !resultFailed(failedResult.event)) continue;
+    const failedAt = time(failedResult.event.recordedAt ?? failedCall.event.recordedAt);
+    const match = calls.find((candidate, candidateIndex) => {
+      if (candidate.order <= failedResult.order || segments.get(candidate.order) !== segments.get(failedCall.order)) return false;
+      const candidateResult = results.get(candidate.event.toolCallId!);
+      if (!candidateResult || resultFailed(candidateResult.event)) return false;
+      const recoveredAt = time(candidateResult.event.recordedAt ?? candidate.event.recordedAt);
+      return Number.isFinite(failedAt) && Number.isFinite(recoveredAt) && recoveredAt >= failedAt
+        && recoveredAt - failedAt <= RECOVERY_WINDOW_MS
+        && (sameLogicalTarget(failedCall.event, candidate.event)
+          || candidateIndex === failedCallIndex + 1 && likelyCorrectedReadTarget(failedCall.event, candidate.event));
+    });
+    if (!match) continue;
+    const recoveryResult = results.get(match.event.toolCallId!)!.event;
+    recovered.set(failedCall.event.toolCallId!, {
+      recoveredAt: String(recoveryResult.recordedAt ?? match.event.recordedAt),
+      recoveryToolCallId: match.event.toolCallId!,
+      recoveryToolName: String(match.event.toolName ?? "unknown"),
+      exitCode: typeof recoveryResult.exitCode === "number" ? recoveryResult.exitCode : null,
+      exitCodeExact: recoveryResult.exitCodeExact === true
+    });
+  }
+  return recovered;
+}