pi-agent-flow 1.0.8 → 1.1.0

package/config.ts

@@ -15,6 +15,10 @@ export interface FlowModelConfig {
 	full?: string;
 }
 
+export interface FlowSettings {
+	toolOptimize?: boolean;
+}
+
 function readSettingsJson(filePath: string): Record<string, unknown> | null {
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
@@ -40,6 +44,20 @@ function extractFlowModels(settings: Record<string, unknown> | null): FlowModelC
 	return result;
 }
 
+function extractFlowSettings(settings: Record<string, unknown> | null): FlowSettings {
+	if (!settings) return {};
+	const flowSettings = settings.flowSettings;
+	if (!flowSettings || typeof flowSettings !== "object" || Array.isArray(flowSettings)) {
+		return {};
+	}
+	const obj = flowSettings as Record<string, unknown>;
+	const result: FlowSettings = {};
+	if (typeof obj.toolOptimize === "boolean") {
+		result.toolOptimize = obj.toolOptimize;
+	}
+	return result;
+}
+
 function getGlobalSettingsPath(): string {
 	const agentDir = process.env["PI_CODING_AGENT_DIR"]?.trim() || path.join(os.homedir(), ".pi", "agent");
 	return path.join(agentDir, "settings.json");
@@ -65,3 +83,20 @@ export function loadFlowModels(cwd: string): FlowModelConfig {
 		...projectModels,
 	};
 }
+
+/**
+ * Load flowSettings from global and project settings.json.
+ * Project overrides global (shallow merge per key).
+ */
+export function loadFlowSettings(cwd: string): FlowSettings {
+	const globalSettings = readSettingsJson(getGlobalSettingsPath());
+	const globalFlowSettings = extractFlowSettings(globalSettings);
+
+	const projectSettings = readSettingsJson(getProjectSettingsPath(cwd));
+	const projectFlowSettings = extractFlowSettings(projectSettings);
+
+	return {
+		...globalFlowSettings,
+		...projectFlowSettings,
+	};
+}

package/flow.ts

@@ -23,11 +23,14 @@ import {
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
-const AGENT_END_GRACE_MS = 250;
+const AGENT_END_GRACE_MS = 2000;
+const DEFAULT_FLOW_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
 const FLOW_STACK_ENV = "PI_FLOW_STACK";
 const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
+const FLOW_TIMEOUT_ENV = "PI_FLOW_TIMEOUT_MS";
+export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
 const PI_OFFLINE_ENV = "PI_OFFLINE";
 
 type FlowUpdateCallback = (partial: AgentToolResult<FlowDetails>) => void;
@@ -49,7 +52,8 @@ function mergeStreamingUsage(
 		...actual,
 		...(estimatedOutputTokens > 0 ? { output: Math.max(actual.output, estimatedOutputTokens) } : {}),
 		...(ctxEstimate > 0 ? { contextTokens: Math.max(actual.contextTokens, ctxEstimate) } : {}),
-		...(smoothedTps > 0 ? { smoothedTps: Math.max(actual.smoothedTps ?? 0, smoothedTps) } : {}),
+		// Preserve the peak smoothedTPS seen during the stream rather than the live EMA value.
+		...(smoothedTps > 0 ? { smoothedTps: Math.max(actual.smoothedTps || 0, smoothedTps) } : {}),
 	};
 }
 
@@ -99,6 +103,27 @@ function cleanupFlowTempDir(dir: string | null): void {
 
 const inheritedCliArgs = parseFlowCliArgs(process.argv);
 
+/**
+ * Transform a flow's tool list when toolOptimize is enabled.
+ * Replaces separate read/write/edit tools with the unified batch tool.
+ */
+export function getOptimizedTools(
+	flowTools: string[] | undefined,
+	toolOptimize: boolean,
+): string[] | undefined {
+	if (!toolOptimize || !flowTools) return flowTools;
+	const hasLegacyTools = flowTools.some(
+		(t) => t === "read" || t === "write" || t === "edit",
+	);
+	if (!hasLegacyTools) return flowTools;
+	const filtered = flowTools.filter(
+		(t) => t !== "read" && t !== "write" && t !== "edit" && t !== "batch",
+	);
+	return filtered.includes("batch")
+		? filtered
+		: [...filtered, "batch"];
+}
+
 function buildFlowArgs(
 	flow: FlowConfig,
 	intent: string,
@@ -106,6 +131,7 @@ function buildFlowArgs(
 	tieredModels?: { lite?: string; flash?: string; full?: string },
 	parentDepth: number = 0,
 	maxDepth: number = 0,
+	toolOptimize: boolean = false,
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -127,15 +153,22 @@ function buildFlowArgs(
 	const thinking = flow.thinking ?? inheritedCliArgs.fallbackThinking;
 	if (thinking) args.push("--thinking", thinking);
 
-	if (flow.tools && flow.tools.length > 0) {
-		args.push("--tools", flow.tools.join(","));
-	} else if (flow.tools === undefined) {
-		if (inheritedCliArgs.fallbackTools !== undefined) {
-			args.push("--tools", inheritedCliArgs.fallbackTools);
-		} else if (inheritedCliArgs.fallbackNoTools) {
-			args.push("--no-tools");
-		}
+	// Child flows get their configured tools from flow.tools, optimized by
+	// getOptimizedTools, with web explicitly filtered out.
+	// When flow.tools is undefined and toolOptimize=true, default to batch+bash+web
+	// (flow is unnecessary since the child is already inside a flow).
+	// When toolOptimize=false, include batch and web alongside legacy tools.
+	const defaultTools = toolOptimize
+		? ["batch", "bash", "web"]
+		: ["read", "write", "edit", "batch", "bash", "flow", "web"];
+	const optimizedTools = getOptimizedTools(flow.tools, toolOptimize) ?? defaultTools;
+	let harnessTools = optimizedTools.filter((t) => t !== "web");
+	// If the flow explicitly listed only "web" (or nothing after filtering),
+	// fall back to defaultTools so the child isn't orphaned with zero tools.
+	if (harnessTools.length === 0) {
+		harnessTools = defaultTools.filter((t) => t !== "web");
 	}
+	args.push("--tools", harnessTools.join(","));
 
 	// No --append-system-prompt: child inherits parent's system prompt for cache hits.
 	// Flow instructions go in the intent message instead.
@@ -143,7 +176,7 @@ function buildFlowArgs(
 	const currentDepth = Math.max(0, Math.floor(parentDepth)) + 1;
 	const effectiveMaxDepth = Math.max(0, Math.floor(maxDepth));
 	const canDelegate = currentDepth < effectiveMaxDepth;
-	const availableTools = flow.tools?.join(", ") ?? "all";
+	const availableTools = harnessTools.join(", ");
 
 	// Phase 1: Context seal — sharp boundary declaring history sealed
 	const contextSeal =
@@ -196,6 +229,8 @@ export interface RunFlowOptions {
 	flowName: string;
 	/** Intent description. */
 	intent: string;
+	/** Short headline for display. */
+	aim: string;
 	/** Optional override working directory. */
 	taskCwd?: string;
 	/** Serialized parent session snapshot for fork mode. Null when the flow starts with a clean slate. */
@@ -208,6 +243,8 @@ export interface RunFlowOptions {
 	maxDepth: number;
 	/** Whether cycle prevention should be enforced in child processes. */
 	preventCycles: boolean;
+	/** Whether to transform tool lists to use batch. */
+	toolOptimize?: boolean;
 	/** Tiered model overrides (lite/flash/full). */
 	tieredModels?: { lite?: string; flash?: string; full?: string };
 	/** Abort signal for cancellation. */
@@ -216,6 +253,8 @@ export interface RunFlowOptions {
 	onUpdate?: FlowUpdateCallback;
 	/** Factory to wrap results into FlowDetails. */
 	makeDetails: (results: SingleResult[]) => FlowDetails;
+	/** Max execution time in ms before child is terminated. Default: 10 minutes. */
+	timeoutMs?: number;
 }
 
 /**
@@ -229,12 +268,14 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		flows,
 		flowName,
 		intent,
+		aim,
 		taskCwd,
 		forkSessionSnapshotJsonl,
 		parentDepth,
 		parentFlowStack,
 		maxDepth,
 		preventCycles,
+		toolOptimize = false,
 		signal,
 		onUpdate,
 		makeDetails,
@@ -248,6 +289,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			type: normalizedFlowName,
 			agentSource: "unknown",
 			intent,
+			aim,
 			exitCode: 1,
 			messages: [],
 			stderr: `Unknown flow: "${flowName}". Available flows: ${available}.`,
@@ -260,6 +302,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		type: normalizedFlowName,
 		agentSource: flow.source,
 		intent,
+		aim,
 		exitCode: -1,
 		messages: [],
 		stderr: "",
@@ -302,9 +345,18 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			opts.tieredModels,
 			parentDepth,
 			maxDepth,
+			toolOptimize,
 		);
 		let wasAborted = false;
 
+		// Resolve timeout: explicit option > env var > default (10 min)
+		const envTimeoutRaw = process.env[FLOW_TIMEOUT_ENV];
+		const envTimeout = envTimeoutRaw !== undefined ? (() => {
+			const n = Number(envTimeoutRaw);
+			return Number.isSafeInteger(n) && n >= 0 ? n : null;
+		})() : null;
+		const effectiveTimeout = opts.timeoutMs ?? envTimeout ?? DEFAULT_FLOW_TIMEOUT_MS;
+
 		const exitCode = await new Promise<number>((resolve) => {
 			const nextDepth = Math.max(0, Math.floor(parentDepth)) + 1;
 			const propagatedMaxDepth = Math.max(0, Math.floor(maxDepth));
@@ -314,12 +366,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				cwd: taskCwd ?? cwd,
 				shell: false,
 				stdio: ["pipe", "pipe", "pipe"],
+				// Process group on Unix so we can kill all descendants on timeout/abort.
+				detached: !isWindows,
 				env: {
 					...process.env,
 					[FLOW_DEPTH_ENV]: String(nextDepth),
 					[FLOW_MAX_DEPTH_ENV]: String(propagatedMaxDepth),
 					[FLOW_STACK_ENV]: JSON.stringify(propagatedStack),
 					[FLOW_PREVENT_CYCLES_ENV]: preventCycles ? "1" : "0",
+					[FLOW_TOOL_OPTIMIZE_ENV]: toolOptimize ? "1" : "0",
 					[PI_OFFLINE_ENV]: "1",
 				},
 			});
@@ -353,9 +408,12 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					return;
 				}
 
-				proc.kill("SIGTERM");
+				// Kill the entire process group (negative PID).
+				if (proc.pid === undefined) { proc.kill("SIGTERM"); } else { try { process.kill(-proc.pid, "SIGTERM"); } catch { proc.kill("SIGTERM"); } }
 				const sigkillTimer = setTimeout(() => {
-					if (!didClose) proc.kill("SIGKILL");
+					if (!didClose) {
+						if (proc.pid === undefined) { proc.kill("SIGKILL"); } else { try { process.kill(-proc.pid, "SIGKILL"); } catch { proc.kill("SIGKILL"); } }
+					}
 				}, SIGKILL_TIMEOUT_MS);
 				sigkillTimer.unref();
 			};
@@ -381,19 +439,17 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				}
 			};
 
+			let semanticCompletionTimerArmed = false;
 			const maybeFinishFromAgentEnd = () => {
-				if (!result.sawAgentEnd || didClose || settled) return;
-				clearSemanticCompletionTimer();
+				if (!result.sawAgentEnd || didClose || settled || semanticCompletionTimerArmed) return;
+				semanticCompletionTimerArmed = true;
 				semanticCompletionTimer = setTimeout(() => {
 					if (didClose || settled || !result.sawAgentEnd) return;
 					if (buffer.trim()) {
 						flushBufferedLines(buffer);
 						buffer = "";
 					}
-					proc.stdout.removeListener("data", onStdoutData);
-					proc.stderr.removeListener("data", onStderrData);
 					finish(0);
-					terminateChild();
 				}, AGENT_END_GRACE_MS);
 				semanticCompletionTimer.unref();
 			};
@@ -433,6 +489,16 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				if (signal.aborted) abortHandler();
 				else signal.addEventListener("abort", abortHandler, { once: true });
 			}
+
+			// Execution timeout — kill child if it runs too long
+			if (effectiveTimeout > 0) {
+				const timeoutTimer = setTimeout(() => {
+					if (didClose || settled) return;
+					result.stderr += `\nFlow timed out after ${Math.round(effectiveTimeout / 1000)}s.`;
+					terminateChild();
+				}, effectiveTimeout);
+				timeoutTimer.unref();
+			}
 		});
 
 		result.exitCode = exitCode;

package/hooks.ts

@@ -68,38 +68,56 @@ export function clearHooks(): void {
 // Built-in hooks
 // ---------------------------------------------------------------------------
 
-/** Suggest review flow after a successful code flow. */
+/** Suggest audit flow after a successful build flow. */
 registerHook({
-	name: "pi-agent-flow/code-to-review",
-	trigger: { flowTypes: ["code"], onlyOnSuccess: true },
+	name: "pi-agent-flow/build-to-audit",
+	trigger: { flowTypes: ["build"], onlyOnSuccess: true },
 	action: (ctx) => {
-		const reviewWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "review",
+		const auditWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "audit",
 		);
-		if (reviewWasRequested) return null;
+		if (auditWasRequested) return null;
 
 		return {
 			content:
-				"Consider running a [review] flow to audit the changes for security, correctness, and code quality.",
+				"Consider running a [audit] flow to audit the changes for security, correctness, and code quality.",
 			priority: 10,
 		};
 	},
 });
 
-/** Suggest code flow after a successful debug flow. */
+/** Suggest build flow after a successful debug flow. */
 registerHook({
-	name: "pi-agent-flow/debug-to-code",
+	name: "pi-agent-flow/debug-to-build",
 	trigger: { flowTypes: ["debug"], onlyOnSuccess: true },
 	action: (ctx) => {
-		const codeWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "code",
+		const buildWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "build",
 		);
-		if (codeWasRequested) return null;
+		if (buildWasRequested) return null;
 
 		return {
 			content:
-				"The root cause has been identified. Consider running a [code] flow to implement the fix.",
+				"The root cause has been identified. Consider running a [build] flow to implement the fix.",
 			priority: 10,
 		};
 	},
 });
+
+/** Suggest explore flow after a successful audit flow. */
+registerHook({
+	name: "pi-agent-flow/audit-to-explore",
+	trigger: { flowTypes: ["audit"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const exploreWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "explore",
+		);
+		if (exploreWasRequested) return null;
+
+		return {
+			content:
+				"Audit complete. Consider running an [explore] flow to review the audit findings.",
+			priority: 15,
+		};
+	},
+});

package/index.ts

@@ -8,7 +8,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { type FlowConfig, discoverFlows } from "./agents.js";
-import { loadFlowModels, type FlowModelConfig } from "./config.js";
+import { loadFlowModels, loadFlowSettings, type FlowModelConfig } from "./config.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
 import { runHooks } from "./hooks.js";
@@ -20,6 +20,12 @@ import {
 	isFlowError,
 	isFlowSuccess,
 } from "./types.js";
+import { createBatchTool } from "./batch.js";
+import {
+	createWebTool,
+	looksLikeUrlPrompt,
+	looksLikeWebSearchPrompt,
+} from "./web-tool.js";
 
 // ---------------------------------------------------------------------------
 // Limits
@@ -31,6 +37,7 @@ const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
 const FLOW_STACK_ENV = "PI_FLOW_STACK";
 const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
+export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
 
 // ---------------------------------------------------------------------------
 // Tool parameter schema
@@ -38,11 +45,14 @@ const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
 
 const FlowItem = Type.Object({
 	type: Type.String({
-		description: "Flow type. Matching is case-insensitive. Must correspond to an available flow name such as explore, debug, code, architect, review, or brainstorm.",
+		description: "Flow type. Matching is case-insensitive. Must correspond to an available flow name such as scout, debug, build, craft, audit, or ideas.",
 	}),
 	intent: Type.String({
 		description: "Clear, specific mission for this flow.",
 	}),
+	aim: Type.String({
+		description: "Extreme short intent — one sentence, 5-7 words, headline-style summary of what this flow does.",
+	}),
 	cwd: Type.Optional(
 		Type.String({ description: "Working directory override for this flow." }),
 	),
@@ -52,7 +62,7 @@ const FlowParams = Type.Object({
 	flow: Type.Array(FlowItem, {
 		description:
 			"Array of flow tasks to execute. Each runs in its own forked process. " +
-			'Example: { flow: [{ type: "explore", "intent": "Find auth code" }, { type: "code", "intent": "Fix bug" }] }',
+			'Example: { flow: [{ type: "scout", "intent": "Find all authentication-related code and trace JWT validation", "aim": "Find auth code and trace JWT" }, { type: "build", "intent": "Fix the bug in user registration", "aim": "Fix registration bug" }] }',
 		minItems: 1,
 	}),
 	confirmProjectFlows: Type.Optional(
@@ -362,6 +372,12 @@ function appendReminder(
 	return copy;
 }
 
+function computeActiveTools(optimize: boolean): string[] {
+	return optimize
+		? ["batch", "bash", "flow", "web"]
+		: ["read", "write", "edit", "batch", "bash", "flow", "web"];
+}
+
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
@@ -376,62 +392,133 @@ export default function (pi: ExtensionAPI) {
 		type: "boolean",
 	});
 	pi.registerFlag("flow-lite-model", {
-		description: "Model for lite-tier flows (explore, debug).",
+		description: "Model for lite-tier flows (scout, debug).",
 		type: "string",
 	});
 	pi.registerFlag("flow-flash-model", {
-		description: "Model for flash-tier flows (code, review).",
+		description: "Model for flash-tier flows (build, audit).",
 		type: "string",
 	});
 	pi.registerFlag("flow-full-model", {
-		description: "Model for full-tier flows (brainstorm, architect).",
+		description: "Model for full-tier flows (ideas, craft).",
 		type: "string",
 	});
+	pi.registerFlag("tool-optimize", {
+		description: "Use the unified batch tool instead of separate read/write/edit tools (default: true).",
+		type: "boolean",
+	});
 
 	const depthConfig = resolveFlowDepthConfig(pi);
 	const { currentDepth, maxDepth, canDelegate, ancestorFlowStack, preventCycles } =
 		depthConfig;
 
+	// toolOptimize: CLI flag > env var > settings.json > default (true)
+	let toolOptimize = true;
+	const envToolOptimize = process.env[FLOW_TOOL_OPTIMIZE_ENV];
+	if (envToolOptimize !== undefined) {
+		const parsed = parseBoolean(envToolOptimize);
+		if (parsed !== null) toolOptimize = parsed;
+	}
+
 	let discoveredFlows: FlowConfig[] = [];
 	let flowModelConfig: FlowModelConfig = {};
 
 	// Auto-discover flows on session start
 	pi.on("session_start", async (_event, ctx) => {
-		if (!canDelegate) return;
-
 		const discovery = discoverFlows(ctx.cwd, "all");
 		discoveredFlows = discovery.flows;
 		flowModelConfig = loadFlowModels(ctx.cwd);
+
+		// Resolve toolOptimize: CLI flag > env var > settings.json > default
+		const cliFlag = pi.getFlag("tool-optimize");
+		if (typeof cliFlag === "boolean") {
+			toolOptimize = cliFlag;
+		} else if (typeof cliFlag === "string") {
+			const parsed = parseBoolean(cliFlag);
+			if (parsed !== null) toolOptimize = parsed;
+		} else {
+			const flowSettings = loadFlowSettings(ctx.cwd);
+			if (typeof flowSettings.toolOptimize === "boolean") {
+				toolOptimize = flowSettings.toolOptimize;
+			}
+		}
+
+		// Only restrict tools for the main orchestrator (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(toolOptimize));
+		}
+
+		// Register batch so it is available for both main agent and child flows.
+		if (toolOptimize) {
+			pi.registerTool(createBatchTool());
+		}
 	});
 
-	// Inject available flows into the system prompt
+	// 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) return;
+		pi.setActiveTools(computeActiveTools(toolOptimize));
+	});
+	// Inject available flows into the system prompt.
+	// Skip entirely for child flows (depth > 0) — they get their instructions
+	// from the 4-part prompt structure in buildFlowArgs and have no web tool.
 	pi.on("before_agent_start", async (event) => {
-		if (!canDelegate) return;
-		if (discoveredFlows.length === 0) return;
+		if (currentDepth > 0) return undefined;
+
+		const prompt = event.prompt;
+		const hasUrl = looksLikeUrlPrompt(prompt);
+		const likelyNeedsWeb = looksLikeWebSearchPrompt(prompt);
+
+
+		const webInstructions: string[] = [];
+		if (hasUrl) {
+			webInstructions.push(
+				"The prompt includes a URL. Use web tool with op: { o: 'fetch', u: '<url>' } before answering about that page.",
+			);
+		}
+		if (likelyNeedsWeb) {
+			webInstructions.push(
+				"The prompt likely needs external or current info. Prefer web tool with op: [{ o: 'search', q: '<query>' }] over memory.",
+			);
+		}
+
+		let systemPrompt = event.systemPrompt;
+		if (webInstructions.length > 0) {
+			systemPrompt +=
+				"\n\n## pi-web steering\n" +
+				webInstructions.map((line) => `- ${line}`).join("\n");
+		}
+
+		if (!canDelegate || discoveredFlows.length === 0) {
+			return webInstructions.length > 0 ? { systemPrompt } : undefined;
+		}
 
 		return {
 			systemPrompt:
-				event.systemPrompt +
+				systemPrompt +
 				`\n\n## Flows
 
 Before acting, reason about whether to dive into a flow:
 
-- [explore] — when you need to understand first. Find files, trace code paths, map architecture.
+- [scout] — when you need to understand first. Find files, trace code paths, map architecture.
 - [debug] — when something is broken. Investigate logs, errors, stack traces to find root cause.
-- [code] — when you are ready to build. Implement features, fix bugs, write tests.
-- [architect] — when you need a plan. Design structure, break down requirements before building.
-- [review] — when you need to verify. Audit security, quality, correctness.
-- [brainstorm] — when you need fresh ideas. Start from a clean slate with only the intent.
+- [build] — when you are ready to build. Implement features, fix bugs, write tests.
+- [craft] — when you need a plan. Design structure, break down requirements before building.
+- [audit] — when you need to verify. Audit security, quality, correctness.
+- [ideas] — when you need fresh ideas. Start from a clean slate with only the intent.
 
 Multiple independent flows? Batch them into one call:
 
-✅ { "flow": [{ "type": "explore", "intent": "..." }, { "type": "review", "intent": "..." }] }
+✅ { "flow": [{ "type": "scout", "intent": "..." }, { "type": "audit", "intent": "..." }] }
 ❌ Two separate calls — wastes time
 
 Each call renders as:
 
-• flow [explore] — Map the full directory structure...
-• flow [review] — Audit security and quality...
+• flow [scout] — Map the full directory structure...
+• flow [audit] — Audit security and quality...
 
 Each flow returns:
 
@@ -448,18 +535,22 @@ flow [type] accomplished
 		};
 	});
 
-	// Sliding reminder: strip from all earlier user messages, append to latest
+	// Sliding reminder: strip from all earlier user messages, append to latest.
+	// Skip for child flows — they have explicit <mission> instructions and
+	// injecting the reminder is noise.
 	pi.on("context", async (event) => {
+		if (currentDepth > 0) return undefined;
+
 		const messages = event.messages;
 		const userIndices = messages
-			.map((m, i) => (m.role === "user" ? i : -1))
-			.filter((i) => i !== -1);
+			.map((m: any, i: number) => (m.role === "user" ? i : -1))
+			.filter((i: number) => i !== -1);
 
 		if (userIndices.length === 0) return undefined;
 
 		const lastUserIndex = userIndices[userIndices.length - 1];
 
-		const modified = messages.map((msg, idx) => {
+		const modified = messages.map((msg: any, idx: number) => {
 			if (msg.role !== "user") return msg;
 
 			const content = stripReminder(msg.content);
@@ -472,6 +563,9 @@ flow [type] accomplished
 		return { messages: modified };
 	});
 
+	// Register the web tool
+	pi.registerTool(createWebTool());
+
 	// Register the flow tool
 	if (canDelegate) {
 		pi.registerTool({
@@ -482,8 +576,8 @@ flow [type] accomplished
 				"You MUST enter to the following flow states, with tool call method.",
 				"",
 				"Flow states are isolated \u03c0 processes with forked session snapshots. They run in parallel.",
-				'Invoke: { "flow": [{ "type": "explore", "intent": "..." }, ...] }',
-				"States: explore (tanken), debug (kensh\u014d), code (shokunin), architect (keikaku), review (kanshi), brainstorm (mushin).",
+				'Invoke: { "flow": [{ "type": "scout", "intent": "..." }, ...] }',
+				"States: scout (tanken), debug (kensh\u014d), build (shokunin), craft (keikaku), audit (kanshi), ideas (mushin).",
 				"Custom states configs in (create if not exists): .md files in .pi/agents/ or ~/.pi/agent/agents/.",
 			].join("\n"),
 			parameters: FlowParams,
@@ -506,7 +600,7 @@ flow [type] accomplished
 				);
 
 				// Collect all requested flow names
-				const requested = new Set(params.flow.map((f) => f.type.toLowerCase()));
+				const requested = new Set<string>(params.flow.map((f: any) => f.type.toLowerCase()));
 
 				// Cycle check
 				if (preventCycles) {
@@ -558,6 +652,7 @@ flow [type] accomplished
 						type: params.flow[i].type,
 						agentSource: "unknown",
 						intent: params.flow[i].intent,
+						aim: params.flow[i].aim,
 						exitCode: -1,
 						messages: [],
 						stderr: "",
@@ -581,7 +676,7 @@ flow [type] accomplished
 
 				if (onUpdate) emitProgress();
 
-				const results = await mapFlowConcurrent(params.flow, 4, async (item, index) => {
+				const results = await mapFlowConcurrent(params.flow, 4, async (item: any, index: number) => {
 					const normalizedType = item.type.toLowerCase();
 					const targetFlow = flows.find((f) => f.name === normalizedType);
 					const effectiveMaxDepth =
@@ -593,12 +688,14 @@ flow [type] accomplished
 						flows,
 						flowName: normalizedType,
 						intent: item.intent,
+						aim: item.aim,
 						taskCwd: item.cwd,
 						forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
 						parentDepth: currentDepth,
 						parentFlowStack: ancestorFlowStack,
 						maxDepth: effectiveMaxDepth,
 						preventCycles,
+						toolOptimize,
 						tieredModels,
 						signal,
 						onUpdate: (partial) => {
@@ -642,4 +739,5 @@ flow [type] accomplished
 				renderFlowResult(result, expanded, theme, args),
 		});
 	}
+
 }