@piagent/platform 1.2.13 → 1.2.14

package/packages/piagent-core/extensions/task-state.js

@@ -123,7 +123,9 @@ function pickFields(value, allowed) {
 function legacyRunId(task, sourceName = "task") {
   const taskId = safeTaskId(task?.taskId ?? sourceName);
   const identity = `${taskId}\u0000${task?.createdAt ?? "legacy"}\u0000${sourceName}`;
-  return safeTaskId(`${taskId}-legacy-${crypto.createHash("sha256").update(identity).digest("hex").slice(0, 12)}`);
+  const suffix = `legacy-${crypto.createHash("sha256").update(identity).digest("hex").slice(0, 12)}`;
+  const taskKey = taskId.slice(0, 80 - suffix.length - 1).replace(/-+$/g, "") || "task";
+  return `${taskKey}-${suffix}`;
 }
 
 export function taskContractValidationErrors(input) {
@@ -620,10 +622,27 @@ export function migrateTaskState(cwd, options = {}) {
       sessionName: belongsToCurrentSession ? options.sessionName : undefined
     });
     if (!task) continue;
-    writeTaskContract(cwd, task);
     const safeArchiveRoot = ensurePrivateStateDirectory(cwd, archiveRoot, "Task state archive");
     const archiveTarget = resolveLocalStatePath(cwd, path.join(safeArchiveRoot, entry.name), { label: "Task state archive file" });
-    fs.renameSync(source, archiveTarget);
+    if (fs.existsSync(archiveTarget)) {
+      const archived = fs.readFileSync(archiveTarget);
+      const legacy = fs.readFileSync(source);
+      if (!archived.equals(legacy)) {
+        warnings.push(`legacy task archive conflict: ${entry.name}`);
+        continue;
+      }
+    } else {
+      fs.copyFileSync(source, archiveTarget, fs.constants.COPYFILE_EXCL);
+      fs.chmodSync(archiveTarget, 0o600);
+    }
+    const written = writeTaskContract(cwd, task);
+    const currentTarget = taskRunPath(cwd, written.taskRunId);
+    const sourceStat = fs.statSync(source);
+    const targetStat = fs.statSync(currentTarget);
+    const sameInode = sourceStat.ino > 0 && targetStat.ino > 0
+      && sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino;
+    const sameCanonicalPath = fs.realpathSync(source) === fs.realpathSync(currentTarget);
+    if (!sameInode && !sameCanonicalPath) fs.rmSync(source);
     migrated += 1;
   }
   return { migrated, current, warnings };

package/packages/piagent-core/package.json

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

package/packages/piagent-core/runtime/hooks/agent-start-hook.ts

@@ -0,0 +1,213 @@
+import crypto from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  buildContextPack,
+  classifyContextTask,
+  ensureContextIndexV2,
+  estimateContextTokens
+} from "../../extensions/context-engine.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { RuntimeSessionState } from "../session/runtime-state.ts";
+import {
+  compactManagedProjectInstructions,
+  rewriteLegacyProjectInstructions
+} from "../session/system-prompt.ts";
+import { PIAGENT_TOOL_NAMES } from "../tools/tool-groups.ts";
+import { extractTaskRequest, looksLikeGovernedBoilerplate } from "../workflows/input-routing.ts";
+import {
+  AUTO_INTAKE_SNAPSHOT_PATTERNS,
+  automaticTaskIntakeEligible
+} from "../workflows/task-intake.ts";
+
+type RuntimeIntakeResult = {
+  started: boolean;
+  text: string;
+  task?: TaskContract;
+};
+
+type AgentStartHookDependencies = {
+  state: RuntimeSessionState;
+  autoContextEnabled: boolean;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  readProtectedPaths: (ctx: ExtensionContext) => string[];
+  contextExcludePatterns: (ctx: ExtensionContext) => string[];
+  promptPackKey: (ctx: ExtensionContext, promptHash: string) => string;
+  retrievalKey: (ctx: ExtensionContext, query: string) => string;
+  startAutomaticTask: (query: string, ctx: ExtensionContext) => Promise<RuntimeIntakeResult | undefined>;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+export function registerAgentStartHook(pi: ExtensionAPI, dependencies: AgentStartHookDependencies): void {
+  pi.on("before_agent_start", async (event, ctx) => {
+    const projectInstructions = rewriteLegacyProjectInstructions(event.systemPrompt);
+    const query = looksLikeGovernedBoilerplate(event.prompt) ? extractTaskRequest(event.prompt) : event.prompt.trim();
+    const signal = classifyContextTask(query);
+    const readProtectedPaths = dependencies.readProtectedPaths(ctx);
+    const protectedOnlyTarget = signal.paths.length > 0
+      && signal.paths.every((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
+    const activeTask = dependencies.activeTask(ctx);
+    const runtimeIntake = !activeTask && automaticTaskIntakeEligible(query, readProtectedPaths);
+    const compactMode = protectedOnlyTarget
+      ? "protected"
+      : runtimeIntake || activeTask?.intakeMode === "runtime"
+        ? "automatic"
+        : undefined;
+    const compactedInstructions = compactMode
+      ? compactManagedProjectInstructions(projectInstructions.systemPrompt, compactMode)
+      : { systemPrompt: projectInstructions.systemPrompt, compacted: false };
+    const effectiveSystemPrompt = compactedInstructions.systemPrompt;
+    const systemPromptUpdate = effectiveSystemPrompt !== event.systemPrompt
+      ? { systemPrompt: effectiveSystemPrompt }
+      : undefined;
+    const active = new Set<string>(pi.getActiveTools() as string[]);
+    const toolMetadata = pi.getAllTools()
+      .filter((tool) => active.has(tool.name))
+      .map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        promptGuidelines: tool.promptGuidelines
+      }));
+    const toolSchemaTokens = estimateContextTokens(JSON.stringify(toolMetadata));
+    const systemPromptTokens = estimateContextTokens(effectiveSystemPrompt);
+    const autoPackUseful = activeTask?.trace.outcome !== "pending"
+      && (runtimeIntake || signal.paths.length === 0);
+    dependencies.telemetry(ctx, {
+      event: "agent_prompt",
+      promptHash: signal.promptHash,
+      promptChars: signal.promptChars,
+      workflow: signal.workflow,
+      riskLane: signal.lane,
+      activeTools: active.size,
+      activePiagentTools: [...active].filter((toolName) => PIAGENT_TOOL_NAMES.has(toolName)).length,
+      toolSchemaTokens,
+      systemPromptTokens,
+      systemPromptHash: crypto.createHash("sha256").update(effectiveSystemPrompt).digest("hex"),
+      legacyProjectInstructionsRewritten: projectInstructions.rewritten,
+      managedInstructionsCompacted: compactedInstructions.compacted,
+      contextUsage: ctx.getContextUsage()
+    });
+
+    const finishAgentStart = async (contextMessage?: {
+      customType: string;
+      content: string;
+      details: Record<string, unknown>;
+    }) => {
+      const intake = await dependencies.startAutomaticTask(query, ctx);
+      if (!contextMessage && !intake) return systemPromptUpdate;
+      const content = [contextMessage?.content, intake?.text].filter(Boolean).join("\n\n");
+      return {
+        ...(systemPromptUpdate ?? {}),
+        message: {
+          customType: contextMessage?.customType ?? "piagent-runtime-task-intake",
+          content,
+          display: false,
+          details: {
+            ...(contextMessage?.details ?? {}),
+            runtimeTask: intake?.task
+              ? {
+                  taskId: intake.task.taskId,
+                  taskRunId: intake.task.taskRunId,
+                  scope: intake.task.scope,
+                  verifyCommands: intake.task.verifyCommands,
+                  intakeMode: intake.task.intakeMode
+                }
+              : undefined,
+            runtimeIntakeStarted: intake?.started ?? false
+          }
+        }
+      };
+    };
+
+    const packKey = dependencies.promptPackKey(ctx, signal.promptHash);
+    if (
+      query.length < 20
+      || signal.workflow === "usage"
+      || !dependencies.autoContextEnabled
+      || !autoPackUseful
+      || dependencies.state.hasAutoPackedPrompt(packKey)
+    ) {
+      return finishAgentStart();
+    }
+
+    dependencies.state.rememberAutoPackedPrompt(packKey);
+    try {
+      const excludePatterns = dependencies.contextExcludePatterns(ctx);
+      const ensured = await ensureContextIndexV2(ctx.cwd, {
+        excludePatterns,
+        rebuildMissing: false
+      });
+      const status = ensured.status;
+      if (!status.exists || status.stale) {
+        dependencies.telemetry(ctx, {
+          event: "context_pack",
+          queryHash: signal.promptHash,
+          confidence: "none",
+          candidates: 0,
+          selected: 0,
+          skipped: status.exists ? "stale-index" : "missing-index"
+        });
+        return finishAgentStart();
+      }
+      const budgetTokens = runtimeIntake
+        ? 900
+        : signal.lane === "high-risk" ? 1_200 : signal.lane === "tiny" ? 500 : 900;
+      const pack = await buildContextPack(ctx.cwd, query, {
+        budgetTokens,
+        includeCode: runtimeIntake,
+        includePatterns: runtimeIntake ? AUTO_INTAKE_SNAPSHOT_PATTERNS : undefined,
+        currentSnapshot: runtimeIntake,
+        limit: runtimeIntake ? 8 : 12,
+        excludePatterns
+      });
+      dependencies.telemetry(ctx, {
+        event: "context_pack",
+        queryHash: pack.queryHash,
+        confidence: pack.confidence,
+        candidates: pack.candidates,
+        selected: pack.selected.length,
+        estimatedTokens: pack.estimatedTokens,
+        selectedPaths: pack.selected.map((item) => item.path),
+        finderRecommended: pack.finderRecommended,
+        currentSnapshot: runtimeIntake
+      });
+      if (!["medium", "high"].includes(pack.confidence) || pack.selected.length === 0) return finishAgentStart();
+      dependencies.state.rememberInjectedContextPack(ctx, dependencies.retrievalKey(ctx, query), {
+        queryHash: pack.queryHash,
+        confidence: pack.confidence,
+        estimatedTokens: pack.estimatedTokens,
+        paths: pack.selected.map((item) => item.path)
+      });
+      for (const selected of pack.selected) {
+        dependencies.state.rememberObservedContext(ctx, {
+          path: selected.path,
+          reason: "Runtime injected a bounded Context Engine navigation pack."
+        });
+      }
+      return finishAgentStart({
+        customType: "piagent-context-pack-v2",
+        content: pack.text,
+        details: {
+          schemaVersion: 2,
+          queryHash: pack.queryHash,
+          confidence: pack.confidence,
+          estimatedTokens: pack.estimatedTokens,
+          paths: pack.selected.map((item) => item.path),
+          currentSnapshot: runtimeIntake
+        }
+      });
+    } catch (error) {
+      dependencies.telemetry(ctx, {
+        event: "context_pack",
+        queryHash: signal.promptHash,
+        confidence: "none",
+        candidates: 0,
+        selected: 0,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return finishAgentStart();
+    }
+  });
+}

package/packages/piagent-core/runtime/hooks/completion-hook.ts

@@ -0,0 +1,203 @@
+import crypto from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { runtimeLifecycleMode, workingTreeEvidenceDigest } from "../../extensions/task-lifecycle.js";
+import { workingTreeSnapshot } from "../../extensions/task-state.js";
+import {
+  assistantMessageHasToolCall,
+  assistantMessageText,
+  looksLikeCompletionClaim,
+  looksLikeIncompleteHandoff
+} from "../session/message-signals.ts";
+import { RuntimeSessionState } from "../session/runtime-state.ts";
+import type { ObservedTaskContext } from "../session/runtime-state.ts";
+
+type CompletionGate = {
+  decision: "pass" | "fail";
+  missing: string[];
+  missingVerifyCommands: string[];
+};
+
+type CompletionHookDependencies = {
+  state: RuntimeSessionState;
+  maxManifestFiles: number;
+  autoRecoveryEnabled: boolean;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  flushObservedTaskContext: (
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    pendingContext: ObservedTaskContext[],
+    maxManifestFiles: number,
+    event: string
+  ) => TaskContract | undefined;
+  completionProjection: (
+    cwd: string,
+    task: TaskContract,
+    currentDigests: Record<string, string>
+  ) => TaskContract;
+  evaluateGate: (
+    cwd: string,
+    task: TaskContract,
+    currentDigests: Record<string, string>,
+    currentDigest: string
+  ) => CompletionGate;
+  writeTask: (cwd: string, task: TaskContract) => TaskContract;
+  activateBaseTools: (ctx: ExtensionContext) => unknown;
+  appendTrace: (cwd: string, payload: Record<string, unknown>) => void;
+  appendSessionTrace: (pi: ExtensionAPI, payload: Record<string, unknown>) => void;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+  finalGateMode: (ctx: ExtensionContext) => string;
+  verifierInstructions: (commands: string[]) => string[];
+};
+
+export function registerCompletionHook(pi: ExtensionAPI, dependencies: CompletionHookDependencies): void {
+  const {
+    state,
+    maxManifestFiles,
+    autoRecoveryEnabled,
+    activeTask,
+    flushObservedTaskContext,
+    completionProjection,
+    evaluateGate,
+    writeTask,
+    activateBaseTools,
+    appendTrace,
+    appendSessionTrace,
+    telemetry,
+    finalGateMode,
+    verifierInstructions
+  } = dependencies;
+
+  pi.on("message_end", async (event, ctx) => {
+    if (!event.message || event.message.role !== "assistant" || assistantMessageHasToolCall(event.message)) return;
+    let task = flushObservedTaskContext(
+      pi,
+      ctx,
+      state.observedContext(ctx),
+      maxManifestFiles,
+      "context_observed_before_handoff"
+    ) ?? activeTask(ctx);
+    if (!task) return;
+    const text = assistantMessageText(event.message);
+    const completionClaim = looksLikeCompletionClaim(text);
+    const incompleteHandoff = looksLikeIncompleteHandoff(text);
+    if (task.trace.outcome !== "pending") return;
+    const readOnlyEvidenceObserved = task.changeMode === "read-only" && task.contextManifest.length > 0;
+    const potentiallyFinalEvidence = task.observedChangedFiles.length > 0
+      || task.verifyEvidence.some((evidence) => evidence.exitCode === 0 && evidence.observed === true && evidence.matchedProfileCommand === true)
+      || readOnlyEvidenceObserved;
+    if (!completionClaim && (incompleteHandoff || !potentiallyFinalEvidence)) return;
+
+    const currentDigests = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
+    const currentDigest = workingTreeEvidenceDigest(currentDigests);
+    const currentPassingVerifierObserved = task.verifyEvidence.some((evidence) => (
+      evidence.exitCode === 0
+      && evidence.observed === true
+      && evidence.matchedProfileCommand === true
+      && evidence.workingTreeDigest === currentDigest
+    ));
+    const handoffAttempt = completionClaim || (
+      !incompleteHandoff
+      && (task.observedChangedFiles.length > 0 || currentPassingVerifierObserved || readOnlyEvidenceObserved)
+    );
+    let completionGate: CompletionGate | undefined;
+    if (handoffAttempt) {
+      const projected = completionProjection(ctx.cwd, task, currentDigests);
+      const projectedGate = evaluateGate(ctx.cwd, projected, currentDigests, currentDigest);
+      completionGate = projectedGate;
+      if (projectedGate.decision === "pass") {
+        task = writeTask(ctx.cwd, projected);
+        state.cacheTaskIdentity(ctx, task);
+        state.clearCompletionRecoveryAttempt(task.taskRunId);
+        state.clearObservedContext(ctx);
+        activateBaseTools(ctx);
+        const trace = {
+          event: "task_auto_completed",
+          taskId: task.taskId,
+          taskRunId: task.taskRunId,
+          sessionId: task.sessionId,
+          changedFiles: task.changedFiles,
+          lifecycleMode: runtimeLifecycleMode(task)
+        };
+        appendTrace(ctx.cwd, trace);
+        appendSessionTrace(pi, trace);
+        telemetry(ctx, trace);
+        return;
+      }
+    }
+    if (!handoffAttempt || finalGateMode(ctx) !== "enforce") return;
+    const gate = completionGate ?? evaluateGate(ctx.cwd, task, currentDigests, currentDigest);
+    if (gate.decision === "pass") return;
+
+    const recoveryAttempt = state.completionRecoveryAttempt(task.taskRunId);
+    const lifecycleMode = runtimeLifecycleMode(task);
+    if (autoRecoveryEnabled && lifecycleMode !== "manual" && recoveryAttempt < 1) {
+      state.rememberCompletionRecoveryAttempt(task.taskRunId, recoveryAttempt + 1);
+      const recoveryGuidance = task.changeMode === "read-only"
+        ? [
+            "Continue the same read-only task. Review the cited evidence against the requested scope, state concrete unknowns, and complete the returned review step when required.",
+            "Do not mutate project source or repeat diagnostic Piagent tools; use ordinary targeted reads and the active progress tool only."
+          ]
+        : [
+            "Continue the same bounded task. Re-check the requested behavior against current source, make a relevant in-scope change when required, and run every exact configured verifier.",
+            ...verifierInstructions(gate.missingVerifyCommands),
+            "A pre-existing passing test without a relevant source diff is not completion. Do not repeat diagnostic Piagent tools; use ordinary read/edit/bash work."
+          ];
+      const recovery = [
+        "[Piagent continuation required]",
+        `Task ${task.taskId} cannot finish yet. Missing: ${gate.missing.join(", ")}.`,
+        ...recoveryGuidance
+      ].join("\n");
+      pi.sendMessage(
+        { customType: "piagent-completion-recovery", content: recovery, display: false, details: { taskId: task.taskId, missing: gate.missing } },
+        { deliverAs: "followUp", triggerTurn: true }
+      );
+      const recoveryTrace = {
+        event: "completion_recovery_scheduled",
+        taskId: task.taskId,
+        taskRunId: task.taskRunId,
+        sessionId: task.sessionId,
+        attempt: recoveryAttempt + 1,
+        missing: gate.missing
+      };
+      appendTrace(ctx.cwd, recoveryTrace);
+      appendSessionTrace(pi, recoveryTrace);
+      telemetry(ctx, recoveryTrace);
+      const continuingNotice = [
+        "[Piagent completion gate: CONTINUING]",
+        `Task ${task.taskId} needs one bounded correction pass before handoff.`,
+        ""
+      ].join("\n");
+      const content = Array.isArray(event.message.content)
+        ? [{ type: "text" as const, text: continuingNotice }, ...event.message.content]
+        : [{ type: "text" as const, text: `${continuingNotice}${text}` }];
+      return { message: { ...event.message, content } };
+    }
+
+    const notice = [
+      "[Piagent completion gate: NOT APPROVED]",
+      `Task ${task.taskId} (${task.taskRunId}) is still open.`,
+      `Missing: ${gate.missing.join(", ") || "a completed task trace"}.`,
+      ...verifierInstructions(gate.missingVerifyCommands),
+      "The response below is preserved as work in progress and must not be treated as a completion report.",
+      ""
+    ].join("\n");
+    const content = Array.isArray(event.message.content)
+      ? [{ type: "text" as const, text: notice }, ...event.message.content]
+      : [{ type: "text" as const, text: `${notice}${text}` }];
+    const trace = {
+      event: "completion_claim_blocked",
+      taskId: task.taskId,
+      taskRunId: task.taskRunId,
+      sessionId: task.sessionId,
+      missing: gate.missing,
+      responseHash: crypto.createHash("sha256").update(text).digest("hex"),
+      responseChars: text.length
+    };
+    appendTrace(ctx.cwd, trace);
+    appendSessionTrace(pi, trace);
+    telemetry(ctx, trace);
+    return { message: { ...event.message, content } };
+  });
+}

package/packages/piagent-core/runtime/hooks/input-hook.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { classifyContextTask } from "../../extensions/context-engine.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { attachLocalImagesFromText } from "../input/chat-images.ts";
+import type { ChatImageAccessPolicy } from "../input/chat-images.ts";
+import { LONG_INPUT_CHARS } from "../runtime-limits.ts";
+import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
+import { activeTaskToolGroups, toolGroupsForPrompt } from "../tools/tool-groups.ts";
+import type { PiagentToolGroup } from "../tools/tool-groups.ts";
+import {
+  buildFreshCommand,
+  chooseFreshWorkflow,
+  extractTaskRequest,
+  isFreshOrUtilityInput,
+  isPiagentWorkflowInput,
+  looksLikeGovernedBoilerplate,
+  trimTaskForInline
+} from "../workflows/input-routing.ts";
+import {
+  automaticTaskIntakeEligible,
+  manualTaskIntakeEligible
+} from "../workflows/task-intake.ts";
+
+type InputHookDependencies = {
+  boilerplateCollapseChars: number;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  readProtectedPaths: (ctx: ExtensionContext) => string[];
+  imageAccess: (ctx: ExtensionContext) => ChatImageAccessPolicy;
+  activateToolGroups: (ctx: ExtensionContext, groups: PiagentToolGroup[]) => unknown;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDependencies): void {
+  pi.on("input", async (event, ctx) => {
+    const text = event.text.trim();
+    if (!text || isFreshOrUtilityInput(text)) return { action: "continue" };
+    if (/^\/piagent-workflow\b/i.test(text)) {
+      return { action: "transform", text: text.replace(/^\/piagent-workflow\b/i, "/workflow") };
+    }
+
+    const taskSignal = classifyContextTask(text);
+    const activeTask = dependencies.activeTask(ctx);
+    const readProtectedPaths = dependencies.readProtectedPaths(ctx);
+    const protectedTarget = taskSignal.paths.some((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
+    const protectedOnlyTarget = taskSignal.paths.length > 0
+      && taskSignal.paths.every((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
+    const runtimeIntake = !activeTask && automaticTaskIntakeEligible(text, readProtectedPaths);
+    const manualIntake = !activeTask && !runtimeIntake && manualTaskIntakeEligible(text, readProtectedPaths);
+    const promptGroups = protectedOnlyTarget
+      ? []
+      : toolGroupsForPrompt(text).filter((group) => (
+          runtimeIntake ? group !== "intake" && group !== "task" : true
+        ));
+    if (manualIntake && !promptGroups.includes("intake")) promptGroups.push("intake");
+    dependencies.activateToolGroups(ctx, activeTask?.trace.outcome === "pending"
+      ? [...promptGroups.filter((group) => group !== "intake"), ...activeTaskToolGroups(activeTask)]
+      : promptGroups);
+    dependencies.telemetry(ctx, {
+      event: "user_input",
+      source: event.source,
+      promptHash: taskSignal.promptHash,
+      promptChars: taskSignal.promptChars,
+      workflow: taskSignal.workflow,
+      riskLane: taskSignal.lane,
+      intakeMode: runtimeIntake ? "runtime" : "model",
+      protectedTarget,
+      protectedOnlyTarget,
+      manualIntake,
+      explicitPathCount: taskSignal.paths.length,
+      termCount: taskSignal.terms.length
+    });
+
+    const imageAttachment = attachLocalImagesFromText(
+      text,
+      event.images,
+      ctx.cwd,
+      () => dependencies.imageAccess(ctx)
+    );
+    if (imageAttachment?.attached.length) {
+      ctx.ui.notify(`Piagent image input: attached ${imageAttachment.attached.map((item) => item.marker).join(", ")}`, "info");
+    } else if (imageAttachment?.skipped.length) {
+      ctx.ui.notify(`Piagent image input: skipped ${imageAttachment.skipped.length} local image path(s)`, "warning");
+    }
+
+    const inputText = imageAttachment?.text ?? text;
+    const canRewriteWorkflow = event.source !== "extension";
+    const snapshot = buildUsageSnapshot(ctx, String(pi.getThinkingLevel()));
+    const preflight = buildContextPreflight(snapshot, chooseFreshWorkflow(inputText, inputText), inputText.length);
+    const hasBoilerplate = looksLikeGovernedBoilerplate(inputText);
+    const shouldFreshen = canRewriteWorkflow
+      && preflight.recommendation === "fresh-session"
+      && (hasBoilerplate || isPiagentWorkflowInput(inputText) || inputText.length >= LONG_INPUT_CHARS);
+    const shouldCollapseBoilerplate = canRewriteWorkflow
+      && hasBoilerplate
+      && inputText.length >= dependencies.boilerplateCollapseChars;
+    const outgoingImages = [
+      ...(Array.isArray(event.images) ? event.images : []),
+      ...(imageAttachment?.images ?? [])
+    ];
+
+    if (!shouldFreshen && !shouldCollapseBoilerplate) {
+      if (imageAttachment?.attached.length) return { action: "transform", text: inputText, images: outgoingImages };
+      return { action: "continue" };
+    }
+
+    const task = extractTaskRequest(inputText);
+    const workflow = chooseFreshWorkflow(inputText, task);
+    const reason = shouldFreshen
+      ? "Current session is near context limits; use a fresh governed session."
+      : "Mandatory flow boilerplate is already part of the platform; collapse it to the task request.";
+    const command = shouldFreshen
+      ? buildFreshCommand(ctx.cwd, workflow, inputText, reason)
+      : `/${workflow} ${trimTaskForInline(task)}`;
+
+    ctx.ui.notify(`Piagent preflight: ${reason}`, "warning");
+    return outgoingImages.length > 0
+      ? { action: "transform", text: command, images: outgoingImages }
+      : { action: "transform", text: command };
+  });
+}