@piagent/platform 1.6.1 → 1.8.0

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

@@ -1,43 +1,34 @@
+import { criticalAcceptanceRecoveryGuidance, type CriticalRecoveryProjection } from "../recovery/acceptance-recovery-guidance.ts";
 import crypto from "node:crypto";
 import path from "node:path";
+import { completionPreparationCurrent, completionPreparationDeferred, type CompletionPreparation } from "../verification/completion-preparation.ts";
+import { apiBaselineCriterionEvidence as apiBaselineEvidence } from "../verification/acceptance-api-baseline.js";
+import { createCompositeCompletionFinalizer } from "../verification/composite-completion-finalizer.ts";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import {
-  acceptanceCriticalRecoveryProjection,
-  applyAcceptanceRecoveryProvenance
-} from "../../extensions/acceptance-receipt.js";
+import { acceptanceCriticalRecoveryProjection, applyAcceptanceRecoveryProvenance } from "../../extensions/acceptance-receipt.js";
 import { hasDurableContextEvidence } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.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 { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 import { taskDeltaFilesFromSnapshot } from "../../extensions/task-contract-view.js";
 import { latestObservedVerification, verificationEvidenceProvesStableTree } from "../../extensions/verification-intelligence.js";
-import {
-  assistantMessageHasToolCall,
-  assistantMessageText,
-  looksLikeCompletionClaim,
-  looksLikeIncompleteHandoff
-} from "../session/message-signals.ts";
+import { assistantMessageHasToolCall, assistantMessageText, prependAssistantNotice, looksLikeCompletionClaim, looksLikeIncompleteHandoff } from "../session/message-signals.ts";
 import { RuntimeSessionState, type ObservedTaskContext } from "../session/runtime-state.ts";
 import type { RecoveryDecision } from "../recovery/recovery-policy.ts";
+import { independentVerificationRecovery } from "../recovery/independent-verification-recovery.ts";
 import { buildHandoffProjection, handoffProjectionPath, writeHandoffProjection } from "../recovery/handoff-projection.ts";
 import { evaluateExactFinalOutputContract } from "../quality/exact-output-contract.ts";
 import { performanceReviewGuidance, taskPerformanceAssurance } from "../quality/performance-assurance.ts";
-import { planRecoveryContinuation, reserveSemanticReviewContinuation } from "../recovery/continuation-budget.ts";
+import { protectedRefusalHandoffMatches, settleNativeProtectedRefusal } from "./protected-refusal-completion.ts";
+import { planRecoveryContinuation, reserveSemanticReviewContinuation, terminalRecoveryForContinuationDenial } from "../recovery/continuation-budget.ts";
 import { semanticRepairProvenance } from "../recovery/semantic-repair-handshake.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncOptions, TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
-
-type CompletionGate = { decision: "pass" | "fail"; missing: string[]; missingVerifyCommands: string[] };
-
-type CriticalRecoveryProjection = {
-  criterionText: string;
-  targets: string[];
-  missingDimensions: string[];
-  proofHints: string[];
-};
+type CompletionGate = { decision: "pass" | "fail"; missing: string[]; missingVerifyCommands: string[];
+  acceptanceProof?: { mode: "enforce" | "diagnostic"; pendingCriterionIds: string[]; missing: string[] } };
 function exactPathCoverage(expectedPaths: string[], reviewedPaths: string[] | undefined): boolean {
   const expected = [...new Set(expectedPaths)].sort();
   const reviewed = [...new Set(reviewedPaths ?? [])].sort();
@@ -45,30 +36,13 @@ function exactPathCoverage(expectedPaths: string[], reviewedPaths: string[] | un
     && expected.length === reviewed.length
     && expected.every((file, index) => file === reviewed[index]);
 }
-
-function compactRecoveryField(value: unknown, maximum: number): string {
-  const text = String(value ?? "").replace(/\s+/g, " ").trim();
-  return text.length > maximum ? `${text.slice(0, Math.max(0, maximum - 1)).trimEnd()}…` : text;
-}
-
-function criticalAcceptanceRecoveryGuidance(projections: CriticalRecoveryProjection[]): string[] {
-  if (projections.length === 0) return [];
-  const lines = ["Critical proof targets (derived only from the current task contract and working tree):"];
-  for (const projection of projections.slice(0, 8)) {
-    const targets = projection.targets.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
-    const dimensions = projection.missingDimensions.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
-    const criterion = compactRecoveryField(projection.criterionText, 700);
-    lines.push(`- Target: ${targets.join(", ") || "task-scoped behavior"}; missing proof: ${dimensions.join(", ") || "focused-evidence"}; criterion: ${criterion}`);
-  }
-  const hints = [...new Set(projections.flatMap((projection) => projection.proofHints)
-    .map((hint) => compactRecoveryField(hint, 300))
-    .filter(Boolean))].slice(0, 8);
-  if (hints.length > 0) lines.push("Proof requirements:", ...hints.map((hint) => `- ${hint}`));
-  return lines;
-}
-
 type CompletionHookDependencies = {
   state: RuntimeSessionState;
+  prepareIndependentAcceptance?: (ctx: ExtensionContext, task: TaskContract, response?: { origin: "assistant"; bytes: string }) => Promise<CompletionPreparation | boolean | void>;
+  deferIndependentCompletion?: (ctx: ExtensionContext, task: TaskContract, response: { origin: "assistant"; bytes: string }, finalizer: {
+    preflight: () => object | false; publication: (capability: object) => object | false; finalize: (capability: object) => boolean }) => boolean;
+  projectIndependentLifecycle?: (ctx: ExtensionContext, task: TaskContract, candidate: TaskContract) => TaskContract | false;
+  nativeRefusalFallbackAllowed?: (ctx: ExtensionContext, task: TaskContract) => boolean;
   maxManifestFiles: number; semanticReviewAllowed: (task: TaskContract) => boolean;
   activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
   flushObservedTaskContext: (
@@ -89,6 +63,7 @@ type CompletionHookDependencies = {
     currentDigests: Record<string, string>,
     currentDigest: string
   ) => CompletionGate;
+  acceptanceEvidenceFiles: (cwd: string, task: TaskContract, currentDigests: Record<string, string>, taskLocalDelta?: string[]) => string[];
   writeTask: (cwd: string, task: TaskContract) => TaskContract;
   activateBaseTools: (ctx: ExtensionContext) => unknown;
   appendTrace: (cwd: string, payload: Record<string, unknown>) => void;
@@ -99,15 +74,13 @@ type CompletionHookDependencies = {
   recoveryDecision: (ctx: ExtensionContext, task: TaskContract, gate: CompletionGate, currentDigest: string) => RecoveryDecision;
   syncTrajectory?: (ctx: ExtensionContext, task: TaskContract, options: TrajectorySyncOptions) => TrajectorySyncResult;
 };
-
 export function registerCompletionHook(pi: ExtensionAPI, dependencies: CompletionHookDependencies): void {
   const {
     state,
     maxManifestFiles,
     activeTask,
     flushObservedTaskContext,
-    completionProjection,
-    evaluateGate,
+    completionProjection, evaluateGate, acceptanceEvidenceFiles,
     writeTask,
     activateBaseTools,
     appendTrace,
@@ -119,7 +92,6 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
     semanticReviewAllowed,
     syncTrajectory
   } = dependencies;
-
   function persistHandoff(
     ctx: ExtensionContext,
     task: TaskContract,
@@ -174,6 +146,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
 
   pi.on("message_end", async (event, ctx) => {
     if (!event.message || event.message.role !== "assistant" || assistantMessageHasToolCall(event.message)) return;
+    if (state.currentTurn(ctx)?.lightweightNonAuthorizingChange) return;
     let task = flushObservedTaskContext(
       pi,
       ctx,
@@ -184,7 +157,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
     if (!task) return;
     observeTrajectorySync(ctx, syncTrajectory?.(ctx, task, { sourceHook: "completion" }), telemetry);
     const text = assistantMessageText(event.message);
-    const completionClaim = looksLikeCompletionClaim(text);
+    const protectedRefusalHandoff = protectedRefusalHandoffMatches(task.operatorRequest, text), completionClaim = looksLikeCompletionClaim(text) || protectedRefusalHandoff;
     const incompleteHandoff = looksLikeIncompleteHandoff(text);
     if (task.trace.outcome !== "pending") return;
     const readOnlyEvidenceObserved = (task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && hasDurableContextEvidence(task);
@@ -194,9 +167,23 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
       || readOnlyEvidenceObserved;
     if (!completionClaim && (incompleteHandoff || !potentiallyFinalEvidence)) return;
 
-    const currentDigests = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
-    const currentDigest = workingTreeEvidenceDigest(currentDigests);
-    const currentPassingVerifierObserved = verificationEvidenceProvesStableTree(latestExactVerifier, currentDigest);
+    const preparation = await dependencies.prepareIndependentAcceptance?.(ctx, task, { origin: "assistant", bytes: text });
+    // Preserve content-observed bytes until native persistence/settlement exists.
+    if (completionPreparationDeferred(preparation)) {
+      const finalizer = createCompositeCompletionFinalizer({ ctx, pi, state, task, responseText: text, activeTask,
+        completionProjection, evaluateGate, semanticReviewAllowed, syncTrajectory,
+        projectCompositeLifecycle: (candidate) => dependencies.projectIndependentLifecycle?.(ctx, task, candidate) ?? false,
+        withRecoveryProvenance: (candidate, gate, digests) => withRecoveryProvenance(ctx, candidate, gate, digests, null),
+        writeTask, activateBaseTools, appendTrace, appendSessionTrace, telemetry,
+        persistHandoff: (completed, gate, digests) => persistHandoff(ctx, completed, gate, digests, null) });
+      dependencies.deferIndependentCompletion?.(ctx, task, { origin: "assistant", bytes: text }, finalizer);
+      return;
+    }
+    if (!completionPreparationCurrent(preparation)) return { message: prependAssistantNotice(event.message,
+      "[Piagent completion gate: NOT APPROVED]\nIndependent verification stopped with the session; no completion or follow-up was scheduled.\n\n") };
+    const currentDigests = workingTreeSnapshot(ctx.cwd) as Record<string, string>, currentDigest = workingTreeEvidenceDigest(currentDigests);
+    if (settleNativeProtectedRefusal({ pi, ctx, task, response: text, currentDigests, enabled: protectedRefusalHandoff && dependencies.nativeRefusalFallbackAllowed?.(ctx, task) === true, dependencies, persistHandoff })) return;
+    const currentPassingVerifierObserved = verificationEvidenceProvesStableTree(latestExactVerifier, currentDigest, currentWorkspaceRevisionDigest(ctx.cwd));
     const handoffAttempt = completionClaim || (
       !incompleteHandoff
       && (task.observedChangedFiles.length > 0 || currentPassingVerifierObserved || readOnlyEvidenceObserved)
@@ -247,7 +234,8 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
           telemetry(ctx, trace);
         }
         if (semanticReviewAllowed(task) && assurance.requiresReview && !reviewReady) {
-          task = writeTask(ctx.cwd, { ...task, changedFiles: projected.changedFiles, acceptanceReceipt: projected.acceptanceReceipt });
+          task = writeTask(ctx.cwd, { ...task, changedFiles: projected.changedFiles, finalWorkingTreeFiles: projected.finalWorkingTreeFiles,
+            finalFileDigests: projected.finalFileDigests, acceptanceReceipt: projected.acceptanceReceipt });
           const reservation = reserveSemanticReviewContinuation(ctx.cwd, task, {
             currentWorkingTreeDigest: currentDigest, expectedPaths: expectedReviewPaths, reasonCodes: assurance.reasonCodes
           });
@@ -275,15 +263,16 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
             return { message: { ...event.message, content } };
           }
           const reviewGate: CompletionGate = { decision: "fail", missing: [`semantic review handoff: ${reservation.reason}`], missingVerifyCommands: [] };
+          const reviewRecovery = terminalRecoveryForContinuationDenial(recoveryDecision(ctx, task, reviewGate, currentDigest), reservation.reason);
           observeTrajectorySync(ctx, syncTrajectory?.(ctx, task, { sourceHook: "completion", handoffObserved: true }), telemetry);
-          persistHandoff(ctx, task, reviewGate, currentDigests, null);
+          persistHandoff(ctx, task, reviewGate, currentDigests, reviewRecovery);
           const handoffTrace = {
             event: "performance_review_handed_off", taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId,
             reason: reservation.reason, progressSignature: reservation.progressSignature,
             globalContinuationConsumed: reservation.consumed, globalContinuationMaximum: reservation.maximum
           };
           appendTrace(ctx.cwd, handoffTrace); appendSessionTrace(pi, handoffTrace); telemetry(ctx, handoffTrace);
-          recordCompletionAudit(ctx, task, { outcome: "blocked", evidence: handoffTrace });
+          recordCompletionAudit(ctx, task, { outcome: "blocked", evidence: { ...handoffTrace, recovery: reviewRecovery } });
           const notice = [
             "[Piagent completion gate: NOT APPROVED]",
             `Task ${task.taskId} cannot schedule another semantic review: ${reservation.reason}; ${review?.activityObserved ? "current-tree review activity was observed but did not produce complete credit" : "no current-tree review activity was observed"}.`,
@@ -296,6 +285,10 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
           return { message: { ...event.message, content } };
         }
         observeTrajectorySync(ctx, syncTrajectory?.(ctx, task, { sourceHook: "completion", handoffObserved: true }), telemetry);
+        const diagnosticProof = projectedGate.acceptanceProof?.mode === "diagnostic" ? projectedGate.acceptanceProof : undefined;
+        const diagnosticNotice = diagnosticProof?.pendingCriterionIds.length
+          ? `Diagnostic acceptance: ${diagnosticProof.pendingCriterionIds.length} criteria remain unproved; no quality claim.` : undefined;
+        if (diagnosticNotice) projected.trace.notes = [projected.trace.notes, diagnosticNotice].filter(Boolean).join("\n");
         projected = withRecoveryProvenance(ctx, projected, projectedGate, currentDigests, null);
         task = writeTask(ctx.cwd, projected);
         observeTrajectorySync(ctx, syncTrajectory?.(ctx, task, { sourceHook: "completion" }), telemetry);
@@ -305,6 +298,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         recordCompletionAudit(ctx, task, {
           outcome: "completed",
           evidence: {
+            ...(diagnosticProof ? { acceptanceProof: diagnosticProof } : {}),
             changedFiles: task.changedFiles,
             lifecycleMode: runtimeLifecycleMode(task)
           }
@@ -312,6 +306,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         persistHandoff(ctx, task, projectedGate, currentDigests, null);
         const trace = {
           event: "task_auto_completed",
+          ...(diagnosticProof ? { acceptanceProof: diagnosticProof } : {}),
           taskId: task.taskId,
           taskRunId: task.taskRunId,
           sessionId: task.sessionId,
@@ -321,21 +316,30 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         appendTrace(ctx.cwd, trace);
         appendSessionTrace(pi, trace);
         telemetry(ctx, trace);
+        if (diagnosticNotice) return { message: prependAssistantNotice(event.message, `[Piagent diagnostic] ${diagnosticNotice}\n`) };
         return;
       }
-      task = writeTask(ctx.cwd, {
-        ...task,
-        changedFiles: projected.changedFiles,
-        acceptanceReceipt: projected.acceptanceReceipt
-      });
+      task = writeTask(ctx.cwd, { ...task, changedFiles: projected.changedFiles, finalWorkingTreeFiles: projected.finalWorkingTreeFiles,
+        finalFileDigests: projected.finalFileDigests, acceptanceReceipt: projected.acceptanceReceipt });
       state.cacheTaskIdentity(ctx, task);
     }
     if (!handoffAttempt || finalGateMode(ctx) !== "enforce") return;
     const gate = completionGate ?? evaluateGate(ctx.cwd, task, currentDigests, currentDigest);
     if (gate.decision === "pass") return;
-
     const selectedRecovery = recoveryDecision(ctx, task, gate, currentDigest);
     const missingAcceptanceProof = gate.missing.some((item) => /^critical acceptance evidence\b/i.test(item));
+    let criticalRecovery: CriticalRecoveryProjection[] = [];
+    if (missingAcceptanceProof) {
+      try {
+        criticalRecovery = acceptanceCriticalRecoveryProjection(task, {
+          cwd: ctx.cwd, apiBaselineEvidence,
+          changedFiles: acceptanceEvidenceFiles(ctx.cwd, task, currentDigests, taskDeltaFilesFromSnapshot(task, currentDigests)),
+          currentWorkingTreeDigest: currentDigest
+        }) as CriticalRecoveryProjection[];
+      } catch {
+        // The exact gate remains authoritative if advisory projection is unavailable.
+      }
+    }
     const lifecycleMode = runtimeLifecycleMode(task);
     const continuation = planRecoveryContinuation(ctx.cwd, task, selectedRecovery, {
       lifecycleMode, currentWorkingTreeDigest: currentDigest, missing: gate.missing, missingVerifyCommands: gate.missingVerifyCommands
@@ -360,24 +364,11 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
           recoveryRequested: true
         }), telemetry);
       }
-      let criticalRecovery: CriticalRecoveryProjection[] = [];
-      if (missingAcceptanceProof) {
-        try {
-          criticalRecovery = acceptanceCriticalRecoveryProjection(task, {
-            cwd: ctx.cwd,
-            changedFiles: taskDeltaFilesFromSnapshot(task, currentDigests),
-            currentWorkingTreeDigest: currentDigest
-          }) as CriticalRecoveryProjection[];
-        } catch {
-          // Exact gate evidence remains the fail-closed fallback when advisory projection is unavailable.
-        }
-      }
-      const criticalRecoveryGuidance = criticalAcceptanceRecoveryGuidance(criticalRecovery);
       const recoveryGuidance = selectedRecovery.action === "repair" && selectedRecovery.sourceMutationAllowed
         ? missingAcceptanceProof
           ? [
             "Continue the same bounded task with one acceptance-proof repair pass.",
-            ...criticalRecoveryGuidance,
+            ...criticalAcceptanceRecoveryGuidance(criticalRecovery),
             "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 repeat a failed hypothesis, expand permission, or perform an external action."
@@ -389,6 +380,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
           ]
         : selectedRecovery.reasonCodes.includes("unknown-diagnostic-pass") || task.changeMode === "read-only" || task.mutationPolicy === "forbidden"
         ? [
+            ...criticalAcceptanceRecoveryGuidance(criticalRecovery, false),
             ...(gate.missingVerifyCommands.length > 0
               ? ["Run only the missing exact verifier commands against the current working tree.", ...verifierInstructions(gate.missingVerifyCommands)]
               : [(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."]),
@@ -400,6 +392,9 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
             "Do not mutate project source, expand permission, or perform an external action during this retry."
           ];
       const otherMissing = gate.missing.filter((item) => !/^critical acceptance evidence\b/i.test(item));
+      const contextReadGuidance = gate.missing.includes("context manifest")
+        ? ["Record the missing context evidence with the native read tool on one relevant source or test region in the task scope (use offset/limit for a large file). Shell inspection and test results do not satisfy this gate. Reuse current-tree passing verification; run only missing or stale verifiers."]
+        : [];
       const missingSummary = criticalRecovery.length > 0
         ? [
           `${criticalRecovery.length} critical acceptance proof target(s)`,
@@ -410,6 +405,8 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         "[Piagent continuation required]",
         `Task ${task.taskId} cannot finish yet. Missing: ${missingSummary}.`,
         `Recovery: ${selectedRecovery.action}; class: ${selectedRecovery.failureCategory}; reasons: ${selectedRecovery.reasonCodes.join(", ")}.`,
+        ...(independentVerificationRecovery(ctx.cwd, task, currentDigest)?.guidance ?? []),
+        ...contextReadGuidance,
         ...recoveryGuidance
       ].join("\n");
       pi.sendMessage(
@@ -452,10 +449,7 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         `Task ${task.taskId} needs one bounded ${selectedRecovery.action} pass before handoff.`,
         ""
       ].join("\n");
-      const content = Array.isArray(event.message.content)
-        ? [{ type: "text" as const, text: continuingNotice }, ...event.message.content]
-        : [{ type: "text" as const, text: `${continuingNotice}${text}` }];
-      return { message: { ...event.message, content } };
+      return { message: prependAssistantNotice(event.message, continuingNotice) };
     }
 
     const finalRecovery = continuation.recovery;
@@ -464,13 +458,13 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
       `Task ${task.taskId} (${task.taskRunId}) is still open.`,
       `Missing: ${gate.missing.join(", ") || "a completed task trace"}.`,
       `Recovery disposition: ${finalRecovery.action} (${finalRecovery.reasonCodes.join(", ")}).`,
+      ...criticalAcceptanceRecoveryGuidance(criticalRecovery, false),
+      ...(independentVerificationRecovery(ctx.cwd, task, currentDigest)?.guidance ?? []),
       ...verifierInstructions(gate.missingVerifyCommands),
       "The response below is preserved as work in progress and must not be treated as a completion report.",
       ""
     ].join("\n");
-    const content = Array.isArray(event.message.content)
-      ? [{ type: "text" as const, text: notice }, ...event.message.content]
-      : [{ type: "text" as const, text: `${notice}${text}` }];
+    const blockedMessage = prependAssistantNotice(event.message, notice);
     const trace = {
       event: "completion_claim_blocked",
       taskId: task.taskId,
@@ -494,7 +488,6 @@ export function registerCompletionHook(pi: ExtensionAPI, dependencies: Completio
         recovery: finalRecovery
       }
     });
-    persistHandoff(ctx, task, gate, currentDigests, finalRecovery);
-    return { message: { ...event.message, content } };
+    persistHandoff(ctx, task, gate, currentDigests, finalRecovery); return { message: blockedMessage };
   });
 }

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

@@ -3,18 +3,24 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { classifyContextTask } from "../../extensions/context-engine.js";
 import { matchesProtectedPath } from "../../extensions/policy-core.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
-import { attachLocalImagesFromText } from "../input/chat-images.ts";
+import { attachLocalImagesFromText, extractLocalImagePathCandidates } from "../input/chat-images.ts";
 import type { ChatImageAccessPolicy } from "../input/chat-images.ts";
 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 {
+  isUncertainSendContinuation,
+  terminalUncertainSendReceipt
+} from "../session/uncertain-send-continuation.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 { activeTaskToolGroups, toolGroupsForPrompt, PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER, PIAGENT_TOOL_GROUPS } from "../tools/tool-groups.ts";
 import type { PiagentToolGroup } from "../tools/tool-groups.ts";
 import type { RuntimeSessionState } from "../session/runtime-state.ts";
+import { observeHostWireInput } from "../session/runtime-state.ts";
 import {
   buildFreshCommand,
+  agentStartTaskRequest,
   chooseFreshWorkflow,
   extractTaskRequest,
   isFreshOrUtilityInput,
@@ -24,6 +30,7 @@ import {
 } from "../workflows/input-routing.ts";
 import {
   automaticTaskIntakeMode,
+  isLightweightNonAuthorizingChangeContinuation,
   manualTaskIntakeEligible
 } from "../workflows/task-intake.ts";
 
@@ -38,6 +45,48 @@ type InputHookDependencies = {
   telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
 };
 
+/** Predict configured input definitions; unknown task or replacement state cannot create an allowed wire state. */
+export function projectPiagentWireInput(input: {
+  text: string; expandedPrompt?: string; source: string; activeTask: TaskContract | null;
+  readProtectedPaths: string[]; currentTools: string[]; availableToolNames: string[];
+  dynamicToolsEnabled: boolean; replacementIntake: boolean; hasImages: boolean; phase?: string | null;
+}): Record<string, any> {
+  const blocked = (reason: string) => ({ disposition: "blocked", reason });
+  if (input.activeTask === undefined || !Array.isArray(input.readProtectedPaths)
+    || typeof input.replacementIntake !== "boolean" || typeof input.dynamicToolsEnabled !== "boolean") return blocked("input-state-unfrozen");
+  const text = input.text.trim();
+  if (input.hasImages !== false || extractLocalImagePathCandidates(text, "/").length > 0) return blocked("input-images-unprojected");
+  if (!text || isFreshOrUtilityInput(text) || /^\/piagent-workflow\b/i.test(text)) return blocked("input-transform-unprojected");
+  if (!["rpc", "interactive", "extension"].includes(input.source)) return blocked("input-source-unfrozen");
+  if (input.source !== "extension" && (looksLikeGovernedBoilerplate(text) || isPiagentWorkflowInput(text)
+    || text.length >= LONG_INPUT_CHARS)) return blocked("input-preflight-unfrozen");
+  const signal = classifyContextTask(text), activeTask = input.activeTask?.trace.outcome === "pending" ? input.activeTask : undefined;
+  const onlyProtected = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
+  const runtimeMode = !activeTask ? automaticTaskIntakeMode(text, input.readProtectedPaths) : undefined;
+  const manual = !activeTask && !runtimeMode && manualTaskIntakeEligible(text, input.readProtectedPaths);
+  const groups = onlyProtected ? [] : toolGroupsForPrompt(text).filter((group) => !runtimeMode || group !== "intake" && group !== "task");
+  if (manual && !groups.includes("intake")) groups.push("intake");
+  const selectedGroups = activeTask ? [...groups.filter((group) => input.replacementIntake || group !== "intake"),
+    ...(input.replacementIntake ? ["intake" as const] : activeTaskToolGroups(activeTask))] : groups;
+  const builtins = input.currentTools.filter((name) => !PIAGENT_TOOL_NAMES.has(name));
+  if (builtins.includes("apply_patch")) {
+    const firstWriter = builtins.findIndex((name) => name === "edit" || name === "write");
+    if (firstWriter >= 0) { builtins.splice(builtins.indexOf("apply_patch"), 1); builtins.splice(builtins.findIndex((name) => name === "edit" || name === "write"), 0, "apply_patch"); }
+  }
+  const selectedTools = input.dynamicToolsEnabled ? [...builtins, ...PIAGENT_TOOL_ORDER.filter((name) =>
+    selectedGroups.some((group) => PIAGENT_TOOL_GROUPS[group].includes(name as never)))] : [...input.currentTools];
+  if (selectedTools.some((name) => !input.availableToolNames.includes(name))) return blocked("tool-definition-missing");
+  const query = agentStartTaskRequest(input.expandedPrompt ?? text), querySignal = classifyContextTask(query);
+  const protectedQuery = querySignal.paths.length > 0 && querySignal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
+  const agentStartRuntimeMode = !activeTask ? automaticTaskIntakeMode(query, input.readProtectedPaths) : undefined;
+  if (runtimeMode || agentStartRuntimeMode || input.replacementIntake) return blocked("automatic-task-state-unprojected");
+  if (activeTask && !input.phase) return blocked("current-task-phase-unfrozen");
+  return { disposition: "known", reason: null, groups: selectedGroups, selectedTools,
+    compactMode: protectedQuery ? "protected" : activeTask?.intakeMode === "runtime" ? "automatic" : null,
+    taskPresence: activeTask ? "current" : "none", phase: activeTask ? input.phase : null,
+    inputHash: signal.promptHash, inputText: text };
+}
+
 export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDependencies): void {
   registerAdaptiveContextGovernor(pi, {
     activeTask: dependencies.activeTask,
@@ -53,13 +102,49 @@ export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDepen
 
     const taskSignal = classifyContextTask(text);
     const sessionTask = dependencies.activeTask(ctx);
-    if (sessionTask && sessionTask.trace.outcome !== "pending") dependencies.state.clearTaskBoundary(ctx, sessionTask.taskRunId);
-    else if (!sessionTask) {
-      const cachedTask = dependencies.state.taskIdentity(ctx);
-      if (cachedTask) dependencies.state.clearTaskBoundary(ctx, cachedTask.taskRunId);
+    const uncertainSendContinuation = (!Array.isArray(event.images) || event.images.length === 0)
+      && isUncertainSendContinuation(text);
+    const terminalReceipt = uncertainSendContinuation
+      ? terminalUncertainSendReceipt(ctx.cwd, sessionTask)
+      : undefined;
+    if (terminalReceipt && event.source !== "extension") {
+      dependencies.telemetry(ctx, {
+        event: "uncertain_send_terminal_receipt_reemitted",
+        source: event.source,
+        promptHash: taskSignal.promptHash,
+        taskId: terminalReceipt.details.taskId,
+        taskRunId: terminalReceipt.details.taskRunId,
+        outcome: terminalReceipt.details.outcome,
+        completionApproved: terminalReceipt.details.completionApproved,
+        replacementTaskStarted: false,
+        replayed: false,
+        modelTurnStarted: false
+      });
+      pi.sendMessage(
+        {
+          customType: terminalReceipt.customType,
+          content: terminalReceipt.content,
+          display: true,
+          details: terminalReceipt.details
+        },
+        { triggerTurn: false }
+      );
+      return { action: "handled" };
+    }
+    if (!uncertainSendContinuation) {
+      if (sessionTask && sessionTask.trace.outcome !== "pending") dependencies.state.clearTaskBoundary(ctx, sessionTask.taskRunId);
+      else if (!sessionTask) {
+        const cachedTask = dependencies.state.taskIdentity(ctx);
+        if (cachedTask) dependencies.state.clearTaskBoundary(ctx, cachedTask.taskRunId);
+      }
     }
     const activeTask = sessionTask?.trace.outcome === "pending" ? sessionTask : undefined;
-    const turn = dependencies.state.beginTurn(ctx, taskSignal.promptHash);
+    const turn = dependencies.state.beginTurn(ctx, taskSignal.promptHash, {
+      lightweightNonAuthorizingChange: isLightweightNonAuthorizingChangeContinuation(text)
+    });
+    observeHostWireInput(ctx.cwd, ctx.sessionManager.getSessionId(), { turnId: turn.turnId,
+      promptHash: taskSignal.promptHash, text, source: event.source,
+      hasImages: Boolean(event.images?.length || extractLocalImagePathCandidates(text, ctx.cwd).length) });
     const authorityPolicy = activeTask?.trace.outcome === "pending" ? dependencies.authorityPolicy(ctx, activeTask) : undefined;
     let authorityHandoffReady = false;
     if (activeTask && authorityPolicy?.disposition === "new-attempt-required") {

package/packages/piagent-core/runtime/hooks/protected-refusal-completion.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import { taskDeltaFilesFromSnapshot } from "../../extensions/task-contract-view.js";
+import { recordCompletionAudit } from "../../extensions/task-runtime-audit.js";
+import { RuntimeSessionState } from "../session/runtime-state.ts";
+import { protectedRefusalHandoffMatches } from "../quality/protected-refusal-handoff.ts";
+import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
+import type { TrajectorySyncOptions, TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
+export { protectedRefusalHandoffMatches } from "../quality/protected-refusal-handoff.ts";
+
+type RefusalGate = { decision: "fail"; missing: string[]; missingVerifyCommands: string[] };
+type Dependencies = {
+  state: RuntimeSessionState;
+  writeTask: (cwd: string, task: TaskContract) => TaskContract;
+  activateBaseTools: (ctx: ExtensionContext) => unknown;
+  appendTrace: (cwd: string, payload: Record<string, unknown>) => void;
+  appendSessionTrace: (pi: ExtensionAPI, payload: Record<string, unknown>) => void;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+  syncTrajectory?: (ctx: ExtensionContext, task: TaskContract, options: TrajectorySyncOptions) => TrajectorySyncResult;
+};
+
+export function nativeProtectedRefusalEligible(task: TaskContract, currentDigests: Record<string, string>): boolean {
+  const changedFiles = taskDeltaFilesFromSnapshot(task, currentDigests);
+  const protectedContextObserved = [...task.contextManifest, ...task.memoryCitations].some((entry) =>
+    matchesProtectedPath(entry.path, task.protectedPaths));
+  return changedFiles.length === 0 && task.observedChangedFiles.length === 0 && !protectedContextObserved;
+}
+
+export function settleNativeProtectedRefusal(input: {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  task: TaskContract;
+  response: string;
+  currentDigests: Record<string, string>;
+  enabled: boolean;
+  dependencies: Dependencies;
+  persistHandoff: (ctx: ExtensionContext, task: TaskContract, gate: RefusalGate,
+    currentDigests: Record<string, string>, recovery: null) => void;
+}): boolean {
+  const { pi, ctx, response, currentDigests, enabled, dependencies, persistHandoff } = input;
+  if (!enabled || !protectedRefusalHandoffMatches(input.task.operatorRequest, response)
+    || !nativeProtectedRefusalEligible(input.task, currentDigests)) return false;
+  const gate: RefusalGate = {
+    decision: "fail",
+    missing: ["operator-directed protected-material request was safely refused"],
+    missingVerifyCommands: []
+  };
+  observeTrajectorySync(ctx, dependencies.syncTrajectory?.(ctx, input.task, {
+    sourceHook: "completion", handoffObserved: true
+  }), dependencies.telemetry);
+  const task = dependencies.writeTask(ctx.cwd, {
+    ...input.task,
+    changedFiles: [],
+    finalWorkingTreeFiles: Object.keys(currentDigests).sort(),
+    finalFileDigests: currentDigests,
+    failureReason: "protected-material-request-refused",
+    trace: {
+      outcome: "blocked",
+      terminalDisposition: "refused",
+      friction: "Protected material access and export were refused without reading or mutating project files.",
+      notes: "Native refusal fallback matched only the operator-declared durable refusal markers.",
+      recordedAt: new Date().toISOString()
+    }
+  });
+  observeTrajectorySync(ctx, dependencies.syncTrajectory?.(ctx, task, { sourceHook: "completion" }), dependencies.telemetry);
+  dependencies.state.clearObservedContext(ctx);
+  dependencies.activateBaseTools(ctx);
+  recordCompletionAudit(ctx, task, {
+    outcome: "blocked",
+    evidence: { terminalDisposition: "refused", changedFiles: [], protectedContextObserved: false }
+  });
+  persistHandoff(ctx, task, gate, currentDigests, null);
+  const trace = {
+    event: "task_policy_refused",
+    taskId: task.taskId,
+    taskRunId: task.taskRunId,
+    sessionId: task.sessionId,
+    terminalDisposition: "refused",
+    changedFiles: []
+  };
+  dependencies.appendTrace(ctx.cwd, trace);
+  dependencies.appendSessionTrace(pi, trace);
+  dependencies.telemetry(ctx, trace);
+  return true;
+}

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

@@ -25,7 +25,7 @@ type SessionHookDependencies = {
   ) => TaskContract | undefined;
   onTurnEnd?: (ctx: ExtensionContext) => void;
   onAgentSettled?: (ctx: ExtensionContext) => void;
-  beforeShutdown?: (ctx: ExtensionContext) => void;
+  beforeShutdown?: (ctx: ExtensionContext) => void | Promise<void>;
 };
 
 export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHookDependencies): void {
@@ -59,6 +59,9 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
     const task = activeTask(ctx.cwd, sessionId);
     if (!task) return;
     const sessionName = String(event.name ?? "").trim() || undefined;
+    // Hosts can announce the existing name again during startup. This is not
+    // a task change and must not rewrite its timestamp or append a journal event.
+    if (task.sessionName === sessionName) return;
     task.sessionName = sessionName;
     const written = writeTask(ctx.cwd, task);
     bindTask(ctx.cwd, sessionId, sessionName, written);
@@ -112,7 +115,7 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
   });
 
   pi.on("session_shutdown", async (event, ctx) => {
-    dependencies.beforeShutdown?.(ctx);
+    await dependencies.beforeShutdown?.(ctx);
     flushObservedTaskContext(
       pi,
       ctx,