@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-core/prompts/task.md

@@ -11,9 +11,9 @@ $ARGUMENTS
 
 Core flow:
 
-1. Use the runtime-created contract for a bounded source task; do not call task-management tools during automatic intake. If runtime pauses for broad, high-risk, or ambiguous scope, call `piagent_task_start` exactly once with project-relative path/glob scope and reuse an active contract.
+1. Use the runtime-created contract for a bounded source task; do not call task-management tools during automatic intake. If runtime pauses for a broad, high-risk, or ambiguous task, call `piagent_task_start` exactly once with project-relative focus paths/globs and reuse an active contract.
 2. Read the likely target and nearest relevant test. The runtime injects bounded navigation context when useful.
-3. Make the smallest in-scope change with ordinary tools and one writer.
+3. Make the smallest complete evidence-backed change with ordinary tools and one writer. Initial task scope guides retrieval/review but does not restrict necessary FE, BE, test, config, or child-repository edits.
 4. Run every exact command returned in `task.verifyCommands` after the latest mutation.
 5. Automatic tasks need no lifecycle calls. Manual high-risk and explicitly requested custom plans keep their returned checkpoints.
 6. Let runtime hooks record context, changed files, verification, trace, and final-gate state. Load recovery tools only if the runtime reports missing evidence.
@@ -21,13 +21,14 @@ Core flow:
 Risk-adaptive enrichment:
 
 - `tiny`: stay targeted; no diagnostic Piagent tools or subagents.
-- `normal`: stop searching once current-file evidence is sufficient. Use a read-only subagent only for a genuinely independent lane.
+- `normal`: stop searching once current-file evidence is sufficient. Keep the parent direct. One fresh read-only helper is eligible only when runtime evidence proves at least two independent lanes and at least 30% projected total token savings after handoff/merge.
 - `high-risk`: inspect current source, relevant vendor documentation, and explicit security/data/release review lenses; keep required human confirmations.
 
 Always:
 
 - Treat memory, context-index, and generated tech snapshots as advisory; verify against current files.
 - If navigation confidence is low, run at most one bounded read-only finder pass; do not start an open-ended scout loop.
+- Never delegate implementation, fork/inherit the parent transcript, run more than one helper, or retry a deterministic helper/runtime/scope failure.
 - Do not touch protected paths or use undeclared capabilities.
 - If verification cannot run, report `blocked` or `partial`, never done. If runtime schedules a continuation, keep working in the same task and do not repeat management tools.
 - Do not paste full test/build/tool logs. Summarize the signal and quote only relevant failures.

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

@@ -8,7 +8,7 @@ import {
 } 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 { applyAssistedReadOnlyFinalHandoff, runtimeLifecycleMode, workingTreeEvidenceDigest } from "../../extensions/task-lifecycle.js";
 import { recordCompletionAudit } from "../../extensions/task-runtime-audit.js";
 import { workingTreeSnapshot } from "../../extensions/task-state.js";
 import { taskDeltaFilesFromSnapshot } from "../../extensions/task-contract-view.js";
@@ -203,6 +203,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
     );
     let completionGate: CompletionGate | undefined;
     if (handoffAttempt) {
+      if (applyAssistedReadOnlyFinalHandoff(task, { durableReadEvidence: readOnlyEvidenceObserved, finalHandoffObserved: true }).changed) task = writeTask(ctx.cwd, task);
       let projected = completionProjection(ctx.cwd, task, currentDigests);
       const baseProjectedGate = evaluateGate(ctx.cwd, projected, currentDigests, currentDigest);
       const exactOutput = evaluateExactFinalOutputContract(projected, text, ctx.cwd);
@@ -377,20 +378,20 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
           ? [
             "Continue the same bounded task with one acceptance-proof repair pass.",
             ...criticalRecoveryGuidance,
-            "Add or correct focused in-scope tests for every missing critical obligation. Assert exact boundary partitions and requested error classes; if a focused test exposes a defect, repair the in-scope source before rerunning verification.",
+            "Add or correct focused tests for every missing critical obligation. Assert exact boundary partitions and requested error classes; if a focused test exposes a defect, repair the evidence-backed source before rerunning verification.",
             ...verifierInstructions(gate.missingVerifyCommands),
-            "Do not broaden task scope, repeat a failed hypothesis, expand permission, or perform an external action."
+            "Do not repeat a failed hypothesis, expand permission, or perform an external action."
           ]
           : [
-            "Continue the same bounded task with one targeted in-scope source repair, then run every exact configured verifier.",
+            "Continue the same bounded task with one targeted evidence-backed source repair, then run every exact configured verifier.",
             ...verifierInstructions(gate.missingVerifyCommands),
-            "Do not broaden task scope, repeat a failed hypothesis, expand permission, or perform an external action."
+            "Do not repeat a failed hypothesis, expand permission, or perform an external action."
           ]
         : 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)]
-              : ["Run one bounded diagnostic pass using targeted reads and report the concrete evidence or unknown."]),
+              : [(task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && gate.missing.length > 0 && gate.missing.every((item) => /^completed work plan\b/i.test(item)) ? "Complete only the pending read-only review checkpoint, then re-emit the complete substantive assessment from the immediately preceding response; do not repeat repository reads or replace it with checkpoint evidence." : "Run one bounded diagnostic pass using targeted reads and report the concrete evidence or unknown."]),
             "Do not mutate project source, expand permission, or perform an external action."
           ]
         : [

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

@@ -9,6 +9,7 @@ import { LONG_INPUT_CHARS } from "../runtime-limits.ts";
 import type { AuthorityResumeDecision } from "../policy/authority-resume-policy.ts";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
 import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
+import { registerAdaptiveContextGovernor } from "../session/adaptive-context-governor.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";
@@ -38,6 +39,11 @@ type InputHookDependencies = {
 };
 
 export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDependencies): void {
+  registerAdaptiveContextGovernor(pi, {
+    activeTask: dependencies.activeTask,
+    telemetry: dependencies.telemetry
+  });
+
   pi.on("input", async (event, ctx) => {
     const text = event.text.trim();
     if (!text || isFreshOrUtilityInput(text)) return { action: "continue" };

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";
@@ -40,6 +42,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;
@@ -138,6 +141,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,7 +280,6 @@ 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"

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

@@ -4,7 +4,7 @@ import { estimateContextTokens, toolResultFingerprint } from "../../extensions/c
 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";
@@ -12,6 +12,7 @@ import { recordObservedContextEvidence } from "../context/context-evidence-quali
 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";
@@ -23,6 +24,7 @@ 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 };
@@ -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,73 +82,13 @@ 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();
   pi.on("session_compact", async (_event, ctx) => editRecoveryDelivery.advanceEpoch(ctx));
@@ -172,6 +119,15 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       ? 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;
@@ -224,11 +180,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);
@@ -313,7 +270,36 @@ 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 : {});
+    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 +326,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 +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.]`
@@ -441,7 +427,7 @@ 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",
@@ -458,7 +444,7 @@ 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

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];
+}