@piagent/platform 1.3.1 → 1.4.1

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

@@ -11,18 +11,14 @@ import {
   evaluateExecPolicyCore, extractShellGlobCandidates, extractShellPathCandidates, findProtectedPathInCommand, unresolvedPathExpansions,
   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";
+  expandSimpleGlobAlternatives, findResolvedProtectedPathInCommand, normalizeRelative, protectedPatternExamples,
+  resolveRepositoryPathCandidate, shellGlobMatchesPath, shellGlobSegmentMatches, shellGlobTargetsProtectedPath,
+  unresolvedExpansionReason
+} from "./shell-reach.ts";
+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 {
   DOCUMENT_EXTENSIONS,
   extractDocument,
@@ -94,6 +90,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 +159,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";
@@ -379,10 +379,16 @@ const SHELL_TOOL_NAMES = new Set(["bash", "shell", "exec"]);
 const MAX_MCP_PROXY_ARGS_CHARS = 131_072;
 const SESSION_PERMISSION_OVERRIDES = new Map<string, PermissionProfileMode>();
 
+// The policy used when `policies/base-policy.json` cannot be read. It runs in
+// exactly the case where something is already wrong, so it must never be the
+// looser of the two: this copy had drifted behind the file and silently dropped
+// `.pi/piagent-state/**` -- the guard's own state -- along with the `sudo ` and
+// `chmod -R 777` blocks. A missing policy file is a reason to be stricter, not a
+// quiet downgrade. `tests/policy-core.test.mjs` fails if this drifts again.
 const DEFAULT_POLICY: BasePolicy = {
-  protectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
-  shellProtectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
-  blockedCommandPatterns: ["rm -rf /", "rm -rf ~", "rm -rf $HOME", "git reset --hard", "git clean -fd"],
+  protectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", "**/node_modules/**", "**/dist/**", ".pi/piagent-state/**", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
+  shellProtectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/piagent-state/**", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
+  blockedCommandPatterns: ["rm -rf /", "rm -rf ~", "rm -rf $HOME", "git reset --hard", "git clean -fd", "sudo ", "chmod -R 777"],
   requireConfirmationPatterns: ["deploy", "release", "publish", "migration", "gh pr merge", "git push"],
   defaultRequiredContext: ["AGENTS.md", "README.md"],
   permissionProfiles: {
@@ -651,26 +657,6 @@ function legacyProjectStateWarning(cwd: string): string | undefined {
     : `${detail} No .pi/piagent-profile.json exists, so this project is running unprofiled and its protected paths and verify commands are NOT enforced. Convert it with \`piagent-migrate . --apply\`.`;
 }
 
-function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
-  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
-  let raw = candidate.trim();
-  try {
-    raw = decodeURIComponent(raw);
-  } catch {
-    return undefined;
-  }
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
-    if (!raw.toLowerCase().startsWith("file://")) return undefined;
-    try {
-      raw = fileURLToPath(raw);
-    } catch {
-      return undefined;
-    }
-  }
-  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
-  return path.relative(cwd, absolute).split(path.sep).join("/");
-}
-
 function slugify(input: string): string {
   return input
     .trim()
@@ -962,60 +948,6 @@ function inspectRepositoryPathBoundary(cwd: string, candidate: string): { reason
   return {};
 }
 
-function resolveRepositoryPathCandidate(cwd: string, candidate: string): string | undefined {
-  const normalized = normalizePathCandidate(candidate);
-  if (normalized === ".." || normalized.startsWith("../")) return undefined;
-
-  const relative = path.posix.isAbsolute(normalized)
-    ? path.relative(cwd, normalized).split(path.sep).join("/")
-    : normalized;
-  if (relative === ".." || relative.startsWith("../")) return undefined;
-
-  const pending = relative.split("/").filter((item) => item && item !== ".");
-  let current = cwd;
-  let resolvedDepth = 0;
-  for (let index = 0; index < pending.length; index += 1) {
-    const next = path.join(current, pending[index]);
-    try {
-      fs.lstatSync(next);
-      current = next;
-      resolvedDepth = index + 1;
-    } catch (error) {
-      const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : "";
-      if (code !== "ENOENT") return undefined;
-      break;
-    }
-  }
-
-  let canonicalBase: string;
-  try {
-    canonicalBase = fs.realpathSync.native(current);
-  } catch {
-    return undefined;
-  }
-  const canonical = path.resolve(canonicalBase, ...pending.slice(resolvedDepth));
-  const canonicalRoot = fs.realpathSync.native(cwd);
-  const canonicalRelative = path.relative(canonicalRoot, canonical).split(path.sep).join("/");
-  if (canonicalRelative === ".." || canonicalRelative.startsWith("../") || path.isAbsolute(canonicalRelative)) return undefined;
-  return canonicalRelative || ".";
-}
-
-function findResolvedProtectedPathInCommand(
-  cwd: string,
-  command: string,
-  protectedPatterns: string[]
-): { candidate: string; resolved: string; pattern: string } | undefined {
-  for (const candidate of extractShellPathCandidates(command)) {
-    const relative = normalizeRelative(cwd, candidate);
-    if (!relative) continue;
-    const resolved = resolveRepositoryPathCandidate(cwd, relative);
-    if (!resolved || resolved === relative) continue;
-    const pattern = matchesProtectedPath(resolved, protectedPatterns);
-    if (pattern) return { candidate, resolved, pattern };
-  }
-  return undefined;
-}
-
 const MAX_TOOL_INPUT_INSPECTION_DEPTH = 32;
 
 type StringInputWalkResult = {
@@ -1093,130 +1025,6 @@ function extractLikelyPathFromInput(cwd: string, input: Record<string, unknown>)
   return extractPathInputsFromInput(cwd, input)[0]?.path;
 }
 
-function expandSimpleGlobAlternatives(pattern: string, max = 24): { values: string[]; complete: boolean } {
-  let results = [pattern];
-  let changed = true;
-  let complete = true;
-
-  while (changed) {
-    changed = false;
-    const expanded: string[] = [];
-    for (const item of results) {
-      const match = item.match(/\{([^{}]+)\}/);
-      if (!match) {
-        expanded.push(item);
-        continue;
-      }
-      changed = true;
-      const options = match[1].split(",").map((option) => option.trim());
-      for (const option of options) {
-        expanded.push(`${item.slice(0, match.index)}${option}${item.slice((match.index ?? 0) + match[0].length)}`);
-        if (expanded.length >= max) {
-          complete = false;
-          break;
-        }
-      }
-      if (expanded.length >= max) break;
-    }
-    results = expanded.slice(0, max);
-  }
-
-  return { values: results, complete };
-}
-
-function shellGlobSegmentMatches(patternSegment: string, candidateSegment: string): boolean {
-  if (candidateSegment.startsWith(".") && !patternSegment.startsWith(".")) return false;
-  let source = "";
-  for (let index = 0; index < patternSegment.length; index += 1) {
-    const char = patternSegment[index];
-    if (char === "*") {
-      source += "[^/]*";
-      continue;
-    }
-    if (char === "?") {
-      source += "[^/]";
-      continue;
-    }
-    if (char === "[") {
-      const end = patternSegment.indexOf("]", index + 1);
-      const body = end > index + 1 ? patternSegment.slice(index + 1, end) : "";
-      if (body && /^[!^A-Za-z0-9_-]+$/.test(body)) {
-        const negated = body.startsWith("!") ? `^${body.slice(1)}` : body;
-        source += `[${negated}]`;
-        index = end;
-        continue;
-      }
-    }
-    source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
-  }
-  return new RegExp(`^${source}$`, "i").test(candidateSegment);
-}
-
-function shellGlobMatchesPath(pattern: string, candidate: string): boolean {
-  const patternSegments = normalizePathCandidate(pattern).split("/").filter(Boolean);
-  const candidateSegments = normalizePathCandidate(candidate).split("/").filter(Boolean);
-
-  function match(patternIndex: number, candidateIndex: number): boolean {
-    if (patternIndex === patternSegments.length) return candidateIndex === candidateSegments.length;
-    const patternSegment = patternSegments[patternIndex];
-    if (patternSegment === "**") {
-      if (match(patternIndex + 1, candidateIndex)) return true;
-      for (let next = candidateIndex; next < candidateSegments.length; next += 1) {
-        if (match(patternIndex + 1, next + 1)) return true;
-      }
-      return false;
-    }
-    if (candidateIndex >= candidateSegments.length) return false;
-    return shellGlobSegmentMatches(patternSegment, candidateSegments[candidateIndex])
-      && match(patternIndex + 1, candidateIndex + 1);
-  }
-
-  return patternSegments.length > 0 && candidateSegments.length > 0 && match(0, 0);
-}
-
-function protectedPatternExamples(pattern: string): string[] {
-  const normalized = normalizePathCandidate(pattern);
-  if (!normalized) return [];
-
-  const examples = new Set<string>();
-  const add = (value: string | undefined) => {
-    const normalizedValue = normalizePathCandidate(value ?? "");
-    if (normalizedValue) examples.add(normalizedValue);
-  };
-
-  add(normalized);
-
-  if (normalized.endsWith("/**")) {
-    const base = normalized.slice(0, -3);
-    add(base);
-    add(`${base}/probe`);
-  }
-
-  if (normalized.startsWith("**/")) {
-    const tail = normalized.slice(3);
-    const concreteTail = tail
-      .replace(/\*\*/g, "nested")
-      .replace(/\*/g, tail.includes(".env.") ? "local" : "probe");
-    add(tail);
-    add(concreteTail);
-    add(`nested/${concreteTail}`);
-  }
-
-  const concrete = normalized
-    .replace(/^\*\*\//, "")
-    .replace(/\/\*\*$/, "/probe")
-    .replace(/\*\*/g, "nested")
-    .replace(/\*/g, normalized.includes(".env.") ? "local" : "probe");
-  add(concrete);
-
-  for (const example of [...examples]) {
-    const base = path.posix.basename(example);
-    if (base && base !== "probe") examples.add(base);
-  }
-
-  return [...examples];
-}
-
 function protectedLiteralHints(pattern: string): string[] {
   const normalized = normalizePathCandidate(pattern).toLowerCase();
   if (!normalized) return [];
@@ -1276,32 +1084,6 @@ function globTargetsProtectedPath(glob: unknown, protectedPatterns: string[]): {
   return undefined;
 }
 
-function shellGlobTargetsProtectedPath(
-  command: string,
-  protectedPatterns: string[]
-): { glob: string; pattern: string; example: string } | undefined {
-  for (const candidate of extractShellGlobCandidates(command)) {
-    if (!/[*?{\[]/.test(candidate)) continue;
-    const expanded = expandSimpleGlobAlternatives(candidate);
-    if (!expanded.complete) return { glob: candidate, pattern: "bounded glob expansion", example: "a protected path" };
-    for (const candidateGlob of expanded.values) {
-      for (const pattern of protectedPatterns) {
-        for (const example of protectedPatternExamples(pattern)) {
-          if (/[*?{\[\]]/.test(example)) continue;
-          if (
-            shellGlobMatchesPath(candidateGlob, example)
-            || shellGlobMatchesPath(`**/${candidateGlob}`, example)
-            || shellGlobMatchesPath(candidateGlob, path.posix.basename(example))
-          ) {
-            return { glob: candidate, pattern, example };
-          }
-        }
-      }
-    }
-  }
-  return undefined;
-}
-
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const prototype = Object.getPrototypeOf(value);
@@ -2188,10 +1970,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 +2004,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;
@@ -2541,13 +2337,6 @@ function evaluateMcpApproval(
 // running the substitution. Matching the literal half against the protected
 // patterns answers a different question than the one being asked, so refuse
 // rather than let an unknown filename through unchecked.
-function unresolvedExpansionReason(subject: string, words: string[]): string {
-  const listed = words.map((word) => `\`${word}\``).join(", ");
-  return `${subject} builds a filename this guard cannot resolve: ${listed}. `
-    + "The literal text around the expansion makes it a path, but its value is only known at run time, "
-    + "so it cannot be checked against the protected paths. Write the path out, or put the expansion in its own argument.";
-}
-
 function evaluateMcpProxyShellProtectedAccess(
   cwd: string,
   prepared: PreparedToolInput,
@@ -4034,6 +3823,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 +4032,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 +4059,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 +4079,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 +4094,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 +4291,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 +4430,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 +4494,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 +4513,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 +4549,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 +4595,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,
@@ -4814,7 +4609,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (!sessionTask && taskContractRequired && (shellProjectMutation || directProjectMutation)) {
       return {
         block: true,
-        reason: "A session-bound Task Implementation Contract is required before project files can be mutated. Start the task first."
+        // Naming the tool matters: this is the first wall a new operator hits,
+        // and "start the task first" does not say with what.
+        reason: "A session-bound Task Implementation Contract is required before project files can be mutated."
+          + " Call `piagent_task_start` once with explicit project-relative scope, then retry."
       };
     }
     if (sessionTask?.trace.outcome === "pending" && sessionTask.changeMode === "source-change") {
@@ -4855,6 +4653,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 +4673,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/runtime-evidence.js

@@ -58,11 +58,22 @@ function numericExitCode(value) {
   return undefined;
 }
 
+// `isError: false` is Pi stating that the command succeeded, so it is evidence
+// and a claim of zero matches it. An observation that states neither an exit code
+// nor an error flag says nothing at all, and nothing is not evidence of success:
+// without this an empty record satisfied a claim of zero, which is the one
+// direction a ledger built to catch forged verification must never fail in.
+//
+// Both shapes are unreachable through `observedBashResultFromToolResultEvent` and
+// `readObservedBashResults`, which always set a boolean flag. The guard is here
+// because a reader of this function should not have to prove that to know the
+// answer is safe.
 export function claimedExitMatchesObserved(exitCode, observed) {
   const claimed = numericExitCode(exitCode);
   if (claimed === undefined) return false;
   if (typeof observed?.exitCode === "number") return observed.exitCode === claimed;
-  return observed?.isError === true ? claimed !== 0 : claimed === 0;
+  if (typeof observed?.isError !== "boolean") return false;
+  return observed.isError ? claimed !== 0 : claimed === 0;
 }
 
 export function extractBashCommandFromToolResultEvent(event) {