pi-agent-flow 2.0.0 → 2.0.2

package/dist/flow/warp.js

@@ -0,0 +1,207 @@
+/**
+ * Warp extension — transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), warp extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /flow:warp now implement this for teams as well
+ *   /flow:warp execute phase one of the plan
+ *   /flow:warp check other places that need this fix
+ *   /flow:warp                              (no args = default continuation goal)
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+const WARP_TIMEOUT_MS = 5 * 60 * 1000;
+const WARP_POLL_INTERVAL_MS = 25;
+const WARP_INSTRUCTIONS = `You are writing a warp note for another AI agent with NO access to this chat.
+
+Extract only task-relevant context from this conversation.
+
+Rules:
+- Be tight and token-efficient.
+- Use only concrete facts from this conversation.
+- Prefer specifics: file paths, symbols, commands, errors, outputs, decisions.
+- Include constraints/invariants only when explicit, non-negotiable, and task-relevant.
+- Include line numbers only if known from this conversation.
+- Omit irrelevant history and broad retrospectives.
+- Do not invent missing details.
+- If a critical detail is unknown, say so briefly and include the smallest verification step.
+- Do not write a plan unless one already exists in this conversation.
+- Do not call tools.
+
+Your output MUST use this exact format:
+
+FRONTMATTER (YAML between --- delimiters):
+  context       — 1-2 sentence orientation summary
+  end_goal      — The finish line, not the next step
+  decisions     — Key choices already made (list)
+  files         — Files touched with what changed (list)
+  open_items    — Unresolved work or questions (list)
+  watch_out     — Edge cases, gotchas, fragile assumptions (list)
+  context_gathering:
+    aim         — What the initial scout/discovery should accomplish
+    scope       — Specific things to explore or map (list)
+  execution_plan:
+    - phase     — Phase name
+      parallel  — true/false, can this run alongside other phases?
+      group     — If parallel, which execution group (A, B, C...)
+      flow      — Which flow type to use (scout, build, audit, craft...)
+      flows     — OR multiple flows if parallel within the phase
+      task      — Clear, actionable task for this phase
+      depends_on — Phase(s) that must complete first
+      produces  — What "done" means for this phase
+  success_criteria — How to know the overall work is complete (list)
+
+BODY (after the closing ---):
+  ## Context
+  A concise summary of the conversation context.
+
+RULES:
+1. Always start with a context_gathering phase — the new session has no context yet, so discovery comes first.
+2. Mark phases parallel:true when they have no data dependencies on each other. Use group labels (A, B, C) to cluster parallel work.
+3. Each phase should produce a concrete artifact, evidence of completion before moving on to the next.
+4. Respect the given plan scaffold.
+5. Use flow types from: scout, build, audit, craft, debug, ideas.
+6. Success criteria should be the final state, i.e. integration test pass, code coverage with verified output, etc.
+7. If an active goal from the prior session exists, include it in the frontmatter context.
+8. Preserve unresolved blockers, open questions, or "not done" items from prior flow results in open_items.
+9. Flag any uncertain areas — parts of the codebase, design decisions, or assumptions that may have shifted since the conversation and need re-assessment via a scout or audit flow before committing to a plan.
+10. No tool calls; all attempts that you need to discover, note them to the watch_out list or execution_plan.
+11. Your entire response must be the warp prompt starting with '---' (YAML frontmatter opening). No preamble, no explanations, no tool calls.
+
+IMPORTANT: You are a text generation assistant, not an agent. Do NOT attempt tool calls, file operations, code execution, or any actions. Output ONLY the structured prompt text.`;
+function getRoleMessage(entry, role) {
+    if (entry.type !== "message" || !isRecord(entry.message)) {
+        return null;
+    }
+    const message = entry.message;
+    if (message.role !== role || !("content" in message)) {
+        return null;
+    }
+    return message;
+}
+function getAssistantMessage(entry) {
+    const message = getRoleMessage(entry, "assistant");
+    if (!message || !isRecord(message)) {
+        return null;
+    }
+    return message;
+}
+function getMessageText(entry) {
+    if (entry.type !== "message" || !isRecord(entry.message) || !("content" in entry.message)) {
+        return "";
+    }
+    const content = entry.message.content;
+    if (typeof content === "string") {
+        return content.trim();
+    }
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    return content
+        .filter((block) => isRecord(block) && block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n")
+        .trim();
+}
+function findUserMessageIndex(entries, fromIndex, text) {
+    for (let i = entries.length - 1; i >= fromIndex; i--) {
+        const entry = entries[i];
+        if (!getRoleMessage(entry, "user")) {
+            continue;
+        }
+        if (getMessageText(entry) === text) {
+            return i;
+        }
+    }
+    return -1;
+}
+function hasAssistantAfterIndex(entries, fromIndex) {
+    for (let i = entries.length - 1; i > fromIndex; i--) {
+        const entry = entries[i];
+        if (getRoleMessage(entry, "assistant")) {
+            return true;
+        }
+    }
+    return false;
+}
+async function waitForWarpTurn(ctx, startIndex, warpRequest, timeoutMs = WARP_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const branch = ctx.sessionManager.getBranch();
+        const warpUserIndex = findUserMessageIndex(branch, startIndex, warpRequest);
+        if (warpUserIndex !== -1 && hasAssistantAfterIndex(branch, warpUserIndex) && ctx.isIdle()) {
+            return { branch, warpUserIndex };
+        }
+        await new Promise((resolve) => setTimeout(resolve, WARP_POLL_INTERVAL_MS));
+    }
+    return null;
+}
+function getAssistantText(entries, fromIndex) {
+    for (let i = entries.length - 1; i >= fromIndex; i--) {
+        const entry = entries[i];
+        const message = getAssistantMessage(entry);
+        if (!message) {
+            continue;
+        }
+        if (message.stopReason !== "stop") {
+            return null;
+        }
+        const text = getMessageText(entry);
+        if (text.length > 0) {
+            return text;
+        }
+    }
+    return null;
+}
+const DEFAULT_GOAL = "Continue where we left off — summarize what we have done, where we are, and what the natural next step is.";
+export default function (pi) {
+    pi.registerCommand("flow:warp", {
+        description: "Transfer context to a new focused session",
+        handler: async (args, ctx) => {
+            const notify = (message, level) => {
+                ctx.ui?.notify?.(message, level);
+            };
+            if (!ctx.model) {
+                notify("No model selected", "error");
+                return;
+            }
+            const task = args.trim() || DEFAULT_GOAL;
+            const currentSessionFile = ctx.sessionManager.getSessionFile();
+            const startIndex = ctx.sessionManager.getBranch().length;
+            const warpRequest = `${WARP_INSTRUCTIONS}\n\nTask for the next agent:\n${task}`;
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(warpRequest);
+            }
+            else {
+                pi.sendUserMessage(warpRequest, { deliverAs: "followUp" });
+            }
+            notify("Generating warp note...", "info");
+            const warpTurn = await waitForWarpTurn(ctx, startIndex, warpRequest);
+            if (!warpTurn) {
+                notify("Timed out waiting for warp note", "error");
+                return;
+            }
+            const warpNote = getAssistantText(warpTurn.branch, warpTurn.warpUserIndex + 1);
+            if (!warpNote) {
+                notify("Failed to capture warp note from the assistant response", "error");
+                return;
+            }
+            const promptForNewSession = `${warpNote}\n\n---\n\n## Task\n${task}`;
+            const newSessionResult = await ctx.newSession({
+                parentSession: currentSessionFile,
+                withSession: async (newCtx) => {
+                    await newCtx.sendUserMessage(promptForNewSession);
+                    newCtx.ui?.notify?.("Warp ready...", "info");
+                },
+            });
+            if (newSessionResult.cancelled) {
+                notify("New session cancelled", "info");
+                return;
+            }
+        },
+    });
+}
+//# sourceMappingURL=warp.js.map

package/dist/flow/warp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warp.js","sourceRoot":"","sources":["../../src/flow/warp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,SAAS,QAAQ,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACpD,CAAC;AAYD,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACtC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kLAwDwJ,CAAC;AAEnL,SAAS,cAAc,CAAC,KAAmB,EAAE,IAA0B;IACtE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,SAAS,IAAI,OAAO,CAAC,EAAE,CAAC;QACtD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,OAAsB,CAAC;AAC/B,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAmB;IAC/C,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,OAA+B,CAAC;AACxC,CAAC;AAED,SAAS,cAAc,CAAC,KAAmB;IAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3F,OAAO,EAAE,CAAC;IACX,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;IACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,OAAO;SACZ,MAAM,CAAC,CAAC,KAAK,EAA2C,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;SACtI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;AACV,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAuB,EAAE,SAAiB,EAAE,IAAY;IACrF,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;YACpC,SAAS;QACV,CAAC;QACD,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;YACpC,OAAO,CAAC,CAAC;QACV,CAAC;IACF,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACX,CAAC;AAED,SAAS,sBAAsB,CAAC,OAAuB,EAAE,SAAiB;IACzE,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAOD,KAAK,UAAU,eAAe,CAC7B,GAA4B,EAC5B,UAAkB,EAClB,WAAmB,EACnB,SAAS,GAAG,eAAe;IAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAoB,CAAC;QAChE,MAAM,aAAa,GAAG,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QAC5E,IAAI,aAAa,KAAK,CAAC,CAAC,IAAI,sBAAsB,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3F,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAClC,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAuB,EAAE,SAAiB;IACnE,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,SAAS;QACV,CAAC;QACD,IAAI,OAAO,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC;QACb,CAAC;QACD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,MAAM,YAAY,GAAG,4GAA4G,CAAC;AAElI,MAAM,CAAC,OAAO,WAAW,EAAgB;IACxC,EAAE,CAAC,eAAe,CAAC,WAAW,EAAE;QAC/B,WAAW,EAAE,2CAA2C;QACxD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC5B,MAAM,MAAM,GAAG,CAAC,OAAe,EAAE,KAAmC,EAAE,EAAE;gBACvE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAClC,CAAC,CAAC;YAEF,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;gBAChB,MAAM,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;gBACrC,OAAO;YACR,CAAC;YAED,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,YAAY,CAAC;YAEzC,MAAM,kBAAkB,GAAG,GAAG,CAAC,cAAc,CAAC,cAAc,EAAE,CAAC;YAC/D,MAAM,UAAU,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC;YAEzD,MAAM,WAAW,GAAG,GAAG,iBAAiB,iCAAiC,IAAI,EAAE,CAAC;YAEhF,IAAI,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;gBAClB,EAAE,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACP,EAAE,CAAC,eAAe,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;YAC5D,CAAC;YAED,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;YAC1C,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;YAErE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACf,MAAM,CAAC,iCAAiC,EAAE,OAAO,CAAC,CAAC;gBACnD,OAAO;YACR,CAAC;YAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;YAE/E,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACf,MAAM,CAAC,yDAAyD,EAAE,OAAO,CAAC,CAAC;gBAC3E,OAAO;YACR,CAAC;YAED,MAAM,mBAAmB,GAAG,GAAG,QAAQ,uBAAuB,IAAI,EAAE,CAAC;YAErE,MAAM,gBAAgB,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC;gBAC7C,aAAa,EAAE,kBAAkB;gBACjC,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;oBAC7B,MAAM,MAAM,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;oBAClD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;gBAC9C,CAAC;aACD,CAAC,CAAC;YAEH,IAAI,gBAAgB,CAAC,SAAS,EAAE,CAAC;gBAChC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;gBACxC,OAAO;YACR,CAAC;QACF,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -5,8 +5,9 @@
  * Each flow receives a forked snapshot of the current session context.
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-export { logWarn, logError } from "./config/log.js";
-export { compressToolResults, compressFlowToolResults, stripBatchReadToolCalls } from "./snapshot/snapshot.js";
+import { logWarn, logError } from "./config/log.js";
+export { logWarn, logError };
+export { compressToolResults, stripBatchReadToolCalls } from "./snapshot/snapshot.js";
 export { type FlowColorConfig } from "./tui/flow-colors.js";
 export default function (pi: ExtensionAPI): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA6CpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAmFpD,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAC/G,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAM5D,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAwZxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA+CpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AA+K7B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAM5D,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAycxC"}

package/dist/index.js

@@ -10,25 +10,133 @@ import { discoverFlows, getFlowTier } from "./core/agents.js";
 import { getInheritedCliArgs } from "./snapshot/cli-args.js";
 import { renderFlowCall, renderFlowResult } from "./tui/render.js";
 import { terminateAllChildGroups } from "./core/flow.js";
-import { executeFlows } from "./core/executor.js";
-import { appendStrategicHintOnce, resetStrategicHintTracker, configureStrategicHint } from "./steering/tool-utils.js";
+import { executeFlows, evictCacheOverflow } from "./core/executor.js";
+import { appendDirectiveOnce, resetDirectiveTracker, configureDirective, stripDirectivesFromMessages } from "./steering/tool-utils.js";
 import { createBatchTool, createBatchReadTool, BashProcessTracker, createBatchBashPollTool, } from "./batch/index.js";
 import { createWebTool } from "./tools/web-tool.js";
 import { createAskUserTool } from "./tools/ask-user.js";
 import { stripSteeringHintText, stripSteeringHintsFromMessages, makeSteeringHintMessage, configureSteering, } from "./steering/sliding-prompt.js";
-import { registerFlow, getGoalForSession, recordFlowCompletion, addTokens, shutdownWakeup } from "./flow/index.js";
+import { registerFlow, getGoal, getGoalForSession, recordFlowCompletion, addTokens, shutdownWakeup } from "./flow/index.js";
 import * as sessionRegistry from "./core/session-registry.js";
 import { createTimedBashToolDefinition } from "./tools/timed-bash.js";
 import { resolveFlowDepthConfig, } from "./core/depth.js";
 import { buildForkSessionSnapshotJsonl, sanitizeForkSnapshot, } from "./snapshot/snapshot.js";
 import { resolveSettings, } from "./config/settings-resolver.js";
 import { scrambleManager } from "./tui/scramble/index.js";
-export { logWarn, logError } from "./config/log.js";
+import { logWarn, logError } from "./config/log.js";
+export { logWarn, logError };
 // ---------------------------------------------------------------------------
 // Persistent flow result cache — shared across execute() calls so historical
 // flow results are compressed properly in fork snapshots.
 // ---------------------------------------------------------------------------
 const flowResultCache = new Map();
+/**
+ * Reconstruct flowResultCache from an existing session branch after restart.
+ * Scans tool results for the "flow" tool and rebuilds CompressedFlowResult
+ * entries so child-fork compression works immediately without waiting for
+ * new flows to complete.
+ */
+function reconstructFlowResultCache(sessionManager, cache) {
+    const branch = sessionManager.getBranch();
+    if (!Array.isArray(branch) || branch.length === 0)
+        return;
+    // Pass 1: map toolCallId -> "flow" from assistant messages
+    const toolCallIdToName = new Map();
+    for (const entry of branch) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (e.type !== "message")
+            continue;
+        const msg = e.message;
+        if (!msg || msg.role !== "assistant")
+            continue;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if (!part || typeof part !== "object")
+                continue;
+            const p = part;
+            if (p.type === "toolCall" && p.name === "flow") {
+                const tcId = (p.id ?? p.toolCallId);
+                if (tcId)
+                    toolCallIdToName.set(tcId, "flow");
+            }
+        }
+    }
+    // Pass 2: scan tool/toolResult messages and rebuild cache
+    for (const entry of branch) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (e.type !== "message")
+            continue;
+        const msg = e.message;
+        if (!msg || (msg.role !== "tool" && msg.role !== "toolResult"))
+            continue;
+        let toolCallId;
+        if (typeof msg.toolCallId === "string" && msg.toolCallId.trim()) {
+            toolCallId = msg.toolCallId;
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if (!part || typeof part !== "object")
+                    continue;
+                const p = part;
+                if (p.type === "toolResult" && typeof p.toolCallId === "string" && p.toolCallId.trim()) {
+                    toolCallId = p.toolCallId;
+                    break;
+                }
+            }
+        }
+        if (!toolCallId || toolCallIdToName.get(toolCallId) !== "flow")
+            continue;
+        const details = msg.details;
+        if (!details || !Array.isArray(details.results))
+            continue;
+        const results = details.results;
+        const compressed = [];
+        for (const r of results) {
+            const so = r.structuredOutput;
+            if (!so)
+                continue;
+            const c = {
+                type: typeof r.type === "string" ? r.type : "unknown",
+                status: typeof r.exitCode === "number" && r.exitCode === 0 ? "accomplished" : "failed",
+            };
+            if (typeof r.intent === "string")
+                c.intent = r.intent;
+            if (typeof r.aim === "string")
+                c.aim = r.aim;
+            if (typeof so.summary === "string")
+                c.summary = so.summary;
+            if (Array.isArray(so.files))
+                c.files = so.files;
+            if (Array.isArray(so.actions))
+                c.actions = so.actions;
+            if (Array.isArray(so.commands))
+                c.commands = so.commands;
+            if (Array.isArray(so.notDone))
+                c.notDone = so.notDone;
+            if (Array.isArray(so.nextSteps))
+                c.nextSteps = so.nextSteps;
+            if (Array.isArray(so.reasoning))
+                c.reasoning = so.reasoning;
+            if (Array.isArray(so.notes))
+                c.notes = so.notes;
+            if (typeof r.errorMessage === "string")
+                c.error = r.errorMessage;
+            compressed.push(c);
+        }
+        if (compressed.length > 0) {
+            const existing = cache.get(toolCallId) ?? [];
+            existing.push(...compressed);
+            cache.set(toolCallId, existing);
+        }
+    }
+    evictCacheOverflow(cache);
+}
 import { computeActiveTools, buildBeforeAgentStartPrompt, } from "./steering/flow-prompt.js";
 // ---------------------------------------------------------------------------
 // Tool parameter schema
@@ -46,12 +154,13 @@ const FlowItem = Type.Object({
     acceptance: Type.Optional(Type.String({ description: "Short success criteria — one sentence stating what done looks like." })),
     cwd: Type.Optional(Type.String({ description: "Working directory override for this flow." })),
     sessionMode: Type.Optional(Type.Union([
+        Type.Literal("snap"),
         Type.Literal("fast"),
         Type.Literal("default"),
         Type.Literal("long"),
         Type.Literal("extreme_long"),
     ], {
-        description: "Agent session budget for this flow: fast=300s, default=600s, long=900s, extreme_long=1200s. Use long or extreme_long only when the work genuinely needs the larger budget.",
+        description: "Agent session budget for this flow: snap=90s, fast=300s, default=600s, long=900s, extreme_long=1200s. Use long or extreme_long only when the work genuinely needs the larger budget.",
     })),
 }, {
     title: "FlowTask",
@@ -60,7 +169,7 @@ const FlowItem = Type.Object({
 const FlowParams = Type.Object({
     flow: Type.Array(FlowItem, {
         description: "Array of flow tasks to execute. Each runs in its own forked process. " +
-            "Optional sessionMode selects the child-agent budget: fast=300s, default=600s, long=900s, extreme_long=1200s.",
+            "Optional sessionMode selects the flow state budget: fast=300s, default=600s, long=900s, extreme_long=1200s.",
         examples: [
             { type: "scout", intent: "Map auth module files and trace JWT validation path", aim: "Map auth and trace JWT" },
             { type: "audit", intent: "Audit input validation and SQL injection risks in user routes", aim: "Audit user route security" },
@@ -85,7 +194,7 @@ function makeFlowDetailsFactory(projectFlowsDir) {
     });
 }
 // Re-export compressToolResults and stripBatchReadToolCalls for tests
-export { compressToolResults, compressFlowToolResults, stripBatchReadToolCalls } from "./snapshot/snapshot.js";
+export { compressToolResults, stripBatchReadToolCalls } from "./snapshot/snapshot.js";
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
@@ -123,7 +232,7 @@ export default function (pi) {
         type: "string",
     });
     pi.registerFlag("flow-session-mode", {
-        description: "Default child-flow session mode: fast (300s), default (600s), long (900s), or extreme_long (1200s).",
+        description: "Default child-flow session mode: snap (90s), fast (300s), default (600s), long (900s), or extreme_long (1200s).",
         type: "string",
     });
     pi.registerFlag("tool-optimize", {
@@ -131,7 +240,7 @@ export default function (pi) {
         type: "boolean",
     });
     pi.registerFlag("no-steering", {
-        description: "Disable orchestrator steering hint injection.",
+        description: "Disable root state steering hint injection.",
         type: "boolean",
     });
     pi.registerFlag("steering-prompt", {
@@ -155,7 +264,7 @@ export default function (pi) {
     // Wire up /flow command and continuation hooks
     registerFlow(pi);
     const depthConfig = resolveFlowDepthConfig(pi);
-    const { currentDepth, maxDepth, canDelegate, ancestorFlowStack, preventCycles } = depthConfig;
+    const { currentDepth, maxDepth, canTransition, ancestorFlowStack, preventCycles } = depthConfig;
     let resolved;
     let _sessionCtx;
     let bashTracker;
@@ -164,18 +273,23 @@ export default function (pi) {
         sessionRegistry.register(ctx.cwd, ctx.sessionManager.getSessionId());
         _sessionCtx = ctx;
         resolved = resolveSettings(pi, ctx.cwd);
+        // Reconstruct historical flow result cache so fork snapshots can compress
+        // past flow results immediately (instead of showing placeholder text until
+        // new flows complete). bashTracker is created fresh below — pending OS
+        // processes are inherently lost across restarts, which is expected.
+        reconstructFlowResultCache(ctx.sessionManager, flowResultCache);
         // Wire resolved settings to modules
         configureSteering({ enabled: resolved.steeringEnabled, customPrompt: resolved.steeringCustomPrompt });
-        configureStrategicHint(resolved.steeringStrategicHint);
+        configureDirective(resolved.steeringStrategicHint);
         scrambleManager.setAnimationConfig({ enabled: resolved.animationEnabled, glitch: resolved.animationGlitch });
-        // Only restrict tools for the main orchestrator (depth 0).
+        // Only restrict tools for the main root state (depth 0).
         // Child flows (depth > 0) receive their tools via --tools CLI arg;
         // overriding them here would strip bash/batch from children.
         if (currentDepth === 0) {
             pi.setActiveTools(computeActiveTools(resolved.toolOptimize));
         }
         // Register tools based on depth.
-        // Depth 0 (main orchestrator): only batch_read — no bash ops, only reads + flow tool.
+        // Depth 0 (main root state): only batch_read — no bash ops, only reads + flow tool.
         // Depth > 0 (child flows): batch (with bash), batch_bash_poll — they need bash ops.
         // Children use batch for reads (which includes read ops), so batch_read is NOT
         // registered for depth > 0 to avoid confusion and keep the tool set minimal.
@@ -200,13 +314,27 @@ export default function (pi) {
             }
         }
     });
+    // Clean up global mutable state on session shutdown
+    pi.on("session_shutdown", () => {
+        flowResultCache.clear();
+        _sessionCtx = undefined;
+        // bashTracker and its pending OS processes are discarded on restart.
+        // This is expected — child process state is not serializable.
+        if (bashTracker) {
+            try {
+                bashTracker.abortAll();
+            }
+            catch { /* best-effort */ }
+            bashTracker = undefined;
+        }
+    });
     // Re-apply active tools every turn to survive registry refreshes.
     // Skip for child flows — they get tools from --tools CLI arg.
     pi.on("turn_start", () => {
         if (currentDepth > 0 || !resolved)
             return;
         pi.setActiveTools(computeActiveTools(resolved.toolOptimize));
-        resetStrategicHintTracker();
+        resetDirectiveTracker();
     });
     // Inject available flows into the system prompt.
     // Skip entirely for child flows (depth > 0) — they get their instructions
@@ -214,7 +342,7 @@ export default function (pi) {
     pi.on("before_agent_start", async (event) => {
         if (currentDepth > 0 || !resolved)
             return undefined;
-        const augmented = buildBeforeAgentStartPrompt(event, resolved.toolOptimize, canDelegate, resolved.discoveredFlows, depthConfig);
+        const augmented = buildBeforeAgentStartPrompt(event, resolved.toolOptimize, canTransition, resolved.discoveredFlows, depthConfig);
         if (augmented === undefined)
             return undefined;
         return { systemPrompt: augmented };
@@ -229,7 +357,10 @@ export default function (pi) {
         if (currentDepth > 0)
             return undefined;
         // Always strip old steering hint messages to prevent accumulation
-        const { messages, changed: messagesChanged } = stripSteeringHintsFromMessages(event.messages);
+        const { messages: steeringStrippedMessages, changed: steeringChanged } = stripSteeringHintsFromMessages(event.messages);
+        // Also strip directive hints (adaptive hints appended to tool results)
+        const { messages, changed: directiveChanged } = stripDirectivesFromMessages(steeringStrippedMessages);
+        const messagesChanged = steeringChanged || directiveChanged;
         // Find latest user message
         const userIndices = messages
             .map((m, i) => (m.role === "user" ? i : -1))
@@ -287,10 +418,16 @@ export default function (pi) {
     // Register the ask_user tool
     pi.registerTool(createAskUserTool());
     // Register the flow tool
-    if (canDelegate) {
+    if (canTransition) {
         pi.registerTool({
             name: "flow",
             label: "Flow",
+            promptSnippet: "Transition to specialized agent flows running in isolated forked processes",
+            promptGuidelines: [
+                "Use `flow` when the task requires skills beyond your current context (scout, debug, build, craft, audit, ideas).",
+                "Combine multiple related tasks into a single `flow` call with an array of flow items.",
+                "Always provide a concrete intent, aim, and optional acceptance criteria.",
+            ],
             description: [
                 "If you cannot answer from your current context, you are forbidden from guessing.",
                 "You MUST enter to the following flow states, with tool call method.",
@@ -304,11 +441,7 @@ export default function (pi) {
             parameters: FlowParams,
             async execute(toolCallId, params, signal, onUpdate, ctx) {
                 if (!resolved) {
-                    return {
-                        content: [{ type: "text", text: "Error: session not initialized" }],
-                        details: makeFlowDetailsFactory(null)([]),
-                        isError: true,
-                    };
+                    throw new Error("Error: session not initialized");
                 }
                 const discovery = discoverFlows(ctx.cwd, "all");
                 const { flows } = discovery;
@@ -317,7 +450,7 @@ export default function (pi) {
                 // artifacts before passing it to child flows.
                 // Uses the persistent module-level cache so historical flow results
                 // are properly compressed (not passed through verbatim).
-                const { result: forkSessionSnapshotJsonl } = sanitizeForkSnapshot(buildForkSessionSnapshotJsonl(ctx.sessionManager), flowResultCache, {
+                const { result: forkSessionSnapshotJsonl, stats: forkSessionSnapshotStats } = sanitizeForkSnapshot(buildForkSessionSnapshotJsonl(ctx.sessionManager), flowResultCache, {
                     forkedFrom: ctx.sessionManager.getSessionId(),
                     forkedAt: new Date().toISOString(),
                     depth: currentDepth + 1,
@@ -335,7 +468,14 @@ export default function (pi) {
                     const inheritedValue = inheritedCliArgs.tieredModels?.[tier];
                     return typeof inheritedValue === "string" && inheritedValue.trim() ? inheritedValue.trim() : undefined;
                 };
-                const activeGoal = getGoalForSession(ctx.cwd, sessionRegistry.getSessionId(ctx.cwd));
+                let activeGoal = getGoalForSession(ctx.cwd, sessionRegistry.getSessionId(ctx.cwd));
+                if (!activeGoal) {
+                    const anyGoal = getGoal(ctx.cwd);
+                    if (anyGoal && anyGoal.status === "active") {
+                        logWarn(`[pi-agent-flow] Session mismatch for goal: expected ${sessionRegistry.getSessionId(ctx.cwd)}, got ${anyGoal.sessionId ?? "none"}. Using goal anyway.`);
+                        activeGoal = anyGoal;
+                    }
+                }
                 const goalContext = activeGoal ? {
                     objective: activeGoal.objective,
                     acceptance: activeGoal.acceptance,
@@ -361,6 +501,7 @@ export default function (pi) {
                     tierOverrideResolver: getTierOverride,
                     fallbackModel: inheritedCliArgs.fallbackModel,
                     forkSessionSnapshotJsonl,
+                    forkSessionSnapshotStats,
                     flowResultCache,
                     projectFlowsDir: discovery.projectFlowsDir,
                     sessionManager: ctx.sessionManager,
@@ -380,13 +521,29 @@ export default function (pi) {
                         }
                     },
                 }, params.flow.map((f) => ({ type: f.type, intent: f.intent, aim: f.aim, acceptance: f.acceptance, cwd: f.cwd, sessionMode: f.sessionMode })), toolCallId);
+                if (result.failed) {
+                    const text = result.content?.[0]?.text ?? "Flow execution failed";
+                    throw new Error(text);
+                }
                 const flowToolResult = {
                     content: result.content,
                     details: result.details,
-                    isError: result.isError,
+                    failed: result.failed,
                     _toolCallId: toolCallId,
                 };
-                appendStrategicHintOnce(flowToolResult);
+                // Build adaptive directive context from flow results
+                const hintContext = { hasNotDone: false, statusVague: false };
+                if (result.details?.results && Array.isArray(result.details.results)) {
+                    for (const r of result.details.results) {
+                        if (r.structuredOutput?.notDone?.length) {
+                            hintContext.hasNotDone = true;
+                        }
+                        if (!r.structuredOutput || !["complete", "partial", "blocked"].includes(r.structuredOutput.status)) {
+                            hintContext.statusVague = true;
+                        }
+                    }
+                }
+                appendDirectiveOnce(flowToolResult, hintContext);
                 return flowToolResult;
             },
             renderCall: (args, theme) => renderFlowCall(args, theme),
@@ -427,11 +584,11 @@ export default function (pi) {
     }
     // Register cleanup on process exit (once).
     // We use prependListener on SIGINT/SIGTERM to propagate to child processes
-    // before the host's own signal handler runs. This avoids orphaned sub-agents.
+    // before the host's own signal handler runs. This avoids orphaned flow states.
     // The host handler still runs afterward and handles terminal cleanup.
     if (!globalThis.__pi_agent_flow_shutdown_registered) {
         globalThis.__pi_agent_flow_shutdown_registered = true;
-        // Propagate signals to child process groups so sub-agents don't become orphans.
+        // Propagate signals to child process groups so flow states don't become orphans.
         // We use prependListener so our handler runs first, before the host's cleanup.
         const shutdown = () => {
             // First, abort any pending bash operations tracked by the batch tool.