@piagent/platform 1.3.0 → 1.4.0

package/packages/piagent-core/capabilities/runtime-integrity.js

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+
 export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/context/adaptive-planner.ts",
   "packages/piagent-core/runtime/context/retrieval-route-policy.ts",
@@ -7,17 +10,23 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/extensions/acceptance-receipt.js",
   "packages/piagent-core/extensions/criterion-graph.js",
   "packages/piagent-core/extensions/criterion-context-pack.js",
+  "packages/piagent-core/extensions/document-intake.ts",
+  "packages/piagent-core/extensions/execution-backend.js",
   "packages/piagent-core/extensions/failure-types.ts",
   "packages/piagent-core/extensions/repository-memory.js",
+  "packages/piagent-core/extensions/state-retention.js",
   "packages/piagent-core/extensions/task-contract-view.js",
   "packages/piagent-core/extensions/task-authority-contract.js",
   "packages/piagent-core/extensions/task-digest-migration.js",
   "packages/piagent-core/extensions/task-journal.js",
   "packages/piagent-core/extensions/task-runtime-audit.js",
+  "packages/piagent-core/extensions/task-state.js",
   "packages/piagent-core/extensions/tenant-contract.js",
+  "packages/piagent-core/extensions/verification-intelligence.js",
   "packages/piagent-core/extensions/working-tree-digest.js",
   "packages/piagent-core/policy/authority-manifest.v1.json",
   "packages/piagent-core/capabilities/authority-manifest.ts",
+  "packages/piagent-core/capabilities/capability-verification-cache.js",
   "packages/piagent-core/runtime/hooks/agent-start-hook.ts",
   "packages/piagent-core/runtime/hooks/completion-hook.ts",
   "packages/piagent-core/runtime/hooks/input-hook.ts",
@@ -25,7 +34,53 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/hooks/session-start-hook.ts",
   "packages/piagent-core/runtime/hooks/tool-call-hook.ts",
   "packages/piagent-core/runtime/hooks/tool-result-hook.ts",
+  "packages/piagent-core/runtime/hooks/tool-result-metadata.ts",
   "packages/piagent-core/runtime/input/chat-images.ts",
+  "packages/piagent-core/runtime/inspection/activity-event-adapter.ts",
+  "packages/piagent-core/runtime/inspection/approval-broker.ts",
+  "packages/piagent-core/runtime/inspection/criteria-links.ts",
+  "packages/piagent-core/runtime/inspection/commit-summary-projection.ts",
+  "packages/piagent-core/runtime/inspection/diff-projection.ts",
+  "packages/piagent-core/runtime/inspection/git-numstat-adapter.ts",
+  "packages/piagent-core/runtime/inspection/git-filter-safety.ts",
+  "packages/piagent-core/runtime/inspection/git-status-adapter.ts",
+  "packages/piagent-core/runtime/inspection/git-tree-adapter.ts",
+  "packages/piagent-core/runtime/inspection/mcp-control.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-contract.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-recorder.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-store.ts",
+  "packages/piagent-core/runtime/inspection/project-runtime-inspection.ts",
+  "packages/piagent-core/runtime/inspection/review-state-contract.ts",
+  "packages/piagent-core/runtime/inspection/review-state-projection.ts",
+  "packages/piagent-core/runtime/inspection/review-state-store.ts",
+  "packages/piagent-core/runtime/inspection/runtime-event-store.ts",
+  "packages/piagent-core/runtime/inspection/same-process-bridge-proof.ts",
+  "packages/piagent-core/runtime/inspection/zero-turn-conformance.ts",
+  "packages/piagent-core/runtime/inspection/source-evidence-contract.ts",
+  "packages/piagent-core/runtime/inspection/source-evidence-store.ts",
+  "packages/piagent-core/runtime/inspection/source-inspection-plan.ts",
+  "packages/piagent-core/runtime/inspection/source-mutation-projection.ts",
+  "packages/piagent-core/runtime/inspection/source-mutation-store.ts",
+  "packages/piagent-core/runtime/inspection/source-revert-projection.ts",
+  "packages/piagent-core/runtime/inspection/source-handoff-store.ts",
+  "packages/piagent-core/runtime/inspection/source-open-target.ts",
+  "packages/piagent-core/runtime/inspection/task-run-index.ts",
+  "packages/piagent-core/runtime/inspection/task-recovery-timeline.ts",
+  "packages/piagent-core/runtime/inspection/task-compaction-history.ts",
+  "packages/piagent-core/runtime/inspection/context-telemetry-inspection.ts",
+  "packages/piagent-core/runtime/inspection/task-handoff-history.ts",
+  "packages/piagent-core/runtime/inspection/task-subagent-tree.ts",
+  "packages/piagent-core/runtime/inspection/task-baseline-start-capture.ts",
+  "packages/piagent-core/runtime/inspection/task-control-journal.ts",
+  "packages/piagent-core/runtime/inspection/task-source-projection.ts",
+  "packages/piagent-core/runtime/inspection/task-provenance-projection.ts",
+  "packages/piagent-core/runtime/inspection/verifier-snapshot-contract.ts",
+  "packages/piagent-core/runtime/inspection/verifier-snapshot-store.ts",
+  "packages/piagent-core/runtime/inspection/webui-snapshot.ts",
+  "packages/piagent-core/runtime/inspection/text-diff.ts",
+  "packages/piagent-core/runtime/inspection/source-change-projection.ts",
+  "packages/piagent-core/runtime/inspection/workspace-file-reader.ts",
+  "packages/piagent-core/runtime/inspection/workspace-source-projection.ts",
   "packages/piagent-core/runtime/model/capabilities.ts",
   "packages/piagent-core/runtime/model/authenticated-catalog.ts",
   "packages/piagent-core/runtime/model/model-route-policy.ts",
@@ -36,6 +91,10 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/model/snapshot-telemetry.ts",
   "packages/piagent-core/runtime/policy/authority-manifest.ts",
   "packages/piagent-core/runtime/policy/authority-resume-policy.ts",
+  "packages/piagent-core/runtime/policy/source-index-transaction.ts",
+  "packages/piagent-core/runtime/policy/source-mutation-guard-binding.ts",
+  "packages/piagent-core/runtime/policy/source-mutation-guard.ts",
+  "packages/piagent-core/runtime/policy/source-worktree-transaction.ts",
   "packages/piagent-core/runtime/policy/task-authority-runtime.ts",
   "packages/piagent-core/runtime/orchestration/role-policy.ts",
   "packages/piagent-core/runtime/orchestration/role-binder.ts",
@@ -95,5 +154,98 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/tools/phase-tools.ts",
   "packages/piagent-core/runtime/tools/phase-tool-runtime.ts",
   "packages/piagent-core/runtime/workflows/input-routing.ts",
-  "packages/piagent-core/runtime/workflows/task-intake.ts"
+  "packages/piagent-core/runtime/workflows/task-intake.ts",
+  "scripts/piagent-cli.mjs",
+  "scripts/register-typescript-loader.mjs",
+  "scripts/typescript-loader.mjs"
 ]);
+
+const EXECUTABLE_SOURCE = /\.(?:[cm]?js|ts|json|sh)$/;
+const IMPORT_SPECIFIER = /(?:\bimport\s*(?:type\s+)?(?:[^"'`]*?\s+from\s*)?|\bexport\s+(?:type\s+)?[^"'`]*?\s+from\s*)["']([^"']+)["']/g;
+const DYNAMIC_IMPORT = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
+const RUNTIME_LITERAL = /["']((?:packages|scripts)\/[A-Za-z0-9_./-]+\.(?:[cm]?js|ts|json|sh))["']/g;
+const MAX_INTEGRITY_FILES = 5_000;
+
+function normalizedRelative(root, absolute) {
+  const relative = path.relative(root, absolute);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
+  return relative.split(path.sep).join("/");
+}
+
+function executableFilesBelow(root, relativeDirectory) {
+  const directory = path.join(root, relativeDirectory);
+  if (!fs.existsSync(directory)) return [];
+  const files = [];
+  const visit = (absolute) => {
+    const entries = fs.readdirSync(absolute, { withFileTypes: true });
+    for (const entry of entries) {
+      const target = path.join(absolute, entry.name), stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) throw new Error(`runtime-integrity-symlink:${normalizedRelative(root, target) ?? "outside-root"}`);
+      if (stat.isDirectory()) visit(target);
+      else if (stat.isFile() && EXECUTABLE_SOURCE.test(entry.name)) files.push(normalizedRelative(root, target));
+    }
+  };
+  visit(directory);
+  return files.filter(Boolean);
+}
+
+function localImportTarget(root, importer, specifier) {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = path.resolve(path.dirname(path.join(root, importer)), specifier);
+  const candidates = [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, "index.ts"), path.join(base, "index.js")];
+  for (const candidate of candidates) {
+    const relative = normalizedRelative(root, candidate);
+    if (!relative || !fs.existsSync(candidate)) continue;
+    const stat = fs.lstatSync(candidate);
+    if (stat.isSymbolicLink()) throw new Error(`runtime-integrity-symlink:${relative}`);
+    if (stat.isFile() && EXECUTABLE_SOURCE.test(candidate)) return relative;
+  }
+  return undefined;
+}
+
+function sourceReferences(root, relativeFile) {
+  if (!/\.(?:[cm]?js|ts)$/.test(relativeFile)) return [];
+  const source = fs.readFileSync(path.join(root, relativeFile), "utf8"), references = new Set();
+  for (const pattern of [IMPORT_SPECIFIER, DYNAMIC_IMPORT]) {
+    pattern.lastIndex = 0;
+    for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+      const target = localImportTarget(root, relativeFile, match[1]);
+      if (target) references.add(target);
+    }
+  }
+  RUNTIME_LITERAL.lastIndex = 0;
+  for (let match = RUNTIME_LITERAL.exec(source); match; match = RUNTIME_LITERAL.exec(source)) {
+    const target = path.join(root, match[1]), relative = normalizedRelative(root, target);
+    if (relative && fs.existsSync(target) && fs.lstatSync(target).isFile()) references.add(relative);
+  }
+  return [...references];
+}
+
+export function discoverRuntimeIntegrityFiles(root) {
+  const packageDocument = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const declaredExtensions = Array.isArray(packageDocument.pi?.extensions) ? packageDocument.pi.extensions : [];
+  const declaredBins = packageDocument.bin && typeof packageDocument.bin === "object" ? Object.values(packageDocument.bin) : [];
+  const declaredEntrypoints = Array.isArray(packageDocument.piagent?.runtimeIntegrityEntrypoints)
+    ? packageDocument.piagent.runtimeIntegrityEntrypoints : [];
+  const seeds = new Set([
+    ...CORE_RUNTIME_INTEGRITY_FILES,
+    "packages/piagent-core/extensions/piagent-guard.ts",
+    ...executableFilesBelow(root, "packages/piagent-core/runtime"),
+    ...declaredExtensions,
+    ...declaredBins,
+    ...declaredEntrypoints
+  ].filter((entry) => typeof entry === "string" && !path.isAbsolute(entry)));
+  const files = new Set(), pending = [...seeds];
+  while (pending.length) {
+    if (files.size >= MAX_INTEGRITY_FILES) throw new Error("runtime-integrity-file-limit");
+    const relative = pending.pop();
+    if (files.has(relative)) continue;
+    const absolute = path.join(root, relative), contained = normalizedRelative(root, absolute);
+    if (!contained || !fs.existsSync(absolute)) continue;
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`runtime-integrity-file-unsafe:${relative}`);
+    files.add(contained);
+    for (const reference of sourceReferences(root, contained)) if (!files.has(reference)) pending.push(reference);
+  }
+  return [...files].sort((left, right) => left.localeCompare(right, "en"));
+}

package/packages/piagent-core/extensions/document-intake.ts

@@ -51,6 +51,8 @@ export type DocumentExtraction =
   | { status: "ok"; text: string; truncated: boolean; kind: "text" | "docx" | "pdf" }
   | { status: "error"; reason: string };
 
+type DocumentCommandResult = { status: number | null; stdout: string; stderr: string; error?: Error };
+
 export function expandHome(candidate: string, home: string | undefined): string {
   if (candidate === "~") return home ?? candidate;
   if (candidate.startsWith("~/")) {
@@ -435,7 +437,7 @@ export function extractTextDocument(buffer: Buffer): DocumentExtraction {
 // missing tool would be a lie in the direction that wastes the most time.
 export function extractPdfFromDescriptor(
   fd: number,
-  run: (command: string, args: string[], input?: number) => { status: number | null; stdout: string; stderr: string; error?: Error } = defaultRun
+  run: (command: string, args: string[], input?: number) => DocumentCommandResult = defaultRun
 ): DocumentExtraction {
   const probe = run("command", ["-v", "pdftotext"]);
   if (probe.error || probe.status !== 0) {
@@ -471,19 +473,31 @@ export function extractPdfFromDescriptor(
 // returns would hang the session rather than fail the read.
 const PDF_TIMEOUT_MS = 20_000;
 
+export function probeExecutableOnPath(executable: string): DocumentCommandResult {
+  const result = spawnSync("/bin/sh", ["-c", 'command -v "$1"', "piagent-command-probe", executable], {
+    encoding: "utf8",
+    timeout: PDF_TIMEOUT_MS
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+}
+
 function defaultRun(
   command: string,
   args: string[],
   input?: number
-): { status: number | null; stdout: string; stderr: string; error?: Error } {
-  const result = command === "command"
-    ? spawnSync("/bin/sh", ["-c", `command -v ${args[1]}`], { encoding: "utf8", timeout: PDF_TIMEOUT_MS })
-    : spawnSync(command, args, {
-      encoding: "utf8",
-      maxBuffer: MAX_DOCUMENT_BYTES,
-      timeout: PDF_TIMEOUT_MS,
-      stdio: [input ?? "ignore", "pipe", "pipe"]
-    });
+): DocumentCommandResult {
+  if (command === "command") return probeExecutableOnPath(args[1] ?? "");
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    maxBuffer: MAX_DOCUMENT_BYTES,
+    timeout: PDF_TIMEOUT_MS,
+    stdio: [input ?? "ignore", "pipe", "pipe"]
+  });
   return {
     status: result.status,
     stdout: result.stdout ?? "",

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,
@@ -49,10 +40,13 @@ import * as mcpActions from "../mcp/mcp-command-actions.js";
 import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
-  verifyCapabilityLock,
   writeJsonAtomic,
   writeProfileLockAtomic
 } from "../capabilities/capability-core.js";
+import {
+  createCapabilityVerificationCache,
+  verifyProjectCapabilityStateCached
+} from "../capabilities/capability-verification-cache.js";
 import { resolveCapabilitySourceRoots } from "../capabilities/capability-sources.js";
 import {
   actionTextMatchesAny, actionTokens, classifyActionTokenSequence, classifyExplicitActionValues, classifyToolNameAction,
@@ -91,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,
@@ -157,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";
@@ -715,7 +713,15 @@ type ProjectCapabilityState = {
   filesystemWrite?: string[];
 };
 
-function verifyProjectCapabilityState(extensionDir: string, cwd: string, projectTrusted: boolean): ProjectCapabilityState {
+const capabilityVerificationCache = createCapabilityVerificationCache();
+const sessionCapabilityDigests = new Map<string, string>();
+
+function verifyProjectCapabilityState(
+  extensionDir: string,
+  cwd: string,
+  projectTrusted: boolean,
+  options: { allowRepin?: boolean; forceFull?: boolean; sessionId?: string } = {}
+): ProjectCapabilityState {
   if (process.env.PIAGENT_PROFILE?.trim()) return { ok: true };
   if (!projectTrusted) return { ok: true };
   const profilePath = projectProfilePath(cwd);
@@ -725,46 +731,24 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
   // would skip the lock entirely for every project that references an adapter.
   const stored = readJsonFile<ProjectProfile>(profilePath);
   if (!stored) return { ok: true };
-  let profile: ProjectProfile;
   try {
-    profile = resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+    const profile = resolveProjectProfileDocument(findPlatformRoot(extensionDir), stored).profile;
+    if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) };
   }
-  if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   const lockPath = path.join(cwd, ".pi", "piagent-profile.lock.json");
   if (!fs.existsSync(lockPath)) return { ok: false, reason: "Capability lock is missing. Reapply the project profile." };
   const lock = readJsonFile<Record<string, unknown>>(lockPath);
   if (!lock) return { ok: false, reason: "Capability lock is unreadable. Reapply the project profile." };
   try {
-    const verification = verifyCapabilityLock(findPlatformRoot(extensionDir), profilePath, lock, {
-      packageSource: projectPackageSource(cwd),
-      extraRoots: capabilitySourceRoots(cwd, profile)
+    return verifyProjectCapabilityStateCached({
+      cache: capabilityVerificationCache, cwd, platformRoot: findPlatformRoot(extensionDir), profilePath, lockPath,
+      lockDocument: lock, storedProfile: stored, packageSource: projectPackageSource, extraRoots: capabilitySourceRoots,
+      writeLock: writeJsonAtomic, allowRepin: options.allowRepin, forceFull: options.forceFull,
+      sessionDigest: options.sessionId ? sessionCapabilityDigests.get(`${cwd}\0${options.sessionId}`) : undefined,
+      rememberSessionDigest: options.sessionId ? (digest: string) => sessionCapabilityDigests.set(`${cwd}\0${options.sessionId}`, digest) : undefined
     });
-    if (verification.status === "blocked") {
-      return {
-        ok: false,
-        reason: `Capability lock does not match what this project agreed to: ${verification.reasons.join("; ")}. Reapply the project profile.`
-      };
-    }
-    const granted = {
-      filesystemRead: verification.expected.permissions.filesystemRead,
-      filesystemWrite: verification.expected.permissions.filesystemWrite
-    };
-    if (verification.status !== "repin") return { ok: true, ...granted };
-
-    // The grant is unchanged and only the platform build moved. Record the new
-    // build instead of stopping the session, which is what turned every release
-    // into a chore in every project.
-    try {
-      writeJsonAtomic(lockPath, verification.expected);
-    } catch (error) {
-      return {
-        ok: false,
-        reason: `Capability lock is behind the installed platform and could not be rewritten: ${error instanceof Error ? error.message : String(error)}`
-      };
-    }
-    return { ok: true, repinned: verification.reasons.join("; "), ...granted };
   } catch (error) {
     return { ok: false, reason: `Capability validation failed: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -2199,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;
@@ -2231,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;
@@ -4045,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);
@@ -4253,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
   });
@@ -4273,13 +4273,15 @@ export default function piagentGuard(pi: ExtensionAPI) {
     resolveTaskAny: (cwd, reference) => resolveTaskContract(cwd, reference, undefined) as TaskContract | undefined,
     bindTask: bindSessionTask,
     writeTask,
-    capabilityState: (ctx) => verifyProjectCapabilityState(extensionDir, ctx.cwd, ctx.isProjectTrusted()),
+    capabilityState: (ctx) => verifyProjectCapabilityState(extensionDir, ctx.cwd, ctx.isProjectTrusted(), { allowRepin: true, forceFull: true, sessionId: ctx.sessionManager.getSessionId() }),
     permissionProfile: (ctx, profile) => resolvePermissionProfile(profile, policy, permissionOverrideFromContext(ctx)),
     legacyProjectWarning: legacyProjectStateWarning,
     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)
@@ -4297,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, {
@@ -4311,7 +4313,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
     flushObservedTaskContext,
     onTurnEnd: activityInspector.refresh,
     onAgentSettled: activityInspector.refresh,
-    beforeShutdown: activityInspector.dispose
+    beforeShutdown: (ctx) => {
+      sourceMutationGuardBindings.unbind(ctx);
+      activityInspector.dispose(ctx);
+      sessionCapabilityDigests.delete(`${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`);
+    }
   });
 
   registerInputHook(pi, {
@@ -4322,7 +4328,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const projectTrusted = ctx.isProjectTrusted();
       const profile = loadProfileFromContext(ctx);
       const permissionProfile = resolvePermissionProfile(profile, policy, permissionOverrideFromContext(ctx));
-      const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted);
+      const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted, { sessionId: ctx.sessionManager.getSessionId() });
       return {
         roots: resolveDocumentRoots({
           cwd: ctx.cwd,
@@ -4505,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;
@@ -4572,7 +4583,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const eventInput = isPlainRecord(event.input) ? event.input : {};
     const backendDecision = executionBackendToolDecision(isTaskMutationTool(event.toolName, eventInput));
     if (!backendDecision.allowed) return { block: true, reason: backendDecision.reason };
-    const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted);
+    const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted, { sessionId: ctx.sessionManager.getSessionId() });
     const recoveryTools = new Set(["piagent_profile_options", "piagent_profile_apply", "piagent_context", "read", "grep", "find", "ls"]);
     if (!capabilityState.ok && !recoveryTools.has(event.toolName)) {
       return { block: true, reason: capabilityState.reason ?? "Capability lock validation failed." };
@@ -4639,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) {
@@ -4703,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." } };
       }
     }
 
@@ -4725,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]));
@@ -4762,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." } };
       }
     }
 
@@ -4813,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,
@@ -4863,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"
@@ -4872,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;