@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -67,7 +67,7 @@ import {
 } from "./context-index-policy.js";
 import {
   DEFAULT_MAX_TASK_ATTEMPTS, activeSessionTask, bindSessionTask, createTaskRunId, hasGitEvidenceRoot, listTaskContracts,
-  pathWithinChangeEvidenceRoot, priorTaskAttempts, repositoryFileManifest, resolveTaskContract, safeTaskId, summarizeAttempt, taskContractValidationErrors, taskDigestMigrationArchiveStatus,
+  pathWithinChangeEvidenceRoot, priorTaskAttempts, repositoryFileManifest, repositoryFileManifestDetails, resolveTaskContract, safeTaskId, summarizeAttempt, taskContractValidationErrors, taskDigestMigrationArchiveStatus,
   workPlanDependencyError, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence, writeTaskContract
 } from "./task-state.js";
 import { classifyRecordedVerificationFailure, classifyVerificationFailure, latestObservedVerification, meaningfulVerificationCommands, selectCompletionRecoveryClassification, selectVerificationPlan } from "./verification-intelligence.js";
@@ -84,12 +84,14 @@ import {
   invalidateAcceptanceReceiptAfterMutation,
   refreshAcceptanceReceipt
 } from "./acceptance-receipt.js";
+import { acceptanceLanguageAdapterForPath, isAcceptanceTestPath } from "./acceptance-language-adapters.js";
 import { allVerifyCommandsPassCurrentTree, changedSnapshotFiles, compactTaskDetails, mergeObservedTaskContext, passingVerifyCommandsForDigest, taskDeltaFilesFromSnapshot } from "./task-contract-view.js";
 import { applyRuntimeLifecycleObservation, runtimeLifecycleMode, workingTreeEvidenceDigest } from "./task-lifecycle.js";
 import { completeTaskDigestRefresh } from "./task-digest-migration.js";
 import { WORKING_TREE_DIGEST_ALGORITHM, isCurrentWorkingTreeDigest, workingTreeObservation, workingTreeSnapshotUsesCurrentAlgorithm } from "./working-tree-digest.js";
 import { appendJsonlBounded } from "./state-retention.js";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
+import { hasDurableContextEvidence } from "./context-evidence.js";
 import { piApprovalBroker, type ApprovalActionDraft, type ApprovalUnavailableFallback } from "../runtime/inspection/approval-broker.ts";
 import { inspectTaskControlState } from "../runtime/inspection/task-control-journal.ts";
 import { createSourceMutationGuardBindings } from "../runtime/policy/source-mutation-guard-binding.ts";
@@ -121,6 +123,7 @@ import {
   automaticReviewLenses,
   automaticReadOnlyTaskScope,
   automaticTaskIntakeMode,
+  automaticTaskMutationPolicy,
   automaticTaskRiskLane,
   automaticTaskScope,
   resolveTaskScopePatterns,
@@ -137,6 +140,8 @@ import { registerToolResultHook } from "../runtime/hooks/tool-result-hook.ts";
 import { readRuntimeVersionMetadata, RuntimeSnapshotCapture } from "../runtime/model/runtime-snapshot.ts";
 import { recordRuntimeSnapshotTelemetry } from "../runtime/model/snapshot-telemetry.ts";
 import { captureAuthenticatedModelCatalogFromContext } from "../runtime/model/authenticated-catalog.ts";
+import { normalizeOpenAiCodexReasoningPayload } from "../runtime/model/openai-codex-reasoning.ts";
+import { buildOpenAiCodexWireFingerprint } from "../runtime/model/provider-wire-fingerprint.ts";
 import { ModelRouteRuntime, readModelRouteEvents } from "../runtime/model/model-route-runtime.ts";
 import { parentRoutingModeFromEnvironment, routingObjectiveFromEnvironment } from "../runtime/model/model-route-policy.ts";
 import { ModelSelectionProvenanceTracker } from "../runtime/model/model-selection-provenance.ts";
@@ -147,6 +152,7 @@ import { SolverShadowRuntime, solverModeFromEnvironment } from "../runtime/solve
 import { observeTrajectorySync } from "../runtime/trajectory/trajectory-observability.ts";
 import { TrajectoryRuntime } from "../runtime/trajectory/trajectory-runtime.ts";
 import { PhaseToolRuntime, phaseToolModeFromEnvironment } from "../runtime/tools/phase-tool-runtime.ts";
+import { parseApplyPatchTargets, registerApplyPatchTool } from "../runtime/tools/apply-patch-tool.ts";
 import { authorityReplacementState, ensureTaskAuthorityResumePolicy } from "../runtime/policy/authority-resume-policy.ts";
 import { taskAuthorityDecision } from "../runtime/policy/task-authority-runtime.ts";
 import { selectRecoveryDecision } from "../runtime/recovery/recovery-policy.ts";
@@ -226,6 +232,7 @@ type TaskStartParameters = {
   riskLane: "tiny" | "normal" | "high-risk";
   intakeMode?: "model" | "runtime";
   changeMode?: "source-change" | "read-only";
+  mutationPolicy?: "required" | "forbidden";
   verifyGroup?: string;
   maxAttempts?: number;
   expectedOutput: string;
@@ -424,6 +431,7 @@ const DEFAULT_POLICY: BasePolicy = {
   },
   contextBudget: {
     defaultMode: "enforce",
+    contextDeltaShadow: "sample",
     maxContextFileChars: 50000,
     maxMemoryFileChars: 20000,
     maxManifestFiles: 80,
@@ -472,6 +480,7 @@ const DEFAULT_POLICY: BasePolicy = {
       ls: ["filesystem-readonly"],
       write: ["filesystem-write"],
       edit: ["filesystem-write"],
+      apply_patch: ["filesystem-write"],
       browser: ["browser"],
       github: ["github"]
     }
@@ -1395,6 +1404,7 @@ function evaluatePermissionProfileToolAccess(
 function contextBudgetConfig(policy: BasePolicy): Required<ContextBudgetConfig> {
   return {
     defaultMode: policy.contextBudget?.defaultMode ?? DEFAULT_POLICY.contextBudget?.defaultMode ?? "enforce",
+    contextDeltaShadow: policy.contextBudget?.contextDeltaShadow ?? DEFAULT_POLICY.contextBudget?.contextDeltaShadow ?? "off",
     maxContextFileChars: policy.contextBudget?.maxContextFileChars ?? DEFAULT_POLICY.contextBudget?.maxContextFileChars ?? 50000,
     maxMemoryFileChars: policy.contextBudget?.maxMemoryFileChars ?? DEFAULT_POLICY.contextBudget?.maxMemoryFileChars ?? 20000,
     maxManifestFiles: policy.contextBudget?.maxManifestFiles ?? DEFAULT_POLICY.contextBudget?.maxManifestFiles ?? 80,
@@ -1544,9 +1554,10 @@ function normalizeWorkPlanSteps(values: unknown): WorkPlanStep[] {
 function defaultWorkPlan(
   summary: string,
   riskLane: TaskContract["riskLane"],
-  changeMode: TaskContract["changeMode"]
+  changeMode: TaskContract["changeMode"],
+  mutationPolicy: NonNullable<TaskContract["mutationPolicy"]> = changeMode === "read-only" ? "forbidden" : "required"
 ): WorkPlanStep[] {
-  if (changeMode === "read-only") {
+  if (changeMode === "read-only" || mutationPolicy === "forbidden") {
     if (riskLane === "tiny") {
       return [{
         id: "scout",
@@ -1751,6 +1762,69 @@ function collectPatchTargetPaths(value: unknown, key = "", depth = 0): string[]
   return paths;
 }
 
+type ApplyPatchTargetInspection =
+  | { carrier: false; exactLocalExecutor: false; targets: [] }
+  | { carrier: true; exactLocalExecutor: boolean; targets: string[]; reason?: undefined }
+  | { carrier: true; exactLocalExecutor: boolean; targets: []; reason: string };
+
+function isApplyPatchToolName(toolName: string): boolean {
+  const tokens = new Set(actionTokens(toolName));
+  // Pi direct MCP tools are named <server-prefix>_<tool>, for example
+  // filesystem_apply_patch; they never carry an mcp__ prefix. Treat every
+  // apply+patch action carrier as this exact fail-closed protocol so a custom
+  // prefix cannot bypass target extraction.
+  return tokens.has("apply") && tokens.has("patch");
+}
+
+function inspectApplyPatchAuthorizationTargets(
+  toolName: string,
+  input: Record<string, unknown>
+): ApplyPatchTargetInspection {
+  let carrier = toolName;
+  let payload = input;
+  const exactLocalExecutor = toolName === "apply_patch";
+  if (normalizeActionToken(toolName) === "mcp") {
+    const proxyTool = typeof input.tool === "string" ? input.tool.trim() : "";
+    if (!isApplyPatchToolName(proxyTool)) return { carrier: false, exactLocalExecutor: false, targets: [] };
+    carrier = proxyTool;
+    if (typeof input.args !== "string" || input.args.length > MAX_MCP_PROXY_ARGS_CHARS) {
+      return { carrier: true, exactLocalExecutor: false, targets: [], reason: "MCP apply_patch args must be a bounded JSON object string" };
+    }
+    try {
+      const parsed = JSON.parse(input.args);
+      if (!isPlainRecord(parsed)) return { carrier: true, exactLocalExecutor: false, targets: [], reason: "MCP apply_patch args must decode to a JSON object" };
+      payload = parsed;
+    } catch {
+      return { carrier: true, exactLocalExecutor: false, targets: [], reason: "MCP apply_patch args must be valid JSON" };
+    }
+  }
+  if (!isApplyPatchToolName(carrier)) return { carrier: false, exactLocalExecutor: false, targets: [] };
+  const keys = Object.keys(payload);
+  if (keys.length !== 1 || keys[0] !== "patch" || typeof payload.patch !== "string") {
+    return { carrier: true, exactLocalExecutor, targets: [], reason: "apply_patch input must contain only one string field named patch" };
+  }
+  try {
+    return { carrier: true, exactLocalExecutor, targets: parseApplyPatchTargets(payload.patch) };
+  } catch (error) {
+    return {
+      carrier: true,
+      exactLocalExecutor,
+      targets: [],
+      reason: error instanceof Error ? error.message : "apply_patch target extraction failed"
+    };
+  }
+}
+
+function authorizationMutationTargetInspection(
+  cwd: string,
+  toolName: string,
+  input: Record<string, unknown>
+): { targets: string[]; patchCarrier: boolean; exactLocalPatchExecutor: boolean; reason?: string } {
+  const patch = inspectApplyPatchAuthorizationTargets(toolName, input);
+  if (patch.carrier) return { targets: patch.targets, patchCarrier: true, exactLocalPatchExecutor: patch.exactLocalExecutor, reason: patch.reason };
+  return { targets: taskMutationTargets(cwd, toolName, input), patchCarrier: false, exactLocalPatchExecutor: false };
+}
+
 function taskMutationIdentity(toolName: string, input: Record<string, unknown>): string {
   if (normalizeActionToken(toolName) !== "mcp") return toolName;
   const proxyTool = typeof input.tool === "string" ? input.tool.trim() : "";
@@ -2102,7 +2176,7 @@ function flushObservedTaskContext(
   const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
   if (!task || task.trace.outcome !== "pending") return task;
   const added = mergeObservedTaskContext(task, pendingContext, maxManifestFiles, redactText);
-  const lifecycle = task.changeMode === "read-only" && task.contextManifest.length > 0
+  const lifecycle = (task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && hasDurableContextEvidence(task)
     ? applyRuntimeLifecycleObservation(task, "context-complete", nowIso())
     : { changed: false, mode: runtimeLifecycleMode(task) };
   if (added.length === 0 && !lifecycle.changed) return task;
@@ -2173,9 +2247,13 @@ function prepareToolInputForPolicy(
       return { input, reason: "MCP proxy args must be valid JSON" };
     }
     if (!isPlainRecord(parsed)) return { input, reason: "MCP proxy args must decode to a JSON object" };
-    const patchTargets = actionTokens(proxyTool).includes("patch")
-      ? collectPatchTargetPaths(parsed)
-      : [];
+    const exactPatch = inspectApplyPatchAuthorizationTargets(toolName, input);
+    if (exactPatch.carrier && exactPatch.reason) return { input, reason: exactPatch.reason };
+    const patchTargets = exactPatch.carrier
+      ? exactPatch.targets
+      : actionTokens(proxyTool).includes("patch")
+        ? collectPatchTargetPaths(parsed)
+        : [];
     policyInput = patchTargets.length > 0
       ? { ...input, proxyArgs: parsed, proxyPatchTargets: { paths: patchTargets } }
       : { ...input, proxyArgs: parsed };
@@ -3572,7 +3650,7 @@ function taskScopeIncludesPath(scope: string[], file: string): boolean {
 }
 
 function verifierCommandInstructions(commands: string[]): string[] {
-  return commands.map((command, index) => `Verifier ${index + 1} (run as its own shell call): ${command}`);
+  return commands.map((command, index) => `Verifier ${index + 1} (run as an exact standalone shell command): ${command}`);
 }
 
 function evaluateTaskGate(
@@ -3605,7 +3683,7 @@ function evaluateTaskGate(
   if (task.attempt > task.maxAttempts) missing.push(`attempt within maxAttempts (${task.attempt}/${task.maxAttempts})`);
   const plannedVerifyCommands = meaningfulVerificationCommands(task.verifyCommands);
   if (task.changeMode === "source-change" && plannedVerifyCommands.length === 0) missing.push("meaningful verify command");
-  if (finalGate.requireContextManifest && task.contextManifest.length === 0) missing.push("context manifest");
+  if (finalGate.requireContextManifest && !hasDurableContextEvidence(task)) missing.push("context manifest");
   if (task.changeMode === "source-change" && finalGate.requireVerifyEvidence && task.verifyEvidence.length === 0) missing.push("verify evidence");
   if (task.verifyEvidence.some((evidence) => evidence.observed !== true)) {
     warnings.push("Unobserved verify evidence is ignored by the passing verify gate.");
@@ -3632,14 +3710,14 @@ function evaluateTaskGate(
     missing.push(`completed work plan (${incompleteSteps.map((step) => `${step.id}:${step.status}`).join(", ")})`);
   }
   const changedFileEvidence = taskChangedFileEvidence(cwd, task, currentDigests);
-  if (task.changeMode === "source-change" && task.trace.outcome === "completed") {
+  if (task.changeMode === "source-change" && task.trace.outcome === "completed" && task.mutationPolicy !== "forbidden") {
     if (task.changedFiles.length === 0) missing.push("changed files");
     if (changedFileEvidence.undeclared.length > 0) missing.push(`declared observed changes (${changedFileEvidence.undeclared.join(", ")})`);
     if (changedFileEvidence.unsupportedClaims.length > 0) missing.push(`supported changed-file claims (${changedFileEvidence.unsupportedClaims.join(", ")})`);
     if (changedFileEvidence.outsideScope.length > 0) missing.push(`changes within task scope (${changedFileEvidence.outsideScope.join(", ")})`);
   }
-  if (task.changeMode === "read-only" && changedFileEvidence.expected.length > 0) {
-    missing.push(`read-only task has observed changes (${changedFileEvidence.expected.join(", ")})`);
+  if ((task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && changedFileEvidence.expected.length > 0) {
+    missing.push(`mutation-forbidden task has observed changes (${changedFileEvidence.expected.join(", ")})`);
   }
   const acceptance = refreshAcceptanceReceipt(task, {
     cwd,
@@ -3867,6 +3945,55 @@ export default function piagentGuard(pi: ExtensionAPI) {
   pi.on("thinking_level_select", (_event, ctx) => {
     modelSelectionProvenance.observeThinkingSelection(ctx.sessionManager.getSessionId());
   });
+  pi.on("before_provider_request", (event, ctx) => {
+    const normalized = normalizeOpenAiCodexReasoningPayload({
+      payload: event.payload,
+      provider: ctx.model?.provider,
+      modelId: ctx.model?.id,
+      hostThinkingLevel: pi.getThinkingLevel()
+    });
+    if (normalized.applicable) {
+      telemetry(ctx, {
+        event: "provider_request_reasoning",
+        hostThinkingLevel: normalized.hostThinkingLevel,
+        providerReasoningEffort: normalized.providerEffort,
+        expectedProviderReasoningEffort: normalized.expectedProviderEffort,
+        providerReasoningEffortMatches: normalized.providerEffort === normalized.expectedProviderEffort,
+        providerReasoningNormalized: normalized.changed,
+        providerReasoningReasonCode: normalized.reasonCode
+      });
+    }
+    const wire = buildOpenAiCodexWireFingerprint({
+      payload: normalized.changed ? normalized.payload : event.payload,
+      provider: ctx.model?.provider,
+      modelId: ctx.model?.id,
+      workingDirectory: ctx.cwd,
+      platformRoot: PLATFORM_ROOT
+    });
+    if (wire.applicable) {
+      telemetry(ctx, {
+        event: "provider_request_wire_surface",
+        state: wire.state,
+        reasonCode: wire.reasonCode,
+        providerModelId: wire.modelId,
+        instructionsHash: wire.instructionsHash,
+        baseInstructionsHash: wire.baseInstructionsHash,
+        instructionNormalization: wire.instructionNormalization,
+        instructionChars: wire.instructionChars,
+        orderedToolSurfaceHash: wire.orderedToolSurfaceHash,
+        providerToolCount: wire.toolCount,
+        deferredToolSurfaceHash: wire.deferredToolSurfaceHash,
+        deferredToolCount: wire.deferredToolCount,
+        deferredToolBatchCount: wire.deferredToolBatchCount,
+        providerReasoningEffort: wire.reasoningEffort,
+        providerTextVerbosity: wire.textVerbosity,
+        providerToolChoiceKind: wire.toolChoiceKind,
+        providerToolChoiceHash: wire.toolChoiceHash,
+        requestPrefixFingerprint: wire.requestPrefixFingerprint
+      });
+    }
+    return normalized.changed ? normalized.payload : undefined;
+  });
 
   function freshModelRouteBoundary(ctx: ExtensionContext): boolean {
     try {
@@ -3928,7 +4055,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       let taskIdentity = runtimeState.taskIdentity(ctx);
       if (!taskIdentity) {
         const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
-        if (task) {
+        if (task?.trace.outcome === "pending") {
           runtimeState.cacheTaskIdentity(ctx, task);
           taskIdentity = { taskId: task.taskId, taskRunId: task.taskRunId };
         }
@@ -4080,7 +4207,8 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const snapshot = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
       const resume = workingTreeSnapshotHasUnavailableEvidence(snapshot)
         ? { openRepair: false }
-        : { openRepair: taskAuthorityDecision(task, "CAP-13", "block").allowed && semanticRepairRuntime.resume({
+        : { openRepair: (taskAuthorityDecision(task, "CAP-13", "block").allowed
+          || taskAuthorityDecision(task, "CAP-12", "mutate").allowed) && semanticRepairRuntime.resume({
             cwd: ctx.cwd,
             task,
             sessionId: ctx.sessionManager.getSessionId(),
@@ -4115,6 +4243,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
   });
 
   registerInputHook(pi, {
+    state: runtimeState,
     boilerplateCollapseChars: BOILERPLATE_COLLAPSE_CHARS,
     activeTask: (ctx) => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined, authorityPolicy: (ctx, task) => ensureTaskAuthorityResumePolicy(ctx.cwd, task, { authorityProfile: loadProfileFromContext(ctx).authorityProfile, environment: process.env }),
     readProtectedPaths: (ctx) => effectiveProtectedPaths(policy, loadProfileFromContext(ctx)).readProtectedPaths,
@@ -4141,6 +4270,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
   registerAgentStartHook(pi, {
     state: runtimeState,
     autoContextEnabled,
+    contextDeltaShadowMode: contextBudgetConfig(policy).contextDeltaShadow,
     activeTask: (ctx) => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined,
     readProtectedPaths: (ctx) => effectiveProtectedPaths(policy, loadProfileFromContext(ctx)).readProtectedPaths,
     contextExcludePatterns: (ctx) => contextIndexExcludePatterns(policy, loadProfileFromContext(ctx)),
@@ -4168,7 +4298,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     completionProjection: completionTaskProjection,
     evaluateGate: (cwd, task, currentDigests, currentDigest) => {
       const gate = evaluateTaskGate(cwd, task, policy, { currentDigests, currentWorkingTreeDigest: currentDigest });
-      const repairBlock = taskAuthorityDecision(task, "CAP-13", "block").allowed ? semanticRepairRuntime.completionBlock(cwd, task.taskRunId) : undefined;
+      const repairBlock = (taskAuthorityDecision(task, "CAP-13", "block").allowed
+        || taskAuthorityDecision(task, "CAP-12", "mutate").allowed)
+        ? semanticRepairRuntime.completionBlock(cwd, task.taskRunId)
+        : undefined;
       return repairBlock ? { ...gate, decision: "fail", missing: [...new Set([...gate.missing, repairBlock])] } : gate;
     },
     writeTask,
@@ -4187,6 +4320,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     state: runtimeState,
     activeTask: (ctx) => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined,
     maxManifestFiles: contextBudgetConfig(policy).maxManifestFiles,
+    flushObservedTaskContext,
     readProtectedPaths: (ctx) => effectiveProtectedPaths(policy, loadProfileFromContext(ctx)).readProtectedPaths,
     recordObservedBash: (observed) => bashResults.record(observed),
     observedBashLedgerPath,
@@ -4202,7 +4336,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     now: nowIso,
     completeSemanticRepair: (ctx, event, metadata) => {
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
-      return task && taskAuthorityDecision(task, "CAP-13", "mutate").allowed ? semanticRepairRuntime.complete(ctx, task, event, metadata) : undefined;
+      return task && (taskAuthorityDecision(task, "CAP-13", "mutate").allowed
+        || taskAuthorityDecision(task, "CAP-12", "mutate").allowed)
+        ? semanticRepairRuntime.complete(ctx, task, event, metadata)
+        : undefined;
     },
     syncTrajectory: (ctx, contextObserved) => {
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
@@ -4216,10 +4353,19 @@ export default function piagentGuard(pi: ExtensionAPI) {
     telemetry,
     activity: recordActivity,
     beforeAuthorize: (event, ctx) => {
-      if (!["edit", "write", "apply_patch"].includes(event.toolName)) return;
+      const toolInput = isPlainRecord(event.input) ? event.input : {};
+      const targetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, toolInput);
+      if (targetInspection.reason) return { block: true, reason: `Blocked ${event.toolName}: ${targetInspection.reason}.` };
+      if (!["edit", "write"].includes(event.toolName) && !targetInspection.exactLocalPatchExecutor) return;
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
       if (!task || task.trace.outcome !== "pending" || task.changeMode !== "source-change") return;
-      if (!taskAuthorityDecision(task, "CAP-13", "mutate").allowed) return;
+      const semanticRepairEnabled = taskAuthorityDecision(task, "CAP-13", "mutate").allowed;
+      const semanticRepairExactlyOff = !taskAuthorityDecision(task, "CAP-13", "observe").allowed;
+      const boundedRecoveryEnabled = autoRecoveryEnabled
+        && taskAuthorityDecision(task, "CAP-09", "block").allowed
+        && taskAuthorityDecision(task, "CAP-12", "mutate").allowed
+        && semanticRepairExactlyOff;
+      if (!semanticRepairEnabled && !boundedRecoveryEnabled) return;
       const phase = trajectoryRuntime.status(ctx.cwd, task.taskRunId);
       if (!phase.enforcementSafe || !["verify", "review"].includes(String(phase.phase))) return;
 
@@ -4227,16 +4373,41 @@ export default function piagentGuard(pi: ExtensionAPI) {
       if (workingTreeSnapshotHasUnavailableEvidence(currentSnapshot)) return;
       const currentDigest = workingTreeEvidenceDigest(currentSnapshot);
       const expectedReviewPaths = taskDeltaFilesFromSnapshot(task, currentSnapshot);
-      const toolInput = isPlainRecord(event.input) ? event.input : {};
-      const targets = taskMutationTargets(ctx.cwd, event.toolName, toolInput);
+      const targets = targetInspection.targets;
       const boundedInScopeMutation = targets.length > 0
         && targets.every((file) => taskScopeIncludesPath(task.scope, file));
+      const verifierCurrent = allVerifyCommandsPassCurrentTree(task, currentDigest);
 
-      if (phase.phase === "verify" && boundedInScopeMutation && semanticRepairRuntime.prepare({
+      if (phase.phase === "verify" && boundedInScopeMutation && semanticRepairEnabled && semanticRepairRuntime.prepare({
         ctx, task, event, currentDigest, currentDeltaPaths: expectedReviewPaths, targetPaths: targets,
-        verifierCurrent: allVerifyCommandsPassCurrentTree(task, currentDigest)
+        verifierCurrent
       })) return;
 
+      // A public verifier can pass before every explicit user criterion is
+      // covered. CAP-12 therefore reserves one exact structured call when the
+      // model catches its own omission in the same task/run/session. The call
+      // still traverses every normal authorization check; verify -> repair is
+      // committed only by the tool-result hook after a successful tree change.
+      if (phase.phase === "verify" && boundedRecoveryEnabled && verifierCurrent && boundedInScopeMutation) {
+        const authoredFileDigests = runtimeState.successfulModelMutationDigests(
+          { taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId },
+          currentSnapshot
+        );
+        if (semanticRepairRuntime.prepareBoundedRecovery({
+          ctx,
+          task,
+          event,
+          currentDigest,
+          currentDeltaPaths: expectedReviewPaths,
+          observedChangedPaths: task.observedChangedFiles,
+          authoredFileDigests,
+          targetPaths: targets,
+          verifierCurrent
+        })) return;
+      }
+
+      if (!semanticRepairEnabled) return;
+
       let checkpoint = runtimeState.performanceReviewCheckpoint(task.taskRunId);
       const checkpointReady = checkpoint?.workingTreeDigest === currentDigest
         && checkpoint.reviewSatisfied
@@ -4286,8 +4457,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const currentDigest = workingTreeEvidenceDigest(workingTreeSnapshot(ctx.cwd) as Record<string, string>);
       const phase = trajectoryRuntime.status(ctx.cwd, task.taskRunId);
       const toolInput = isPlainRecord(event.input) ? event.input : {};
-      const targets = taskMutationTargets(ctx.cwd, event.toolName, toolInput);
-      if (["edit", "write", "apply_patch"].includes(event.toolName) && (
+      const targetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, toolInput);
+      if (targetInspection.reason) return { block: true, reason: `Blocked ${event.toolName}: ${targetInspection.reason}.` };
+      const targets = targetInspection.targets;
+      if ((["edit", "write"].includes(event.toolName) || targetInspection.patchCarrier) && (
         targets.length === 0 || targets.some((file) => !taskScopeIncludesPath(task.scope, file))
       )) {
         runtimeState.denyPerformanceReviewTool(task.taskRunId);
@@ -4361,6 +4534,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
     authorize: async (event, ctx) => {
     const preTask = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
     const preInput = isPlainRecord(event.input) ? event.input : {};
+    const authorizationTargetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, preInput);
+    if (authorizationTargetInspection.reason) {
+      return { block: true, reason: `Blocked ${event.toolName}: ${authorizationTargetInspection.reason}.` };
+    }
+    const authorizationTargets = authorizationTargetInspection.targets;
     const preSnapshot = preTask ? workingTreeSnapshot(ctx.cwd) as Record<string, string> : undefined;
     const reservedFirstCall = Boolean(preTask && preSnapshot && !workingTreeSnapshotHasUnavailableEvidence(preSnapshot) && semanticRepairRuntime.reservedCallMatches({
       cwd: ctx.cwd,
@@ -4369,7 +4547,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       toolCallId: String(event.toolCallId),
       toolName: event.toolName,
       currentDigest: workingTreeEvidenceDigest(preSnapshot),
-      targetPaths: taskMutationTargets(ctx.cwd, event.toolName, preInput)
+      targetPaths: authorizationTargets
     }));
     const phaseDecision = reservedFirstCall || (preTask?.workingTreeDigestMigration?.status === "verification-refresh-required" && SHELL_TOOL_NAMES.has(event.toolName)) ? undefined : phaseToolRuntime.toolDecision(ctx, event.toolName);
     if (phaseDecision) return phaseDecision;
@@ -4427,10 +4605,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const taskContractRequired = governedTaskProfile
       && runtime.finalGate === "enforce"
       && finalGateConfig(policy).requireTaskContract;
-    if (sessionTask?.trace.outcome === "pending" && sessionTask.changeMode === "read-only" && !SHELL_TOOL_NAMES.has(event.toolName) && isTaskMutationTool(event.toolName, toolInput)) {
+    if (sessionTask?.trace.outcome === "pending" && (sessionTask.changeMode === "read-only" || sessionTask.mutationPolicy === "forbidden")
+      && !SHELL_TOOL_NAMES.has(event.toolName) && isTaskMutationTool(event.toolName, toolInput)) {
       return {
         block: true,
-        reason: `Task ${sessionTask.taskId} is read-only; ${event.toolName} cannot mutate project or external state in this task. Start a source-change task for implementation.`
+        reason: `Task ${sessionTask.taskId} ${sessionTask.changeMode === "read-only" ? "is read-only" : "forbids source mutation"}; ${event.toolName} cannot mutate project or external state in this task. Start a mutation-required source task for implementation.`
       };
     }
     const preparedInput = prepareToolInputForPolicy(event.toolName, toolInput, policy);
@@ -4473,10 +4652,13 @@ export default function piagentGuard(pi: ExtensionAPI) {
           && !candidate.startsWith("../")
           && !candidate.startsWith(".pi/piagent-state/")
         ));
-      if (sessionTask?.trace.outcome === "pending" && sessionTask.changeMode === "read-only" && !isReadOnlyTaskShellCommand(command, execDecision.segments)) {
+      const mutationForbidden = sessionTask?.trace.outcome === "pending"
+        && (sessionTask.changeMode === "read-only" || sessionTask.mutationPolicy === "forbidden");
+      const exactForbiddenTaskVerifier = mutationForbidden && sessionTask.changeMode === "source-change" && configuredVerifierShell;
+      if (mutationForbidden && !exactForbiddenTaskVerifier && !isReadOnlyTaskShellCommand(command, execDecision.segments)) {
         return {
           block: true,
-          reason: `Task ${sessionTask.taskId} is read-only; this shell command is not in the read-only inspection allowlist.`
+          reason: `Task ${sessionTask.taskId} ${sessionTask.changeMode === "read-only" ? "is read-only; this shell command is not in the read-only inspection allowlist" : "forbids source mutation; this shell command is neither bounded inspection nor an exact configured verifier"}.`
         };
       }
       if (execDecision.mode !== "off" && execDecision.decision === "forbid") {
@@ -4533,18 +4715,21 @@ export default function piagentGuard(pi: ExtensionAPI) {
     // Shell inputs need command grammar, not field-by-field path guessing: an
     // exclusion selector in `args` is not an accessed path. The semantic shell
     // checks above already inspect the normalized command, including redirects.
+    const policyPathInput = authorizationTargetInspection.patchCarrier
+      ? { paths: authorizationTargets }
+      : preparedInput.input;
     const pathDecision = SHELL_TOOL_NAMES.has(event.toolName) ? { block: false, reason: undefined } : evaluatePathLikeToolAccess(
       ctx.cwd,
       preparedInput.proxyToolName ?? event.toolName,
-      preparedInput.input,
+      policyPathInput,
       pathPolicy.writeProtectedPaths,
       pathPolicy.readProtectedPaths,
       pathPolicy.readOnlyPaths,
       permissionProfile.mode === "trusted-full-access" ? undefined : capabilityState.filesystemRead,
       permissionProfile.mode === "trusted-full-access" ? undefined : capabilityState.filesystemWrite,
       {
-        forceScopeAware: Boolean(preparedInput.proxyToolName),
-        forceWrite: preparedInput.proxyAction?.decision === "confirm",
+        forceScopeAware: authorizationTargetInspection.patchCarrier || Boolean(preparedInput.proxyToolName),
+        forceWrite: authorizationTargetInspection.patchCarrier || preparedInput.proxyAction?.decision === "confirm",
         allowAmbiguousFilesystemContentFields: !usesKnownExternalProvider && !isPiagentTool(event.toolName)
       }
     );
@@ -4573,7 +4758,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
 
     const mutationTargets = SHELL_TOOL_NAMES.has(event.toolName)
       ? shellMutationTargets
-      : taskMutationTargets(ctx.cwd, event.toolName, toolInput);
+      : authorizationTargets;
     const directProjectMutation = !SHELL_TOOL_NAMES.has(event.toolName) && (
       WRITE_TOOL_NAMES.has(event.toolName)
       || mutationTargets.length > 0
@@ -4597,7 +4782,9 @@ export default function piagentGuard(pi: ExtensionAPI) {
           opaqueCarrier: semanticOpaqueCarrier,
           targetExtractionComplete: SHELL_TOOL_NAMES.has(event.toolName)
             ? !shellHasOpaqueWritePrimitive(authorizedShellCommand)
-            : !semanticOpaqueCarrier && preparedInput.proxyShellCarrier !== true,
+            : authorizationTargetInspection.patchCarrier
+              ? authorizationTargetInspection.exactLocalPatchExecutor
+              : !semanticOpaqueCarrier && preparedInput.proxyShellCarrier !== true,
           recordedAt: nowIso()
         })
       : { handled: false, allowed: false, bypassPhase: false };
@@ -4656,10 +4843,12 @@ export default function piagentGuard(pi: ExtensionAPI) {
         };
       }
     }
-    if (runtime.contextBudget !== "off" && ["write", "edit"].includes(event.toolName)) {
-      const relativePath = extractLikelyPathFromInput(ctx.cwd, event.input as Record<string, unknown>);
-      if (relativePath) {
-        const budget = contextBudgetConfig(policy);
+    if (runtime.contextBudget !== "off" && (["write", "edit"].includes(event.toolName) || authorizationTargetInspection.patchCarrier)) {
+      const budgetTargets = authorizationTargetInspection.patchCarrier
+        ? authorizationTargets
+        : [extractLikelyPathFromInput(ctx.cwd, preInput)].filter((item): item is string => Boolean(item));
+      const budget = contextBudgetConfig(policy);
+      for (const relativePath of budgetTargets) {
         const stats = candidateFileBudget(ctx.cwd, relativePath, budget);
         if (runtime.contextBudget === "enforce" && stats.exists && stats.overLimit) {
           return { block: true, reason: `Context budget blocked editing large file ${relativePath}: ${stats.chars} chars > ${budget.maxContextFileChars}` };
@@ -4688,13 +4877,16 @@ export default function piagentGuard(pi: ExtensionAPI) {
     }
     }
   });
+  // Register only after authorization is live. The same-name override is intentional:
+  // guard target parsing, provenance, and atomicity require this exact tool contract.
+  registerApplyPatchTool(pi, Type);
   const registrationDeps = {
     CONTEXT_INDEX_EDGE_KINDS, CONTEXT_INDEX_NODE_KINDS, DEFAULT_MAX_TASK_ATTEMPTS, FRESH_COMMAND_ACTIONS, FRESH_COMMAND_HELP,
     ONBOARDING_COMMAND_ACTIONS, ORCHESTRATION_ROLES, PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, REVIEW_LENSES,
     StringEnum, TECH_STACK_MANIFEST_FILE, TOOL_RESULT_CAPTURE_MAX_CHARS, TOOL_RESULT_COMPACT_CHAR_THRESHOLD, TOOL_RESULT_COMPACT_LINE_THRESHOLD,
     TOOL_RESULT_PREVIEW_MAX_CHARS, Type, WORKFLOW_COMMAND_EXCLUSIONS, activateToolGroups, activeSessionTask,
     activeTaskToolGroups, allVerifyCommandsPassCurrentTree, appendMemoryNote, appendSessionTrace, appendTrace,
-    acceptanceBaselineGuidance, acceptanceProofGuidance, applyAcceptanceRecoveryProvenance, applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskRiskLane, automaticTaskScope,
+    acceptanceBaselineGuidance, acceptanceLanguageAdapterForPath, acceptanceProofGuidance, applyAcceptanceRecoveryProvenance, applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskMutationPolicy, automaticTaskRiskLane, automaticTaskScope,
     bashResults, bindSessionTask, buildAcceptanceReceipt, buildContextEfficiencyReport, buildContextIndexStatus, buildLiveTaskStatus, buildTaskEfficiencyMetrics,
     buildContextIndexV2, buildContextPack, buildContextPreflight, buildProfileOptions, buildProfileTechOptions,
     buildTestImpact, buildUsageSnapshot, candidateFileBudget, checkoutReferenceRepo, classifyContextTask,
@@ -4706,7 +4898,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     extensionDir, externalActionPolicyConfig, extractDocument, finalGateConfig, findMatchingObservedBashResult,
     formatContextPreflight, formatCount, formatLiveTaskStatus, formatPercent, formatTechOptionsText, formatTechSelectionSummary,
     formatToolResultCaptureStatus, formatUsageSnapshot, fs, hasGitEvidenceRoot, hasOperatorSessionName, helpersMode,
-    loadProfileFromContext, matchesAnyPath, matchesProtectedPath, mcpActions, mcpApprovalCache,
+    isAcceptanceTestPath, loadProfileFromContext, matchesAnyPath, matchesProtectedPath, mcpActions, mcpApprovalCache,
     memoryHandbookPath, memoryLocalDir, memorySummaryPath, normalizeProjectProfileName, normalizeRelative,
     normalizeReviewLenses, normalizeTechSelections, normalizeWorkPlanSteps, nowIso, observedBashLedgerPath,
     path, permissionOverrideFromContext, permissionProfilesConfig, policy, prefixCompletions,
@@ -4724,7 +4916,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     techContextDirPath, techContextFilePath, techContextRelativePath, techOptionById, techStackPath,
     telemetry, toolRegistryConfig, trajectoryRuntime, uniqueStrings, usageExactCommands,
     validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, verifyProjectCapabilityState, workingTreeEvidenceDigest,
-    repositoryFileManifest, resolveTaskScopePatterns,
+    repositoryFileManifest, repositoryFileManifestDetails, resolveTaskScopePatterns,
     workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence, writeContextIndex, writeProfileDocumentWithLock, writeProfileFromAdapter, writeProjectOnboarding,
     writeTask, writeTechStackSelection
   };

package/packages/piagent-core/extensions/task-contract-view.js

@@ -1,4 +1,5 @@
 import { acceptanceReceiptProvenanceSummary, acceptanceReceiptSummary } from "./acceptance-receipt.js";
+import { isDurableContextEvidenceEntry } from "./context-evidence.js";
 import { runtimeLifecycleMode } from "./task-lifecycle.js";
 import { latestObservedVerificationEvidence, meaningfulVerificationCommands, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
 import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM } from "./working-tree-digest.js";
@@ -25,6 +26,7 @@ export function compactTaskDetails(task) {
     sessionId: task.sessionId,
     sessionName: task.sessionName,
     changeMode: task.changeMode,
+    mutationPolicy: task.mutationPolicy ?? (task.changeMode === "read-only" ? "forbidden" : "required"),
     attempt: task.attempt,
     maxAttempts: task.maxAttempts,
     previousAttempts: task.previousAttempts,
@@ -51,12 +53,24 @@ export function compactTaskDetails(task) {
 }
 
 export function mergeObservedTaskContext(task, entries, maxManifestFiles, redact = (value) => String(value ?? "")) {
-  const known = new Set((task.contextManifest ?? []).map((item) => item.path));
+  const known = new Map((task.contextManifest ?? []).map((item, index) => [item.path, index]));
+  let durableCount = (task.contextManifest ?? []).filter(isDurableContextEvidenceEntry).length;
   const added = [];
   for (const entry of entries ?? []) {
-    if (task.contextManifest.length >= maxManifestFiles || known.has(entry.path)) continue;
+    const existingIndex = known.get(entry.path);
+    if (existingIndex !== undefined) {
+      const existing = task.contextManifest[existingIndex];
+      if (isDurableContextEvidenceEntry(existing) || !isDurableContextEvidenceEntry(entry)) continue;
+      if (durableCount >= maxManifestFiles) continue;
+      task.contextManifest[existingIndex] = { path: entry.path, reason: redact(entry.reason) };
+      durableCount += 1;
+      added.push(entry.path);
+      continue;
+    }
+    if (durableCount >= maxManifestFiles || !isDurableContextEvidenceEntry(entry)) continue;
     task.contextManifest.push({ path: entry.path, reason: redact(entry.reason) });
-    known.add(entry.path);
+    durableCount += 1;
+    known.set(entry.path, task.contextManifest.length - 1);
     added.push(entry.path);
   }
   return added;

package/packages/piagent-core/extensions/task-lifecycle.js

@@ -31,16 +31,20 @@ const ASSISTED_READ_ONLY_PLAN = [
   { id: "review", role: "piagent-reviewer", mode: "review", dependsOn: ["scout"] }
 ];
 
+function mutationForbidden(task) {
+  return task?.changeMode === "read-only" || task?.mutationPolicy === "forbidden";
+}
+
 export function runtimeLifecycleMode(task) {
   if (!Array.isArray(task?.workPlan)) return "manual";
   if (
-    task.changeMode === "read-only"
+    mutationForbidden(task)
     && (task.riskLane === "tiny" || (task.intakeMode === "runtime" && task.riskLane === "normal"))
     && task.workPlan.length === AUTOMATIC_READ_ONLY_PLAN.length
     && task.workPlan.every((step, index) => matchesStep(step, AUTOMATIC_READ_ONLY_PLAN[index]))
   ) return "automatic-readonly";
   if (
-    task.changeMode === "read-only"
+    mutationForbidden(task)
     && task.riskLane === "normal"
     && task.workPlan.length === ASSISTED_READ_ONLY_PLAN.length
     && task.workPlan.every((step, index) => matchesStep(step, ASSISTED_READ_ONLY_PLAN[index]))
@@ -68,6 +72,7 @@ function nonEmptyStrings(value) {
 function sourceContractReady(task) {
   return task?.schemaVersion === 2
     && task.changeMode === "source-change"
+    && task.mutationPolicy !== "forbidden"
     && task.trace?.outcome === "pending"
     && nonEmptyStrings(task.acceptanceCriteria)
     && nonEmptyStrings(task.scope)