@piagent/platform 1.2.17 → 1.3.0-ie.9

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

@@ -0,0 +1,380 @@
+{
+  "schemaVersion": 1,
+  "manifestVersion": "authority-v1",
+  "releaseVersion": "1.3.0",
+  "status": "pre-release",
+  "authorityVocabulary": ["off", "observe", "advise", "enforce", "orchestrate"],
+  "sourceProvenance": {
+    "decisionDate": "2026-08-10",
+    "roadmap": "governance/codex-first-product/15-full-source-productionization-roadmap.md",
+    "constitution": "governance/codex-first-product/evidence/fs0/capability-constitution.v1.json",
+    "constitutionSha256": "5dc65f03639df4236ea4e9c70e31e81aa9613317102e1acd2b371c6e44e8c1e8",
+    "evidenceTier": "local-pre-release"
+  },
+  "globalBudgets": {
+    "maxSystemContinuationsPerTask": 1,
+    "maxAutomaticDispatchesPerTask": 1,
+    "maxSpecialistReviewRoundsPerTask": 1
+  },
+  "profiles": [
+    {
+      "id": "broad-default",
+      "description": "Mechanical invariants and efficiency stay active; advanced analysis observes or advises without universal enforcement.",
+      "modes": {
+        "CAP-01": "enforce",
+        "CAP-02": "enforce",
+        "CAP-03": "enforce",
+        "CAP-04": "enforce",
+        "CAP-05": "on",
+        "CAP-06": "on",
+        "CAP-07": "recommend",
+        "CAP-08": "shadow",
+        "CAP-09": "shadow",
+        "CAP-10": "shadow",
+        "CAP-11": "advisory",
+        "CAP-12": "on",
+        "CAP-13": "off",
+        "CAP-14": "recommend",
+        "CAP-15": "off",
+        "CAP-16": "on",
+        "CAP-17": "on"
+      }
+    },
+    {
+      "id": "mechanical-only",
+      "description": "Retain L0/L1 mechanical truth, context, tool and operator foundations while disabling advanced guidance, repair and orchestration.",
+      "modes": {
+        "CAP-01": "enforce",
+        "CAP-02": "enforce",
+        "CAP-03": "enforce",
+        "CAP-04": "enforce",
+        "CAP-05": "on",
+        "CAP-06": "on",
+        "CAP-07": "off",
+        "CAP-08": "off",
+        "CAP-09": "off",
+        "CAP-10": "off",
+        "CAP-11": "off",
+        "CAP-12": "off",
+        "CAP-13": "off",
+        "CAP-14": "off",
+        "CAP-15": "off",
+        "CAP-16": "on",
+        "CAP-17": "on"
+      }
+    },
+    {
+      "id": "strict-high-risk",
+      "description": "Opt-in high-risk profile that adds phase and semantic enforcement under the same global continuation ceiling.",
+      "modes": {
+        "CAP-01": "enforce",
+        "CAP-02": "enforce",
+        "CAP-03": "enforce",
+        "CAP-04": "enforce",
+        "CAP-05": "on",
+        "CAP-06": "on",
+        "CAP-07": "recommend",
+        "CAP-08": "shadow",
+        "CAP-09": "strict",
+        "CAP-10": "shadow",
+        "CAP-11": "advisory",
+        "CAP-12": "on",
+        "CAP-13": "strict",
+        "CAP-14": "recommend",
+        "CAP-15": "off",
+        "CAP-16": "on",
+        "CAP-17": "on"
+      }
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "CAP-01",
+      "owner": "task-contract-maintainer",
+      "layer": "L0",
+      "configKey": "taskContract",
+      "configSources": ["manifest"],
+      "defaultMode": "enforce",
+      "killSwitchMode": "enforce",
+      "dependencies": [],
+      "modeMappings": [
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "enforce", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-02",
+      "owner": "security-policy-maintainer",
+      "layer": "L0",
+      "configKey": "safetyPolicy",
+      "configSources": ["manifest", "PIAGENT_PERMISSION_PROFILE", "PIAGENT_EXECUTION_BACKEND"],
+      "defaultMode": "enforce",
+      "killSwitchMode": "enforce",
+      "dependencies": ["CAP-01"],
+      "modeMappings": [
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "enforce", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-03",
+      "owner": "verification-truth-maintainer",
+      "layer": "L0",
+      "configKey": "verificationTruth",
+      "configSources": ["manifest"],
+      "defaultMode": "enforce",
+      "killSwitchMode": "enforce",
+      "dependencies": ["CAP-01", "CAP-02"],
+      "modeMappings": [
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "enforce", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-04",
+      "owner": "long-task-state-maintainer",
+      "layer": "L0",
+      "configKey": "durableTaskState",
+      "configSources": ["manifest"],
+      "defaultMode": "enforce",
+      "killSwitchMode": "enforce",
+      "dependencies": ["CAP-01", "CAP-03"],
+      "modeMappings": [
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "enforce", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-05",
+      "owner": "context-efficiency-maintainer",
+      "layer": "L1",
+      "configKey": "contextEfficiency",
+      "configSources": ["manifest", "PIAGENT_AUTO_CONTEXT"],
+      "defaultMode": "on",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-06",
+      "owner": "tool-surface-maintainer",
+      "layer": "L1",
+      "configKey": "toolSurface",
+      "configSources": ["manifest", "PIAGENT_DYNAMIC_TOOLS"],
+      "defaultMode": "on",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-07",
+      "owner": "retrieval-memory-maintainer",
+      "layer": "L3",
+      "configKey": "retrievalMemory",
+      "configSources": ["manifest", "PIAGENT_LOCAL_RERANKER"],
+      "defaultMode": "recommend",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02", "CAP-05"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "recommend", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "recommend",
+      "constitutionTargetAuthority": "advise"
+    },
+    {
+      "id": "CAP-08",
+      "owner": "solver-runtime-maintainer",
+      "layer": "L2",
+      "configKey": "solver",
+      "configSources": ["manifest", "PIAGENT_SOLVER_MODE", "PIAGENT_RUNTIME_SNAPSHOT"],
+      "defaultMode": "shadow",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01", "CAP-05"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "recommend", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "assist", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "shadow",
+      "constitutionTargetAuthority": "observe"
+    },
+    {
+      "id": "CAP-09",
+      "owner": "phase-policy-maintainer",
+      "layer": "L2",
+      "configKey": "phaseTools",
+      "configSources": ["manifest", "PIAGENT_PHASE_TOOLS"],
+      "defaultMode": "shadow",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01", "CAP-02", "CAP-10"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "strict", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "shadow",
+      "constitutionTargetAuthority": "observe"
+    },
+    {
+      "id": "CAP-10",
+      "owner": "trajectory-observability-maintainer",
+      "layer": "L2",
+      "configKey": "trajectory",
+      "configSources": ["manifest"],
+      "defaultMode": "shadow",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01", "CAP-04"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "shadow",
+      "constitutionTargetAuthority": "observe"
+    },
+    {
+      "id": "CAP-11",
+      "owner": "assurance-maintainer",
+      "layer": "L3",
+      "configKey": "assurance",
+      "configSources": ["manifest", "PIAGENT_ACCEPTANCE_ASSURANCE"],
+      "defaultMode": "advisory",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01", "CAP-03"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "advisory", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "recommend", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "advisory",
+      "constitutionTargetAuthority": "observe"
+    },
+    {
+      "id": "CAP-12",
+      "owner": "recovery-maintainer",
+      "layer": "L1",
+      "configKey": "recovery",
+      "configSources": ["manifest", "PIAGENT_AUTO_RECOVERY"],
+      "defaultMode": "on",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-01", "CAP-03", "CAP-04"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 1, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-13",
+      "owner": "semantic-enforcement-maintainer",
+      "layer": "L4",
+      "configKey": "semanticRepair",
+      "configSources": ["manifest", "PIAGENT_SEMANTIC_REPAIR"],
+      "defaultMode": "off",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02", "CAP-03", "CAP-09", "CAP-11", "CAP-12"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "advisory", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "strict", "authority": "enforce", "budgets": { "systemContinuations": 1, "automaticDispatches": 0, "reviewRounds": 1 } }
+      ],
+      "constitutionTargetMode": "strict",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-14",
+      "owner": "orchestration-maintainer",
+      "layer": "L3",
+      "configKey": "helpers",
+      "configSources": ["manifest", "PIAGENT_HELPERS_MODE"],
+      "defaultMode": "recommend",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02", "CAP-05", "CAP-08"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "recommend", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "orchestrate", "budgets": { "systemContinuations": 0, "automaticDispatches": 1, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "recommend",
+      "constitutionTargetAuthority": "advise"
+    },
+    {
+      "id": "CAP-15",
+      "owner": "parent-routing-maintainer",
+      "layer": "L4",
+      "configKey": "parentRouting",
+      "configSources": ["manifest", "PIAGENT_PARENT_ROUTING"],
+      "defaultMode": "off",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02", "CAP-08", "CAP-14"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "shadow", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "recommend", "authority": "advise", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "auto", "authority": "orchestrate", "budgets": { "systemContinuations": 0, "automaticDispatches": 1, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "off",
+      "constitutionTargetAuthority": "off"
+    },
+    {
+      "id": "CAP-16",
+      "owner": "release-operator-experience-maintainer",
+      "layer": "L1",
+      "configKey": "operatorExperience",
+      "configSources": ["manifest"],
+      "defaultMode": "on",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-02", "CAP-04"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "enforce", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "enforce"
+    },
+    {
+      "id": "CAP-17",
+      "owner": "evaluation-claims-maintainer",
+      "layer": "L2",
+      "configKey": "evaluationTelemetry",
+      "configSources": ["manifest", "PIAGENT_CONTEXT_TELEMETRY"],
+      "defaultMode": "on",
+      "killSwitchMode": "off",
+      "dependencies": ["CAP-03", "CAP-04"],
+      "modeMappings": [
+        { "value": "off", "authority": "off", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } },
+        { "value": "on", "authority": "observe", "budgets": { "systemContinuations": 0, "automaticDispatches": 0, "reviewRounds": 0 } }
+      ],
+      "constitutionTargetMode": "on",
+      "constitutionTargetAuthority": "observe"
+    }
+  ]
+}

package/packages/piagent-core/runtime/context/adaptive-planner.ts

@@ -0,0 +1,172 @@
+import crypto from "node:crypto";
+
+import { classifyContextTask } from "../../extensions/context-engine.js";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import type { RuntimeModelCapability } from "../model/capabilities.ts";
+import { CONTEXT_PACK_MAX_TOKENS } from "../runtime-limits.ts";
+
+type ContextUsage = {
+  tokens?: number;
+  contextWindow?: number;
+  percent?: number;
+};
+
+export type AdaptiveContextPlan = {
+  schemaVersion: 1;
+  phase: "utility" | "protected" | "intake" | "scout" | "execute" | "review" | "release";
+  lane: "tiny" | "normal" | "high-risk";
+  shouldInject: boolean;
+  budgetTokens: number;
+  limit: number;
+  includeCode: boolean;
+  currentSnapshot: boolean;
+  includePatterns?: string[];
+  minConfidence: "medium" | "high";
+  receipt: string;
+  reasons: string[];
+  reranker: "off" | "local";
+};
+
+type PlannerInput = {
+  prompt: string;
+  activeTask?: TaskContract;
+  runtimeIntake: boolean;
+  protectedOnlyTarget?: boolean;
+  contextUsage?: ContextUsage;
+  modelCapability: RuntimeModelCapability;
+};
+
+const DEFAULT_INTAKE_PATTERNS = [
+  "README.md",
+  "package.json",
+  "src/**",
+  "app/**",
+  "pages/**",
+  "components/**",
+  "tests/**",
+  "__tests__/**"
+];
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function contextPressure(usage?: ContextUsage): number {
+  if (typeof usage?.percent === "number") return Math.max(0, Math.min(1, usage.percent / 100));
+  if (typeof usage?.tokens === "number" && typeof usage?.contextWindow === "number" && usage.contextWindow > 0) {
+    return Math.max(0, Math.min(1, usage.tokens / usage.contextWindow));
+  }
+  return 0;
+}
+
+function phaseFor(signal: ReturnType<typeof classifyContextTask>, input: PlannerInput): AdaptiveContextPlan["phase"] {
+  if (input.protectedOnlyTarget) return "protected";
+  if (signal.workflow === "usage") return "utility";
+  if (signal.workflow === "review") return "review";
+  if (signal.workflow === "scout" || signal.workflow === "onboard") return "scout";
+  if (signal.workflow === "release") return "release";
+  if (input.runtimeIntake) return "intake";
+  return "execute";
+}
+
+function baseBudget(phase: AdaptiveContextPlan["phase"], lane: AdaptiveContextPlan["lane"], explicitPaths: number): number {
+  if (phase === "protected" || phase === "utility") return 0;
+  if (phase === "review") return lane === "high-risk" ? 720 : 520;
+  if (phase === "release") return 620;
+  if (phase === "scout") return lane === "high-risk" ? 820 : 640;
+  if (phase === "intake") {
+    if (explicitPaths > 0) return lane === "high-risk" ? 560 : 420;
+    return lane === "high-risk" ? 780 : lane === "tiny" ? 360 : 540;
+  }
+  return lane === "high-risk" ? 680 : lane === "tiny" ? 320 : 460;
+}
+
+function contextLane(value: string): AdaptiveContextPlan["lane"] {
+  return value === "high-risk" || value === "tiny" ? value : "normal";
+}
+
+function stableReceipt(input: Record<string, unknown>): string {
+  return crypto.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 16);
+}
+
+export function planAdaptiveContext(input: PlannerInput): AdaptiveContextPlan {
+  const signal = classifyContextTask(input.prompt);
+  const lane = contextLane(signal.lane);
+  const phase = phaseFor(signal, input);
+  const reasons: string[] = [`phase:${phase}`, `lane:${lane}`];
+  const pressure = contextPressure(input.contextUsage);
+  const pressureScale = pressure >= 0.72 ? 0.55 : pressure >= 0.58 ? 0.72 : pressure >= 0.42 ? 0.86 : 1;
+  if (pressureScale < 1) reasons.push(`context-pressure:${pressure.toFixed(2)}`);
+  const activePendingTask = input.activeTask?.trace?.outcome === "pending";
+  const explicitPathCount = signal.paths.length;
+  const shouldInject = phase !== "protected"
+    && phase !== "utility"
+    && !activePendingTask
+    && String(input.prompt ?? "").trim().length >= 20;
+  if (activePendingTask) reasons.push("active-task:reuse-working-set");
+  if (!shouldInject) {
+    return {
+      schemaVersion: 1,
+      phase,
+      lane,
+      shouldInject: false,
+      budgetTokens: 0,
+      limit: 0,
+      includeCode: false,
+      currentSnapshot: false,
+      minConfidence: "high",
+      receipt: stableReceipt({ promptHash: signal.promptHash, phase, lane, shouldInject: false }),
+      reasons,
+      reranker: "off"
+    };
+  }
+  const capabilityScale = Number.isFinite(input.modelCapability.phaseBudgetScale)
+    ? Math.max(0.5, Math.min(1.25, input.modelCapability.phaseBudgetScale))
+    : 1;
+  const scaled = baseBudget(phase, lane, explicitPathCount)
+    * capabilityScale
+    * pressureScale;
+  const budgetTokens = clamp(scaled, 240, lane === "high-risk" ? CONTEXT_PACK_MAX_TOKENS : 680);
+  const limit = explicitPathCount > 0
+    ? 4
+    : lane === "high-risk" ? 8 : lane === "tiny" ? 4 : 6;
+  const includeCode = phase === "intake" || phase === "review" || explicitPathCount > 0;
+  const includePatterns = phase === "intake" ? DEFAULT_INTAKE_PATTERNS : undefined;
+  const reranker = "off" as const;
+  if (process.env.PIAGENT_LOCAL_RERANKER === "on") reasons.push("local-reranker:unavailable");
+  const minConfidence = explicitPathCount > 0 || lane === "tiny"
+    ? "medium"
+    : phase === "review" || phase === "release" || lane === "high-risk"
+      ? "high"
+      : "medium";
+  return {
+    schemaVersion: 1,
+    phase,
+    lane,
+    shouldInject: true,
+    budgetTokens,
+    limit,
+    includeCode,
+    currentSnapshot: phase === "intake",
+    includePatterns,
+    minConfidence,
+    receipt: stableReceipt({
+      promptHash: signal.promptHash,
+      phase,
+      lane,
+      budgetTokens,
+      limit,
+      model: input.modelCapability.model,
+      thinkingLevel: input.modelCapability.thinkingLevel,
+      contextWindow: input.modelCapability.contextWindow
+    }),
+    reasons,
+    reranker
+  };
+}
+
+export function contextPlanAcceptsConfidence(plan: AdaptiveContextPlan, confidence: string): boolean {
+  if (!plan.shouldInject) return false;
+  if (plan.minConfidence === "high") return confidence === "high";
+  return confidence === "medium" || confidence === "high";
+}

package/packages/piagent-core/runtime/context/retrieval-route-policy.ts

@@ -0,0 +1,74 @@
+import crypto from "node:crypto";
+
+import type { TaskFeatures } from "../solver/solver-types.ts";
+
+export const RETRIEVAL_ROUTE_POLICY_VERSION = "retrieval-route-v1" as const;
+export const RETRIEVAL_ROUTE_CEILINGS = Object.freeze({ maxParallel: 2, maxRounds: 2 });
+
+export type RetrievalConfidence = "none" | "low" | "medium" | "high" | "unknown";
+export type RetrievalRoutePlan = {
+  schemaVersion: 1;
+  policyVersion: typeof RETRIEVAL_ROUTE_POLICY_VERSION;
+  featureHash: string;
+  activation: "skip" | "local-direct" | "specialist-recommended";
+  specialistRole: "retriever" | null;
+  tools: Array<"grep" | "find" | "read">;
+  maxParallel: number;
+  maxRounds: number;
+  budgetBand: "none" | "small" | "medium" | "large";
+  confidenceFloor: "medium" | "high";
+  reasonCodes: string[];
+  automaticDispatch: false;
+  planDigest: string;
+};
+
+export type RetrievalRouteInput = {
+  features: TaskFeatures;
+  indexReady: boolean;
+  observedConfidence?: RetrievalConfidence;
+  helpersMode?: "off" | "recommend" | "on";
+};
+
+function digest(input: Omit<RetrievalRoutePlan, "planDigest">): string {
+  return crypto.createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+
+function plan(input: Omit<RetrievalRoutePlan, "schemaVersion" | "policyVersion" | "planDigest">): RetrievalRoutePlan {
+  const payload = { schemaVersion: 1 as const, policyVersion: RETRIEVAL_ROUTE_POLICY_VERSION, ...input };
+  return { ...payload, planDigest: digest(payload) };
+}
+
+export function planRetrievalRoute(input: RetrievalRouteInput): RetrievalRoutePlan {
+  const features = input.features;
+  if (features.protectedTarget || features.externalAction || features.destructiveAction || features.permissionExpansion) {
+    return plan({ featureHash: features.featureHash, activation: "skip", specialistRole: null, tools: [], maxParallel: 0, maxRounds: 0, budgetBand: "none", confidenceFloor: "high", reasonCodes: ["authorization-boundary", "retrieval-cannot-widen-access"], automaticDispatch: false });
+  }
+  const confidence = input.observedConfidence ?? "unknown";
+  const explicitNarrow = features.explicitPathCount > 0
+    && features.scopeEstimate !== "broad"
+    && features.ambiguity === "low"
+    && confidence !== "low"
+    && confidence !== "none";
+  if (explicitNarrow) {
+    return plan({ featureHash: features.featureHash, activation: "local-direct", specialistRole: null, tools: ["grep", "read"], maxParallel: 1, maxRounds: 1, budgetBand: "small", confidenceFloor: "medium", reasonCodes: ["explicit-path", "bounded-local-retrieval"], automaticDispatch: false });
+  }
+  const specialistUseful = !input.indexReady
+    || confidence === "none"
+    || confidence === "low"
+    || features.scopeEstimate === "broad"
+    || features.ambiguity === "high"
+    || features.contextPressure !== null && features.contextPressure >= 0.72;
+  if (specialistUseful && input.helpersMode !== "off") {
+    const broad = features.scopeEstimate === "broad" || features.ambiguity === "high";
+    const reasonCodes = [
+      !input.indexReady ? "local-index-unavailable" : "",
+      confidence === "none" || confidence === "low" ? "low-retrieval-confidence" : "",
+      broad ? "multi-region-search" : "",
+      features.contextPressure !== null && features.contextPressure >= 0.72 ? "protect-parent-context" : "",
+      "read-only-specialist-recommended",
+      "bounded-parallel-search"
+    ].filter(Boolean);
+    return plan({ featureHash: features.featureHash, activation: "specialist-recommended", specialistRole: "retriever", tools: ["grep", "find", "read"], maxParallel: RETRIEVAL_ROUTE_CEILINGS.maxParallel, maxRounds: broad ? RETRIEVAL_ROUTE_CEILINGS.maxRounds : 1, budgetBand: broad ? "large" : "medium", confidenceFloor: broad ? "high" : "medium", reasonCodes, automaticDispatch: false });
+  }
+  return plan({ featureHash: features.featureHash, activation: "local-direct", specialistRole: null, tools: ["grep", "find", "read"], maxParallel: RETRIEVAL_ROUTE_CEILINGS.maxParallel, maxRounds: RETRIEVAL_ROUTE_CEILINGS.maxRounds, budgetBand: "medium", confidenceFloor: "medium", reasonCodes: [input.helpersMode === "off" ? "helpers-off" : "local-index-ready", "bounded-local-retrieval"], automaticDispatch: false });
+}