@piagent/platform 1.5.4 → 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,13 +84,15 @@ 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 { piApprovalBroker, type ApprovalActionDraft } from "../runtime/inspection/approval-broker.ts";
+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";
 import {
@@ -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"]
     }
@@ -1090,6 +1099,20 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return prototype === Object.prototype || prototype === null;
 }
 
+function approvalUnavailableFallback(ctx: Pick<ExtensionContext, "ui">): ApprovalUnavailableFallback {
+  // The symbol is a cross-package runtime marker, not an import, so piagent-core
+  // remains independent of the WebUI package. A Gateway has no interactive
+  // terminal behind `ctx.ui.confirm`; if brokering is unavailable it must fail
+  // closed immediately instead of awaiting an impossible terminal response.
+  try {
+    return Reflect.get(ctx.ui as object, Symbol.for("piagent.webui.gateway-runtime-ui.v1")) === true
+      ? "deny"
+      : "terminal-confirm";
+  } catch {
+    return "terminal-confirm";
+  }
+}
+
 function evaluatePathLikeToolAccess(
   cwd: string,
   toolName: string,
@@ -1381,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,
@@ -1530,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",
@@ -1737,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() : "";
@@ -2088,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;
@@ -2159,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 };
@@ -3558,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(
@@ -3591,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.");
@@ -3618,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,
@@ -3853,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 {
@@ -3914,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 };
         }
@@ -4066,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(),
@@ -4101,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,
@@ -4127,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)),
@@ -4154,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,
@@ -4173,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,
@@ -4188,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;
@@ -4202,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;
 
@@ -4213,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
@@ -4272,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);
@@ -4347,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,
@@ -4355,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;
@@ -4413,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);
@@ -4459,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") {
@@ -4519,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)
       }
     );
@@ -4559,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
@@ -4583,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 };
@@ -4596,7 +4797,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     });
     if (phaseMutationDecision) return phaseMutationDecision;
     if (pendingHumanApproval && !sessionTask) {
-      const approval = await piApprovalBroker.request({ cwd: ctx.cwd, rawSessionId: ctx.sessionManager.getSessionId(), toolCallId: String(event.toolCallId), expectedTask: null, action: { ...pendingHumanApproval.action, preconditionClass: "runtime-only", treePrecondition: null }, terminalConfirm: () => ctx.ui.confirm(pendingHumanApproval!.prompt, pendingHumanApproval!.title) });
+      const approval = await piApprovalBroker.request({ cwd: ctx.cwd, rawSessionId: ctx.sessionManager.getSessionId(), toolCallId: String(event.toolCallId), expectedTask: null, action: { ...pendingHumanApproval.action, preconditionClass: "runtime-only", treePrecondition: null }, terminalConfirm: () => ctx.ui.confirm(pendingHumanApproval!.prompt, pendingHumanApproval!.title), unavailableFallback: approvalUnavailableFallback(ctx) });
       if (!approval.allowed) return { block: true, reason: pendingHumanApproval.action.kind === "external-provider-action" && !SHELL_TOOL_NAMES.has(event.toolName) ? `User denied external provider action: ${event.toolName}` : `User denied command: ${pendingHumanApproval.action.reason}` };
       pendingHumanApproval = null;
     }
@@ -4642,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}` };
@@ -4659,6 +4862,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
         : { workspaceRevision: `workspace-rev.${crypto.createHash("sha256").update(currentTreeDigest).digest("hex")}`, indexRevision: null, preimageDigest: currentTreeDigest };
       const approval = await piApprovalBroker.request({ cwd: ctx.cwd, rawSessionId: ctx.sessionManager.getSessionId(), toolCallId: String(event.toolCallId), expectedTask: sessionTask ? { taskId: sessionTask.taskId, taskRunId: sessionTask.taskRunId } : null,
         action: { ...pendingHumanApproval.action, treePrecondition }, terminalConfirm: () => ctx.ui.confirm(pendingHumanApproval!.prompt, pendingHumanApproval!.title),
+        unavailableFallback: approvalUnavailableFallback(ctx),
         recheck: () => !treePrecondition || (() => { const current = workingTreeSnapshot(ctx.cwd);
           return !workingTreeSnapshotHasUnavailableEvidence(current) && workingTreeEvidenceDigest(current) === treePrecondition.preimageDigest; })() });
       if (!approval.allowed) return { block: true, reason: pendingHumanApproval.action.kind === "external-provider-action" && !SHELL_TOOL_NAMES.has(event.toolName) ? `User denied external provider action: ${event.toolName}` : `User denied command: ${pendingHumanApproval.action.reason}` };
@@ -4673,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,
@@ -4691,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,
@@ -4709,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/policy-core.js

@@ -664,7 +664,7 @@ function commandRuleMatches(rule, segment, words) {
     return arrayStartsWith(words, prefix);
   }
   const raw = Array.isArray(rule.value) ? rule.value.join(" ") : rule.value;
-  if (rule.match === "contains") return segment.toLowerCase().includes(raw.toLowerCase());
+  if (rule.match === "contains") return !(rule.ignoreSearchArguments && ["grep", "egrep", "fgrep", "rg"].includes(commandBasename(stripWrapper(words)[0] ?? ""))) && segment.toLowerCase().includes(raw.toLowerCase());
   try {
     return new RegExp(raw, "i").test(segment);
   } catch {