@oh-my-pi/pi-coding-agent 9.4.0 → 9.6.0

package/src/modes/controllers/selector-controller.ts

@@ -3,6 +3,7 @@ import type { OAuthProvider } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Input, Loader, Spacer, Text } from "@oh-my-pi/pi-tui";
 import { getAgentDbPath } from "../../config";
+import { settings } from "../../config/settings";
 import { DebugSelectorComponent } from "../../debug";
 import { disableProvider, enableProvider } from "../../discovery";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
@@ -51,7 +52,6 @@ export class SelectorController {
 		getAvailableThemes().then(availableThemes => {
 			this.showSelector(done => {
 				const selector = new SettingsSelectorComponent(
-					this.ctx.settingsManager,
 					{
 						availableThinkingLevels: this.ctx.session.getAvailableThinkingLevels(),
 						thinkingLevel: this.ctx.session.thinkingLevel,
@@ -68,10 +68,16 @@ export class SelectorController {
 								}
 							});
 						},
-						onStatusLinePreview: settings => {
+						onStatusLinePreview: previewSettings => {
 							// Update status line with preview settings
-							const currentSettings = this.ctx.settingsManager.getStatusLineSettings();
-							this.ctx.statusLine.updateSettings({ ...currentSettings, ...settings });
+							this.ctx.statusLine.updateSettings({
+								preset: settings.get("statusLine.preset"),
+								leftSegments: settings.get("statusLine.leftSegments"),
+								rightSegments: settings.get("statusLine.rightSegments"),
+								separator: settings.get("statusLine.separator"),
+								showHookStatus: settings.get("statusLine.showHookStatus"),
+								...previewSettings,
+							});
 							this.ctx.updateEditorTopBorder();
 							this.ctx.ui.requestRender();
 						},
@@ -86,7 +92,13 @@ export class SelectorController {
 						onCancel: () => {
 							done();
 							// Restore status line to saved settings
-							this.ctx.statusLine.updateSettings(this.ctx.settingsManager.getStatusLineSettings());
+							this.ctx.statusLine.updateSettings({
+								preset: settings.get("statusLine.preset"),
+								leftSegments: settings.get("statusLine.leftSegments"),
+								rightSegments: settings.get("statusLine.rightSegments"),
+								separator: settings.get("statusLine.separator"),
+								showHookStatus: settings.get("statusLine.showHookStatus"),
+							});
 							this.ctx.updateEditorTopBorder();
 							this.ctx.ui.requestRender();
 						},
@@ -123,11 +135,7 @@ export class SelectorController {
 	 * Replaces /status with a unified view of all providers and extensions.
 	 */
 	async showExtensionsDashboard(): Promise<void> {
-		const dashboard = await ExtensionDashboard.create(
-			process.cwd(),
-			this.ctx.settingsManager,
-			this.ctx.ui.terminal.rows,
-		);
+		const dashboard = await ExtensionDashboard.create(process.cwd(), this.ctx.settings, this.ctx.ui.terminal.rows);
 		this.showSelector(done => {
 			dashboard.onClose = () => {
 				done();
@@ -142,7 +150,7 @@ export class SelectorController {
 	 * Most settings are saved directly via SettingsManager in the definitions.
 	 * This handles side effects and session-specific settings.
 	 */
-	handleSettingChange(id: string, value: string | boolean): void {
+	handleSettingChange(id: string, value: unknown): void {
 		// Discovery provider toggles
 		if (id.startsWith("discovery.")) {
 			const providerId = id.replace("discovery.", "");
@@ -232,7 +240,15 @@ export class SelectorController {
 			case "statusLineGitShowUntracked":
 			case "statusLineTimeFormat":
 			case "statusLineTimeShowSeconds": {
-				this.ctx.statusLine.updateSettings(this.ctx.settingsManager.getStatusLineSettings());
+				const statusLineSettings = {
+					preset: settings.get("statusLine.preset"),
+					leftSegments: settings.get("statusLine.leftSegments"),
+					rightSegments: settings.get("statusLine.rightSegments"),
+					separator: settings.get("statusLine.separator"),
+					showHookStatus: settings.get("statusLine.showHookStatus"),
+					segmentOptions: settings.get("statusLine.segmentOptions"),
+				};
+				this.ctx.statusLine.updateSettings(statusLineSettings);
 				this.ctx.updateEditorTopBorder();
 				this.ctx.ui.requestRender();
 				break;
@@ -256,7 +272,7 @@ export class SelectorController {
 			const selector = new ModelSelectorComponent(
 				this.ctx.ui,
 				this.ctx.session.model,
-				this.ctx.settingsManager,
+				this.ctx.settings,
 				this.ctx.session.modelRegistry,
 				this.ctx.session.scopedModels,
 				async (model, role) => {
@@ -369,7 +385,7 @@ export class SelectorController {
 					let wantsSummary = false;
 					let customInstructions: string | undefined;
 
-					const branchSummariesEnabled = this.ctx.settingsManager.getBranchSummaryEnabled();
+					const branchSummariesEnabled = settings.get("branchSummary.enabled");
 
 					while (branchSummariesEnabled) {
 						const summaryChoice = await this.ctx.showHookSelector("Summarize branch?", [

package/src/modes/interactive-mode.ts

@@ -19,7 +19,7 @@ import { isEnoent, logger, postmortem } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { KeybindingsManager } from "../config/keybindings";
 import { renderPromptTemplate } from "../config/prompt-templates";
-import type { SettingsManager } from "../config/settings-manager";
+import { type Settings, settings } from "../config/settings";
 import type { ExtensionUIContext, ExtensionUIDialogOptions } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
 import { loadSlashCommands } from "../extensibility/slash-commands";
@@ -72,7 +72,7 @@ export interface InteractiveModeOptions {
 export class InteractiveMode implements InteractiveModeContext {
 	public session: AgentSession;
 	public sessionManager: SessionManager;
-	public settingsManager: SettingsManager;
+	public settings: Settings;
 	public keybindings: KeybindingsManager;
 	public agent: AgentSession["agent"];
 	public historyStorage?: HistoryStorage;
@@ -159,7 +159,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	) {
 		this.session = session;
 		this.sessionManager = session.sessionManager;
-		this.settingsManager = session.settingsManager;
+		this.settings = session.settings;
 		this.keybindings = KeybindingsManager.inMemory();
 		this.agent = session.agent;
 		this.version = version;
@@ -168,7 +168,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.lspServers = lspServers;
 		this.mcpManager = mcpManager;
 
-		this.ui = new TUI(new ProcessTerminal(), this.settingsManager.getShowHardwareCursor());
+		this.ui = new TUI(new ProcessTerminal(), settings.get("showHardwareCursor"));
 		setMermaidRenderCallback(() => this.ui.requestRender());
 		this.chatContainer = new Container();
 		this.pendingMessagesContainer = new Container();
@@ -193,7 +193,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.statusLine = new StatusLineComponent(session);
 		this.statusLine.setAutoCompactEnabled(session.autoCompactionEnabled);
 
-		this.hideThinkingBlock = this.settingsManager.getHideThinkingBlock();
+		this.hideThinkingBlock = settings.get("hideThinkingBlock");
 
 		// Define slash commands for autocomplete
 		const slashCommands: SlashCommand[] = [
@@ -240,7 +240,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		// Build skill commands from session.skills (if enabled)
 		const skillCommandList: SlashCommand[] = [];
-		if (this.settingsManager.getEnableSkillCommands?.()) {
+		if (settings.get("skills.enableSkillCommands")) {
 			for (const skill of this.session.skills) {
 				const commandName = `skill:${skill.name}`;
 				this.skillCommands.set(commandName, skill.filePath);
@@ -300,7 +300,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				fileTypes: s.fileTypes,
 			})) ?? [];
 
-		const startupQuiet = this.settingsManager.getStartupQuiet();
+		const startupQuiet = settings.get("startup.quiet");
 
 		if (!startupQuiet) {
 			// Add welcome header
@@ -314,7 +314,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			// Add changelog if provided
 			if (this.changelogMarkdown) {
 				this.ui.addChild(new DynamicBorder());
-				if (this.settingsManager.getCollapseChangelog()) {
+				if (settings.get("collapseChangelog")) {
 					const versionMatch = this.changelogMarkdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
 					const latestVersion = versionMatch ? versionMatch[1] : this.version;
 					const condensedText = `Updated to v${latestVersion}. Use ${theme.bold("/changelog")} to view full changelog.`;
@@ -330,7 +330,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 
 		// Set terminal title if session already has one (resumed session)
-		const existingTitle = this.sessionManager.getSessionTitle();
+		const existingTitle = this.sessionManager.getSessionName();
 		if (existingTitle) {
 			setTerminalTitle(`pi: ${existingTitle}`);
 		}
@@ -494,7 +494,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	private resolvePlanFilePath(planFilePath: string): string {
 		if (planFilePath.startsWith("plan://")) {
 			return resolvePlanUrlToPath(planFilePath, {
-				getPlansDirectory: this.settingsManager.getPlansDirectory.bind(this.settingsManager),
+				getPlansDirectory: () => this.settings.getPlansDirectory(),
 				cwd: this.sessionManager.getCwd(),
 			});
 		}

package/src/modes/rpc/rpc-mode.ts

@@ -448,6 +448,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					interruptMode: session.interruptMode,
 					sessionFile: session.sessionFile,
 					sessionId: session.sessionId,
+					sessionName: session.sessionName,
 					autoCompactionEnabled: session.autoCompactionEnabled,
 					messageCount: session.messages.length,
 					queuedMessageCount: session.queuedMessageCount,
@@ -594,6 +595,15 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				return success(id, "get_last_assistant_text", { text });
 			}
 
+			case "set_session_name": {
+				const name = command.name.trim();
+				if (!name) {
+					return error(id, "set_session_name", "Session name cannot be empty");
+				}
+				session.setSessionName(name);
+				return success(id, "set_session_name");
+			}
+
 			// =================================================================
 			// Messages
 			// =================================================================

package/src/modes/rpc/rpc-types.ts

@@ -58,6 +58,7 @@ export type RpcCommand =
 	| { id?: string; type: "branch"; entryId: string }
 	| { id?: string; type: "get_branch_messages" }
 	| { id?: string; type: "get_last_assistant_text" }
+	| { id?: string; type: "set_session_name"; name: string }
 
 	// Messages
 	| { id?: string; type: "get_messages" };
@@ -76,6 +77,7 @@ export interface RpcSessionState {
 	interruptMode: "immediate" | "wait";
 	sessionFile?: string;
 	sessionId: string;
+	sessionName?: string;
 	autoCompactionEnabled: boolean;
 	messageCount: number;
 	queuedMessageCount: number;
@@ -166,6 +168,7 @@ export type RpcResponse =
 			success: true;
 			data: { text: string | null };
 	  }
+	| { id?: string; type: "response"; command: "set_session_name"; success: true }
 
 	// Messages
 	| { id?: string; type: "response"; command: "get_messages"; success: true; data: { messages: AgentMessage[] } }

package/src/modes/types.ts

@@ -2,7 +2,7 @@ import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, UsageReport } from "@oh-my-pi/pi-ai";
 import type { Component, Container, Loader, Spacer, Text, TUI } from "@oh-my-pi/pi-tui";
 import type { KeybindingsManager } from "../config/keybindings";
-import type { SettingsManager } from "../config/settings-manager";
+import type { Settings } from "../config/settings";
 import type { ExtensionUIContext, ExtensionUIDialogOptions } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
@@ -46,7 +46,7 @@ export interface InteractiveModeContext {
 	// Session access
 	session: AgentSession;
 	sessionManager: SessionManager;
-	settingsManager: SettingsManager;
+	settings: Settings;
 	keybindings: KeybindingsManager;
 	agent: AgentSession["agent"];
 	historyStorage?: HistoryStorage;

package/src/modes/utils/ui-helpers.ts

@@ -1,6 +1,7 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Message } from "@oh-my-pi/pi-ai";
 import { Spacer, Text, TruncatedText } from "@oh-my-pi/pi-tui";
+import { settings } from "../../config/settings";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
 import { BashExecutionComponent } from "../../modes/components/bash-execution";
 import { BranchSummaryMessageComponent } from "../../modes/components/branch-summary-message";
@@ -224,9 +225,9 @@ export class UiHelpers {
 						content.name,
 						content.arguments,
 						{
-							showImages: this.ctx.settingsManager.getShowImages(),
-							editFuzzyThreshold: this.ctx.settingsManager.getEditFuzzyThreshold(),
-							editAllowFuzzy: this.ctx.settingsManager.getEditFuzzyMatch(),
+							showImages: settings.get("terminal.showImages"),
+							editFuzzyThreshold: settings.get("edit.fuzzyThreshold"),
+							editAllowFuzzy: settings.get("edit.fuzzyMatch"),
 						},
 						tool,
 						this.ctx.ui,

package/src/patch/index.ts

@@ -26,7 +26,7 @@ import { outputMeta } from "../tools/output-meta";
 import { enforcePlanModeWrite, resolvePlanPath } from "../tools/plan-mode-guard";
 import { applyPatch } from "./applicator";
 import { generateDiffString, generateUnifiedDiffString, replaceText } from "./diff";
-import { DEFAULT_FUZZY_THRESHOLD, findMatch } from "./fuzzy";
+import { findMatch } from "./fuzzy";
 import { detectLineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { buildNormativeUpdateInput } from "./normative";
 import { type EditToolDetails, getLspBatchRequest } from "./shared";
@@ -233,14 +233,14 @@ export class EditTool implements AgentTool<TInput> {
 				this.allowFuzzy = false;
 				break;
 			case "auto":
-				this.allowFuzzy = session.settings?.getEditFuzzyMatch() ?? true;
+				this.allowFuzzy = session.settings.get("edit.fuzzyMatch");
 				break;
 			default:
 				throw new Error(`Invalid OMP_EDIT_FUZZY: ${editFuzzy}`);
 		}
 		switch (editFuzzyThreshold) {
 			case "auto":
-				this.fuzzyThreshold = session.settings?.getEditFuzzyThreshold?.() ?? DEFAULT_FUZZY_THRESHOLD;
+				this.fuzzyThreshold = session.settings.get("edit.fuzzyThreshold");
 				break;
 			default:
 				this.fuzzyThreshold = parseFloat(editFuzzyThreshold);
@@ -251,8 +251,8 @@ export class EditTool implements AgentTool<TInput> {
 		}
 
 		const enableLsp = session.enableLsp ?? true;
-		const enableDiagnostics = enableLsp ? (session.settings?.getLspDiagnosticsOnEdit() ?? false) : false;
-		const enableFormat = enableLsp ? (session.settings?.getLspFormatOnWrite() ?? true) : false;
+		const enableDiagnostics = enableLsp && session.settings.get("lsp.diagnosticsOnEdit");
+		const enableFormat = enableLsp && session.settings.get("lsp.formatOnWrite");
 		this.writethrough = enableLsp
 			? createLspWritethrough(session.cwd, { enableFormat, enableDiagnostics })
 			: writethroughNoop;
@@ -268,11 +268,11 @@ export class EditTool implements AgentTool<TInput> {
 
 		// Auto mode: check model-specific settings
 		const activeModel = this.session.getActiveModelString?.();
-		const modelVariant = this.session.settings?.getEditVariantForModel?.(activeModel);
+		const modelVariant = this.session.settings.getEditVariantForModel(activeModel);
 		if (modelVariant === "replace") return false;
 		if (modelVariant === "patch") return true;
 
-		return this.session.settings?.getEditPatchMode?.() ?? true;
+		return this.session.settings.get("edit.patchMode");
 	}
 
 	/**

package/src/prompts/system/system-prompt.md

@@ -330,7 +330,6 @@ Write what you can defend.
 {{#if isCoordinator}}
 {{#has tools "task"}}
 <critical id="coordinator">
-As the coordinator, **ALWAYS prefer** delegation via Task tool for all SUBSTANTIAL work.
 Your context window is limited—especially the output. Work in discrete steps and run each step using Task tool. Avoid putting substantial work in the main context when possible. Run multiple tasks in parallel whenever possible.
 
 ## Triggers requiring Task tool

package/src/prompts/tools/bash.md

@@ -12,7 +12,7 @@ Executes a bash command in a shell session for terminal operations like git, bun
 
 <output>
 Returns stdout, stderr, and exit code from command execution.
-- Output truncated after 50KB or 2000 lines (whichever comes first); use `| head -n 50` for large output
+- Output truncated after 50KB or 2000 lines (whichever comes first); use `head` parameter to limit output
 - If output is truncated, full output is stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata
 - Exit codes shown on non-zero exit; stderr captured
 </output>
@@ -24,4 +24,14 @@ Do NOT use Bash for these operations—specialized tools exist:
 - Finding files by pattern → Find tool
 - Content-addressed edits → Edit tool
 - Writing new files → Write tool
-</critical>
+</critical>
+
+<avoid>
+Do NOT pipe through `head` or `tail`—use the `head` and `tail` parameters instead:
+- `command | head -n 50` → use `head: 50` parameter
+- `command | tail -n 100` → use `tail: 100` parameter
+
+The pipe pattern breaks streaming output and prevents artifact storage.
+
+Do NOT use `2>&1`—stdout and stderr are already merged.
+</avoid>

package/src/prompts/tools/task.md

@@ -1,22 +1,183 @@
 # Task
 
-Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
+Launch agents to handle complex, multi-step tasks autonomously.
 
 <critical>
-This matters. Get it right.
+## Context is everything
 
-Subagents can access parent conversation context via a file—they can grep or tail it for details you don't include. Don't repeat information unnecessarily; focus `context` on:
-- Task-specific constraints and decisions
-- Critical requirements that must not be missed
-- Information not easily found in the codebase
+Subagents fail when context is vague. They cannot read your mind or infer project conventions. Every task needs:
+1. **Goal** - What this accomplishes (one sentence)
+2. **Constraints** - Hard requirements, banned approaches, naming conventions
+3. **Existing Code** - File paths and function signatures to use as patterns
+4. **API Contract** - If the task produces or consumes an interface, spell it out
 
-Use a single Task call with multiple `tasks` entries when parallelizing. Multiple concurrent Task calls bypass coordination.
+Subagents CAN grep the parent conversation file for supplementary details. They CANNOT grep for:
+- Decisions you made but didn't write down
+- Conventions that exist only in your head
+- Which of 50 possible approaches you want
+  **Rule of thumb:** If you'd need to answer a clarifying question for a junior dev to do this task, that information belongs in context.
+</critical>
 
-For code changes, have subagents write files directly with Edit/Write. Do not ask them to return patches for you to apply.
+<context-structure>
+## Required context structure
 
-Agents with `output="structured"` enforce their own schema; the `schema` parameter is ignored for those agents.
-**Never describe expected output in `context` or task descriptions.** All response format requirements go in the `schema` parameter. Use structured schemas with typed properties—not `{ "type": "string" }`. Prose like "respond as a bullet list" is prohibited.
-</critical>
+Use this template. Sections can be omitted only if truly N/A.
+
+````
+## Goal
+[One sentence: what this task accomplishes]
+
+## Constraints
+- [Hard requirements - MUST/MUST NOT style]
+- [API conventions, naming patterns, error handling]
+- [What already exists vs what to create]
+
+## Existing Code
+Reference files the agent MUST read or use as patterns:
+- `path/to/file.ts` - [what pattern it demonstrates]
+- `path/to/other.rs` - [what to reuse from it]
+
+## API Contract (if applicable)
+```language
+// Exact signatures the agent must implement or consume
+fn example(input: Type) -> Result<Output>
+```
+
+## Task
+{{description}}
+
+## Files
+{{files}}
+````
+
+### Bad context (agent will fail or guess wrong)
+
+```
+N-API migration. Keep highlight sync. Use JsString. No WASM.
+Task: {{description}} Files: {{files}}
+```
+
+Why it fails:
+- No existing code to reference - agent doesn't know your patterns
+- No API contract - agent will invent signatures that don't match consumers
+- No goal - agent doesn't know what success looks like
+- "Keep highlight sync" is meaningless without knowing what highlight is or where it lives
+
+### Good context (agent can act confidently)
+
+````
+## Goal
+Port grep module from WASM to N-API, matching existing text module patterns.
+
+## Constraints
+- Use `#[napi]` attribute macro on all exports (not `#[napi(js_name = "...")]`)
+- Return `napi::Result<T>` for fallible ops, never panic
+- Use `spawn_blocking` for any operation that touches filesystem or runs >1ms
+- Accept `JsString` for string params (NOT JsStringUtf8 - it has lifetime issues)
+- Keep all existing function names - TS bindings depend on them
+- No new crate dependencies
+
+## Existing Code
+- `crates/pi-natives/src/text.rs` - reference N-API pattern: see how `visible_width` uses JsString
+- `crates/pi-natives/src/lib.rs` - module registration pattern
+- `crates/pi-natives/Cargo.toml` - available dependencies (ignore, regex already present)
+
+## API Contract
+Current sync API to convert to async:
+```rust
+// BEFORE (sync, blocks event loop)
+#[napi]
+pub fn search(pattern: String, path: String) -> Vec<Match>
+
+// AFTER (async, uses spawn_blocking)
+#[napi]
+pub async fn search(pattern: JsString, path: JsString, env: Env) -> napi::Result<Vec<Match>>
+```
+
+## Task
+{{description}}
+
+## Files
+{{files}}
+````
+</context-structure>
+
+<parallelization>
+## When to parallelize vs sequence
+**The test:** Can agent B write correct code without seeing agent A's output?
+- If YES → parallelize
+- If NO → sequence (A completes, then B runs with A's output in context)
+
+### Dependency patterns that MUST be sequential
+
+|First|Then|Why|
+|---|---|---|
+|Create Rust API|Update TS bindings|Bindings need to know export names and signatures|
+|Define interface/types|Implement consumers|Consumers need the contract|
+|Scaffold with signatures|Implement bodies|Implementations need the shape|
+|Core module|Dependent modules|Dependents import from core|
+
+### Safe to parallelize
+- Independent modules that don't import each other
+- Tests for already-implemented code
+- Documentation for stable APIs
+- Refactors in isolated file scopes
+
+### Phased execution pattern
+
+For migrations/refactors with layers:
+**Phase 1 - Foundation (do yourself or single task):**
+Create the scaffold, define interfaces, establish API shape. Never fan out until the contract is known.
+**Phase 2 - Parallel implementation:**
+Fan out to independent tasks that all consume the same known interface. Include the API contract from Phase 1 in every task's context.
+**Phase 3 - Integration (do yourself):**
+Wire things together, update build/CI, fix any mismatches.
+**Phase 4 - Dependent layer:**
+Fan out again for work that consumes Phase 2 outputs.
+
+### Example: WASM to N-API migration
+**WRONG** (launched together, will fail):
+
+```
+tasks: [
+  { id: "RustApi", description: "Implement N-API exports" },
+  { id: "TsBindings", description: "Update TS to use N-API" },  // ← needs RustApi output!
+]
+```
+**RIGHT** (phased):
+
+```
+// Phase 1: You create scaffold with signatures in lib.rs
+
+// Phase 2: Fan out Rust implementation
+tasks: [
+  { id: "Grep", description: "Implement grep module", args: { files: "src/grep.rs" } },
+  { id: "Text", description: "Implement text module", args: { files: "src/text.rs" } },
+  // Each task gets the API contract you defined in Phase 1
+]
+
+// Phase 3: You verify Rust compiles, exports are correct
+
+// Phase 4: Fan out TS bindings (now they know what Rust exports)
+tasks: [
+  { id: "GrepBindings", description: "Update grep TS", args: { files: "src/grep/index.ts" } },
+  // Context includes actual export names from Phase 2
+]
+```
+</parallelization>
+
+<parameters>
+- `agent`: Agent type for all tasks
+- `context`: Template with `{{placeholders}}`. **Must follow the structure above.** Include Goal, Constraints, Existing Code references. Subagents can search parent context for background, but core requirements must be explicit here.
+- `isolated`: (optional) Run in git worktree, return patches
+- `tasks`: Array of `{id, description, args}`
+  - `id`: CamelCase identifier (max 32 chars)
+  - `description`: What the task does (for logging)
+  - `args`: Object with keys matching `{{placeholders}}` in context
+  - `skills`: (optional) Skill names to preload
+- `schema`: JTD schema for response structure. **Required.** Use typed properties, not `{ "type": "string" }`.
+**Schema goes in `schema` parameter. Never describe output format in `context`.**
+</parameters>
 
 <agents>
 {{#list agents join="\n"}}
@@ -27,66 +188,12 @@ Agents with `output="structured"` enforce their own schema; the `schema` paramet
 {{/list}}
 </agents>
 
-<instruction>
-This matters. Be thorough.
-1. Plan before acting. Define the goal, acceptance criteria, and scope per task.
-2. Put shared constraints and decisions in `context`; keep each task request short and unambiguous. **Do not describe response format here.**
-3. State whether each task is research-only or should modify files.
-4. **Always provide a `schema`** with typed properties. Avoid `{ "type": "string" }`—if data has any structure (list, fields, categories), model it. Plain text is almost never the right choice.
-5. Assign distinct file scopes per task to avoid conflicts.
-6. Trust the returned data, then verify with tools when correctness matters.
-7. For critical constraints, be explicit in `context`. For general background, subagents can search the parent context file themselves.
-</instruction>
-
-<parameters>
-- `agent`: Agent type to use for all tasks
-- `context`: Template with `\{{placeholders}}` for multi-task. Include critical constraints and task-specific decisions. Subagents have access to parent conversation context via a searchable file, so don't repeat everything—focus on what matters. `\{{id}}` and `\{{description}}` are always available.
-- `isolated`: (optional) Run each task in its own git worktree and return patches; patches are applied only if all apply cleanly.
-- `tasks`: Array of `{id, description, args}` - tasks to run in parallel
-		- `id`: Short CamelCase identifier (max 32 chars, e.g., "SessionStore", "LspRefactor")
-		- `description`: Short human-readable description of what the task does
-		- `args`: Object with keys matching `\{{placeholders}}` in context (always include this, even if empty)
-		- `skills`: (optional) Array of skill names to preload into this task's system prompt. When set, the skills index section is omitted and the full SKILL.md contents are embedded.
-- `schema`: JTD schema defining expected response structure. **Required.** Use objects with typed properties—e.g., `{ "properties": { "items": { "elements": { "type": "string" } } } }` for lists.
-</parameters>
-
-<output>
-Returns task results for each spawned agent:
-- Truncated preview of agent output (use `read agent://<id>` for full content if truncated)
-- Summary with line/character counts
-- For agents with `schema`: structured JSON accessible via `agent://<id>?q=<query>` or `agent://<id>/<path>`
-
-Results are keyed by task `id` (e.g., "AuthProvider", "AuthApi").
-</output>
-
-<example>
-user: "Looks good, execute the plan"
-assistant: I'll execute the refactoring plan.
-assistant: Uses the Task tool:
-{
-  "agent": "task",
-  "context": "Refactoring the auth module into separate concerns.\n\nPlan:\n1. AuthProvider - Extract React context and provider from src/auth/index.tsx\n2. AuthApi - Extract API calls to src/auth/api.ts, use existing fetchJson helper\n3. AuthTypes - Move types to types.ts, re-export from index\n\nConstraints:\n- Preserve all existing exports from src/auth/index.tsx\n- Use project's fetchJson (src/utils/http.ts), don't use raw fetch\n- No new dependencies\n\nTask: \{{step}}\n\nFiles: \{{files}}",
-  "schema": {
-    "properties": {
-      "summary": { "type": "string" },
-      "decisions": { "elements": { "type": "string" } },
-      "concerns": { "elements": { "type": "string" } }
-    }
-  },
-  "tasks": [
-    { "id": "AuthProvider", "description": "Extract React context", "args": { "step": "Execute step 1: Extract AuthProvider and AuthContext", "files": "src/auth/index.tsx" } },
-    { "id": "AuthApi", "description": "Extract API layer", "args": { "step": "Execute step 2: Extract API calls to api.ts", "files": "src/auth/api.ts" } },
-    { "id": "AuthTypes", "description": "Extract types", "args": { "step": "Execute step 3: Move types to types.ts", "files": "src/auth/types.ts" } }
-  ]
-}
-</example>
-
 <avoid>
-- Describing response format in `context` (e.g., "respond as JSON", "return a bullet list")—use `schema` parameter instead
-- Confirmation bias: ask for factual discovery instead of yes/no exploration prompts
-- Reading a specific file path → Use Read tool instead
-- Finding files by pattern/name → Use Find tool instead
-- Searching for a specific class/function definition → Use Grep tool instead
-- Searching code within 2-3 specific files → Use Read tool instead
-- Tasks unrelated to the agent descriptions above
-</avoid>
+- Terse context that requires agents to guess conventions
+- Launching dependent tasks in parallel (bindings + API, consumer + producer)
+- Missing "Existing Code" references - agents need patterns to follow
+- Assuming agents know your codebase - they start fresh each time
+- Describing output format in context instead of schema
+- Single tasks doing too much - prefer focused, file-scoped tasks
+</avoid>
+````