pi-agent-flow 1.2.5 → 1.2.7

package/README.md

@@ -79,7 +79,7 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 
 | Flow | Purpose | Tools | Tier |
 |------|---------|-------|------|
-| `[scout]` | Discover files, trace code paths, map architecture | `batch_read`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[scout]` | Discover files, trace code paths, map architecture | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
 | `[debug]` | Investigate logs, errors, stack traces, root causes | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
 | `[build]` | Implement features, fix bugs, write tests, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[craft]` | Plan structure, break down requirements, design solutions | `batch`, `bash`, `find`, `grep`, `ls` | `full` |

package/agents/scout.md

@@ -1,7 +1,7 @@
 ---
 name: scout
 description: Discover files, trace code paths, map architecture
-tools: batch_read, bash, find, grep, ls
+tools: batch, bash, find, grep, ls
 maxDepth: 0
 ---
 
@@ -12,8 +12,8 @@ During this scout flow — your mission is to discover relevant context. Move fa
 ## Workflow
 
 1. Survey — use `ls`, `find`, and `grep` to locate relevant files and symbols before reading whole files.
-2. Inspect — use `batch_read` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
-3. If `batch_read` returns a context map for a large code/infra file, do not retry the full-file read; use the reported line ranges for targeted follow-up reads.
+2. Inspect — use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+3. If `batch` returns a context map for a large code/infra file, do not retry the full-file read; use the reported line ranges for targeted follow-up reads.
 4. Trace — follow code paths, dependencies, configuration, and tests that explain the requested area.
 5. Report — cite concrete evidence and stop when the requested context is mapped.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/agents.ts

@@ -136,7 +136,22 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 
 	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim().toLowerCase() : "";
 	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
-	if (!name || !description) return null;
+	if (!name || !description) {
+		if (!name) console.warn(`[pi-agent-flow] Skipping flow file "${filePath}": missing or empty 'name' field.`);
+		if (!description) console.warn(`[pi-agent-flow] Skipping flow file "${filePath}": missing or empty 'description' field.`);
+		return null;
+	}
+
+	// Warn about unknown frontmatter keys
+	const knownKeys = new Set([
+		"name", "description", "tools", "model", "thinking",
+		"maxDepth", "inheritContext", "tier",
+	]);
+	for (const key of Object.keys(frontmatter)) {
+		if (!knownKeys.has(key)) {
+			console.warn(`[pi-agent-flow] Unknown frontmatter key "${key}" in "${filePath}". This field will be ignored.`);
+		}
+	}
 
 	let tools: string[] | undefined;
 	if (typeof frontmatter.tools === "string") {

package/src/executor.ts

@@ -139,6 +139,24 @@ async function confirmProjectFlowsIfNeeded(
 	};
 }
 
+// ---------------------------------------------------------------------------
+// Cache limits
+// ---------------------------------------------------------------------------
+
+const FLOW_RESULT_CACHE_MAX_ENTRIES = 50;
+
+/** Evict oldest entries from the cache when it exceeds the cap. */
+function evictCacheOverflow(cache: Map<string, unknown>): void {
+	if (cache.size <= FLOW_RESULT_CACHE_MAX_ENTRIES) return;
+	const excess = cache.size - FLOW_RESULT_CACHE_MAX_ENTRIES;
+	const keys = cache.keys();
+	for (let i = 0; i < excess; i++) {
+		const next = keys.next();
+		if (next.done) break;
+		cache.delete(next.value);
+	}
+}
+
 function shouldFailover(result: SingleResult): boolean {
 	if (result.stopReason === "aborted") return false;
 	const text = `${result.errorMessage ?? ""}\n${result.stderr ?? ""}`.toLowerCase();
@@ -354,6 +372,7 @@ export async function executeFlows(
 		existing.push(compressed);
 		flowResultCache.set(toolCallId, existing);
 	}
+	evictCacheOverflow(flowResultCache);
 
 	// Build tool result
 	const successCount = results.filter((r) => isFlowSuccess(r)).length;
@@ -369,21 +388,21 @@ export async function executeFlows(
 		? "\n\n---\n\n💡 " + hookResult.advisors.join("\n💡 ")
 		: "";
 
-	// Auto-transition: collect qualifying transitions
+	// Auto-transition: collect qualifying transitions.
+	// No confidence threshold gating — non-deterministic agents should not
+	// have unstable numeric params controlling execution flow.
 	const queuedTransitions: Array<{ type: string; intent: string }> = [];
 	if (autoTransition && hookResult.autoTransitions.length > 0) {
 		for (const transition of hookResult.autoTransitions) {
-			if (transition.confidence >= 0.7) {
-				const normalizedType = transition.type.toLowerCase();
-				const flowExists = flows.some((f) => f.name === normalizedType);
-				const notAlreadyRequested = !requested.has(normalizedType);
-				const noCycles = !preventCycles || !ancestorFlowStack.includes(normalizedType);
-				if (flowExists && notAlreadyRequested && noCycles) {
-					queuedTransitions.push({
-						type: transition.type,
-						intent: transition.intent,
-					});
-				}
+			const normalizedType = transition.type.toLowerCase();
+			const flowExists = flows.some((f) => f.name === normalizedType);
+			const notAlreadyRequested = !requested.has(normalizedType);
+			const noCycles = !preventCycles || !ancestorFlowStack.includes(normalizedType);
+			if (flowExists && notAlreadyRequested && noCycles) {
+				queuedTransitions.push({
+					type: transition.type,
+					intent: transition.intent,
+				});
 			}
 		}
 	}

package/src/flow.ts

@@ -67,6 +67,12 @@ function mergeStreamingUsage(
  * work on Unix and Windows without going through a shell wrapper.
  */
 function resolveFlowSpawn(): { command: string; prefixArgs: string[] } {
+	// Support PI_FLOW_SPAWN_COMMAND env var override for exotic runtime
+	// environments (e.g. bundled with pkg/nexe where process.argv[1] is unreliable).
+	const envOverride = process.env["PI_FLOW_SPAWN_COMMAND"];
+	if (envOverride && envOverride.trim()) {
+		return { command: envOverride.trim(), prefixArgs: [] };
+	}
 	const isNode = /[\\/]node(?:\.exe)?$/i.test(process.execPath);
 	if (isNode && process.argv[1]) {
 		return { command: process.execPath, prefixArgs: [process.argv[1]] };

package/src/hooks.ts

@@ -28,10 +28,21 @@ export function registerHook(hook: PostFlowHook): void {
 	else hooks.push(hook);
 }
 
+/**
+ * Unregister a hook by name.
+ * Returns true if a hook was removed, false if no hook with that name existed.
+ */
+export function unregisterHook(name: string): boolean {
+	const idx = hooks.findIndex((h) => h.name === name);
+	if (idx < 0) return false;
+	hooks.splice(idx, 1);
+	return true;
+}
+
 export interface RunHooksResult {
 	/** Advisory messages sorted by priority. */
 	advisors: string[];
-	/** Auto-transitions collected from hooks, sorted by confidence descending. */
+	/** Auto-transitions collected from hooks. */
 	autoTransitions: AutoTransition[];
 }
 
@@ -49,6 +60,9 @@ export function runHooks(
 
 /**
  * Run all hooks and return both advisors and auto-transitions.
+ *
+ * Each hook action is wrapped in try/catch so one bad hook cannot crash
+ * the pipeline. Failures are reported as advisory warnings.
  */
 export function runHooksDetailed(
 	params: Array<{ type: string; intent: string }>,
@@ -67,17 +81,24 @@ export function runHooksDetailed(
 		if (matching.length === 0) continue;
 		if (onlyOnSuccess && !matching.every((r) => isFlowSuccess(r))) continue;
 
-		const result = hook.action({ results: matching, params });
-		if (result) {
-			messages.push({ priority: result.priority ?? 0, content: result.content });
-			if (result.autoTransition) {
-				transitions.push(result.autoTransition);
+		try {
+			const result = hook.action({ results: matching, params });
+			if (result) {
+				messages.push({ priority: result.priority ?? 0, content: result.content });
+				if (result.autoTransition) {
+					transitions.push(result.autoTransition);
+				}
 			}
+		} catch (err) {
+			const errorMessage = err instanceof Error ? err.message : String(err);
+			messages.push({
+				priority: 999,
+				content: `Hook "${hook.name}" failed: ${errorMessage}`,
+			});
 		}
 	}
 
 	messages.sort((a, b) => a.priority - b.priority);
-	transitions.sort((a, b) => b.confidence - a.confidence);
 	return {
 		advisors: messages.map((m) => m.content),
 		autoTransitions: transitions,
@@ -99,7 +120,7 @@ export function clearHooks(): void {
 }
 
 // ---------------------------------------------------------------------------
-// Built-in hooks
+// Built-in hooks — success transitions
 // ---------------------------------------------------------------------------
 
 /** Suggest audit flow after a successful build flow. */
@@ -156,10 +177,6 @@ registerHook({
 	},
 });
 
-// ---------------------------------------------------------------------------
-// Extended transition hooks
-// ---------------------------------------------------------------------------
-
 /** Suggest build or debug flow after a successful scout flow. */
 registerHook({
 	name: "pi-agent-flow/scout-to-build",
@@ -231,3 +248,47 @@ registerHook({
 		};
 	},
 });
+
+// ---------------------------------------------------------------------------
+// Built-in hooks — failure transitions
+// ---------------------------------------------------------------------------
+
+/** Suggest debug flow after a failed build flow. */
+registerHook({
+	name: "pi-agent-flow/build-to-debug-on-failure",
+	trigger: { flowTypes: ["build"], onlyOnSuccess: false },
+	action: (ctx) => {
+		const allSucceeded = ctx.results.every((r) => isFlowSuccess(r));
+		if (allSucceeded) return null;
+		const debugWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "debug",
+		);
+		if (debugWasRequested) return null;
+
+		return {
+			content:
+				"Build failed. Consider running a [debug] flow to investigate the root cause.",
+			priority: 10,
+		};
+	},
+});
+
+/** Suggest build flow after a failed audit flow (found issues). */
+registerHook({
+	name: "pi-agent-flow/audit-to-build-on-failure",
+	trigger: { flowTypes: ["audit"], onlyOnSuccess: false },
+	action: (ctx) => {
+		const allSucceeded = ctx.results.every((r) => isFlowSuccess(r));
+		if (allSucceeded) return null;
+		const buildWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "build",
+		);
+		if (buildWasRequested) return null;
+
+		return {
+			content:
+				"Audit found issues. Consider running a [build] flow to fix them.",
+			priority: 10,
+		};
+	},
+});

package/src/index.ts

@@ -5,7 +5,6 @@
  * Each flow receives a forked snapshot of the current session context.
  */
 
-import { randomUUID } from "node:crypto";
 import * as os from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
@@ -20,7 +19,7 @@ import {
 import { getInheritedCliArgs } from "./cli-args.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
-import { runHooks, runHooksDetailed, getRegisteredHooks, registerHook } from "./hooks.js";
+import { runHooks, runHooksDetailed, getRegisteredHooks, registerHook, unregisterHook } from "./hooks.js";
 import { mapFlowConcurrent, runFlow } from "./flow.js";
 import { executeFlows } from "./executor.js";
 import {
@@ -31,6 +30,7 @@ import {
 	type FileEntry,
 	type CommandEntry,
 	type AutoTransition,
+	type PiAgentFlowAPI,
 	emptyFlowUsage,
 	isFlowError,
 	isFlowSuccess,
@@ -43,6 +43,17 @@ import {
 	looksLikeUrlPrompt,
 	looksLikeWebSearchPrompt,
 } from "./web-tool.js";
+import {
+	SLIDING_PROMPT,
+	SLIDING_PROMPT_OPEN_TAG,
+	stripSlidingPromptText,
+	stripSlidingPromptFromContent,
+	contentContainsSlidingTag,
+	isJsonEqual,
+	stripSlidingPromptsFromMessages,
+	makeSlidingPromptMessage,
+} from "./sliding-prompt.js";
+import { DEFAULT_TRANSITIONS, buildTransitionHooks } from "./transitions.js";
 import { createTimedBashToolDefinition } from "./timed-bash.js";
 
 // ---------------------------------------------------------------------------
@@ -346,110 +357,7 @@ async function confirmProjectFlowsIfNeeded(
 // before the latest user message by the context handler.
 // ---------------------------------------------------------------------------
 
-const SLIDING_PROMPT_UUID = randomUUID();
-const SLIDING_PROMPT_OPEN_TAG = `<pi-flow-sliding-system id="${SLIDING_PROMPT_UUID}">`;
-const SLIDING_PROMPT_CLOSE_TAG = `</pi-flow-sliding-system id="${SLIDING_PROMPT_UUID}">`;
-
-const SLIDING_PROMPT =
-	`${SLIDING_PROMPT_OPEN_TAG}\n` +
-	`You are operating with pi-agent-flow routing.\n` +
-	`If the answer is already in context, answer directly; otherwise delegate to the appropriate flow.\n` +
-	`For git, bash, CLI, or terminal tasks, delegate to [build].\n` +
-	`${SLIDING_PROMPT_CLOSE_TAG}`;
-
-const SLIDING_PROMPT_RE = new RegExp(
-	SLIDING_PROMPT_OPEN_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +
-	"[\\s\\S]*?" +
-	SLIDING_PROMPT_CLOSE_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
-	"g",
-);
-
-/** Legacy regex to strip old bare sliding system prompt tags (no id attribute). */
-const LEGACY_SLIDING_PROMPT_RE = /<pi-flow-sliding-system(?:\s[^>]*)?>[\s\S]*?<\/pi-flow-sliding-system(?:\s[^>]*)?>/g;
-
-/** Strip any old sliding system prompt tags from a string. */
-function stripSlidingPromptText(text: string): string {
-	return text.replace(SLIDING_PROMPT_RE, "").replace(LEGACY_SLIDING_PROMPT_RE, "");
-}
-
-/** Strip sliding prompt tags from content (string or text-part array). */
-function stripSlidingPromptFromContent(
-	content: string | { type: string; text?: string }[],
-): string | { type: string; text?: string }[] {
-	if (typeof content === "string") {
-		return stripSlidingPromptText(content);
-	}
-	return content.map((c) => {
-		if (c.type === "text" && typeof c.text === "string") {
-			return { ...c, text: stripSlidingPromptText(c.text) };
-		}
-		return c;
-	});
-}
-
-/** Check whether content (string or text-part array) contains the sliding tag. */
-/** Input-message content types (string or multipart text-part array). */
-type MessageContent = string | Array<{ type: string; text?: string }>;
-
-/** Type guard: is this a text-part with a string .text? */
-function isTextPart(part: unknown): part is { type: "text"; text: string } {
-	return (
-		part != null &&
-		typeof part === "object" &&
-		"type" in part &&
-		part.type === "text" &&
-		"text" in part &&
-		typeof (part as { text?: unknown }).text === "string"
-	);
-}
-
-/** Check whether content (string or text-part array) contains the sliding tag. */
-function contentContainsSlidingTag(content: MessageContent): boolean {
-	const hasCurrent = (text: string) => text.includes(SLIDING_PROMPT_OPEN_TAG);
-	const hasLegacy = (text: string) => text.includes("<pi-flow-sliding-system>");
-	const check = (text: string) => hasCurrent(text) || hasLegacy(text);
-	if (typeof content === "string") {
-		return check(content);
-	}
-	if (Array.isArray(content)) {
-		return content.some((part) => isTextPart(part) && check(part.text));
-	}
-	return false;
-}
-
-/** Remove any existing sliding-system-prompt system messages and strip tags from user messages.
- *  Returns the sanitized messages and a flag indicating whether anything changed.
- */
-function stripSlidingPromptsFromMessages(messages: any[]): { messages: any[]; changed: boolean } {
-	let changed = false;
-	const result = messages
-		.filter((msg) => {
-			// Remove dedicated sliding system prompt messages
-			if (msg.role === "system" && contentContainsSlidingTag(msg.content)) {
-				changed = true;
-				return false;
-			}
-			return true;
-		})
-		.map((msg) => {
-			// Also strip stray tags embedded in user/assistant messages
-			if (!("content" in msg)) return msg;
-			const stripped = stripSlidingPromptFromContent(msg.content);
-			if (isJsonEqual(stripped, msg.content)) return msg;
-			changed = true;
-			return { ...msg, content: stripped };
-		});
-	return { messages: result, changed };
-}
-
-/** Build a system message containing the sliding prompt. */
-function makeSlidingPromptMessage(referenceMessage?: any): any {
-	return {
-		role: "system",
-		content: SLIDING_PROMPT,
-		timestamp: referenceMessage?.timestamp,
-	};
-}
+// SLIDING_PROMPT, SLIDING_PROMPT_OPEN_TAG imported from ./sliding-prompt.js
 
 const REASONING_PART_TYPES = new Set([
 	"thinking",
@@ -498,22 +406,6 @@ function stripReasoningFromAssistantMessage(message: any): {
 	return { message: next, changed };
 }
 
-/** Deep-equality check that handles unordered object keys (unlike JSON.stringify). */
-function isJsonEqual(a: unknown, b: unknown): boolean {
-	if (Object.is(a, b)) return true;
-	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
-	if (Array.isArray(a) !== Array.isArray(b)) return false;
-
-	const keysA = Object.keys(a as Record<string, unknown>);
-	const keysB = Object.keys(b as Record<string, unknown>);
-	if (keysA.length !== keysB.length) return false;
-
-	for (const key of keysA) {
-		if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
-		if (!isJsonEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) return false;
-	}
-	return true;
-}
 // ---------------------------------------------------------------------------
 // Flow result compression
 // ---------------------------------------------------------------------------
@@ -800,6 +692,11 @@ export default function (pi: ExtensionAPI) {
 		discoveredFlows = discovery.flows;
 		loadedFlowModelConfigs = loadFlowModelConfigs(ctx.cwd);
 
+		// Register declarative transition hooks from the transition matrix
+		for (const hook of buildTransitionHooks(DEFAULT_TRANSITIONS)) {
+			registerHook(hook);
+		}
+
 		// Resolve toolOptimize: CLI flag > env var > settings.json > default
 		const cliFlag = pi.getFlag("tool-optimize");
 		if (typeof cliFlag === "boolean") {
@@ -1072,7 +969,7 @@ flow [type] accomplished
 						sessionManager: ctx.sessionManager,
 						hasUI: ctx.hasUI,
 						uiConfirm: (title, body) => ctx.ui.confirm(title, body),
-						onFlowMetrics: (metrics) => pi.emit("pi-agent-flow:complete", metrics),
+						onFlowMetrics: (metrics) => { if (typeof pi.emit === "function") pi.emit("pi-agent-flow:complete", metrics); },
 						confirmProjectFlows: params.confirmProjectFlows,
 					},
 					params.flow.map((f: any) => ({ type: f.type, intent: f.intent, aim: f.aim, cwd: f.cwd })),
@@ -1097,14 +994,31 @@ flow [type] accomplished
 	// -------------------------------------------------------------------------
 
 	// Emit a ready event with the API surface so external plugins can extend.
+	// Emit a typed plugin API surface
+	const pluginApi: PiAgentFlowAPI = {
+		registerHook,
+		unregisterHook,
+		getRegisteredHooks,
+		discoverFlows: (cwd: string) => discoverFlows(cwd, "all"),
+		getFlowTier: (name: string) => getFlowTier(name),
+		getSettings: () => ({ toolOptimize, structuredOutput, maxConcurrency, autoTransition }),
+	};
+
 	if (typeof pi.emit === "function") {
-		pi.emit("pi-agent-flow:ready", {
-			registerHook,
-			getRegisteredHooks,
-			discoverFlows: (cwd: string) => discoverFlows(cwd, "all"),
-			getFlowTier: (name: string) => getFlowTier(name),
-			getSettings: () => ({ toolOptimize, structuredOutput, maxConcurrency, autoTransition }),
-		});
+		pi.emit("pi-agent-flow:ready", pluginApi);
+	}
+
+	// Register cleanup on process exit (once)
+	if (!(globalThis as any).__pi_agent_flow_shutdown_registered) {
+		(globalThis as any).__pi_agent_flow_shutdown_registered = true;
+		const emitShutdown = () => {
+			if (typeof pi.emit === "function") {
+				pi.emit("pi-agent-flow:shutdown", { reason: "process-exit" });
+			}
+		};
+		process.on("exit", emitShutdown);
+		process.on("SIGINT", () => { emitShutdown(); process.exit(130); });
+		process.on("SIGTERM", () => { emitShutdown(); process.exit(143); });
 	}
 
 }

package/src/sliding-prompt.ts

@@ -0,0 +1,143 @@
+/**
+ * Sliding system prompt utilities.
+ *
+ * Manages the sliding prompt tag that is injected before the latest user
+ * message each turn. Provides helpers for stripping, detecting, and building
+ * the prompt so they can be tested independently.
+ */
+
+import { randomUUID } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Tag constants
+// ---------------------------------------------------------------------------
+
+const SLIDING_PROMPT_UUID = randomUUID();
+
+export const SLIDING_PROMPT_OPEN_TAG = `<pi-flow-sliding-system id="${SLIDING_PROMPT_UUID}">`;
+export const SLIDING_PROMPT_CLOSE_TAG = `</pi-flow-sliding-system id="${SLIDING_PROMPT_UUID}">`;
+
+export const SLIDING_PROMPT =
+	`${SLIDING_PROMPT_OPEN_TAG}\n` +
+	`You are operating with pi-agent-flow routing.\n` +
+	`If the answer is already in context, answer directly; otherwise delegate to the appropriate flow.\n` +
+	`For git, bash, CLI, or terminal tasks, delegate to [build].\n` +
+	`${SLIDING_PROMPT_CLOSE_TAG}`;
+
+const SLIDING_PROMPT_RE = new RegExp(
+	SLIDING_PROMPT_OPEN_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +
+	"[\\s\\S]*?" +
+	SLIDING_PROMPT_CLOSE_TAG.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+	"g",
+);
+
+/** Legacy regex to strip old bare sliding system prompt tags (no id attribute). */
+const LEGACY_SLIDING_PROMPT_RE = /<pi-flow-sliding-system(?:\s[^>]*)?>[\s\S]*?<\/pi-flow-sliding-system(?:\s[^>]*)?>/g;
+
+// ---------------------------------------------------------------------------
+// Content types
+// ---------------------------------------------------------------------------
+
+/** Input-message content types (string or multipart text-part array). */
+type MessageContent = string | Array<{ type: string; text?: string }>;
+
+/** Type guard: is this a text-part with a string .text? */
+function isTextPart(part: unknown): part is { type: "text"; text: string } {
+	return (
+		part != null &&
+		typeof part === "object" &&
+		"type" in part &&
+		part.type === "text" &&
+		"text" in part &&
+		typeof (part as { text?: unknown }).text === "string"
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+
+/** Strip any old sliding system prompt tags from a string. */
+export function stripSlidingPromptText(text: string): string {
+	return text.replace(SLIDING_PROMPT_RE, "").replace(LEGACY_SLIDING_PROMPT_RE, "");
+}
+
+/** Strip sliding prompt tags from content (string or text-part array). */
+export function stripSlidingPromptFromContent(
+	content: string | { type: string; text?: string }[],
+): string | { type: string; text?: string }[] {
+	if (typeof content === "string") {
+		return stripSlidingPromptText(content);
+	}
+	return content.map((c) => {
+		if (c.type === "text" && typeof c.text === "string") {
+			return { ...c, text: stripSlidingPromptText(c.text) };
+		}
+		return c;
+	});
+}
+
+/** Check whether content (string or text-part array) contains the sliding tag. */
+export function contentContainsSlidingTag(content: MessageContent): boolean {
+	const hasCurrent = (text: string) => text.includes(SLIDING_PROMPT_OPEN_TAG);
+	const hasLegacy = (text: string) => text.includes("<pi-flow-sliding-system>");
+	const check = (text: string) => hasCurrent(text) || hasLegacy(text);
+	if (typeof content === "string") {
+		return check(content);
+	}
+	if (Array.isArray(content)) {
+		return content.some((part) => isTextPart(part) && check(part.text));
+	}
+	return false;
+}
+
+/** Deep-equality check that handles unordered object keys (unlike JSON.stringify). */
+export function isJsonEqual(a: unknown, b: unknown): boolean {
+	if (Object.is(a, b)) return true;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+	const keysA = Object.keys(a as Record<string, unknown>);
+	const keysB = Object.keys(b as Record<string, unknown>);
+	if (keysA.length !== keysB.length) return false;
+
+	for (const key of keysA) {
+		if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+		if (!isJsonEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) return false;
+	}
+	return true;
+}
+
+/** Remove any existing sliding-system-prompt system messages and strip tags from user messages.
+ *  Returns the sanitized messages and a flag indicating whether anything changed.
+ */
+export function stripSlidingPromptsFromMessages(messages: any[]): { messages: any[]; changed: boolean } {
+	let changed = false;
+	const result = messages
+		.filter((msg) => {
+			// Remove dedicated sliding system prompt messages
+			if (msg.role === "system" && contentContainsSlidingTag(msg.content)) {
+				changed = true;
+				return false;
+			}
+			return true;
+		})
+		.map((msg) => {
+			// Also strip stray tags embedded in user/assistant messages
+			if (!("content" in msg)) return msg;
+			const stripped = stripSlidingPromptFromContent(msg.content);
+			if (isJsonEqual(stripped, msg.content)) return msg;
+			changed = true;
+			return { ...msg, content: stripped };
+		});
+	return { messages: result, changed };
+}
+
+/** Build a system message containing the sliding prompt. */
+export function makeSlidingPromptMessage(referenceMessage?: any): any {
+	return {
+		role: "system",
+		content: SLIDING_PROMPT,
+		timestamp: referenceMessage?.timestamp,
+	};
+}

package/src/transitions.ts

@@ -0,0 +1,86 @@
+/**
+ * Declarative transition matrix for post-flow routing.
+ *
+ * Instead of imperative hooks for common flow paths, this module defines a
+ * data-driven transition map. Each entry describes a recommended follow-up
+ * flow given a source flow's outcome. The matrix is user-overridable via
+ * settings.json.
+ *
+ * NOTE: There is no confidence threshold gating. Non-deterministic agents
+ * should not have unstable numeric params controlling execution flow.
+ * All matching transitions are recommended; the caller decides whether to
+ * auto-queue them.
+ */
+
+import { type PostFlowHook, type AutoTransition, isFlowSuccess } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Transition descriptor
+// ---------------------------------------------------------------------------
+
+export interface FlowTransition {
+	/** Source flow name (case-insensitive). */
+	from: string;
+	/** Target flow name (case-insensitive). */
+	to: string;
+	/** Condition for this transition. */
+	on: "success" | "failure" | "always";
+	/** Advisory message shown to the user. */
+	advice: string;
+}
+
+// ---------------------------------------------------------------------------
+// Default transition matrix
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_TRANSITIONS: FlowTransition[] = [
+	{ from: "scout", to: "build", on: "success", advice: "Context mapped. Consider running a [build] flow to implement changes, or [debug] if investigating an issue." },
+	{ from: "scout", to: "debug", on: "success", advice: "Context mapped. Consider running a [debug] flow if investigating an issue." },
+	{ from: "debug", to: "build", on: "success", advice: "The root cause has been identified. Consider running a [build] flow to implement the fix." },
+	{ from: "debug", to: "audit", on: "success", advice: "Root cause identified. Consider running an [audit] flow to verify the fix area for related issues." },
+	{ from: "build", to: "audit", on: "success", advice: "Consider running a [audit] flow to audit the changes for security, correctness, and code quality." },
+	{ from: "build", to: "debug", on: "failure", advice: "Build failed. Consider running a [debug] flow to investigate the root cause." },
+	{ from: "audit", to: "scout", on: "success", advice: "Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase." },
+	{ from: "audit", to: "build", on: "failure", advice: "Audit found issues. Consider running a [build] flow to fix them." },
+	{ from: "craft", to: "build", on: "success", advice: "Plan ready. Consider running a [build] flow to implement the design." },
+	{ from: "ideas", to: "craft", on: "success", advice: "Ideas explored. Consider running a [craft] flow to design the approach, or [build] to implement directly." },
+];
+
+// ---------------------------------------------------------------------------
+// Hook generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert the transition matrix into PostFlowHook instances.
+ *
+ * Each transition becomes a hook that checks:
+ *   1. The source flow type matches
+ *   2. The target flow was not already requested
+ *   3. The outcome matches the `on` condition
+ */
+export function buildTransitionHooks(transitions: FlowTransition[]): PostFlowHook[] {
+	return transitions.map((t) => ({
+		name: `pi-agent-flow/${t.from}-to-${t.to}-${t.on}`,
+		trigger: {
+			flowTypes: [t.from],
+			onlyOnSuccess: t.on === "success",
+		},
+		action: (ctx) => {
+			// Respect the on condition: success hooks only fire when all results
+			// succeeded; failure hooks only fire when at least one result failed.
+			const allSucceeded = ctx.results.every((r) => isFlowSuccess(r));
+			if (t.on === "success" && !allSucceeded) return null;
+			if (t.on === "failure" && allSucceeded) return null;
+
+			const alreadyRequested = ctx.params.some(
+				(p) => p.type.toLowerCase() === t.to,
+			);
+			if (alreadyRequested) return null;
+
+			return {
+				content: t.advice,
+				priority: 10,
+			};
+		},
+	}));
+}

package/src/types.ts

@@ -365,6 +365,24 @@ export interface AutoTransition {
 	type: string;
 	/** Intent for the follow-up flow. */
 	intent: string;
-	/** Confidence score (0-1). Higher means more certain. */
-	confidence: number;
 }
+// ---------------------------------------------------------------------------
+// Plugin API types
+// ---------------------------------------------------------------------------
+
+/** Public API surface exposed via the pi-agent-flow:ready event. */
+export interface PiAgentFlowAPI {
+	/** Register or replace a post-flow hook. */
+	registerHook: (hook: PostFlowHook) => void;
+	/** Unregister a hook by name. Returns true if removed. */
+	unregisterHook: (name: string) => boolean;
+	/** Get a snapshot of all registered hooks. */
+	getRegisteredHooks: () => PostFlowHook[];
+	/** Discover all available flows for a given working directory. */
+	discoverFlows: (cwd: string) => { flows: Array<{ name: string; description: string; source: string }>; projectFlowsDir: string | null };
+	/** Determine the model tier for a given flow name. */
+	getFlowTier: (name: string) => string;
+	/** Get current flow settings. */
+	getSettings: () => { toolOptimize: boolean; structuredOutput: boolean; maxConcurrency: number; autoTransition: boolean };
+}
+