@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/extensions/workspace-evidence-roots.js

@@ -0,0 +1,193 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// Parent workspaces commonly carry shared plans, verifier scripts, and agent
+// configuration beside their child repositories. Keep the traversal bounded,
+// but leave enough room for a real multi-repository workspace instead of
+// silently dropping evidence at the former 2,000-file ceiling.
+const WORKSPACE_EVIDENCE_MAX_FILES = 20_000;
+// These names are not merely noisy build output: they carry repository
+// ownership, Piagent authority, or provider credentials. Evidence discovery
+// excludes them and the mutation guard protects them independently of task
+// focus, so broad monorepo access cannot create an unaudited private-state gap.
+export const WORKSPACE_PRIVATE_STATE_PATTERNS = Object.freeze([
+  "**/.git/**", "**/.hg/**", "**/.svn/**", "**/.pi/**",
+  "**/.aws/**", "**/.azure/**", "**/.docker/**", "**/.gnupg/**", "**/.kube/**", "**/.ssh/**",
+  "**/.git-credentials", "**/.netrc", "**/.npmrc", "**/.pypirc",
+  "**/.env", "**/.env.*",
+  "**/auth.json", "**/credential.json", "**/credentials.json", "**/secret.json", "**/secrets.json",
+  "**/token.json", "**/tokens.json"
+]);
+const WORKSPACE_EVIDENCE_SKIP_NAMES = new Set([
+  ".git", ".hg", ".svn", ".pi", "node_modules", "dist", "build", ".next", "coverage",
+  ".cache", ".npm", ".pnpm-store", ".yarn", ".turbo", ".aws", ".azure", ".docker",
+  ".gnupg", ".kube", ".ssh", ".ds_store", ".git-credentials", ".netrc", ".npmrc", ".pypirc"
+]);
+const WORKSPACE_EVIDENCE_PRIORITY_NAMES = new Map([["plans", 0]]);
+
+function excludedWorkspaceEvidenceName(value) {
+  const name = String(value ?? "");
+  return WORKSPACE_EVIDENCE_SKIP_NAMES.has(name.toLowerCase())
+    || /^\.env(?:\.|$)/i.test(name)
+    || /^(?:auth|credentials?|secrets?|tokens?)\.json$/i.test(name);
+}
+
+export function gitOutput(cwd, args, options = {}) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: options.encoding ?? "utf8",
+    maxBuffer: options.maxBuffer ?? 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+}
+
+export function isGitWorkingTree(cwd) {
+  try {
+    return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+  } catch {
+    return false;
+  }
+}
+
+export function normalizedGitPath(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
+}
+
+export function prefixedGitPath(prefix, file) {
+  const normalized = normalizedGitPath(file);
+  return prefix ? `${prefix}/${normalized}` : normalized;
+}
+
+function directChildGitEvidenceRootDetails(cwd) {
+  const roots = [];
+  let complete = true;
+  let entries;
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return { roots, complete: false };
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const child = path.join(cwd, entry.name);
+    try {
+      if (fs.lstatSync(child).isSymbolicLink()) continue;
+      let gitMarker;
+      try {
+        gitMarker = fs.lstatSync(path.join(child, ".git"));
+      } catch (error) {
+        if (error?.code === "ENOENT") continue;
+        complete = false;
+        continue;
+      }
+      if (!gitMarker.isDirectory() && !gitMarker.isFile()) {
+        complete = false;
+        continue;
+      }
+      if (!isGitWorkingTree(child)) {
+        complete = false;
+        continue;
+      }
+      const topLevel = gitOutput(child, ["rev-parse", "--show-toplevel"]).trim();
+      if (fs.realpathSync(topLevel) !== fs.realpathSync(child)) {
+        complete = false;
+        continue;
+      }
+      roots.push({ cwd: child, prefix: normalizedGitPath(entry.name) });
+    } catch {
+      complete = false;
+    }
+  }
+  return { roots: roots.sort((left, right) => left.prefix.localeCompare(right.prefix)), complete };
+}
+
+export function directChildGitEvidenceRoots(cwd) {
+  return directChildGitEvidenceRootDetails(cwd).roots;
+}
+
+export function gitEvidenceRootDetails(cwd) {
+  if (isGitWorkingTree(cwd)) return { roots: [{ cwd, prefix: "" }], complete: true };
+  // A present Git marker combined with a failed Git probe is ambiguous (for
+  // example a broken worktree pointer or a transient command failure). Do not
+  // reinterpret that repository as an ordinary complete non-Git directory.
+  try {
+    fs.lstatSync(path.join(cwd, ".git"));
+    return { roots: [], complete: false };
+  } catch (error) {
+    if (error?.code !== "ENOENT") return { roots: [], complete: false };
+  }
+  return directChildGitEvidenceRootDetails(cwd);
+}
+
+export function gitEvidenceRoots(cwd) {
+  return gitEvidenceRootDetails(cwd).roots;
+}
+
+function workspaceEvidenceFileLimit(value) {
+  return Number.isInteger(value)
+    ? Math.max(1, Math.min(WORKSPACE_EVIDENCE_MAX_FILES, value))
+    : WORKSPACE_EVIDENCE_MAX_FILES;
+}
+
+export function nonGitWorkspaceFileDetails(cwd, gitRootPrefixes, maxFiles = WORKSPACE_EVIDENCE_MAX_FILES) {
+  const files = [];
+  let complete = true;
+  const limit = workspaceEvidenceFileLimit(maxFiles);
+  const gitRoots = new Set(gitRootPrefixes.filter(Boolean));
+  const orderedEntries = (entries) => [...entries].sort((left, right) => {
+    const leftPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(left.name.toLowerCase()) ?? 10;
+    const rightPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(right.name.toLowerCase()) ?? 10;
+    return leftPriority - rightPriority || left.name.localeCompare(right.name, "en-US");
+  });
+  function visit(directory, relativeDirectory) {
+    if (files.length >= limit) {
+      complete = false;
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      complete = false;
+      return;
+    }
+    for (const entry of orderedEntries(entries)) {
+      if (files.length >= limit) {
+        complete = false;
+        return;
+      }
+      // A parent workspace can own real project source in hidden directories
+      // (for example shared verifier scripts). Evidence discovery therefore
+      // excludes explicit private/cache/credential names instead of treating
+      // every dot-prefixed path as non-project state.
+      if (excludedWorkspaceEvidenceName(entry.name)) continue;
+      const relative = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      if (gitRoots.has(relative.split("/")[0])) continue;
+      const absolute = path.join(directory, entry.name);
+      try {
+        if (fs.lstatSync(absolute).isSymbolicLink()) continue;
+      } catch {
+        complete = false;
+        continue;
+      }
+      if (entry.isDirectory()) visit(absolute, relative);
+      else if (entry.isFile()) files.push(normalizedGitPath(relative));
+    }
+  }
+  visit(cwd, "");
+  return { files: files.sort(), complete };
+}
+
+export function nonGitWorkspaceFiles(cwd, gitRootPrefixes, maxFiles = WORKSPACE_EVIDENCE_MAX_FILES) {
+  return nonGitWorkspaceFileDetails(cwd, gitRootPrefixes, maxFiles).files;
+}
+
+export function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
+  const segments = candidate.split("/").filter(Boolean);
+  const topSegment = segments[0];
+  return Boolean(
+    topSegment
+    && !segments.some(excludedWorkspaceEvidenceName)
+    && !gitRootPrefixes.includes(topSegment)
+  );
+}

package/packages/piagent-core/package.json

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

package/packages/piagent-core/policies/base-policy.json

@@ -3,7 +3,27 @@
   "name": "piagent-base-policy",
   "protectedPaths": [
     ".git/**",
+    "**/.git/**",
+    "**/.hg/**",
+    "**/.svn/**",
+    "**/.pi/**",
+    "**/.aws/**",
+    "**/.azure/**",
+    "**/.docker/**",
+    "**/.gnupg/**",
+    "**/.kube/**",
+    "**/.ssh/**",
+    "**/.git-credentials",
+    "**/.netrc",
+    "**/.npmrc",
+    "**/.pypirc",
     "**/auth.json",
+    "**/credential.json",
+    "**/credentials.json",
+    "**/secret.json",
+    "**/secrets.json",
+    "**/token.json",
+    "**/tokens.json",
     "**/.env",
     "**/.env.*",
     "**/node_modules/**",
@@ -16,7 +36,27 @@
   ],
   "shellProtectedPaths": [
     ".git/**",
+    "**/.git/**",
+    "**/.hg/**",
+    "**/.svn/**",
+    "**/.pi/**",
+    "**/.aws/**",
+    "**/.azure/**",
+    "**/.docker/**",
+    "**/.gnupg/**",
+    "**/.kube/**",
+    "**/.ssh/**",
+    "**/.git-credentials",
+    "**/.netrc",
+    "**/.npmrc",
+    "**/.pypirc",
     "**/auth.json",
+    "**/credential.json",
+    "**/credentials.json",
+    "**/secret.json",
+    "**/secrets.json",
+    "**/token.json",
+    "**/tokens.json",
     "**/.env",
     "**/.env.*",
     ".pi/piagent-state/**",
@@ -107,6 +147,7 @@
   },
   "contextBudget": {
     "defaultMode": "enforce",
+    "contextDeltaShadow": "sample",
     "maxContextFileChars": 50000,
     "maxMemoryFileChars": 20000,
     "maxManifestFiles": 80,
@@ -155,6 +196,7 @@
       "ls": ["filesystem-readonly"],
       "write": ["filesystem-write"],
       "edit": ["filesystem-write"],
+      "apply_patch": ["filesystem-write"],
       "browser": ["browser"],
       "github": ["github"]
     }
@@ -230,7 +272,7 @@
   },
   "orchestrationPolicy": {
     "defaultMode": "solo-first",
-    "maxConcurrentSubagents": 2,
+    "maxConcurrentSubagents": 1,
     "defaultReviewLenses": [
       "correctness",
       "tests",
@@ -238,7 +280,7 @@
     ],
     "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."
     },

package/packages/piagent-core/policy/authority-manifest.v1.json

@@ -34,7 +34,7 @@
         "CAP-11": "advisory",
         "CAP-12": "on",
         "CAP-13": "off",
-        "CAP-14": "recommend",
+        "CAP-14": "off",
         "CAP-15": "off",
         "CAP-16": "on",
         "CAP-17": "on"
@@ -80,7 +80,7 @@
         "CAP-11": "advisory",
         "CAP-12": "on",
         "CAP-13": "strict",
-        "CAP-14": "recommend",
+        "CAP-14": "off",
         "CAP-15": "off",
         "CAP-16": "on",
         "CAP-17": "on"
@@ -314,7 +314,7 @@
       "layer": "L3",
       "configKey": "helpers",
       "configSources": ["manifest", "PIAGENT_HELPERS_MODE"],
-      "defaultMode": "recommend",
+      "defaultMode": "off",
       "killSwitchMode": "off",
       "dependencies": ["CAP-02", "CAP-05", "CAP-08"],
       "modeMappings": [

package/packages/piagent-core/prompts/be-to-fe.md

@@ -26,13 +26,7 @@ Flow:
    - BE scout: read-only.
    - FE implementation: source-write.
    - Auth/data migration/external provider: high-risk, ask before implementation.
-4. Use bounded read-only subagents only when BE/FE mapping has independent lanes worth the extra token/tool cost:
-   - `piagent-scout` maps backend contract read-only;
-   - `piagent-scout` maps frontend touchpoints read-only;
-   - builtin `context-builder` may create handoff context when the BE→FE mapping touches multiple journeys/forms/contracts;
-   - `piagent-planner` produces the FE implementation plan when the contract touches multiple layers;
-   - `piagent-reviewer` reviews diff/verification after implementation.
-   Continue single-agent if subagents are unavailable, the task is tiny, or requirements are unresolved.
+4. Keep BE scouting and FE implementation in the parent by default. At most one fresh read-only `piagent-scout` may map either the BE contract or FE touchpoints only when runtime evidence proves two independent lanes and at least 30% projected total token savings after handoff/merge. Never launch two scouts, delegate FE writes/planning/review, inherit the parent transcript, or retry a deterministic helper failure.
 5. Scout backend contract read-only:
    - controller/route/handler;
    - request/response DTO/schema;
@@ -53,7 +47,7 @@ Flow:
    - route/page/component/form;
    - tests/e2e.
 9. Call `piagent_task_start` exactly once before FE source writes and reuse an active contract.
-10. Implement FE only with one writer by default.
+10. Implement FE in the parent; helper workers are disabled.
 11. Run every exact command returned in `task.verifyCommands` after the latest mutation. For a normal default plan, review the final diff and mark only its review step done with `piagent_task_progress`.
 12. Let runtime hooks record context, verification, trace, and final-gate state. Use recovery tools only if the runtime reports missing evidence.
 13. Do not paste full test/build/tool logs into chat or final output. Summarize the signal and quote only relevant failing lines.

package/packages/piagent-core/prompts/plan.md

@@ -17,7 +17,7 @@ Rules:
 4. Read `.pi/project-context.md`; if it is missing or still pending, recommend `/onboard-project run` before implementation.
 5. Read required context.
 6. Identify protected paths and external/high-risk actions.
-7. Decide whether subagents are useful enough to justify extra token/tool cost. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns and safety boundaries. If `pi-subagents`/`subagent(...)` is available, use `piagent-scout` for independent read-only repo/spec mapping before medium/large plans. Use builtin `context-builder` when the task needs a handoff context/meta-prompt. Use `piagent-oracle` for architecture/risk challenge when the decision is non-obvious. Continue single-agent for tiny plans or unavailable subagent tooling.
+7. Keep planning in the parent. At most one fresh read-only helper may run only when runtime evidence proves two independent workstreams, no dependency on later parent output, and at least 30% projected total token savings after transfer/merge. Never delegate implementation, fork parent history, retry a deterministic helper failure, or add a helper only for review quality.
 8. Produce a compact task tree/workPlan with exact files, commands, owner role, review lenses, and verify gates.
 9. Do not implement yet unless the user explicitly asks.
 

package/packages/piagent-core/prompts/platform-improve.md

@@ -23,18 +23,14 @@ Flow:
 1. Use runtime automatic intake for a bounded platform change. If runtime pauses for broad, high-risk, or ambiguous scope, call `piagent_task_start` exactly once with project-relative path/glob scope and reuse an active contract.
 2. Read the narrow current implementation, its tests, and the relevant policy/schema/docs. Runtime hooks inject bounded navigation context when useful.
 3. Treat memory and generated context as advisory; verify against current files.
-4. Use bounded subagents only when independent lanes justify their extra token/tool cost:
-   - use `piagent-scout` for read-only code/package mapping;
-   - use `piagent-planner` for a plan when multiple modules are affected;
-   - use `piagent-reviewer` for diff, docs, and verification review;
-   - continue single-agent for small, localized edits.
+4. Keep platform analysis, planning, implementation, and review in the parent. At most one fresh read-only helper may map a genuinely independent lane only when runtime evidence projects at least 30% lower total tokens after handoff/merge. Do not delegate writes, fork parent history, run parallel helpers, or retry deterministic runtime/scope failures.
 5. If the task needs external repository context provided by the user, use a targeted read-only checkout when available.
 6. Produce an implementation matrix only when multiple platform areas are affected:
 
     | Area | Current behavior | Target behavior | Files/config | Verification |
     |---|---|---|---|---|
 
-7. Implement only the bounded target behavior with one writer by default.
+7. Implement only the bounded target behavior in the parent.
 8. If runtime behavior changes, update README/docs and add or adjust a decision note when appropriate.
 9. Run every exact command returned in `task.verifyCommands` after the latest mutation. For a normal default plan, review the final diff and mark only its review step done with `piagent_task_progress`.
 10. Let runtime hooks record context, verification, trace, and final-gate state. Use recovery tools only if the runtime reports missing evidence.

package/packages/piagent-core/prompts/review.md

@@ -14,13 +14,8 @@ Rules:
 1. Read the current diff and the narrow surrounding source/tests. Runtime hooks inject bounded navigation context when useful.
 2. Select review lenses from the actual change risk; do not load orchestration or diagnostic tools just to choose them.
 3. Stay read-only unless explicitly asked to write a report.
-4. Check protected paths, scope drift, acceptance behavior, and verify-command coverage.
-5. For a non-trivial diff, use bounded read-only reviewers only when independent lanes justify their token cost:
-   - correctness/edge cases;
-   - tests/verification;
-   - scope drift/protected paths;
-   - security/high-risk only when relevant.
-   If the user asks for a loop, use `/review-loop` semantics or equivalent parent-controlled max-round loop. Continue single-agent for tiny diffs or unavailable subagent tooling.
+4. Check protected paths, unrelated change drift, acceptance behavior, and verify-command coverage. Treat task scope as an initial focus, not write authority.
+5. Review directly in the parent. A non-trivial diff does not itself justify another model run. At most one fresh read-only reviewer is eligible only when a runtime estimate proves an independent lane and at least 30% projected total token savings after handoff/merge; never run parallel review or retry a deterministic helper failure. If the user explicitly asks for a loop, keep it parent-controlled and bounded.
 6. Report findings by severity.
 7. Do not call diagnostic Piagent tools for routine review and do not paste full diff/test/tool logs. Summarize the signal and quote only relevant lines.
 

package/packages/piagent-core/prompts/scout.md

@@ -15,7 +15,7 @@ Lean scouting flow:
 
 1. Read targeted current files and return cited evidence. Runtime hooks inject bounded navigation context when useful and enforce read boundaries.
 2. Create a read-only contract with `piagent_task_start` only for a broad governed scout that needs persisted scope or handoff. Tiny default scouts complete from observed reads; for a normal default scout, review the evidence and mark only the returned review step done with `piagent_task_progress`.
-3. Use memory, vendor documentation, or a read-only subagent only when current source is insufficient or the work has independent lanes. Verify advisory material against current files.
+3. Use memory or vendor documentation only when current source is insufficient. Keep scouting in the parent; a helper requires separate runtime proof of two independent lanes and at least 30% projected net token saving.
 4. A low-confidence search may trigger one bounded finder pass. Stop broad search when the requested evidence is covered.
 5. Do not call diagnostic Piagent tools for a routine scout. Load them only when the runtime reports a recovery need or the operator explicitly asks for diagnostics.
 6. Do not edit source or paste full command output. Summarize relevant evidence and unknowns.

package/packages/piagent-core/prompts/task.md

@@ -11,9 +11,9 @@ $ARGUMENTS
 
 Core flow:
 
-1. Use the runtime-created contract for a bounded source task; do not call task-management tools during automatic intake. If runtime pauses for broad, high-risk, or ambiguous scope, call `piagent_task_start` exactly once with project-relative path/glob scope and reuse an active contract.
+1. Use the runtime-created contract for a bounded source task; do not call task-management tools during automatic intake. If runtime pauses for a broad, high-risk, or ambiguous task, call `piagent_task_start` exactly once with project-relative focus paths/globs and reuse an active contract.
 2. Read the likely target and nearest relevant test. The runtime injects bounded navigation context when useful.
-3. Make the smallest in-scope change with ordinary tools and one writer.
+3. Make the smallest complete evidence-backed change with ordinary tools and one writer. Initial task scope guides retrieval/review but does not restrict necessary FE, BE, test, config, or child-repository edits.
 4. Run every exact command returned in `task.verifyCommands` after the latest mutation.
 5. Automatic tasks need no lifecycle calls. Manual high-risk and explicitly requested custom plans keep their returned checkpoints.
 6. Let runtime hooks record context, changed files, verification, trace, and final-gate state. Load recovery tools only if the runtime reports missing evidence.
@@ -21,13 +21,14 @@ Core flow:
 Risk-adaptive enrichment:
 
 - `tiny`: stay targeted; no diagnostic Piagent tools or subagents.
-- `normal`: stop searching once current-file evidence is sufficient. Use a read-only subagent only for a genuinely independent lane.
+- `normal`: stop searching once current-file evidence is sufficient. Keep the parent direct. One fresh read-only helper is eligible only when runtime evidence proves at least two independent lanes and at least 30% projected total token savings after handoff/merge.
 - `high-risk`: inspect current source, relevant vendor documentation, and explicit security/data/release review lenses; keep required human confirmations.
 
 Always:
 
 - Treat memory, context-index, and generated tech snapshots as advisory; verify against current files.
 - If navigation confidence is low, run at most one bounded read-only finder pass; do not start an open-ended scout loop.
+- Never delegate implementation, fork/inherit the parent transcript, run more than one helper, or retry a deterministic helper/runtime/scope failure.
 - Do not touch protected paths or use undeclared capabilities.
 - If verification cannot run, report `blocked` or `partial`, never done. If runtime schedules a continuation, keep working in the same task and do not repeat management tools.
 - Do not paste full test/build/tool logs. Summarize the signal and quote only relevant failures.

package/packages/piagent-core/runtime/context/context-delivery.ts

@@ -0,0 +1,103 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import type { PendingContextDelivery, RuntimeSessionState, ObservedTaskContext } from "../session/runtime-state.ts";
+
+export type ContextDeliveryConfirmationDependencies = {
+  state: RuntimeSessionState;
+  maxManifestFiles: number;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  flushObservedTaskContext: (
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    pendingContext: ObservedTaskContext[],
+    maxManifestFiles: number,
+    event: string
+  ) => TaskContract | undefined;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+export function contextDeliveryIdFromDetails(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+  const rawDelivery = (details as { contextDelivery?: unknown }).contextDelivery;
+  if (!rawDelivery || typeof rawDelivery !== "object" || Array.isArray(rawDelivery)) return undefined;
+  const deliveryId = (rawDelivery as { deliveryId?: unknown }).deliveryId;
+  return typeof deliveryId === "string" && deliveryId.length > 0 && deliveryId.length <= 200
+    ? deliveryId
+    : undefined;
+}
+
+export function confirmContextDelivery(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  deliveryId: string,
+  dependencies: ContextDeliveryConfirmationDependencies
+): TaskContract | undefined {
+  const delivery = dependencies.state.takeContextDelivery(ctx, deliveryId);
+  if (!delivery) return undefined;
+  const task = dependencies.activeTask(ctx);
+  if (!task || task.trace.outcome !== "pending" || task.taskRunId !== delivery.taskRunId) {
+    dependencies.telemetry(ctx, { event: "context_delivery_rejected", deliveryId, reason: "task-identity-mismatch" });
+    return undefined;
+  }
+  for (const entry of delivery.entries) {
+    dependencies.state.rememberObservedContext(ctx, entry);
+    dependencies.state.rememberQualifiedContextEvidence(ctx, delivery.taskRunId, entry);
+  }
+  const written = dependencies.flushObservedTaskContext(
+    pi,
+    ctx,
+    dependencies.state.qualifiedContextEvidence(ctx, delivery.taskRunId),
+    dependencies.maxManifestFiles,
+    "context_delivery_confirmed"
+  );
+  if (!written || written.taskRunId !== delivery.taskRunId) return undefined;
+  if (delivery.pack) {
+    const { retrievalKey, ...pack } = delivery.pack;
+    dependencies.state.rememberInjectedContextPack(ctx, retrievalKey, pack);
+  }
+  dependencies.telemetry(ctx, {
+    event: "context_delivery_confirmed",
+    deliveryId,
+    turnId: delivery.turnId,
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    selectedPaths: delivery.entries.map((entry) => entry.path),
+    selected: delivery.entries.length
+  });
+  if (delivery.injection) dependencies.telemetry(ctx, {
+    event: "context_pack_injected",
+    injectionId: deliveryId,
+    turnId: delivery.turnId,
+    ...delivery.injection,
+    selectedPaths: delivery.injection.selectedItems.map((item) => item.path)
+  });
+  return written;
+}
+
+export function stageContextDelivery(
+  ctx: ExtensionContext,
+  delivery: PendingContextDelivery,
+  dependencies: Pick<ContextDeliveryConfirmationDependencies, "state" | "telemetry">
+): void {
+  dependencies.state.stageContextDelivery(ctx, delivery);
+  if (!delivery.injection) return;
+  dependencies.telemetry(ctx, {
+    event: "context_pack_offered",
+    deliveryId: delivery.deliveryId,
+    turnId: delivery.turnId,
+    ...delivery.injection,
+    selectedPaths: delivery.injection.selectedItems.map((item) => item.path)
+  });
+}
+
+export function confirmContextDeliveryFromToolResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  event: { details?: unknown; isError?: boolean },
+  dependencies: ContextDeliveryConfirmationDependencies
+): TaskContract | undefined {
+  if (event.isError === true) return undefined;
+  const deliveryId = contextDeliveryIdFromDetails(event.details);
+  return deliveryId ? confirmContextDelivery(pi, ctx, deliveryId, dependencies) : undefined;
+}

package/packages/piagent-core/runtime/context/context-delta-shadow.ts

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { buildContextPack, ensureContextIndexV2 } from "../../extensions/context-engine.js";
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
+import type { TaskContract } from "../../extensions/guard-types.js";
+
+export type ContextDeltaShadowMode = "off" | "sample" | "on";
+
+type ShadowInput = {
+  ctx: ExtensionContext;
+  query: string;
+  turnId: string;
+  task: TaskContract;
+  mode: ContextDeltaShadowMode;
+  protectedTarget: boolean;
+  excludePatterns: string[];
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+function sampled(taskRunId: string, query: string): boolean {
+  const byte = crypto.createHash("sha256").update(`${taskRunId}\0${query}`).digest()[0];
+  return byte < 64;
+}
+
+export async function measureContextDeltaShadow(input: ShadowInput): Promise<void> {
+  if (input.mode === "off" || input.protectedTarget || (input.mode === "sample" && !sampled(input.task.taskRunId, input.query))) return;
+  const usage = input.ctx.getContextUsage();
+  if (usage && Number(usage.percent ?? 0) >= 80) return;
+  try {
+    const { status } = await ensureContextIndexV2(input.ctx.cwd, { excludePatterns: input.excludePatterns, rebuildMissing: false });
+    if (!status.exists || status.stale) return;
+    const pack = await buildContextPack(input.ctx.cwd, input.query, {
+      budgetTokens: 1_200,
+      includeCode: false,
+      limit: 10,
+      excludePatterns: input.excludePatterns
+    });
+    const manifested = new Set(durableContextEvidenceEntries(input.task).map((entry) => entry.path));
+    const duplicateItems = pack.selected.filter((item) => manifested.has(item.path));
+    input.telemetry(input.ctx, {
+      event: "context_delta_shadow",
+      turnId: input.turnId,
+      queryHash: pack.queryHash,
+      candidatePaths: pack.selected.map((item) => item.path),
+      pathsAlreadyManifested: duplicateItems.map((item) => item.path),
+      candidateTokens: pack.selected.reduce((sum, item) => sum + item.estimatedTokens, 0),
+      duplicateCandidateTokens: duplicateItems.reduce((sum, item) => sum + item.estimatedTokens, 0)
+    });
+  } catch (error) {
+    input.telemetry(input.ctx, { event: "context_delta_shadow", turnId: input.turnId, skipped: "error", error: error instanceof Error ? error.message : String(error) });
+  }
+}

package/packages/piagent-core/runtime/context/context-efficiency-format.ts

@@ -0,0 +1,47 @@
+type ContextEfficiencyReport = {
+  metrics: {
+    contextWasteScore: number | null;
+    contextWasteScoreEstimate: number;
+    contextWasteScoreEvidenceCoverage: number;
+    averageActiveTools: number;
+    toolSchemaPrefixShare: number;
+    toolSchemaToSystemRatio: number;
+    duplicateReads: number;
+    comparableReadCalls: number;
+    readCalls: number;
+    readEvidenceCoverage: number;
+    contextFallbackRereads: number;
+    contextSelections: number;
+    duplicateOutputRate: number;
+    lowConfidencePacks: number;
+    editRecoveryContextCount: number;
+    editRecoveryFailures: number;
+    editRecoverySuppressedFailures: number;
+    editRecoveryEstimatedTokens: number;
+    editRecoveryFailureEvidenceCoverage: number;
+  };
+  coverage: { wasteScore: { status: string } };
+  sample: { contextPacks: number };
+  recommendations: string[];
+};
+
+export function formatContextEfficiencyReport(
+  report: ContextEfficiencyReport,
+  formatPercent: (value: number) => string
+): string {
+  const wasteScore = report.metrics.contextWasteScore === null
+    ? `unavailable (diagnostic estimate ${report.metrics.contextWasteScoreEstimate}/100; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`
+    : `${report.metrics.contextWasteScore}/100 (lower is better; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`;
+  return [
+    `contextWasteScore: ${wasteScore}`,
+    `activeTools: ${report.metrics.averageActiveTools}`,
+    `toolSchemaPrefixShare: ${formatPercent(report.metrics.toolSchemaPrefixShare)}`,
+    `toolSchemaToSystemRatio: ${report.metrics.toolSchemaToSystemRatio}`,
+    `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.comparableReadCalls} comparable (${report.metrics.readCalls} observed; coverage ${formatPercent(report.metrics.readEvidenceCoverage)})`,
+    `fallbackRereads: ${report.metrics.contextFallbackRereads}/${report.metrics.contextSelections}`,
+    `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
+    `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
+    `editRecovery: ${report.metrics.editRecoveryContextCount}/${report.metrics.editRecoveryFailures} failures returned context; ${report.metrics.editRecoverySuppressedFailures} suppressed; ${report.metrics.editRecoveryEstimatedTokens} estimated tokens; classification coverage ${formatPercent(report.metrics.editRecoveryFailureEvidenceCoverage)}`,
+    ...report.recommendations.map((recommendation) => `- ${recommendation}`)
+  ].join("\n");
+}