@piagent/platform 1.3.1 → 1.4.0

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

@@ -12,17 +12,8 @@ import {
   globMatchesPath, matchesProtectedPath, normalizePathCandidate, matchesAnyPath
 } from "./policy-core.js";
 import { extractShellWritePathCandidates, shellHasFileWriteRedirection } from "./shell-write-targets.js";
-import {
-  commandMatchesVerifyPlan,
-  createBashResultLedger,
-  findMatchingObservedBashResult,
-  readObservedBashResults
-} from "./runtime-evidence.js";
-import {
-  findPackageRoot,
-  findPlatformRoot,
-  readJsonFile
-} from "./guard-io.js";
+import { commandMatchesVerifyPlan, createBashResultLedger, findMatchingObservedBashResult, readObservedBashResults } from "./runtime-evidence.js";
+import { findPackageRoot, findPlatformRoot, readJsonFile } from "./guard-io.js";
 import {
   DOCUMENT_EXTENSIONS,
   extractDocument,
@@ -94,6 +85,9 @@ 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 { inspectTaskControlState } from "../runtime/inspection/task-control-journal.ts";
+import { createSourceMutationGuardBindings } from "../runtime/policy/source-mutation-guard-binding.ts";
 import {
   TOOL_RESULT_CAPTURE_MAX_CHARS,
   TOOL_RESULT_COMPACT_CHAR_THRESHOLD,
@@ -160,6 +154,7 @@ import { buildLiveTaskStatus, formatLiveTaskStatus } from "../runtime/product/op
 import { buildTaskEfficiencyMetrics } from "../runtime/product/efficiency-metrics.ts";
 import { performanceReviewToolDecision, performanceReviewToolKind } from "../runtime/quality/performance-assurance.ts";
 import { expectedModelMutationProof } from "../runtime/quality/model-mutation-proof.ts";
+import { captureVerifierFileSnapshot } from "../runtime/inspection/verifier-snapshot-store.ts";
 import { prefixCompletions, registerPiagentTool, registerRuntimeCommand, registerRuntimeTool } from "../runtime/registration/extension-registration.ts";
 import { FRESH_COMMAND_ACTIONS, FRESH_COMMAND_HELP, ONBOARDING_COMMAND_ACTIONS, WORKFLOW_COMMAND_EXCLUSIONS } from "../runtime/registration/operator-catalogs.ts";
 import { registerPiagentStatusCommand } from "../runtime/registration/runtime-model-status.ts";
@@ -2188,10 +2183,12 @@ function recordObservedTaskVerification(
     isError?: boolean;
     recordedAt?: string;
     outputText?: string;
+    toolCallId?: string;
   },
   pendingContext: ObservedTaskContext[],
   maxManifestFiles: number, shellSnapshotBefore?: Record<string, string>,
-  eventTree?: ReturnType<typeof workingTreeObservation>
+  eventTree?: ReturnType<typeof workingTreeObservation>,
+  readProtectedPaths: string[] = []
 ): TaskContract | undefined {
   const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
   if (!task || task.trace.outcome !== "pending") return;
@@ -2220,19 +2217,31 @@ function recordObservedTaskVerification(
   ));
   const contextAdded = mergeObservedTaskContext(task, pendingContext, maxManifestFiles, redactText);
   if (!duplicate) {
+    const evidenceRecordedAt = nowIso();
+    const observedAt = observed.recordedAt ?? evidenceRecordedAt;
     task.verifyEvidence.push({
       command: redactText(command),
       exitCode,
       summary: `Runtime observed configured verifier exit ${exitCode} (${classification.category}${classification.retryable ? ", retryable" : ""}).`,
-      recordedAt: nowIso(),
+      recordedAt: evidenceRecordedAt,
       observed: true,
-      observedAt: observed.recordedAt ?? nowIso(),
+      observedAt,
       isError: observed.isError === true,
       matchedProfileCommand: true,
       preWorkingTreeDigest,
       workingTreeDigest: currentDigest
     });
     task.verifyEvidence = task.verifyEvidence.slice(-100);
+    try {
+      captureVerifierFileSnapshot({
+        projectRoot: ctx.cwd, taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId,
+        toolCallId: observed.toolCallId ?? "", commandHash: observed.commandHash, observedAt,
+        capturedAt: evidenceRecordedAt, exitCode, treeDigest: currentDigest, snapshot: currentDigests,
+        protectedPaths: readProtectedPaths
+      });
+    } catch (error) {
+      ctx.ui.notify(`Piagent could not persist verifier file snapshot: ${error instanceof Error ? error.message : String(error)}`, "warn");
+    }
   }
 
   const hasChanges = taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected.length > 0;
@@ -4034,6 +4043,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
   const runtimeState = new RuntimeSessionState({
     maxObservedContext: contextBudgetConfig(policy).maxManifestFiles
   });
+  const sourceMutationGuardBindings = createSourceMutationGuardBindings(policy, loadProfileFromContext);
   const runtimeSnapshotCapture = new RuntimeSnapshotCapture(), runtimeVersions = readRuntimeVersionMetadata(PLATFORM_ROOT);
   const solverShadow = solverMode === "off" ? undefined : new SolverShadowRuntime(solverMode);
   const modelRouteRuntime = new ModelRouteRuntime(parentRoutingMode, routingObjective);
@@ -4242,6 +4252,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
   const activityInspector = registerActivityInspector(pi, {
     activeTask: (ctx) => activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined,
     readEvents: (cwd) => readContextTelemetry(cwd, { limit: 5_000 }) as any[],
+    protectedPaths: (ctx) => effectiveProtectedPaths(policy, loadProfile(ctx.cwd)).readProtectedPaths,
     selectAction: selectRuntimeAction,
     emit: emitRuntimeMessage
   });
@@ -4268,7 +4279,9 @@ export default function piagentGuard(pi: ExtensionAPI) {
     mcpReadinessNotice,
     updateAvailabilityNotice,
     contextExcludePatterns: (profile) => contextIndexExcludePatterns(policy, profile),
-    inspectResume: inspectTaskResumeState,
+    inspectResume: (cwd, task, sessionId) => inspectTaskResumeState(cwd, task, sessionId, undefined, {
+      protectedPaths: effectiveProtectedPaths(policy, loadProfile(cwd)).readProtectedPaths
+    }),
     syncTrajectory: (ctx, task) => {
       const snapshot = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
       const resume = workingTreeSnapshotHasUnavailableEvidence(snapshot)
@@ -4286,7 +4299,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       })));
     },
     telemetry,
-    afterStart: activityInspector.refresh
+    afterStart: async (ctx) => { sourceMutationGuardBindings.bind(ctx); await activityInspector.refresh(ctx); }
   });
 
   registerSessionHooks(pi, {
@@ -4301,6 +4314,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     onTurnEnd: activityInspector.refresh,
     onAgentSettled: activityInspector.refresh,
     beforeShutdown: (ctx) => {
+      sourceMutationGuardBindings.unbind(ctx);
       activityInspector.dispose(ctx);
       sessionCapabilityDigests.delete(`${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`);
     }
@@ -4497,6 +4511,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
       if (reviewDecision) runtimeState.denyPerformanceReviewTool(task.taskRunId);
       return reviewDecision;
     },
+    beforeStart: (_event, ctx) => {
+      const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+      const control = task?.trace.outcome === "pending" ? inspectTaskControlState(ctx.cwd, task) : null;
+      if (control?.dispatchBlocked) return { block: true, reason: `Task lifecycle control blocks tool start while state is ${control.state}.` };
+    },
     afterDecision: (_event, ctx, metadata) => {
       if (metadata.allowed) return;
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
@@ -4631,13 +4650,13 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (approvalDecision.block) {
       return { block: true, reason: approvalDecision.reason };
     }
-
     let shellProjectMutation = false;
     let shellMutationTargets: string[] = [];
     let shellMutationTargetBounded = false;
     let configuredVerifierShell = false;
     let authorizedShellCommand = "";
     let authorizedShellSegments: Array<{ words: string[] }> = [];
+    let pendingHumanApproval: { prompt: string; title: string; action: Omit<ApprovalActionDraft, "treePrecondition"> } | null = null;
     if (SHELL_TOOL_NAMES.has(event.toolName)) {
       const shellInput = extractShellCommandInput(toolInput);
       if (!shellInput.command) {
@@ -4695,17 +4714,14 @@ export default function piagentGuard(pi: ExtensionAPI) {
         return { block: true, reason: unresolvedExpansionReason("Command", unresolvedExpansions) };
       }
 
-      const confirmationReasons = execDecision.mode !== "off" && execDecision.decision === "prompt"
-        ? [...execDecision.reasons]
-        : [];
+      const confirmationReasons = execDecision.mode !== "off" && execDecision.decision === "prompt" ? [...execDecision.reasons] : [];
       const externalReason = findShellExternalConfirmationReason(execDecision.segments, externalActionPolicyConfig(policy));
       if (externalReason) confirmationReasons.push(externalReason);
       if (confirmationReasons.length > 0) {
-        const ok = await ctx.ui.confirm(
-          `Command requires confirmation.\n\n${confirmationReasons.join("\n")}\n\nAllow?`,
-          "Piagent exec policy confirmation"
-        );
-        if (!ok) return { block: true, reason: `User denied command: ${confirmationReasons.join("; ")}` };
+        pendingHumanApproval = { prompt: `Command requires confirmation.\n\n${confirmationReasons.join("\n")}\n\nAllow?`, title: "Piagent exec policy confirmation",
+          action: { kind: externalReason ? "external-provider-action" : "workspace-patch", preconditionClass: externalReason ? "runtime-only" : "workspace-tree", toolName: event.toolName, rawAction: { toolName: event.toolName, command, input: preparedInput.input },
+            commandPreview: command, parameterPreview: preparedInput.confirmationSummary ?? "Shell command", targetPaths: shellMutationTargets, targetSummaries: confirmationReasons, provider: externalReason ? "shell-external" : null, urlOrigin: null,
+            requestedScope: "one-shell-command", reason: confirmationReasons.join("; "), riskClass: shellProjectMutation ? "high" : "medium", allowConsequence: "Run this exact command once after the guard rechecks the task and working tree.", denyConsequence: "Block this command and return the denial to the active Pi operation." } };
       }
     }
 
@@ -4717,7 +4733,6 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (proxyShellDecision.block) {
       return { block: true, reason: proxyShellDecision.reason };
     }
-
     const policyToolIdentity = preparedInput.proxyToolName ?? event.toolName;
     const usesKnownExternalProvider = externalActionPolicyConfig(policy).providerKeywords
       .some((provider) => actionTextMatchesAny(policyToolIdentity, [provider]));
@@ -4754,16 +4769,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
           }
         : classifiedExternalAction;
       if (externalAction.decision === "confirm") {
-        const inputSummary = preparedInput.confirmationSummary
-          ? `\ninput: ${preparedInput.confirmationSummary}`
-          : "";
-        const ok = await ctx.ui.confirm(
-          `External provider action requires confirmation.\n\nprovider: ${externalAction.provider}\naction: ${externalAction.action}\ntool: ${event.toolName}${inputSummary}\n\nAllow?`,
-          "Piagent external action confirmation"
-        );
-        if (!ok) {
-          return { block: true, reason: `User denied external provider action: ${event.toolName}` };
-        }
+        const inputSummary = preparedInput.confirmationSummary ? `\ninput: ${preparedInput.confirmationSummary}` : "";
+        pendingHumanApproval = { prompt: `External provider action requires confirmation.\n\nprovider: ${externalAction.provider}\naction: ${externalAction.action}\ntool: ${event.toolName}${inputSummary}\n\nAllow?`, title: "Piagent external action confirmation",
+          action: { kind: "external-provider-action", preconditionClass: "runtime-only", toolName: event.toolName, rawAction: { toolName: event.toolName, input: preparedInput.input, provider: externalAction.provider, action: externalAction.action },
+            commandPreview: null, parameterPreview: preparedInput.confirmationSummary ?? String(externalAction.action), targetPaths: [], targetSummaries: [], provider: String(externalAction.provider),
+            urlOrigin: null, requestedScope: "one-external-action", reason: `External provider action ${String(externalAction.action)} requires confirmation`, riskClass: "high", allowConsequence: "Release this exact provider action once after the guard rechecks runtime authority.", denyConsequence: "Block the provider action without changing external state." } };
       }
     }
 
@@ -4805,6 +4815,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
       verificationCarrier: SHELL_TOOL_NAMES.has(event.toolName)
     });
     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) });
+      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;
+    }
     if (sessionTask && sessionTask.trace.outcome !== "pending" && (shellProjectMutation || directProjectMutation)) {
       return {
         block: true,
@@ -4855,6 +4870,17 @@ export default function piagentGuard(pi: ExtensionAPI) {
       }
     }
 
+    if (pendingHumanApproval) {
+      const currentTreeDigest = semanticSnapshot && !workingTreeSnapshotHasUnavailableEvidence(semanticSnapshot) ? workingTreeEvidenceDigest(semanticSnapshot) : null;
+      const treePrecondition = pendingHumanApproval.action.preconditionClass === "runtime-only" || !currentTreeDigest ? null
+        : { 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),
+        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}` };
+      if (!approval.consume()) return { block: true, reason: "Approval became stale before tool start; the action was blocked." };
+    }
     if (
       sessionTask?.trace.outcome === "pending"
       && sessionTask.changeMode === "source-change"
@@ -4864,7 +4890,6 @@ export default function piagentGuard(pi: ExtensionAPI) {
     }
     }
   });
-
   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,

package/packages/piagent-core/extensions/redaction-core.d.ts

@@ -0,0 +1,2 @@
+export function redactSensitiveText(input: unknown): { text: string; redacted: boolean };
+export function redactForStorage(value: unknown): unknown;

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

@@ -282,6 +282,23 @@ export function appendTaskJournalEventAtMost(cwd, event, options = {}) {
   }
 }
 
+export function transactTaskJournal(cwd, transaction) {
+  if (typeof transaction !== "function") throw new TypeError("Task journal transaction must be a function");
+  const safePaths = writableJournalPaths(cwd);
+  const release = acquireLock(safePaths);
+  try {
+    const journal = recoverIncompleteJournalTail(cwd, safePaths, readTaskJournal(cwd));
+    if (journal.corruptions.length > 0) throw new Error(`Task journal chain is corrupt: ${journal.corruptions[0]}`);
+    const decision = transaction({ events: [...journal.events], head: journal.head ? { ...journal.head } : undefined });
+    if (!decision || typeof decision !== "object" || Array.isArray(decision)) throw new Error("Task journal transaction returned an invalid decision");
+    if (!decision.event) return { appended: false, record: undefined, result: decision.result };
+    const record = appendJournalRecord(safePaths, journal, decision.event, decision.recordedAt);
+    return { appended: true, record, result: decision.result };
+  } finally {
+    release();
+  }
+}
+
 export function readTaskJournal(cwd, options = {}) {
   const paths = taskJournalPaths(cwd);
   let safePath;
@@ -290,7 +307,17 @@ export function readTaskJournal(cwd, options = {}) {
   } catch {
     return { events: [], corruptions: ["journal path is unsafe"], head: undefined };
   }
-  if (!fs.existsSync(safePath)) return { events: [], corruptions: [], head: undefined };
+  if (!fs.existsSync(safePath)) return { events: [], corruptions: [], head: undefined, inputTruncated: false, omittedEvents: 0 };
+  if (Number.isInteger(options.maximumBytes) && options.maximumBytes > 0) {
+    try {
+      const stat = fs.lstatSync(safePath);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > options.maximumBytes) {
+        return { events: [], corruptions: ["journal exceeds bounded inspection size"], head: undefined, inputTruncated: true, omittedEvents: 0 };
+      }
+    } catch {
+      return { events: [], corruptions: ["journal size could not be inspected"], head: undefined, inputTruncated: false, omittedEvents: 0 };
+    }
+  }
   const content = fs.readFileSync(safePath);
   const finalNewline = content.length === 0 || content.at(-1) === 0x0a;
   const lastNewline = finalNewline ? content.length - 1 : content.lastIndexOf(0x0a);
@@ -329,6 +356,8 @@ export function readTaskJournal(cwd, options = {}) {
   return {
     events: visibleEvents,
     corruptions,
+    inputTruncated: visibleEvents.length < events.length,
+    omittedEvents: Math.max(0, events.length - visibleEvents.length),
     recoverableTailBytes,
     validBytes,
     head: events.at(-1)

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

@@ -66,17 +66,9 @@ export function safeTaskId(value) {
   return normalized || "task";
 }
 
-function stateRoot(cwd) {
-  return path.join(cwd, ".pi", "piagent-state");
-}
-
-function tasksRoot(cwd) {
-  return path.join(stateRoot(cwd), "tasks");
-}
-
-function sessionsRoot(cwd) {
-  return path.join(stateRoot(cwd), "session-tasks");
-}
+function stateRoot(cwd) { return path.join(cwd, ".pi", "piagent-state"); }
+function tasksRoot(cwd) { return path.join(stateRoot(cwd), "tasks"); }
+function sessionsRoot(cwd) { return path.join(stateRoot(cwd), "session-tasks"); }
 
 function taskRunPath(cwd, taskRunId) {
   return path.join(tasksRoot(cwd), `${safeTaskId(taskRunId)}.json`);
@@ -98,7 +90,12 @@ function readJson(cwd, filePath) {
     const safePath = resolveLocalStatePath(cwd, filePath, { label: "Task state", kind: "file" });
     const descriptor = fs.openSync(safePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
     try {
-      return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      const before = fs.fstatSync(descriptor, { bigint: true });
+      if (!before.isFile() || before.size > BigInt(8 * 1024 * 1024)) return undefined;
+      const value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      const after = fs.fstatSync(descriptor, { bigint: true });
+      const fields = ["dev", "ino", "mode", "size", "mtimeNs", "ctimeNs"];
+      return fields.every((field) => before[field] === after[field]) ? value : undefined;
     } finally {
       fs.closeSync(descriptor);
     }
@@ -586,7 +583,6 @@ function gitOutput(cwd, args, options = {}) {
     stdio: ["ignore", "pipe", "ignore"]
   });
 }
-
 function gitHasHead(cwd) {
   try {
     gitOutput(cwd, ["rev-parse", "--verify", "HEAD"]);
@@ -595,7 +591,6 @@ function gitHasHead(cwd) {
     return false;
   }
 }
-
 export function isGitWorkingTree(cwd) {
   try {
     return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
@@ -603,20 +598,18 @@ export function isGitWorkingTree(cwd) {
     return false;
   }
 }
-
 function normalizedGitPath(value) {
   return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
 }
-
 function prefixedGitPath(prefix, file) {
   const normalized = normalizedGitPath(file);
   return prefix ? `${prefix}/${normalized}` : normalized;
 }
 
-function workingTreeFilesForGitRoot(cwd) {
+function workingTreeFilesForGitRoot(cwd, observeRename) {
   if (!isGitWorkingTree(cwd)) return [];
   const changed = gitHasHead(cwd)
-    ? changedPathsFromNameStatus(gitOutput(cwd, ["diff", "--name-status", "-z", "--find-renames", "--diff-filter=ACMRD", "HEAD", "--"]))
+    ? changedPathsFromNameStatus(gitOutput(cwd, ["diff", "--name-status", "-z", "--find-renames", "--diff-filter=ACMRD", "HEAD", "--"]), observeRename)
     : gitOutput(cwd, ["ls-files", "-z"]).split("\0").filter(Boolean);
   const untracked = gitOutput(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
   return [...new Set([...changed, ...untracked].map(normalizedGitPath).filter((item) => item && !item.startsWith(".pi/piagent-state/")))].sort();
@@ -694,9 +687,7 @@ function nonGitWorkspaceFiles(cwd, gitRootPrefixes) {
   return files.sort();
 }
 
-function nonGitWorkspaceFileDigest(cwd, file) {
-  return streamedWorkingTreeFileDigest(cwd, file, false);
-}
+function nonGitWorkspaceFileDigest(cwd, file, protectedProjectPath = null) { return streamedWorkingTreeFileDigest(cwd, file, false, protectedProjectPath); }
 
 function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
   const topSegment = candidate.split("/")[0];
@@ -777,7 +768,7 @@ export function repositoryFileManifest(cwd, maxFiles = 10_000) {
   return [...new Set(files)].sort();
 }
 
-function changedPathsFromNameStatus(output) {
+function changedPathsFromNameStatus(output, observeRename) {
   const fields = String(output ?? "").split("\0").filter(Boolean);
   const files = [];
   for (let index = 0; index < fields.length;) {
@@ -787,7 +778,7 @@ function changedPathsFromNameStatus(output) {
     files.push(source);
     if (/^[RC]/.test(status)) {
       const destination = fields[index++];
-      if (destination) files.push(destination);
+      if (destination) { files.push(destination); observeRename?.(source, destination); }
     }
   }
   return files;
@@ -804,8 +795,12 @@ export function workingTreeSnapshotHasUnavailableEvidence(snapshot) {
   return Object.values(snapshot ?? {}).some((digest) => isUnavailableWorkingTreeDigest(digest));
 }
 
-function streamedWorkingTreeFileDigest(root, file, hasHead) {
+function streamedWorkingTreeFileDigest(root, file, hasHead, protectedProjectPath = null) {
   const absolute = path.resolve(root, file);
+  if (protectedProjectPath) {
+    try { return unavailableWorkingTreeDigest(protectedProjectPath, "protected-path", fs.lstatSync(absolute)); }
+    catch { return unavailableWorkingTreeDigest(protectedProjectPath, "protected-path"); }
+  }
   const relative = path.relative(root, absolute);
   if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
     return unavailableWorkingTreeDigest(file, "outside-root");
@@ -866,22 +861,24 @@ function streamedWorkingTreeFileDigest(root, file, hasHead) {
   }
 }
 
-export function workingTreeSnapshot(cwd) {
+export function workingTreeSnapshot(cwd, options = {}) {
   const snapshot = {};
+  const isProtectedProjectPath = typeof options.isProtectedProjectPath === "function" ? options.isProtectedProjectPath : () => false;
   const roots = gitEvidenceRoots(cwd);
   for (const root of roots) {
-    const hasHead = gitHasHead(root.cwd);
-    for (const file of workingTreeFilesForGitRoot(root.cwd)) {
-      const snapshotPath = prefixedGitPath(root.prefix, file);
-      snapshot[snapshotPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead);
+    const protectedAliases = new Set();
+    const observeRename = (source, destination) => {
+      const paths = [source, destination];
+      if (paths.some((file) => file === ".pi/piagent-state" || file.startsWith(".pi/piagent-state/") || isProtectedProjectPath(prefixedGitPath(root.prefix, file))))
+        paths.forEach((file) => protectedAliases.add(file));
+    };
+    const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
+      const projectPath = prefixedGitPath(root.prefix, file);
+      snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
     }
-  }
-  if (!isGitWorkingTree(cwd) && roots.length > 0) {
-    for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
-      snapshot[file] = nonGitWorkspaceFileDigest(cwd, file);
-    }
-  }
-  return snapshot;
+  } if (!isGitWorkingTree(cwd) && roots.length > 0) for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
+      snapshot[file] = nonGitWorkspaceFileDigest(cwd, file, isProtectedProjectPath(file) ? file : null);
+  } return snapshot;
 }
 
 export function taskStateMigrationStatus(cwd) {

package/packages/piagent-core/mcp/mcp-server-catalog.js

@@ -68,7 +68,7 @@ export const CATALOG_SERVERS = {
     }
   },
   figma: {
-    description: "Figma remote MCP server. Requires Figma OAuth from the MCP panel when first used.",
+    description: "Figma remote MCP server. OAuth works only for clients approved in the Figma MCP Catalog.",
     config: {
       url: "https://mcp.figma.com/mcp",
       auth: "oauth",
@@ -99,7 +99,7 @@ export const CATALOG_PREREQUISITES = {
     "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
   ],
   playwright: ["browsers installed on first use (npx playwright install)"],
-  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
+  figma: ["Piagent approved in the Figma MCP Catalog before remote OAuth can register"],
   "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
 };
 
@@ -119,12 +119,12 @@ export const CATALOG_PRESETS = {
   docs: ["context7"],
   browser: ["chrome-devtools", "playwright"],
   github: ["github"],
-  design: ["figma"],
+  design: ["figma-desktop"],
   "design-local": ["figma-desktop"],
   web: ["context7", "chrome-devtools", "playwright"],
   core: ["context7", "chrome-devtools", "github"],
-  popular: ["context7", "chrome-devtools", "playwright", "github", "figma"],
-  all: ["context7", "chrome-devtools", "playwright", "github", "figma", "figma-desktop"]
+  popular: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop"],
+  all: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop", "figma"]
 };
 
 /** @param {string} name @returns {boolean} */

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "type": "module",
   "private": true,
   "license": "MIT",

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

@@ -49,7 +49,7 @@ type SessionStartHookDependencies = {
   inspectResume: (cwd: string, task: TaskContract, sessionId: string) => ResumeState;
   telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
   syncTrajectory?: (ctx: ExtensionContext, task: TaskContract) => TrajectorySyncResult;
-  afterStart?: (ctx: ExtensionContext) => void;
+  afterStart?: (ctx: ExtensionContext) => void | Promise<void>;
 };
 
 export function registerSessionStartHook(pi: ExtensionAPI, dependencies: SessionStartHookDependencies): void {
@@ -227,6 +227,6 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
       taskRecovery,
       executionBackend
     });
-    dependencies.afterStart?.(ctx);
+    await dependencies.afterStart?.(ctx);
   });
 }

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

@@ -17,6 +17,7 @@ type ToolCallHookDependencies = {
   beforeAuthorize?: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallDecision> | ToolCallDecision;
   authorize: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallDecision> | ToolCallDecision;
   reviewBudgetDecision?: (event: ToolCallEvent, ctx: ExtensionContext) => ToolCallDecision;
+  beforeStart?: (event: ToolCallEvent, ctx: ExtensionContext) => ToolCallDecision;
   afterDecision?: (
     event: ToolCallEvent,
     ctx: ExtensionContext,
@@ -72,7 +73,9 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
     const decision = authorizationDecision && typeof authorizationDecision === "object" && authorizationDecision.block
       ? authorizationDecision
       : dependencies.reviewBudgetDecision?.(resolvedEvent, ctx);
-    const blockedDecision = decision && typeof decision === "object" ? decision : undefined;
+    const startDecision = !(decision && typeof decision === "object" && decision.block) ? dependencies.beforeStart?.(resolvedEvent, ctx) : undefined;
+    const finalDecision = startDecision && typeof startDecision === "object" && startDecision.block ? startDecision : decision;
+    const blockedDecision = finalDecision && typeof finalDecision === "object" ? finalDecision : undefined;
     record(ctx, {
       activityId: `decision:${toolCallId}`,
       event: "tool_decision",
@@ -88,6 +91,6 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
       observeTrajectorySync(ctx, dependencies.afterAuthorized?.(resolvedEvent, ctx, { toolCallId }), dependencies.telemetry);
     }
     dependencies.afterDecision?.(resolvedEvent, ctx, { toolCallId, allowed: !blockedDecision?.block, reason: blockedDecision?.reason });
-    return decision;
+    return finalDecision;
   });
 }

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

@@ -11,6 +11,7 @@ import { redactForStorage, redactSensitiveText } from "../../extensions/redactio
 import { appendObservedBashResult, hashEvidenceCommand, observedBashResultFromToolResultEvent } from "../../extensions/runtime-evidence.js";
 import { workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence } from "../../extensions/task-state.js";
 import { workingTreeObservation } from "../../extensions/working-tree-digest.js";
+import { recordMutationResult } from "../inspection/mutation-provenance-recorder.ts";
 import { boundedGitDiffReview } from "../quality/performance-assurance.ts";
 import { currentFileContentDigests } from "../quality/model-mutation-proof.ts";
 import { boundedPerformanceReviewResultText } from "../quality/performance-review-evidence.ts";
@@ -18,6 +19,7 @@ import { attachToolResultCompactionDetails, compactToolResultDetails, compactToo
 import { RuntimeSessionState, type ObservedTaskContext } from "../session/runtime-state.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
+import { patchLineStats } from "./tool-result-metadata.ts";
 
 type ToolResultEvent = { toolCallId?: string; toolName: string; input?: unknown; content?: unknown; details?: unknown; isError?: boolean; usage?: unknown };
 type ObservedBashResult = NonNullable<ReturnType<typeof observedBashResultFromToolResultEvent>>;
@@ -50,7 +52,8 @@ type ToolResultHookDependencies = {
     ctx: ExtensionContext,
     observed: ObservedVerificationResult,
     pendingContext: ObservedTaskContext[],
-    maxManifestFiles: number, shellSnapshotBefore?: Record<string, string>, eventTree?: WorkingTreeObservation
+    maxManifestFiles: number, shellSnapshotBefore?: Record<string, string>, eventTree?: WorkingTreeObservation,
+    readProtectedPaths?: string[]
   ) => unknown;
   extractLikelyPath: (cwd: string, input: Record<string, unknown>) => string | undefined;
   mutationTargets: (cwd: string, toolName: string, input: Record<string, unknown>) => string[];
@@ -124,20 +127,6 @@ function boundedToolResultText(content: unknown): string {
   return text.slice(-20_000);
 }
 
-function patchLineStats(details: unknown): { additions?: number; deletions?: number } {
-  if (!details || typeof details !== "object") return {};
-  const patch = (details as Record<string, unknown>).patch;
-  if (typeof patch !== "string" || !patch.trim()) return {};
-  let additions = 0;
-  let deletions = 0;
-  for (const line of patch.split(/\r?\n/)) {
-    if (line.startsWith("+++ ") || line.startsWith("--- ")) continue;
-    if (line.startsWith("+")) additions += 1;
-    else if (line.startsWith("-")) deletions += 1;
-  }
-  return { additions, deletions };
-}
-
 function countChangedStringLeaves(before: unknown, after: unknown): number {
   if (typeof before === "string" && typeof after === "string") return before === after ? 0 : 1;
   if (Array.isArray(before) && Array.isArray(after)) {
@@ -270,9 +259,9 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
       dependencies.recordObservedTaskVerification(
         pi,
         ctx,
-        { ...observed, outputText: boundedToolResultText(event.content) },
+        { ...observed, toolCallId: observed.toolCallId ?? resultToolCallId, outputText: boundedToolResultText(event.content) },
         pendingContext,
-        dependencies.maxManifestFiles, shellSnapshotBefore, eventTree
+        dependencies.maxManifestFiles, shellSnapshotBefore, eventTree, readProtectedPaths
       );
     }
 
@@ -287,20 +276,32 @@ export function registerToolResultHook(pi: ExtensionAPI, dependencies: ToolResul
     const currentSnapshot = taskIdentity ? eventTree?.snapshot : undefined;
     const currentTreeDigest = taskIdentity ? eventTree?.digest : undefined;
     const directMutationResult = modelMutationIdentity && currentSnapshot
-      ? dependencies.state.completeAuthorizedModelMutation(
+      ? dependencies.state.completeAuthorizedModelMutationEvidence(
           modelMutationIdentity,
           resultToolCallId,
           successfulToolResult(event),
           currentSnapshot,
           currentFileContentDigests(ctx.cwd, directMutationTargets)
         )
-      : { changedPaths: [] as string[], recordedDigests: {} as Record<string, string> };
+      : { changedPaths: [] as string[], recordedDigests: {} as Record<string, string>, beforeSnapshot: null,
+          targetPaths: [] as string[], recordedContentDigests: {} as Record<string, string>, proofModes: {} as Record<string, "full-content" | "exact-replacement"> };
     const shellChangedPaths = taskIdentity && currentSnapshot && shellSnapshotBefore
       ? changedSnapshotFiles(shellSnapshotBefore, currentSnapshot)
       : [];
     if (modelMutationIdentity && shellChangedPaths.length > 0) {
       dependencies.state.invalidateSuccessfulModelMutationPaths(modelMutationIdentity, shellChangedPaths);
     }
+    if (modelMutationIdentity && currentSnapshot) {
+      try {
+        recordMutationResult({
+          projectRoot: ctx.cwd, identity: modelMutationIdentity, toolCallId: resultToolCallId, toolName: event.toolName,
+          recordedAt: dependencies.now(), successful: successfulToolResult(event), currentSnapshot,
+          completion: directMutationResult, shellSnapshotBefore, shellChangedPaths, protectedPaths: readProtectedPaths
+        });
+      } catch (error) {
+        ctx.ui.notify(`Piagent could not persist mutation provenance: ${error instanceof Error ? error.message : String(error)}`, "warn");
+      }
+    }
     const outputText = boundedToolResultText(event.content);
     const performanceReviewOutputText = boundedPerformanceReviewResultText(event.content);
     const observedExitCode = observed?.exitCode