pi-taskflow 0.0.15 → 0.0.17

package/extensions/agents.ts

@@ -10,10 +10,57 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
 
-export interface AgentOverride {
-	model?: string;
-	thinking?: string;
-	tools?: string[];
+export interface TaskflowSettings {
+	/** Whether taskflow's package-local built-in agents are available to flows. */
+	builtInAgents: boolean;
+	/** Whether package-local built-ins are copied into the current project's .pi/agents/. */
+	syncBuiltinAgentsToProject: boolean;
+	/** Maximum completed/failed runs to keep. 0 disables cleanup. */
+	maxKeptRuns: number;
+	/** Maximum age (days) for completed/failed runs. 0 disables age cleanup. */
+	maxRunAgeDays: number;
+}
+
+import { DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS, writeFileAtomic } from "./store.ts";
+
+export const DEFAULT_TASKFLOW_SETTINGS: TaskflowSettings = {
+	builtInAgents: true,
+	syncBuiltinAgentsToProject: false,
+	maxKeptRuns: DEFAULT_KEPT_RUNS,
+	maxRunAgeDays: DEFAULT_RUN_AGE_DAYS,
+};
+
+export function normalizeTaskflowSettings(raw: unknown): TaskflowSettings {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return { ...DEFAULT_TASKFLOW_SETTINGS };
+	}
+	const rec = raw as Record<string, unknown>;
+	return {
+		builtInAgents:
+			typeof rec.builtInAgents === "boolean"
+				? rec.builtInAgents
+				: DEFAULT_TASKFLOW_SETTINGS.builtInAgents,
+		syncBuiltinAgentsToProject:
+			typeof rec.syncBuiltinAgentsToProject === "boolean"
+				? rec.syncBuiltinAgentsToProject
+				: DEFAULT_TASKFLOW_SETTINGS.syncBuiltinAgentsToProject,
+		maxKeptRuns:
+			typeof rec.maxKeptRuns === "number" && rec.maxKeptRuns >= 0 && Number.isInteger(rec.maxKeptRuns)
+				? rec.maxKeptRuns
+				: DEFAULT_TASKFLOW_SETTINGS.maxKeptRuns,
+		maxRunAgeDays:
+			typeof rec.maxRunAgeDays === "number" && rec.maxRunAgeDays >= 0 && Number.isInteger(rec.maxRunAgeDays)
+				? rec.maxRunAgeDays
+				: DEFAULT_TASKFLOW_SETTINGS.maxRunAgeDays,
+	};
+}
+
+export function shouldLoadBuiltinAgents(settings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS): boolean {
+	return settings.builtInAgents;
+}
+
+export function shouldSyncBuiltinAgentsToProject(settings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS): boolean {
+	return settings.builtInAgents && settings.syncBuiltinAgentsToProject;
 }
 
 export interface AgentConfig {
@@ -67,16 +114,18 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "built-in")
 			if (!frontmatter.name || !frontmatter.description) continue;
 
 			// frontmatter is YAML-parsed: tools may be a comma-separated string ("a, b")
-			// OR a YAML sequence ([a, b]). Handle both forms.
+			// OR a YAML sequence ([a, b]). Handle both forms; reject other types to
+			// prevent garbage output from malformed YAML (e.g. boolean, number).
 			const rawTools = frontmatter.tools;
-			const tools: string[] | undefined = Array.isArray(rawTools)
-				? rawTools.map((t) => String(t).trim()).filter(Boolean)
-				: rawTools !== undefined && rawTools !== null
-					? String(rawTools)
-							.split(",")
-							.map((t) => t.trim())
-							.filter(Boolean)
-					: undefined;
+			let tools: string[] | undefined;
+			if (Array.isArray(rawTools)) {
+				tools = rawTools.map((t) => String(t).trim()).filter(Boolean);
+			} else if (typeof rawTools === "string") {
+				tools = rawTools.split(",").map((t) => t.trim()).filter(Boolean);
+			} else if (rawTools !== undefined && rawTools !== null) {
+				console.warn(`[taskflow] Agent '${String(frontmatter.name)}': 'tools' must be a string or array, got ${typeof rawTools}. Ignoring.`);
+				tools = undefined;
+			}
 
 			agents.push({
 				name: String(frontmatter.name),
@@ -120,14 +169,15 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
-	overrides?: Record<string, AgentOverride>,
 	modelRoles?: Record<string, string>,
+	taskflowSettings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS,
 ): AgentDiscoveryResult {
-	// Built-in agents ship with the package (extensions/agents/*.md)
-	// PI_TASKFLOW_BUILTIN_AGENTS_DIR allows tests to override or disable (empty = skip)
+	// Built-in agents ship with the package (extensions/agents/*.md).
+	// PI_TASKFLOW_BUILTIN_AGENTS_DIR is kept as a test hook only; user-facing
+	// enable/disable lives in settings.json under `taskflow.builtInAgents`.
 	const builtInDirEnv = process.env.PI_TASKFLOW_BUILTIN_AGENTS_DIR;
 	const builtInDir = builtInDirEnv ? builtInDirEnv : builtInDirEnv === undefined ? path.resolve(import.meta.dirname, "agents") : "";
-	const builtInAgents = builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
+	const builtInAgents = shouldLoadBuiltinAgents(taskflowSettings) && builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
 
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
@@ -147,28 +197,16 @@ export function discoverAgents(
 		for (const a of projectAgents) agentMap.set(a.name, a);
 	}
 
-	if (overrides) {
-		for (const [name, override] of Object.entries(overrides)) {
-			const agent = agentMap.get(name);
-			if (agent) {
-				// Clone before mutating: agentMap owns the original AgentConfig
-				// (loaded from disk in loadAgentsFromDir). Mutating it in place
-				// would cause cross-contamination for any caller that retains a
-				// reference and invokes discoverAgents again with different overrides.
-				const mutated: AgentConfig = { ...agent };
-				if (override.model !== undefined) mutated.model = override.model;
-				if (override.thinking !== undefined) mutated.thinking = override.thinking;
-				if (override.tools !== undefined) mutated.tools = override.tools;
-				agentMap.set(name, mutated);
-			}
-		}
-	}
-
 	// Resolve {{role}} model references (e.g. {{fast}} → openrouter/deepseek/v4-flash)
+	// Clone before mutating, consistent with the overrides block above.
 	if (modelRoles) {
-		for (const agent of agentMap.values()) {
+		for (const [name, agent] of agentMap.entries()) {
 			const resolved = resolveModelRole(agent.model, modelRoles);
-			if (resolved !== agent.model) agent.model = resolved;
+			if (resolved !== agent.model) {
+				const mutated: AgentConfig = { ...agent };
+				mutated.model = resolved;
+				agentMap.set(name, mutated);
+			}
 		}
 	}
 
@@ -176,9 +214,9 @@ export function discoverAgents(
 }
 
 export interface SubagentSettings {
-	agentOverrides?: Record<string, AgentOverride>;
 	globalThinking?: string;
 	modelRoles?: Record<string, string>;
+	taskflow: TaskflowSettings;
 }
 
 /**
@@ -197,15 +235,15 @@ export function resolveModelRole(model: string | undefined, roles?: Record<strin
 export function readSubagentSettings(): SubagentSettings {
 	try {
 		const settingsPath = path.join(getAgentDir(), "settings.json");
-		if (!fs.existsSync(settingsPath)) return {};
+		if (!fs.existsSync(settingsPath)) return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
 		const raw = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
 		return {
-			agentOverrides: raw.subagents?.agentOverrides,
 			globalThinking: raw.subagents?.globalThinking ?? raw.defaultThinkingLevel,
 			modelRoles: raw.modelRoles,
+			taskflow: normalizeTaskflowSettings(raw.taskflow),
 		};
 	} catch {
-		return {};
+		return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
 	}
 }
 
@@ -249,7 +287,7 @@ export function syncBuiltinAgentsToProject(cwd: string): void {
 
 		try {
 			const content = fs.readFileSync(src, "utf-8");
-			fs.writeFileSync(dst, content, "utf-8");
+			writeFileAtomic(dst, content);
 		} catch {
 			// Best-effort: a locked file must not block the sync.
 		}

package/extensions/cache.ts

@@ -47,9 +47,13 @@ function resolveOne(entry: string, cwd: string): string {
 					cwd,
 					encoding: "utf-8",
 					stdio: ["ignore", "pipe", "ignore"],
+					timeout: 30_000,
 				}).trim();
 				return `git:${ref}=${sha}`;
-			} catch {
+			} catch (e: unknown) {
+				if ((e as NodeJS.ErrnoException).code === "ETIMEDOUT") {
+					return `git:${ref}=<timeout>`;
+				}
 				return `git:${ref}=<no-git>`;
 			}
 		}

package/extensions/index.ts

@@ -24,7 +24,7 @@ import {
 	runInteractiveInit,
 } from "./init.ts";
 import { Type } from "typebox";
-import { type AgentScope, discoverAgents, readSubagentSettings, syncBuiltinAgentsToProject } from "./agents.ts";
+import { type AgentScope, discoverAgents, readSubagentSettings, shouldSyncBuiltinAgentsToProject, syncBuiltinAgentsToProject } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
 import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
 import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
@@ -38,8 +38,11 @@ import {
 	type RunState,
 	saveFlow,
 	saveRun,
+	DEFAULT_KEPT_RUNS,
+	DEFAULT_RUN_AGE_DAYS,
 } from "./store.ts";
 import { CacheStore } from "./cache.ts";
+import { safeParse } from "./interpolate.ts";
 
 interface TaskflowDetails {
 	state?: RunState;
@@ -142,11 +145,12 @@ async function runFlow(
 
 	// Throttled persistence: avoid disk writes on every sub-item event.
 	let lastPersist = 0;
+	const cleanupConfig = { maxKeep: DEFAULT_KEPT_RUNS, maxAgeDays: DEFAULT_RUN_AGE_DAYS };
 	const persistThrottled = (s: RunState) => {
 		const now = Date.now();
 		if (now - lastPersist >= 1000) {
 			lastPersist = now;
-			saveRun(s);
+			saveRun(s, cleanupConfig);
 		}
 	};
 
@@ -189,8 +193,10 @@ async function runFlow(
 		// discoverAgents or readSubagentSettings (F-001) is caught and
 		// the heartbeat timer is cleared by the finally block below.
 		const settings = readSubagentSettings();
+		cleanupConfig.maxKeep = settings.taskflow.maxKeptRuns;
+		cleanupConfig.maxAgeDays = settings.taskflow.maxRunAgeDays;
 		const scope: AgentScope = def.agentScope ?? "user";
-		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides, settings.modelRoles);
+		const { agents } = discoverAgents(ctx.cwd, scope, settings.modelRoles, settings.taskflow);
 
 		// Hint: if any agent still has unresolved {{role}} references, suggest configuring modelRoles
 		const unresolvedRoles = agents
@@ -225,7 +231,7 @@ async function runFlow(
 		return result;
 	} finally {
 		if (heartbeat) clearInterval(heartbeat);
-		saveRun(state); // force-persist terminal state
+		saveRun(state, cleanupConfig); // force-persist terminal state
 		emit(state); // final render reflecting terminal state
 	}
 }
@@ -255,16 +261,44 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_e, ctx) => {
 		registerSavedFlowCommands(ctx);
 
-		// Sync built-in agents into .pi/agents/ so Pi's native subagent tool
-		// (and any other extension) can discover them — taskflow's
-		// extensions/agents/ directory is invisible to the rest of Pi.
+		// Optional: copy built-in agents into .pi/agents/ so Pi's native
+		// subagent tool (and other extensions) can discover them. This is
+		// disabled by default to avoid surprising project file creation.
 		try {
-			syncBuiltinAgentsToProject(ctx.cwd);
+			const settings = readSubagentSettings();
+			if (shouldSyncBuiltinAgentsToProject(settings.taskflow)) {
+				syncBuiltinAgentsToProject(ctx.cwd);
+			}
 		} catch {
 			// Best-effort: a locked or readonly .pi/ directory must not block
 			// session startup.
 		}
 
+		// Upgrade hint: if the project already has .pi/agents/ with agent
+		// files but no explicit taskflow settings, the user is upgrading
+		// from the old default (sync=true) and may be surprised that sync
+		// is now disabled by default.
+		try {
+			const raw = readSettings();
+			if (!("taskflow" in raw)) {
+				const fs = await import("node:fs");
+				const path = await import("node:path");
+				const projectAgentsDir = path.join(ctx.cwd, ".pi", "agents");
+				try {
+					const entries = fs.readdirSync(projectAgentsDir).filter((e: string) => e.endsWith(".md"));
+					if (entries.length > 0) {
+						console.warn(
+							`[taskflow] Note: built-in agents are no longer synced to .pi/agents/ by default. ` +
+							`If you rely on this, run /tf init → 'Configure taskflow preferences' to re-enable. ` +
+							`(This is a one-time upgrade hint.)`,
+						);
+					}
+				} catch { /* .pi/agents/ doesn't exist — no hint needed */ }
+			}
+		} catch {
+			// Best-effort: settings.json missing or unreadable is not an error.
+		}
+
 		// Hint: prompt to configure model roles if not set
 		try {
 			const settings = readSubagentSettings();
@@ -282,7 +316,7 @@ export default function (pi: ExtensionAPI) {
 		name: "taskflow",
 		label: "Taskflow",
 		description: [
-			"Orchestrate subagents — the ONLY delegation tool. Fully replaces the built-in subagent tool.",
+			"IMPORTANT: Before using this tool for the first time in a session, invoke skill_load('taskflow') to read the full documentation (DSL syntax, examples, best practices). This tool description is a reference, not a tutorial.",
 			"Shorthand (same API as subagent): pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` for parallel, or `chain:[{task,agent?}]` for sequential (use {previous.output}).",
 			"DSL: use action=run with an inline `define` (you write the DAG) or a saved `name`. Phases (agent, parallel, map, gate, reduce, approval, flow, loop, tournament) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
 			"Every delegation is tracked (runId), resumable across sessions, and saveable as /tf:<name> via action=save.",
@@ -293,7 +327,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: TaskflowParams,
 		promptSnippet: "Orchestrate subagents — single, parallel, chain, or DAG — with tracking, resume, and context isolation. Replaces the subagent tool.",
 		promptGuidelines: [
-			"Use taskflow for ALL delegation — single tasks, parallel, chain, or full DAG orchestration. It fully replaces the subagent tool: every delegation is tracked with a runId, resumable across sessions, context-isolated (only final output returns), and saveable as /tf:<name>. Do NOT call the subagent tool directly; use taskflow shorthand (task/tasks/chain) for simple cases instead.",
+			"BEFORE FIRST USE: invoke skill_load('taskflow') to read the full skill documentation (DSL syntax, phase types, examples, best practices). This tool description is a condensed reference only — the skill is the authoritative guide.\n\nUse taskflow for ALL delegation — single tasks, parallel, chain, or full DAG orchestration. It fully replaces the subagent tool: every delegation is tracked with a runId, resumable across sessions, context-isolated (only final output returns), and saveable as /tf:<name>. Do NOT call the subagent tool directly; use taskflow shorthand (task/tasks/chain) for simple cases instead.",
 			"For complex multi-phase work (explore / 审计 / analyze the project, auditing endpoints, reviewing or migrating many files/modules, cross-checked research), use the full DSL with phases. For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
@@ -370,6 +404,7 @@ export default function (pi: ExtensionAPI) {
 						modelRegistry: ctx.modelRegistry,
 						modelList,
 						currentRoles: current,
+						currentTaskflowSettings: readSubagentSettings().taskflow,
 					});
 					const text = formatFlowResult(result);
 					return { content: [{ type: "text", text }], details: { action } satisfies TaskflowDetails };
@@ -382,7 +417,7 @@ export default function (pi: ExtensionAPI) {
 			if (action === "agents") {
 				const scope = params.scope ?? "both";
 				const settings2 = readSubagentSettings();
-				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined, settings2.modelRoles);
+				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, settings2.modelRoles, settings2.taskflow);
 				const text = agents.length
 					? agents
 							.map(
@@ -407,13 +442,18 @@ export default function (pi: ExtensionAPI) {
 				const { verifyTaskflow } = await import("./verify.ts");
 				// Load definition: inline define takes priority, then saved name
 				let def: Taskflow | undefined;
-				if (params.define) {
-					const d = params.define as Record<string, unknown>;
+				let resolvedDefine: unknown = params.define;
+				if (typeof resolvedDefine === "string") {
+					const parsed = safeParse(resolvedDefine);
+					if (parsed && typeof parsed === "object") resolvedDefine = parsed;
+				}
+				if (resolvedDefine) {
+					const d = resolvedDefine as Record<string, unknown>;
 					if (typeof d === "object" && d !== null && Array.isArray(d.phases)) {
 						def = d as unknown as Taskflow;
-					} else if (isShorthand(params.define)) {
-						const r = validateTaskflow(params.define);
-						if (r.ok) def = params.define as unknown as Taskflow;
+					} else if (isShorthand(resolvedDefine)) {
+						const r = validateTaskflow(resolvedDefine);
+						if (r.ok) def = resolvedDefine as unknown as Taskflow;
 					}
 				} else if (params.name) {
 					const saved = getFlow(ctx.cwd, params.name);
@@ -471,9 +511,25 @@ export default function (pi: ExtensionAPI) {
 			// resolve the definition: inline `define` / shorthand (single|parallel|chain), else saved `name`.
 			let def: Taskflow | undefined;
 
+			// Auto-parse string `define` — LLMs sometimes pass a JSON string
+			// instead of a parsed object. safeParse handles markdown fences too.
+			let resolvedDefine: unknown = params.define;
+			if (typeof resolvedDefine === "string") {
+				const parsed = safeParse(resolvedDefine);
+				if (parsed && typeof parsed === "object") {
+					resolvedDefine = parsed;
+				} else {
+					return errorResult(
+						action,
+						`'define' was passed as a string, not a JSON object. Pass it as a proper object, e.g.:\n` +
+							`define: {"name":"my-flow","phases":[{"id":"step1","task":"do something"}]}`,
+					);
+				}
+			}
+
 			// A shorthand spec can come from `define` (no phases) or top-level params.
 			const shorthandSpec: unknown =
-				params.define ??
+				resolvedDefine ??
 				(params.chain
 					? { chain: params.chain, name: params.name }
 					: params.tasks
@@ -496,11 +552,25 @@ export default function (pi: ExtensionAPI) {
 				def = candidate as Taskflow;
 			} else if (params.name) {
 				const saved = getFlow(ctx.cwd, params.name);
-				if (!saved) return errorResult(action, `Saved flow not found: ${params.name}`);
+				if (!saved) {
+					const available = listFlows(ctx.cwd);
+					const hint = available.length
+						? ` Available flows: ${available.map((f) => f.name).join(", ")}.`
+						: " No saved flows found. Use action=save to create one, or pass 'define' for an inline flow.";
+					return errorResult(action, `Saved flow '${params.name}' not found.${hint}`);
+				}
 				def = saved.def;
 			}
 			if (!def)
-				return errorResult(action, "Provide 'define' (DSL), shorthand 'task'/'tasks'/'chain', or 'name' (saved).");
+				return errorResult(
+					action,
+					`No taskflow definition provided. Use one of:\n` +
+						`- define: {"name":"...","phases":[...]} (inline DSL object)\n` +
+						`- task: "..." (shorthand single agent)\n` +
+						`- tasks: [{"task":"..."},...] (shorthand parallel)\n` +
+						`- chain: [{"task":"..."},...] (shorthand sequential)\n` +
+						`- name: "saved-flow-name" (run a previously saved flow)`,
+				);
 
 			// save
 			if (action === "save") {
@@ -528,7 +598,17 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// run
-			const args = resolveArgs(def, params.args);
+			// Auto-parse string args — LLMs sometimes pass a JSON string.
+			let resolvedArgs: Record<string, unknown> | undefined;
+			if (typeof params.args === "string") {
+				const parsed = safeParse(params.args);
+				if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+					resolvedArgs = parsed as Record<string, unknown>;
+				}
+			} else if (params.args && typeof params.args === "object") {
+				resolvedArgs = params.args as Record<string, unknown>;
+			}
+			const args = resolveArgs(def, resolvedArgs);
 			const v = validateTaskflow(def, { args, cwd: ctx.cwd });
 			if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
 			for (const w of v.warnings) {
@@ -545,7 +625,14 @@ export default function (pi: ExtensionAPI) {
 
 		renderCall(args, theme) {
 			const action = args.action ?? "run";
-			let label = args.name || (args.define as { name?: string } | undefined)?.name;
+			let label = args.name;
+		if (!label) {
+			let define = args.define;
+			if (typeof define === "string") {
+				try { define = JSON.parse(define); } catch { /* not JSON */ }
+			}
+			label = (define as { name?: string } | undefined)?.name;
+		}
 			let suffix = "";
 			const phases = (args.define as Taskflow | undefined)?.phases;
 			if (phases) suffix = ` (${phases.length} phases)`;
@@ -579,7 +666,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerCommand("tf", {
 		description: "Taskflow: list | run <name> | show <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume", "init"];
+			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -713,17 +800,13 @@ export default function (pi: ExtensionAPI) {
 					modelRegistry: ctx.modelRegistry,
 					modelList,
 					currentRoles,
+					currentTaskflowSettings: readSubagentSettings().taskflow,
 				});
-				ctx.ui.notify(
-					result.kind === "saved"
-						? `Saved model roles to ${result.savedPath}:\n${Object.entries(result.chosen)
-								.map(([k, v]) => `  ${k.padEnd(10)} → ${v}`)
-								.join("\n")}`
-						: result.kind === "no-change"
-							? "No changes made."
-							: "Init cancelled.",
-					result.kind === "saved" ? "info" : "info",
-				);
+				if (result.kind === "cancelled") {
+					ctx.ui.notify("Init cancelled.", "info");
+				} else {
+					ctx.ui.notify(formatFlowResult(result), "info");
+				}
 				return;
 			}
 
@@ -767,13 +850,13 @@ function parseArgsString(input: string, def: Taskflow): Record<string, unknown>
 	}
 	// key=value pairs
 	const out: Record<string, unknown> = {};
-	const pairs = trimmed.match(/(\w+)=("[^"]*"|\S+)/g);
+	const pairs = trimmed.match(/(\w+)=("(?:[^"\\]|\\.)*"|\S+)/g);
 	if (pairs) {
 		for (const p of pairs) {
 			const idx = p.indexOf("=");
 			const k = p.slice(0, idx);
 			let v: string = p.slice(idx + 1);
-			if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+			if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1).replace(/\\"/g, '"');
 			out[k] = v;
 		}
 		return out;

package/extensions/init.ts

@@ -17,6 +17,7 @@ import * as path from "node:path";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_TASKFLOW_SETTINGS, normalizeTaskflowSettings, type TaskflowSettings } from "./agents.ts";
 import { writeFileAtomic } from "./store.ts";
 
 // ---------------------------------------------------------------------------
@@ -330,8 +331,23 @@ export function formatDiffReport(
 	return lines.join("\n");
 }
 
+export function formatTaskflowSettingsReport(settings: TaskflowSettings): string {
+	return [
+		"Taskflow preferences:",
+		`  Built-in agents: ${settings.builtInAgents ? "enabled" : "disabled"}`,
+		`  Sync built-ins to project .pi/agents: ${settings.syncBuiltinAgentsToProject ? "enabled" : "disabled"}`,
+	].join("\n");
+}
+
 export function formatFlowResult(result: InitFlowResult): string {
 	if (result.kind === "cancelled") return "Init cancelled.";
+	if (result.kind === "preferences-no-change") {
+		return "No changes.\n" + formatTaskflowSettingsReport(result.settings);
+	}
+	if (result.kind === "preferences-saved") {
+		const savedPath = formatSettingsPath(result.savedPath);
+		return `Saved taskflow preferences to ${savedPath}:\n` + formatTaskflowSettingsReport(result.settings);
+	}
 	if (result.kind === "no-change") {
 		return (
 			"No changes.\n" +
@@ -357,6 +373,8 @@ export function formatFlowResult(result: InitFlowResult): string {
 export type InitFlowResult =
 	| { kind: "saved"; chosen: Record<string, string>; savedPath: string }
 	| { kind: "no-change"; chosen: Record<string, string> }
+	| { kind: "preferences-saved"; settings: TaskflowSettings; savedPath: string }
+	| { kind: "preferences-no-change"; settings: TaskflowSettings }
 	| { kind: "cancelled" };
 
 export async function runInteractiveInit(ctx: {
@@ -366,6 +384,7 @@ export async function runInteractiveInit(ctx: {
 	modelRegistry: ExtensionContext["modelRegistry"];
 	modelList: Model<Api>[];
 	currentRoles: Record<string, string>;
+	currentTaskflowSettings?: TaskflowSettings;
 }): Promise<InitFlowResult> {
 	if (!ctx.hasUI) {
 		throw new Error("runInteractiveInit requires an interactive session (hasUI=true).");
@@ -373,6 +392,7 @@ export async function runInteractiveInit(ctx: {
 
 	const recommended = RECOMMENDED_DEFAULTS;
 	const current = ctx.currentRoles;
+	const currentTaskflowSettings = ctx.currentTaskflowSettings ?? normalizeTaskflowSettings(readSettings().taskflow);
 	const hasCurrent = Object.keys(current).length > 0;
 
 	// ---- Action menu ----
@@ -381,10 +401,11 @@ export async function runInteractiveInit(ctx: {
 				"Use recommended defaults",
 				"Configure each role",
 				"Edit one role",
+				"Configure taskflow preferences",
 				"Show current roles",
 				"Cancel",
 			]
-		: ["Use recommended defaults", "Configure each role"];
+		: ["Use recommended defaults", "Configure each role", "Configure taskflow preferences"];
 
 	const action = await ctx.ui.select(
 		"What do you want to do with model roles?",
@@ -416,6 +437,11 @@ export async function runInteractiveInit(ctx: {
 	// ---- Cancel ----
 	if (action === "Cancel") return { kind: "cancelled" };
 
+	// ---- Configure taskflow preferences ----
+	if (action === "Configure taskflow preferences") {
+		return configureTaskflowPreferences(ctx, currentTaskflowSettings);
+	}
+
 	// ---- Configure each role ----
 	if (action === "Configure each role") {
 		const chosen = await collectRolePicks(ctx, current, recommended, undefined);
@@ -437,6 +463,59 @@ export async function runInteractiveInit(ctx: {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+function taskflowSettingsIdentical(a: TaskflowSettings, b: TaskflowSettings): boolean {
+	return a.builtInAgents === b.builtInAgents && a.syncBuiltinAgentsToProject === b.syncBuiltinAgentsToProject;
+}
+
+async function configureTaskflowPreferences(
+	ctx: { signal: AbortSignal; ui: ExtensionUIContext },
+	current: TaskflowSettings,
+): Promise<InitFlowResult> {
+	const builtInPick = await ctx.ui.select(
+		"Taskflow built-in agents",
+		[
+			`Enable built-in agents${current.builtInAgents ? " (current)" : ""}`,
+			`Disable built-in agents${!current.builtInAgents ? " (current)" : ""}`,
+			"Back to action menu",
+		],
+		{ signal: ctx.signal },
+	);
+	if (builtInPick === undefined || builtInPick === "Back to action menu") return { kind: "cancelled" };
+
+	const chosen: TaskflowSettings = {
+		...DEFAULT_TASKFLOW_SETTINGS,
+		builtInAgents: builtInPick.startsWith("Enable"),
+	};
+
+	if (chosen.builtInAgents) {
+		const syncPick = await ctx.ui.select(
+			"Expose built-in agents to native Pi/project discovery?",
+			[
+				`Do not copy to project .pi/agents${!current.syncBuiltinAgentsToProject ? " (current)" : ""}`,
+				`Copy to project .pi/agents on session start${current.syncBuiltinAgentsToProject ? " (current)" : ""}`,
+				"Back to action menu",
+			],
+			{ signal: ctx.signal },
+		);
+		if (syncPick === undefined || syncPick === "Back to action menu") return { kind: "cancelled" };
+		chosen.syncBuiltinAgentsToProject = syncPick.startsWith("Copy");
+	}
+
+	if (taskflowSettingsIdentical(current, chosen)) {
+		return { kind: "preferences-no-change", settings: chosen };
+	}
+
+	const preview = await ctx.ui.select(
+		`Review taskflow preferences:\n\n${formatTaskflowSettingsReport(chosen)}`,
+		["Save these preferences", "Cancel"],
+		{ signal: ctx.signal },
+	);
+	if (preview !== "Save these preferences") return { kind: "cancelled" };
+
+	const savedPath = writeSettings({ ...readSettings(), taskflow: chosen });
+	return { kind: "preferences-saved", settings: chosen, savedPath };
+}
+
 /** Collect picks for all roles. Returns undefined if user escapes to action menu. */
 async function collectRolePicks(
 	ctx: { signal: AbortSignal; ui: ExtensionUIContext; modelList: Model<Api>[] },