@piagent/platform 1.6.0 → 1.6.1

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

@@ -67,7 +67,7 @@ import {
 } from "./context-index-policy.js";
 import {
   DEFAULT_MAX_TASK_ATTEMPTS, activeSessionTask, bindSessionTask, createTaskRunId, hasGitEvidenceRoot, listTaskContracts,
-  pathWithinChangeEvidenceRoot, priorTaskAttempts, repositoryFileManifest, repositoryFileManifestDetails, resolveTaskContract, safeTaskId, summarizeAttempt, taskContractValidationErrors, taskDigestMigrationArchiveStatus,
+  priorTaskAttempts, repositoryFileManifest, repositoryFileManifestDetails, resolveTaskContract, safeTaskId, summarizeAttempt, taskContractValidationErrors, taskDigestMigrationArchiveStatus,
   workPlanDependencyError, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence, writeTaskContract
 } from "./task-state.js";
 import { classifyRecordedVerificationFailure, classifyVerificationFailure, latestObservedVerification, meaningfulVerificationCommands, selectCompletionRecoveryClassification, selectVerificationPlan } from "./verification-intelligence.js";
@@ -110,6 +110,7 @@ import {
 } from "../runtime/session/tool-result-compaction.ts";
 import { RuntimeSessionState } from "../runtime/session/runtime-state.ts";
 import type { ObservedTaskContext } from "../runtime/session/runtime-state.ts";
+import { reuseCurrentTreeExactVerifier } from "../runtime/verification/exact-verifier-reuse.ts";
 import {
   PIAGENT_TOOL_GROUPS,
   PIAGENT_TOOL_NAMES,
@@ -161,11 +162,14 @@ import { inspectTaskResumeState } from "../runtime/recovery/resume-state.ts";
 import { SemanticRepairRuntime } from "../runtime/recovery/semantic-repair-runtime.ts";
 import { defaultRolePolicy } from "../runtime/orchestration/role-policy.ts";
 import { helpersMode } from "../runtime/orchestration/helper-lifecycle.ts";
+import { evaluateDirectSubagentDispatch, recordDirectSubagentResult, reserveDirectSubagentDispatch, taskHelperUsageMode } from "../runtime/orchestration/subagent-tool-policy.ts";
 import { buildLiveTaskStatus, formatLiveTaskStatus } from "../runtime/product/operator-projections.ts";
 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 { EditFreshnessGuard, editFreshnessModeFromEnvironment } from "../runtime/quality/edit-freshness-guard.ts";
 import { captureVerifierFileSnapshot } from "../runtime/inspection/verifier-snapshot-store.ts";
+import { fallbackBasePolicy } from "./fallback-base-policy.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";
@@ -341,11 +345,11 @@ const DEFAULT_RUNTIME_POLICY: Required<RuntimePolicySettings> = {
 
 const DEFAULT_ORCHESTRATION_POLICY: ResolvedOrchestrationPolicy = {
   defaultMode: "solo-first",
-  maxConcurrentSubagents: 2,
+  maxConcurrentSubagents: 1,
   defaultReviewLenses: ["correctness", "tests", "scope"],
   roleModelGuidance: {
     planner: "Use the strongest available model for decomposition, architecture, risk, and acceptance criteria.",
-    worker: "Use the fastest reliable model for a bounded, already-planned single write set.",
+    worker: "Disabled by default. The parent model owns all implementation and mutation.",
     reviewer: "Use a model or thinking setting decorrelated from the worker when review quality matters.",
     watchdog: "Use a strong model only for final risk review, security, release, or high-impact changes."
   },
@@ -357,9 +361,9 @@ const DEFAULT_ORCHESTRATION_POLICY: ResolvedOrchestrationPolicy = {
     readBeforeTask: true
   },
   rules: [
-    "Default to one parent agent; do not start a swarm for ordinary implementation.",
-    "Use subagents only for bounded read-only scout, planning, review, or a single approved worker.",
-    "Parallel read-only review is allowed when the diff is non-trivial; parallel writers require explicit user approval and isolation.",
+    "Default to the parent model working directly; a helper is an exceptional token optimization, not a reasoning phase.",
+    "Use at most one fresh read-only helper only when runtime evidence proves at least two independent lanes and at least 30% projected net token savings.",
+    "Never delegate implementation, inherit parent history, retry a deterministic helper failure, or run parallel helpers/writers.",
     "Treat Field Guide memory as advisory; verify every durable fact against current repository files.",
     "Keep review lenses explicit so cheap review work catches drift before release."
   ]
@@ -386,176 +390,7 @@ 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.*", "**/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: {
-    defaultMode: "workspace-write",
-    allowedModes: ["read-only", "workspace-write", "trusted-full-access"]
-  },
-  execPolicy: {
-    defaultMode: "enforce",
-    bannedPrefixSuggestions: [
-      ["python"],
-      ["python3"],
-      ["node"],
-      ["node", "-e"],
-      ["bash"],
-      ["bash", "-lc"],
-      ["sh"],
-      ["sh", "-c"],
-      ["zsh"],
-      ["zsh", "-lc"],
-      ["git"],
-      ["sudo"],
-      ["env"]
-    ],
-    rules: [
-      {
-        id: "prompt-git-add-broad",
-        action: "prompt",
-        match: "regex",
-        value: "(?:^|\\s)git\\s+(?:-C\\s+\\S+\\s+)?add\\s+(?:(?:--all|-A)(?:\\s+(?:\\.|:/))?|--\\s+(?:\\.|:/)|(?:\\.|:/))(?:\\s|$)",
-        reason: "Broad git staging can include unrelated or sensitive changes; inspect git status/diff and confirm the exact scope first."
-      }
-    ]
-  },
-  contextBudget: {
-    defaultMode: "enforce",
-    contextDeltaShadow: "sample",
-    maxContextFileChars: 50000,
-    maxMemoryFileChars: 20000,
-    maxManifestFiles: 80,
-    warnFragmentChars: 4000
-  },
-  toolRegistry: {
-    defaultMode: "advisory",
-    alwaysAllowedTools: [
-      "piagent_tools",
-      "piagent_context_engine",
-      "piagent_context",
-      "piagent_permission_status",
-      "piagent_exec_policy_check",
-      "piagent_context_budget",
-      "piagent_tool_policy_check",
-      "piagent_task_gate_check",
-      "piagent_usage_snapshot",
-      "piagent_orchestration_policy",
-      "piagent_memory_status",
-      "piagent_memory_note",
-      "piagent_memory_search",
-      "piagent_memory_citation_record",
-      "piagent_context_index_status",
-      "piagent_context_index_record",
-      "piagent_context_index_search",
-      "piagent_profile_options",
-      "piagent_profile_apply",
-      "piagent_profile_tech_options",
-      "piagent_profile_tech_apply",
-      "piagent_profile_tech_context_record",
-      "piagent_project_onboarding_record",
-      "piagent_task_start",
-      "piagent_task_progress",
-      "piagent_source_checkout",
-      "piagent_context_record",
-      "piagent_verify_record",
-      "piagent_trace_record"
-    ],
-    toolCapabilities: {
-      bash: ["shell"],
-      shell: ["shell"],
-      exec: ["shell"],
-      read: ["filesystem-readonly"],
-      grep: ["filesystem-readonly"],
-      find: ["filesystem-readonly"],
-      ls: ["filesystem-readonly"],
-      write: ["filesystem-write"],
-      edit: ["filesystem-write"],
-      apply_patch: ["filesystem-write"],
-      browser: ["browser"],
-      github: ["github"]
-    }
-  },
-  externalActionPolicy: {
-    defaultMode: "enforce",
-    providerKeywords: [
-      "github",
-      "gitlab",
-      "bitbucket",
-      "vercel",
-      "netlify",
-      "cloudflare",
-      "aws",
-      "gcp",
-      "azure",
-      "slack",
-      "teams",
-      "jira",
-      "linear",
-      "notion",
-      "figma",
-      "stripe",
-      "supabase",
-      "firebase"
-    ],
-    writeVerbs: [
-      "add",
-      "approve",
-      "archive",
-      "assign",
-      "close",
-      "comment",
-      "create",
-      "delete",
-      "deploy",
-      "dispatch",
-      "merge",
-      "open",
-      "post",
-      "publish",
-      "push",
-      "release",
-      "remove",
-      "reopen",
-      "run",
-      "send",
-      "submit",
-      "trigger",
-      "update",
-      "upload",
-      "write"
-    ],
-    safeVerbs: [
-      "fetch",
-      "find",
-      "get",
-      "inspect",
-      "list",
-      "read",
-      "search",
-      "show",
-      "view"
-    ]
-  },
-  finalGate: {
-    defaultMode: "enforce",
-    requireTaskContract: true,
-    requireContextManifest: true,
-    requireVerifyEvidence: true,
-    requireTrace: true,
-    requirePassingVerify: true
-  },
-  orchestrationPolicy: DEFAULT_ORCHESTRATION_POLICY
-};
+const DEFAULT_POLICY = fallbackBasePolicy(CONTEXT_INDEX_FILE, DEFAULT_ORCHESTRATION_POLICY);
 
 // Which platform supplies the adapters is fixed by where this file is installed,
 // so it is resolved once here rather than threaded through every profile load.
@@ -1016,7 +851,12 @@ function inspectPathInputsFromInput(
   const seen = new Set<string>();
   const walked = walkStringInputs(input, [], 0, includeFilesystemContentFields);
   for (const item of walked.items) {
-    const normalized = normalizeRelative(cwd, item.value);
+    const relative = normalizeRelative(cwd, item.value);
+    // `path.relative(root, root)` is the empty string. Treat that canonical
+    // project-root spelling as `.` so a capability such as `**/*` admits
+    // `ls .` and an absolute path equal to cwd. The empty candidate matched no
+    // scope and made fresh helpers unable to inspect even their own project.
+    const normalized = relative === "" ? "." : relative;
     if (normalized === undefined) continue;
     const key = `${item.field}\0${normalized}`;
     if (seen.has(key)) continue;
@@ -1126,6 +966,7 @@ function evaluatePathLikeToolAccess(
     forceScopeAware?: boolean;
     forceWrite?: boolean;
     allowAmbiguousFilesystemContentFields?: boolean;
+    sourceCheckoutReadRoots?: string[];
   } = {}
 ): { block: boolean; reason?: string } {
   const scopeAwareTool = options.forceScopeAware === true || ["read", "write", "edit", "grep", "find", "ls"].includes(toolName)
@@ -1167,9 +1008,13 @@ function evaluatePathLikeToolAccess(
   }
 
   for (const item of inspectedPaths) {
+    const fieldAccessMode = filesystemFieldAccessMode(toolName, item.field, writesFilesystem);
+    const sourceCheckoutReadRoot = fieldAccessMode === "read"
+      ? grantedSourceCheckoutRootForPath(cwd, item.path, options.sourceCheckoutReadRoots ?? [])
+      : undefined;
     if (scopeAwareTool && isFilesystemScopeField(item.field)) {
       const boundary = inspectRepositoryPathBoundary(cwd, item.path);
-      if (boundary.reason) return { block: true, reason: `Blocked ${toolName}: ${boundary.reason}` };
+      if (boundary.reason && !sourceCheckoutReadRoot) return { block: true, reason: `Blocked ${toolName}: ${boundary.reason}` };
     }
     const resolvedPath = resolveRepositoryPathCandidate(cwd, item.path);
     const readMatched = matchesProtectedPath(item.path, readProtectedPaths)
@@ -1181,7 +1026,6 @@ function evaluatePathLikeToolAccess(
       };
     }
 
-    const fieldAccessMode = filesystemFieldAccessMode(toolName, item.field, writesFilesystem);
     if (fieldAccessMode === "write") {
       const readOnlyMatched = matchesProtectedPath(item.path, readOnlyPaths)
         ?? (resolvedPath ? matchesProtectedPath(resolvedPath, readOnlyPaths) : undefined);
@@ -1205,7 +1049,8 @@ function evaluatePathLikeToolAccess(
           reason: `Blocked ${toolName} write outside resolved filesystem scope from ${item.field}: ${item.path}`
         };
       }
-    } else if (scopeAwareTool && filesystemRead && isFilesystemScopeField(item.field) && !matchesAnyPath(item.path, filesystemRead)) {
+    } else if (scopeAwareTool && filesystemRead && isFilesystemScopeField(item.field)
+      && !sourceCheckoutReadRoot && !matchesAnyPath(item.path, filesystemRead)) {
       return {
         block: true,
         reason: `Blocked ${toolName} read outside resolved filesystem scope from ${item.field}: ${item.path}`
@@ -1236,6 +1081,21 @@ function evaluatePathLikeToolAccess(
   return { block: false };
 }
 
+function grantedSourceCheckoutRootForPath(cwd: string, candidate: string, roots: string[]): string | undefined {
+  if (roots.length === 0) return undefined;
+  const absolute = path.resolve(cwd, normalizePathCandidate(candidate));
+  let canonical: string;
+  try {
+    canonical = fs.realpathSync.native(absolute);
+  } catch {
+    return undefined;
+  }
+  return roots.find((root) => {
+    const relative = path.relative(root, canonical);
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+  });
+}
+
 function stateRoot(cwd: string): string {
   return path.join(cwd, ".pi", "piagent-state");
 }
@@ -1513,7 +1373,7 @@ function resolveOrchestrationPolicy(profile: ProjectProfile, policy: BasePolicy)
   };
   return {
     defaultMode: normalizeOrchestrationMode(configured.defaultMode, defaultPolicy.defaultMode),
-    maxConcurrentSubagents: boundedInteger(configured.maxConcurrentSubagents, defaultPolicy.maxConcurrentSubagents, 0, 6),
+    maxConcurrentSubagents: Math.min(1, boundedInteger(configured.maxConcurrentSubagents, defaultPolicy.maxConcurrentSubagents, 0, 1)),
     defaultReviewLenses: normalizeReviewLenses(configured.defaultReviewLenses, defaultPolicy.defaultReviewLenses),
     roleModelGuidance,
     fieldGuide: {
@@ -1846,13 +1706,18 @@ function isReadOnlyTaskShellCommand(
   if (/[<>]|`|\$\(/.test(command)) {
     return false;
   }
-  const safeCommands = new Set(["pwd", "ls", "find", "rg", "grep", "cat", "sed", "head", "tail", "wc", "stat", "file", "test", "[", "which"]);
+  const safeCommands = new Set(["pwd", "ls", "find", "rg", "grep", "cat", "sed", "head", "tail", "wc", "stat", "file", "test", "[", "which", "printf", "sort"]);
   const safeGitSubcommands = new Set(["status", "diff", "log", "show", "ls-files", "rev-parse"]);
   return segments.length > 0 && segments.every((segment) => {
     const words = segment.words.filter(Boolean);
     const executable = path.basename(words[0] ?? "");
     if (executable === "sed" && words.some((word) => /^-.*i/.test(word))) return false;
     if (executable === "find" && words.some((word) => ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"].includes(word))) return false;
+    if (executable === "sort" && words.slice(1).some((word) => (
+      word === "--output"
+      || word.startsWith("--output=")
+      || /^-[^-]*o/.test(word)
+    ))) return false;
     if (safeCommands.has(executable)) return true;
     if (executable === "git") return safeGitSubcommands.has(words[1] ?? "");
     if (executable === "command") return words[1] === "-v";
@@ -1860,6 +1725,16 @@ function isReadOnlyTaskShellCommand(
   });
 }
 
+function shellTouchesGrantedSourceCheckout(cwd: string, command: string, roots: string[]): boolean {
+  if (roots.length === 0) return false;
+  for (const root of roots) {
+    const relative = path.relative(cwd, root).split(path.sep).join("/");
+    if (command.includes(root) || (relative && command.includes(relative))) return true;
+  }
+  return extractShellPathCandidates(command)
+    .some((candidate) => Boolean(grantedSourceCheckoutRootForPath(cwd, normalizeRelative(cwd, candidate) ?? candidate, roots)));
+}
+
 const PROJECT_MUTATING_EXECUTABLES = new Set([
   "apply_patch", "bash", "chmod", "chown", "cp", "dd", "install", "ln", "make", "mkdir", "mv", "prename", "rename",
   "node", "patch", "perl", "php", "python", "python3", "rm", "rmdir", "rsync", "ruby", "scp", "sh",
@@ -3714,7 +3589,9 @@ function evaluateTaskGate(
     if (task.changedFiles.length === 0) missing.push("changed files");
     if (changedFileEvidence.undeclared.length > 0) missing.push(`declared observed changes (${changedFileEvidence.undeclared.join(", ")})`);
     if (changedFileEvidence.unsupportedClaims.length > 0) missing.push(`supported changed-file claims (${changedFileEvidence.unsupportedClaims.join(", ")})`);
-    if (changedFileEvidence.outsideScope.length > 0) missing.push(`changes within task scope (${changedFileEvidence.outsideScope.join(", ")})`);
+    if (changedFileEvidence.outsideScope.length > 0) {
+      warnings.push(`Task focus expanded beyond the initial scope (${changedFileEvidence.outsideScope.join(", ")}).`);
+    }
   }
   if ((task.changeMode === "read-only" || task.mutationPolicy === "forbidden") && changedFileEvidence.expected.length > 0) {
     missing.push(`mutation-forbidden task has observed changes (${changedFileEvidence.expected.join(", ")})`);
@@ -3725,9 +3602,11 @@ function evaluateTaskGate(
     currentWorkingTreeDigest
   });
   const semanticEnforcement = taskAuthorityDecision(task, "CAP-13", "block").allowed;
-  if (semanticEnforcement && acceptance.criticalMissing.length > 0) {
-    missing.push(`critical acceptance evidence (${acceptance.criticalMissing.map((criterion) => `${criterion.id}:${criterion.obligation}`).join(", ")})`);
-  }
+  const abstainedIds = new Set(acceptance.adapterAbstained.map((criterion) => criterion.id));
+  const adapterCritical = acceptance.criticalMissing.filter((criterion) => abstainedIds.has(criterion.id));
+  const linkedCritical = acceptance.criticalMissing.filter((criterion) => !abstainedIds.has(criterion.id));
+  if (semanticEnforcement && linkedCritical.length > 0) missing.push(`critical acceptance evidence (${linkedCritical.map((criterion) => `${criterion.id}:${criterion.obligation}`).join(", ")})`);
+  if (semanticEnforcement && adapterCritical.length > 0) missing.push(`critical acceptance evidence adapter-unresolved (${adapterCritical.map((criterion) => `${criterion.id}:${criterion.obligation}`).join(", ")}); remedy: add a direct-relative focused test or configure a deterministic adapter`);
   const acceptanceConflicts = acceptanceSemanticConflicts(task, {
     cwd,
     changedFiles: changedFileEvidence.expected
@@ -3735,7 +3614,11 @@ function evaluateTaskGate(
   if (semanticEnforcement && acceptanceConflicts.length > 0) {
     missing.push(`acceptance semantic conflicts (${acceptanceConflicts.join(", ")})`);
   }
-  const normalMissing = acceptance.missing.filter((criterion) => criterion.priority !== "critical");
+  const criticalIds = new Set(acceptance.criticalMissing.map((criterion) => criterion.id));
+  const normalMissing = acceptance.missing.filter((criterion) => !criticalIds.has(criterion.id));
+  if (semanticEnforcement && acceptance.adapterAbstained.length > 0) {
+    warnings.push(`Acceptance proof adapter abstained; rigorous criteria remain pending and hand off without an automatic model retry: ${acceptance.adapterAbstained.map((criterion) => `${criterion.id}:${criterion.obligation}`).join(", ")}`);
+  }
   if (!semanticEnforcement && (acceptance.criticalMissing.length > 0 || acceptanceConflicts.length > 0)) warnings.push("Acceptance projection is advisory under the pinned task authority and cannot block completion.");
   if (normalMissing.length > 0) {
     warnings.push(`Acceptance criteria pending evidence: ${normalMissing.map((criterion) => `${criterion.id}:${criterion.obligation}`).join(", ")}`);
@@ -3915,6 +3798,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
   const runtimeState = new RuntimeSessionState({
     maxObservedContext: contextBudgetConfig(policy).maxManifestFiles
   });
+  const editFreshnessGuard = new EditFreshnessGuard(editFreshnessModeFromEnvironment(process.env.PIAGENT_EDIT_FRESHNESS));
   const sourceMutationGuardBindings = createSourceMutationGuardBindings(policy, loadProfileFromContext);
   const runtimeSnapshotCapture = new RuntimeSnapshotCapture(), runtimeVersions = readRuntimeVersionMetadata(PLATFORM_ROOT);
   const solverShadow = solverMode === "off" ? undefined : new SolverShadowRuntime(solverMode);
@@ -4137,8 +4021,11 @@ export default function piagentGuard(pi: ExtensionAPI) {
       failed?.exitCode ?? 1
     );
     const trajectory = trajectoryRuntime.status(ctx.cwd, task.taskRunId);
-    const dependencyMutationAuthorized = task.scope.some((entry) => /(?:^|\/)(?:package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|[^/]*(?:config|lock)[^/]*)$/i.test(entry));
-    return selectRecoveryDecision({
+    // Task scope is a retrieval/review hint, not filesystem authority. Recovery
+    // may update a dependency or config file when repository evidence requires
+    // it; protected-path and approval policy still run on the exact call.
+    const dependencyMutationAuthorized = true;
+    const selected = selectRecoveryDecision({
       featureEnabled: autoRecoveryEnabled && taskAuthorityDecision(task, "CAP-12", "model-turn").allowed,
       task: {
         taskId: task.taskId,
@@ -4157,6 +4044,9 @@ export default function piagentGuard(pi: ExtensionAPI) {
         : true,
       dependencyMutationAuthorized
     });
+    return gate?.missing.some((item) => /^critical acceptance evidence adapter-unresolved\b/i.test(item))
+      ? { ...selected, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false, reasonCodes: ["unknown-diagnostic-exhausted"] }
+      : selected;
   }
 
   function trajectoryRecoveryOptions(ctx: ExtensionContext, task: TaskContract, options: any): any {
@@ -4194,6 +4084,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     resolveTaskAny: (cwd, reference) => resolveTaskContract(cwd, reference, undefined) as TaskContract | undefined,
     bindTask: bindSessionTask,
     writeTask,
+    appendTrace,
     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,
@@ -4237,6 +4128,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     onAgentSettled: activityInspector.refresh,
     beforeShutdown: (ctx) => {
       sourceMutationGuardBindings.unbind(ctx);
+      editFreshnessGuard.clear(ctx);
       activityInspector.dispose(ctx);
       sessionCapabilityDigests.delete(`${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`);
     }
@@ -4334,6 +4226,36 @@ export default function piagentGuard(pi: ExtensionAPI) {
     telemetry,
     activity: recordActivity,
     now: nowIso,
+    recordSubagentResult: (ctx, event, result) => {
+      const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+      const written = recordDirectSubagentResult(task, event, result, {
+        now: nowIso,
+        persist: (candidate) => writeTask(ctx.cwd, candidate),
+        trace: (payload) => appendTrace(ctx.cwd, payload),
+        sessionTrace: (payload) => appendSessionTrace(pi, payload)
+      });
+      telemetry(ctx, {
+        event: "helper_result_classified",
+        recordedAt: nowIso(),
+        taskRunId: written?.taskRunId,
+        toolCallId: event.toolCallId,
+        spawned: result.spawned,
+        failed: result.failed,
+        disposition: result.disposition,
+        reasonCode: result.reasonCode,
+        calls: result.calls,
+        tokens: result.tokens
+      });
+    },
+    observeEditFreshness: (ctx, event, metadata) => {
+      if (!metadata.successful || !metadata.taskRunId) return;
+      const protectedPaths = effectiveProtectedPaths(policy, loadProfileFromContext(ctx)).readProtectedPaths;
+      const source = event.toolName === "read" ? "read" : ["edit", "write", "apply_patch"].includes(event.toolName) ? "mutation" : undefined;
+      const candidates = source === "read" && metadata.targetPath ? [metadata.targetPath] : source === "mutation" ? metadata.mutationTargets : [];
+      const safeTargets = candidates.filter((file) => !matchesProtectedPath(file, protectedPaths));
+      const observed = source ? editFreshnessGuard.observe(ctx, metadata.taskRunId, safeTargets, source, nowIso()) : [];
+      if (observed.length) telemetry(ctx, { event: "edit_freshness_snapshot_observed", taskRunId: metadata.taskRunId, source, paths: observed.map(redactText) });
+    },
     completeSemanticRepair: (ctx, event, metadata) => {
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
       return task && (taskAuthorityDecision(task, "CAP-13", "mutate").allowed
@@ -4354,10 +4276,42 @@ export default function piagentGuard(pi: ExtensionAPI) {
     activity: recordActivity,
     beforeAuthorize: (event, ctx) => {
       const toolInput = isPlainRecord(event.input) ? event.input : {};
+      const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+      const helperPreflight = evaluateDirectSubagentDispatch({
+        toolName: event.toolName,
+        toolInput,
+        cwd: ctx.cwd,
+        helpersMode: task ? taskHelperUsageMode(task) : helpersMode(),
+        taskPending: task?.trace.outcome === "pending",
+        dispatchAuthority: Boolean(task && taskAuthorityDecision(task, "CAP-14", "dispatch").allowed),
+        durableSubagentState: task?.orchestration?.subagents
+      });
+      if (helperPreflight.applicable && helperPreflight.dispatch && !helperPreflight.allowed) {
+        telemetry(ctx, {
+          event: "helper_dispatch_blocked",
+          recordedAt: nowIso(),
+          taskRunId: task?.taskRunId,
+          toolCallId: event.toolCallId,
+          reasonCode: helperPreflight.reasonCode,
+          role: helperPreflight.role,
+          requestCount: helperPreflight.requestCount
+        });
+        return { block: true, reason: `Blocked ${event.toolName}: ${helperPreflight.reason} Do not retry this helper; continue in the parent.` };
+      }
+      const verifierReuse = reuseCurrentTreeExactVerifier({ cwd: ctx.cwd, task, toolName: event.toolName, toolInput, sessionEntries: ctx.sessionManager.getEntries() as unknown[] });
+      if (verifierReuse.reused) {
+        telemetry(ctx, { event: "verifier_evidence_reused", recordedAt: nowIso(), taskRunId: task?.taskRunId, toolCallId: event.toolCallId, reasonCode: verifierReuse.reasonCode, commandDigest: verifierReuse.commandDigest, workingTreeDigest: verifierReuse.workingTreeDigest }); return;
+      }
       const targetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, toolInput);
       if (targetInspection.reason) return { block: true, reason: `Blocked ${event.toolName}: ${targetInspection.reason}.` };
+      if (task?.trace.outcome === "pending" && task.changeMode === "source-change" && (event.toolName === "edit" || targetInspection.exactLocalPatchExecutor)) {
+        const freshness = editFreshnessGuard.evaluate(ctx, task.taskRunId, targetInspection.targets);
+        if (freshness.decision === "stale") {
+          telemetry(ctx, { event: "edit_freshness_stale", taskRunId: task.taskRunId, toolCallId: event.toolCallId, enforce: freshness.enforce, paths: freshness.stalePaths.map(redactText) });
+          if (freshness.enforce) return { block: true, reason: `Blocked ${event.toolName}: the previously observed source snapshot is stale for ${freshness.stalePaths.map(redactText).join(", ")}. Reread the affected file once; no patch hunk was started.` };
+        }
+      }
       if (!["edit", "write"].includes(event.toolName) && !targetInspection.exactLocalPatchExecutor) return;
-      const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
       if (!task || task.trace.outcome !== "pending" || task.changeMode !== "source-change") return;
       const semanticRepairEnabled = taskAuthorityDecision(task, "CAP-13", "mutate").allowed;
       const semanticRepairExactlyOff = !taskAuthorityDecision(task, "CAP-13", "observe").allowed;
@@ -4374,11 +4328,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const currentDigest = workingTreeEvidenceDigest(currentSnapshot);
       const expectedReviewPaths = taskDeltaFilesFromSnapshot(task, currentSnapshot);
       const targets = targetInspection.targets;
-      const boundedInScopeMutation = targets.length > 0
-        && targets.every((file) => taskScopeIncludesPath(task.scope, file));
+      const boundedTargetMutation = targets.length > 0;
       const verifierCurrent = allVerifyCommandsPassCurrentTree(task, currentDigest);
 
-      if (phase.phase === "verify" && boundedInScopeMutation && semanticRepairEnabled && semanticRepairRuntime.prepare({
+      if (phase.phase === "verify" && boundedTargetMutation && semanticRepairEnabled && semanticRepairRuntime.prepare({
         ctx, task, event, currentDigest, currentDeltaPaths: expectedReviewPaths, targetPaths: targets,
         verifierCurrent
       })) return;
@@ -4388,7 +4341,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       // model catches its own omission in the same task/run/session. The call
       // still traverses every normal authorization check; verify -> repair is
       // committed only by the tool-result hook after a successful tree change.
-      if (phase.phase === "verify" && boundedRecoveryEnabled && verifierCurrent && boundedInScopeMutation) {
+      if (phase.phase === "verify" && boundedRecoveryEnabled && verifierCurrent && boundedTargetMutation) {
         const authoredFileDigests = runtimeState.successfulModelMutationDigests(
           { taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId },
           currentSnapshot
@@ -4436,7 +4389,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
         return reviewDecision;
       }
 
-      if (targets.length === 0 || targets.some((file) => !taskScopeIncludesPath(task.scope, file))) return;
+      if (targets.length === 0) return;
       const result = trajectoryRuntime.sync(ctx.cwd, ctx.sessionManager.getSessionId(), task, {
         sourceHook: "tool-call",
         recoveryRequested: true,
@@ -4460,11 +4413,9 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const targetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, toolInput);
       if (targetInspection.reason) return { block: true, reason: `Blocked ${event.toolName}: ${targetInspection.reason}.` };
       const targets = targetInspection.targets;
-      if ((["edit", "write"].includes(event.toolName) || targetInspection.patchCarrier) && (
-        targets.length === 0 || targets.some((file) => !taskScopeIncludesPath(task.scope, file))
-      )) {
+      if ((["edit", "write"].includes(event.toolName) || targetInspection.patchCarrier) && targets.length === 0) {
         runtimeState.denyPerformanceReviewTool(task.taskRunId);
-        return { block: true, reason: `Task ${task.taskId} semantic repair must stay inside its declared task scope.` };
+        return { block: true, reason: `Task ${task.taskId} semantic repair requires an exact statically bounded target.` };
       }
       const reviewDecision = performanceReviewToolDecision({
         toolName: event.toolName,
@@ -4492,6 +4443,30 @@ export default function piagentGuard(pi: ExtensionAPI) {
     },
     afterAuthorized: (event, ctx, metadata) => {
       const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+      const helperPreflight = evaluateDirectSubagentDispatch({
+        toolName: event.toolName,
+        toolInput: event.input,
+        cwd: ctx.cwd,
+        helpersMode: task ? taskHelperUsageMode(task) : helpersMode(),
+        taskPending: task?.trace.outcome === "pending",
+        dispatchAuthority: Boolean(task && taskAuthorityDecision(task, "CAP-14", "dispatch").allowed),
+        durableSubagentState: task?.orchestration?.subagents
+      });
+      if (helperPreflight.applicable && helperPreflight.dispatch && helperPreflight.allowed) {
+        const reserved = reserveDirectSubagentDispatch(task, metadata.toolCallId, {
+          now: nowIso,
+          persist: (candidate) => writeTask(ctx.cwd, candidate),
+          trace: (payload) => appendTrace(ctx.cwd, payload)
+        });
+        telemetry(ctx, {
+          event: "helper_dispatch_reserved",
+          recordedAt: nowIso(),
+          taskRunId: reserved?.taskRunId,
+          toolCallId: metadata.toolCallId,
+          role: helperPreflight.role,
+          requestCount: helperPreflight.requestCount
+        });
+      }
       if (task?.trace.outcome === "pending") {
         const snapshot = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
         const currentDigest = workingTreeEvidenceDigest(snapshot);
@@ -4639,6 +4614,12 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const execDecision = evaluateExecPolicy(command, profile, policy);
       authorizedShellCommand = command;
       authorizedShellSegments = execDecision.segments;
+      if (shellTouchesGrantedSourceCheckout(ctx.cwd, command, runtimeState.sourceCheckoutReadRoots(ctx))) {
+        return {
+          block: true,
+          reason: "Shared source checkouts are shell-inaccessible. Inspect the exact session-granted checkout with read, grep, find, or ls; cache mutation is never authorized."
+        };
+      }
       shellProjectMutation = isProjectMutatingShellCommand(command, execDecision.segments);
       configuredVerifierShell = Boolean(sessionTask && commandMatchesVerifyPlan(command, sessionTask.verifyCommands));
       const shellWriteCandidates = extractShellWritePathCandidates(command);
@@ -4730,7 +4711,8 @@ export default function piagentGuard(pi: ExtensionAPI) {
       {
         forceScopeAware: authorizationTargetInspection.patchCarrier || Boolean(preparedInput.proxyToolName),
         forceWrite: authorizationTargetInspection.patchCarrier || preparedInput.proxyAction?.decision === "confirm",
-        allowAmbiguousFilesystemContentFields: !usesKnownExternalProvider && !isPiagentTool(event.toolName)
+        allowAmbiguousFilesystemContentFields: !usesKnownExternalProvider && !isPiagentTool(event.toolName),
+        sourceCheckoutReadRoots: runtimeState.sourceCheckoutReadRoots(ctx)
       }
     );
     if (pathDecision.block) {
@@ -4816,32 +4798,18 @@ export default function piagentGuard(pi: ExtensionAPI) {
           + " Call `piagent_task_start` once with explicit project-relative scope, then retry."
       };
     }
-    if (sessionTask?.trace.outcome === "pending" && sessionTask.changeMode === "source-change") {
-      if (
-        shellProjectMutation
-        && opaqueShellMutationNeedsBoundedTarget(authorizedShellCommand, authorizedShellSegments)
-        && !shellMutationTargetBounded
-        && !configuredVerifierShell
-      ) {
-        return {
-          block: true,
-          reason: `Task ${sessionTask.taskId} cannot run an opaque shell mutation whose write target is not statically bounded. Use edit/write/apply_patch, an explicit in-scope redirection, or the exact configured verifier.`
-        };
-      }
-      const outsideScope = mutationTargets.filter((file) => !taskScopeIncludesPath(sessionTask.scope, file));
-      if (outsideScope.length > 0) {
-        return {
-          block: true,
-          reason: `Task ${sessionTask.taskId} cannot mutate paths outside its declared scope: ${outsideScope.join(", ")}.`
-        };
-      }
-      const outsideEvidenceRoot = mutationTargets.filter((file) => !pathWithinChangeEvidenceRoot(ctx.cwd, file));
-      if (outsideEvidenceRoot.length > 0) {
-        return {
-          block: true,
-          reason: `Task ${sessionTask.taskId} cannot mutate paths outside a change evidence root: ${outsideEvidenceRoot.join(", ")}. In a parent workspace with separate repos, write under a child repo or a scoped workspace directory such as plans/**.`
-        };
-      }
+    if (
+      sessionTask?.trace.outcome === "pending"
+      && sessionTask.changeMode === "source-change"
+      && shellProjectMutation
+      && opaqueShellMutationNeedsBoundedTarget(authorizedShellCommand, authorizedShellSegments)
+      && !shellMutationTargetBounded
+      && !configuredVerifierShell
+    ) {
+      return {
+        block: true,
+        reason: `Task ${sessionTask.taskId} cannot run an opaque shell mutation whose write target is not statically bounded. Use edit/write/apply_patch, an explicit project-local redirection, or the exact configured verifier.`
+      };
     }
     if (runtime.contextBudget !== "off" && (["write", "edit"].includes(event.toolName) || authorizationTargetInspection.patchCarrier)) {
       const budgetTargets = authorizationTargetInspection.patchCarrier