@oh-my-pi/pi-coding-agent 16.3.11 → 16.3.12

package/src/modes/github-ref-autocomplete.ts

@@ -0,0 +1,75 @@
+/**
+ * Autocomplete for GitHub issue/PR references typed as `#<number>` (e.g. `#3164`).
+ *
+ * Mirrors the `@` file-reference and `scheme://` internal-url conventions: the
+ * token is rewritten to an internal URL (`pr://3164` or `issue://3164`) plus a
+ * trailing space, and the existing tool-mediated pipeline (the `read` tool →
+ * InternalUrlRouter → `gh`) resolves it from the session cwd's git remote.
+ *
+ * No network at suggestion time — candidates are generated locally. GitHub
+ * shares the issue/PR number space and there is no cheap way to tell which a
+ * given number is while typing, so both a PR and an Issue candidate are offered
+ * by default. Naming the type first (`pr #3164` / `issue #3164`) constrains the
+ * candidates to that kind. Anything that is not a standalone `#<number>` token
+ * keeps falling through to the existing prompt-action menu.
+ */
+import type { AutocompleteItem } from "@oh-my-pi/pi-tui";
+
+/** Candidate kinds, in default display order. */
+const GITHUB_REF_KINDS = [
+	{ qualifier: "pr", scheme: "pr", label: "PR", description: "GitHub pull request" },
+	{ qualifier: "issue", scheme: "issue", label: "Issue", description: "GitHub issue" },
+] as const;
+
+export interface GithubRefContext {
+	/** Text to replace on accept: `#3164`, or `pr #3164` when a qualifier precedes it. */
+	prefix: string;
+	/** Type the user named (`pr`/`pull` → `pr`, `issue` → `issue`), or null to offer both. */
+	qualifier: "pr" | "issue" | null;
+	/** The numeric reference, e.g. `3164`. */
+	number: string;
+}
+
+/**
+ * A standalone `#<positive-number>` token ending at the cursor. The `#` must be
+ * preceded by a token boundary (start, whitespace, or an opening quote/paren/`<`/`=`,
+ * matching the internal-URL boundary set) so embedded hashes like `owner/repo#N`,
+ * `foo#N`, `C#12`, or a URL fragment do not match. An optional `pr`/`pull`/`issue`
+ * qualifier word (case-insensitive) immediately before the `#` constrains the kind.
+ */
+const GITHUB_REF_TOKEN_RE = /(?:^|[\s"'`(<=])(?:(pr|pull|issue)(\s+))?#([1-9]\d*)$/i;
+
+export function getGithubRefContext(textBeforeCursor: string): GithubRefContext | null {
+	const match = textBeforeCursor.match(GITHUB_REF_TOKEN_RE);
+	if (!match) return null;
+	const qualifierWord = match[1];
+	const whitespace = match[2] ?? "";
+	const number = match[3] ?? "";
+	return {
+		prefix: qualifierWord ? `${qualifierWord}${whitespace}#${number}` : `#${number}`,
+		qualifier: !qualifierWord ? null : qualifierWord.toLowerCase() === "issue" ? "issue" : "pr",
+		number,
+	};
+}
+
+/**
+ * Suggestions for a `#<number>` token. Both kinds are offered unless the user
+ * named a type (`pr #3164` / `issue #3164`), in which case only that kind is
+ * offered. Returns `null` when the text before the cursor is not a standalone
+ * `#<number>` token.
+ */
+export function getGithubRefSuggestions(
+	textBeforeCursor: string,
+): { items: AutocompleteItem[]; prefix: string } | null {
+	const context = getGithubRefContext(textBeforeCursor);
+	if (!context) return null;
+	const kinds = context.qualifier
+		? GITHUB_REF_KINDS.filter(kind => kind.qualifier === context.qualifier)
+		: GITHUB_REF_KINDS;
+	const items: AutocompleteItem[] = kinds.map(kind => ({
+		value: `${kind.scheme}://${context.number}`,
+		label: `${kind.label} #${context.number}`,
+		description: kind.description,
+	}));
+	return { items, prefix: context.prefix };
+}

package/src/modes/interactive-mode.ts

@@ -579,10 +579,10 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.retryLoader.stop();
 			this.retryLoader = undefined;
 		}
-		this.statusContainer.clear();
-		this.pendingMessagesContainer.clear();
+		this.statusContainer.disposeChildren();
+		this.pendingMessagesContainer.disposeChildren();
 		this.#cancelModelCycleClearTimer();
-		this.modelCycleContainer.clear();
+		this.modelCycleContainer.disposeChildren();
 		this.compactionQueuedMessages = [];
 		this.streamingComponent = undefined;
 		this.streamingMessage = undefined;
@@ -2602,6 +2602,49 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
+	#resolveLocalRoot(): string {
+		return resolveLocalUrlToPath("local://", {
+			getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
+			getSessionId: () => this.sessionManager.getSessionId(),
+		});
+	}
+
+	async #copyLocalArtifactsForFreshSession(sourceRoot: string, destinationRoot: string): Promise<void> {
+		if (sourceRoot === destinationRoot) return;
+
+		let sourceRootStat: { isDirectory(): boolean };
+		try {
+			sourceRootStat = await fs.lstat(sourceRoot);
+		} catch (error) {
+			if (isEnoent(error)) return;
+			throw error;
+		}
+
+		if (!sourceRootStat.isDirectory()) return;
+
+		await fs.mkdir(destinationRoot, { recursive: true });
+		await this.#copyLocalArtifactEntries(sourceRoot, destinationRoot);
+	}
+
+	async #copyLocalArtifactEntries(sourceDir: string, destinationDir: string): Promise<void> {
+		const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+		for (const entry of entries) {
+			const sourcePath = path.join(sourceDir, entry.name);
+			const destinationPath = path.join(destinationDir, entry.name);
+
+			if (entry.isDirectory()) {
+				await fs.mkdir(destinationPath, { recursive: true });
+				await this.#copyLocalArtifactEntries(sourcePath, destinationPath);
+				continue;
+			}
+
+			if (entry.isFile()) {
+				await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+				await fs.copyFile(sourcePath, destinationPath);
+			}
+		}
+	}
+
 	async #approvePlan(
 		planContent: string,
 		options: {
@@ -2632,14 +2675,16 @@ export class InteractiveMode implements InteractiveModeContext {
 			});
 
 			if (!options.preserveContext) {
+				const oldLocalRoot = this.#resolveLocalRoot();
 				await this.handleClearCommand();
-				// The new session has a fresh local:// root — persist the approved plan there
-				// so `local://<slug>-plan.md` resolves correctly in the execution session.
+				const newLocalRoot = this.#resolveLocalRoot();
+				await this.#copyLocalArtifactsForFreshSession(oldLocalRoot, newLocalRoot);
 				const newLocalPath = resolveLocalUrlToPath(options.planFilePath, {
 					getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
 					getSessionId: () => this.sessionManager.getSessionId(),
 				});
-				await Bun.write(newLocalPath, planContent);
+				await fs.mkdir(path.dirname(newLocalPath), { recursive: true });
+				await fs.writeFile(newLocalPath, planContent);
 			} else if (options.compactBeforeExecute) {
 				// Distill the plan-mode transcript before the execution turn is queued so
 				// the plan-approved synthetic prompt lands as a fresh cache anchor.
@@ -3626,7 +3671,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	ensureLoadingAnimation(): void {
 		if (!this.loadingAnimation) {
 			this.#clearWorkingMessageAccentCache();
-			this.statusContainer.clear();
+			this.statusContainer.disposeChildren();
 			const messageColorFn = ((message: string) =>
 				renderWorkingMessage(message, this.#getWorkingMessageAccent())) as LoaderMessageColorFn & {
 				animated?: true;
@@ -3647,7 +3692,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			);
 			this.statusContainer.addChild(this.loadingAnimation);
 		} else if (!this.statusContainer.children.includes(this.loadingAnimation)) {
-			this.statusContainer.clear();
+			this.statusContainer.disposeChildren();
 			this.statusContainer.addChild(this.loadingAnimation);
 			this.ui.requestRender();
 		}
@@ -3660,7 +3705,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.loadingAnimation = undefined;
 		this.#clearWorkingMessageAccentCache();
 		if (clearStatusContainer) {
-			this.statusContainer.clear();
+			this.statusContainer.disposeChildren();
 		}
 	}
 
@@ -4123,7 +4168,6 @@ export class InteractiveMode implements InteractiveModeContext {
 			}
 			this.#btwController.dispose();
 			this.#omfgController.dispose();
-			this.chatContainer.clear();
 			this.renderInitialMessages({ clearTerminalHistory: true });
 			this.updateEditorBorderColor();
 			this.showStatus(

package/src/modes/prompt-action-autocomplete.ts

@@ -9,6 +9,7 @@ import {
 import { formatKeyHints, type KeybindingsManager } from "../config/keybindings";
 import { isSettingsInitialized, settings } from "../config/settings";
 import { applyEmojiCompletion, getEmojiSuggestions, isEmojiPrefix, tryEmojiInlineReplace } from "./emoji-autocomplete";
+import { getGithubRefContext, getGithubRefSuggestions } from "./github-ref-autocomplete";
 import {
 	applyInternalUrlCompletion,
 	getInternalUrlSuggestions,
@@ -94,6 +95,36 @@ function getPromptActionPrefix(textBeforeCursor: string): string | null {
 	return textBeforeCursor.slice(hashIndex);
 }
 
+function applyGithubRefCompletion(
+	lines: string[],
+	cursorLine: number,
+	cursorCol: number,
+	item: AutocompleteItem,
+	prefix: string,
+): { lines: string[]; cursorLine: number; cursorCol: number } | null {
+	if (!getGithubRefContext(prefix)) return null;
+	const scheme: "pr" | "issue" | null = item.value.startsWith("pr://")
+		? "pr"
+		: item.value.startsWith("issue://")
+			? "issue"
+			: null;
+	if (!scheme) return { lines, cursorLine, cursorCol };
+
+	const currentLine = lines[cursorLine] || "";
+	const liveContext = getGithubRefContext(currentLine.slice(0, cursorCol));
+	if (!liveContext || (liveContext.qualifier && liveContext.qualifier !== scheme)) {
+		return { lines, cursorLine, cursorCol };
+	}
+
+	return applyInternalUrlCompletion(
+		lines,
+		cursorLine,
+		cursorCol,
+		{ ...item, value: `${scheme}://${liveContext.number}` },
+		liveContext.prefix,
+	);
+}
+
 export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 	#commands: SlashCommand[];
 	#baseProvider: CombinedAutocompleteProvider;
@@ -129,6 +160,8 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			}
 		}
 
+		const githubRefSuggestions = getGithubRefSuggestions(textBeforeCursor);
+		if (githubRefSuggestions) return githubRefSuggestions;
 		const promptActionPrefix = getPromptActionPrefix(textBeforeCursor);
 		if (promptActionPrefix) {
 			const query = promptActionPrefix.slice(1).toLowerCase();
@@ -176,6 +209,8 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 		cursorCol: number;
 		onApplied?: () => void;
 	} {
+		const githubRefCompletion = applyGithubRefCompletion(lines, cursorLine, cursorCol, item, prefix);
+		if (githubRefCompletion) return githubRefCompletion;
 		if (prefix.startsWith("#") && isPromptActionItem(item)) {
 			if (item.actionId === "undo") {
 				return {

package/src/modes/utils/context-usage.ts

@@ -43,6 +43,7 @@ export interface ContextBreakdown {
 
 const EMPTY_STRING_PARTS: readonly string[] = [];
 const EMPTY_TOOLS: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">> = [];
+const EMPTY_SKILLS: readonly Skill[] = [];
 
 export function estimateSkillsTokens(skills: readonly Skill[]): number {
 	const fragments: string[] = [];
@@ -86,10 +87,58 @@ export function estimateToolSchemaTokens(
  * cadence — non-message recomputed only when the inputs identity changes,
  * messages walked incrementally as new entries append.
  */
+// Non-message inputs (system prompt, tools, skills) change rarely — at most
+// once per turn via setSystemPrompt/setTools — but the per-turn compaction and
+// threshold paths call these helpers several times: getContextBreakdown calls
+// both, and #estimateStoredContextTokens adds a third. Memoize on the identity
+// of the three input arrays so the expensive parts (system-prompt tokenization
+// and the per-tool JSON.stringify(toolWireSchema) inside estimateToolSchemaTokens)
+// run at most once per input change rather than per call. The identity keys are
+// the same stable references the StatusLineComponent cache already trusts
+// (setSystemPrompt/setTools replace the array reference rather than mutating it).
+interface NonMessageTokenCache {
+	systemPromptRef: readonly string[];
+	toolsRef: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>;
+	skillsRef: readonly Skill[];
+	tokens: number | undefined;
+	breakdown:
+		| {
+				skillsTokens: number;
+				toolsTokens: number;
+				systemContextTokens: number;
+				systemPromptTokens: number;
+		  }
+		| undefined;
+}
+
+const nonMessageTokenCache = new WeakMap<AgentSession, NonMessageTokenCache>();
+
+function nonMessageTokenCacheEntry(session: AgentSession): NonMessageTokenCache {
+	const systemPromptRef = session.systemPrompt ?? EMPTY_STRING_PARTS;
+	const toolsRef = session.agent?.state?.tools ?? EMPTY_TOOLS;
+	const skillsRef = session.skills ?? EMPTY_SKILLS;
+	let entry = nonMessageTokenCache.get(session);
+	if (
+		entry &&
+		entry.systemPromptRef === systemPromptRef &&
+		entry.toolsRef === toolsRef &&
+		entry.skillsRef === skillsRef
+	) {
+		return entry;
+	}
+	entry = { systemPromptRef, toolsRef, skillsRef, tokens: undefined, breakdown: undefined };
+	nonMessageTokenCache.set(session, entry);
+	return entry;
+}
+
 export function computeNonMessageTokens(session: AgentSession): number {
+	const entry = nonMessageTokenCacheEntry(session);
+	if (entry.tokens !== undefined) return entry.tokens;
 	const systemPromptParts = session.systemPrompt ?? EMPTY_STRING_PARTS;
 	const tools = session.agent?.state?.tools ?? EMPTY_TOOLS;
-	return countTokens(systemPromptParts) + estimateToolSchemaTokens(tools);
+	const tokens = countTokens(systemPromptParts) + estimateToolSchemaTokens(tools);
+	entry.tokens = tokens;
+	return tokens;
 }
 
 /**
@@ -104,12 +153,16 @@ export function computeNonMessageBreakdown(session: AgentSession): {
 	systemContextTokens: number;
 	systemPromptTokens: number;
 } {
-	const skillsTokens = estimateSkillsTokens(session.skills ?? []);
-	const toolsTokens = estimateToolSchemaTokens(session.agent?.state?.tools ?? []);
-	const systemPromptParts = session.systemPrompt ?? [];
+	const entry = nonMessageTokenCacheEntry(session);
+	if (entry.breakdown) return entry.breakdown;
+	const skillsTokens = estimateSkillsTokens(session.skills ?? EMPTY_SKILLS);
+	const toolsTokens = estimateToolSchemaTokens(session.agent?.state?.tools ?? EMPTY_TOOLS);
+	const systemPromptParts = session.systemPrompt ?? EMPTY_STRING_PARTS;
 	const systemContextTokens = countTokens(systemPromptParts.slice(1));
 	const systemPromptTokens = Math.max(0, countTokens(systemPromptParts[0] ?? "") - skillsTokens);
-	return { skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens };
+	const breakdown = { skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens };
+	entry.breakdown = breakdown;
+	return breakdown;
 }
 
 /**

package/src/modes/utils/hotkeys-markdown.ts

@@ -52,7 +52,8 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | Paste image or text from clipboard |`,
 		"| Hold `Space` | Speech-to-text (push-to-talk): hold to record, release to transcribe |",
 		`| \`${appKey(bindings, "app.agents.hub")}\` / \`${appKey(bindings, "app.session.observe")}\` / double-tap \`←\` (empty editor) | Open the agent hub |`,
-		"| `#` | Open prompt actions |",
+		"| `#<number>` | GitHub issue/PR reference (e.g. `#3164` → `pr://`/`issue://`) |",
+		"| `#` / `#<text>` | Prompt actions (copy / undo / move cursor) |",
 		"| `/` | Slash commands |",
 		"| `!` | Run bash command |",
 		"| `!!` | Run bash command (excluded from context) |",

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

@@ -581,7 +581,7 @@ export class UiHelpers {
 		} else {
 			this.ctx.resetTranscript();
 		}
-		this.ctx.pendingMessagesContainer.clear();
+		this.ctx.pendingMessagesContainer.disposeChildren();
 		this.ctx.pendingBashComponents = [];
 		this.ctx.pendingPythonComponents = [];
 
@@ -647,7 +647,7 @@ export class UiHelpers {
 	}
 
 	updatePendingMessagesDisplay(): void {
-		this.ctx.pendingMessagesContainer.clear();
+		this.ctx.pendingMessagesContainer.disposeChildren();
 		const queuedMessages = this.ctx.viewSession.getQueuedMessages() as QueuedMessages;
 
 		const steeringMessages: Array<{ message: string; label: string }> = [];

package/src/modes/workflow.ts

@@ -1,4 +1,5 @@
-import workflowNotice from "../prompts/system/workflow-notice.md" with { type: "text" };
+import { prompt } from "@oh-my-pi/pi-utils";
+import workflowNoticeTemplate from "../prompts/system/workflow-notice.md" with { type: "text" };
 import { createGradientHighlighter, type KeywordHighlighter } from "./gradient-highlight";
 import { keywordInProse } from "./markdown-prose";
 
@@ -7,18 +8,23 @@ import { keywordInProse } from "./markdown-prose";
  *
  * Typing the standalone word in the input editor paints it with a warm
  * amber→green gradient ({@link highlightWorkflow}); submitting a message that
- * mentions it appends a hidden {@link WORKFLOW_NOTICE} that steers the model to
- * author a deterministic multi-subagent workflow in eval cells (agent/parallel/
- * pipeline). Matching is whitespace-delimited and case-sensitive (lowercase
- * only) — "workflowz" triggers, but "workflowzed", "Workflowz", and
- * "workflowz.ts" never do.
+ * mentions it appends a hidden workflow notice that steers the model to author
+ * a deterministic multi-subagent workflow through the active task schema.
+ * Matching is whitespace-delimited and case-sensitive (lowercase only) —
+ * "workflowz" triggers, but "workflowzed", "Workflowz", and "workflowz.ts"
+ * never do.
  */
 
 // Detection: lowercase keyword flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
 const WORKFLOW_WORD = /(?<!\S)workflowz(?!\S)/;
 
-/** Hidden system notice appended after a user message that mentions "workflowz". */
-export const WORKFLOW_NOTICE: string = workflowNotice.trim();
+/** WORKFLOW_NOTICE is the default hidden notice for sessions with batched task calls enabled. */
+export const WORKFLOW_NOTICE: string = renderWorkflowNotice({ taskBatch: true });
+
+/** renderWorkflowNotice renders the workflow notice for the active task schema. */
+export function renderWorkflowNotice({ taskBatch }: { taskBatch: boolean }): string {
+	return prompt.render(workflowNoticeTemplate, { taskBatch }).trim();
+}
 
 /**
  * Whether `text` contains the standalone keyword "workflowz"

package/src/prompts/system/plan-mode-active.md

@@ -1,7 +1,10 @@
 <critical>
-Plan mode is active. You MUST perform READ-ONLY work only:
-- You NEVER create, edit, or delete files — except the single plan file named below.
+Plan mode is active. You MUST preserve read-only working-tree and system semantics:
+- You NEVER create, edit, delete, or rename working-tree files.
 - You NEVER run state-changing commands (`git commit`, `npm install`, migrations) or make any other system change.
+- `local://` artifacts are session-local planning artifacts. You MAY create or update them when explicitly requested or needed for the plan.
+- You NEVER delete or rename `local://` artifacts.
+- You MUST write the canonical plan to `local://<slug>-plan.md`.
 
 To leave plan mode and implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<slug>" }`, where `<slug>` matches your `local://<slug>-plan.md`. The user then picks an execution option and full write access is restored. `<slug>` may contain only letters, numbers, underscores, and hyphens.
 

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

@@ -110,9 +110,8 @@ You MUST use the specialized tool over its shell equivalent:
 {{#has tools "lsp"}}- Code intelligence → `{{toolRefs.lsp}}`.{{/has}}
 {{#has tools "grep"}}- Regex search → `{{toolRefs.grep}}`, not `grep`, `rg`, or `awk`.{{/has}}
 {{#has tools "glob"}}- Globbing → `{{toolRefs.glob}}`, not `ls **/*.ext` or `fd`.{{/has}}
-{{#has tools "eval"}}- Default for any compute: `{{toolRefs.eval}}` cells. Bash is the EXCEPTION — only single binary calls or short fact-computing pipelines (`wc -l`, `sort | uniq -c`, `diff`, checksums). The moment a command grows a loop, conditional, heredoc, `-e`/`-c` script, `$(…)` nesting, or >2 pipe stages, it's a program → `{{toolRefs.eval}}`. NEVER write multiline or inline-script bash.{{/has}}
 {{#has tools "bash"}}- `{{toolRefs.bash}}`: real binaries and short fact pipelines only. Commands shadowing the specialized tools above are blocked.{{/has}}
-{{#has tools "bash"}}- Litmus: one external-CLI call or short pipeline returning a count, frequency, set difference, or checksum → bash.{{#has tools "eval"}} Needs control flow, state, or fights shell quoting → `{{toolRefs.eval}}`.{{/has}} Merely moves, pages, or trims bytes a tool can fetch → use the tool.{{/has}}
+{{#has tools "bash"}}- Litmus: one external-CLI call or short pipeline returning a count, frequency, set difference, or checksum → bash. Merely moves, pages, or trims bytes a tool can fetch → use the tool.{{/has}}
 
 {{#has tools "report_tool_issue"}}
 <critical>

package/src/prompts/system/workflow-notice.md

@@ -1,70 +1,89 @@
 <system-notice>
-The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration as Python in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
+The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Use the `task` tool {{#if taskBatch}}for batched fan-out{{else}}once per independent subagent{{/if}} — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
 
 <when>
-Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline FIRST (list the files, scope the diff, find the call sites) to discover the work-list, then fan out over it — you don't need to know the shape before the *task*, only before the *fan-out*. Common shapes, each a well-scoped `eval` call you can chain across turns:
-- **Understand** — parallel readers over subsystems → structured map
-- **Design** — judge panel of N independent approaches → scored synthesis
-- **Review** — split into dimensions → find per dimension → adversarially verify each finding
-- **Research** — multi-modal sweep → deep-read the hits → synthesize
-- **Migrate** — discover sites → transform each → verify
+Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline first (list the files, scope the diff, find the call sites) to discover the work list, then fan out over it. Common shapes:
+- **Understand** — parallel readers over subsystems → structured map.
+- **Design** — independent approaches → scored synthesis.
+- **Review** — split dimensions → find per dimension → adversarially verify each finding.
+- **Research** — multi-modal sweep → deep-read the hits → synthesize.
+- **Migrate** — discover sites → transform each → verify.
 </when>
 
-<helpers>
-State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
+<task-contract>
+{{#if taskBatch}}
+Call `task` once per independent fan-out batch. Put shared background in `context`, and put each independent work item in `tasks[]`. Do not emulate batching with shell loops or eval helper APIs.
 
-- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("explore", "reviewer", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes. Recursion follows `task.maxRecursionDepth` (default 2; `-1` uses eval's hard cap 3): main agent depth = 0, each `agent()` child increments depth by 1, and a spawner may call `agent()` only while its current `taskDepth < effective cap`. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
-- `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
-- `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
-- `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.
-- `log(message)` — emit a progress line above the status tree. `phase(title)` — start a phase; the status lines that follow group under it.
-- `budget` — `budget.total` (output-token ceiling, or `None` when none is set), `budget.spent()` (tokens spent this turn — main loop + eval subagents), `budget.remaining()` (`math.inf` when total is `None`), `budget.hard` (whether it's enforced). A ceiling is set by the user: `+Nk` in their message is advisory (you self-limit via `budget.remaining()`), `+Nk!` (or Goal Mode) is hard — `agent()` refuses to spawn once spent reaches it. Gate loops on `budget.total` first, since it's `None` when the user set no budget.
+`context` must carry the shared contract:
 
-Everything runs INLINE and synchronously inside the eval call — no background mode, no resume, no separate progress app. Each eval call is one well-scoped fan-out; chain several across calls and turns for multi-phase work, reading each result before you decide the next phase.
-</helpers>
+    # Goal
+    What the batch accomplishes.
+    # Constraints
+    Rules, non-goals, permissions, and verification limits.
+    # Contract
+    Shared interfaces, output shape, branch/base assumptions, and coordination rules.
 
-<structure>
-For independent per-item chains (review → verify, fetch → extract → score), wrap the WHOLE chain in one function and run it with `parallel()` — then each item flows through its own steps without waiting on the others:
+Each task assignment must be self-contained:
+
+    # Target
+    Exact files, symbols, subsystem, or evidence surface; explicit non-goals.
+    # Change
+    What to inspect or modify, step by step, including APIs and patterns to reuse.
+    # Acceptance
+    Observable result, return packet, and local verification. Subagents skip formatters,
+    linters, and project-wide tests; the parent runs shared proof once.
+{{else}}
+Call `task` once per independent subagent. Put the full shared background and the leaf work in that call's `assignment`. Do not pass `context` or `tasks[]`: the flat task schema rejects them when batch calls are disabled.
 
-    DIMENSIONS = [{"key": "bugs", "prompt": "…"}, {"key": "perf", "prompt": "…"}]
-    def review_and_verify(d):
-        found = agent(d["prompt"], label=f"review:{d['key']}", schema=FINDINGS_SCHEMA)
-        return parallel([lambda f=f: {**f, "verdict": agent(
-            f"Refute if you can (default refuted when unsure): {f['title']}",
-            label=f"verify:{f['file']}", schema=VERDICT_SCHEMA)} for f in found["findings"]])
-    phase("Review")
-    results = parallel([lambda d=d: review_and_verify(d) for d in DIMENSIONS])
-    confirmed = [f for group in results for f in group if f["verdict"]["is_real"]]
+Each assignment must be self-contained:
 
-Reach for `pipeline()` only when a stage genuinely needs ALL of the previous stage first — dedup/merge across the whole set, early-exit on zero, or "compare against the other findings" — because its inter-stage barrier makes every item wait for the slowest peer:
+    # Target
+    Exact files, symbols, subsystem, or evidence surface; explicit non-goals.
+    # Change
+    Shared background plus what to inspect or modify, step by step, including APIs and patterns to reuse.
+    # Acceptance
+    Observable result, return packet, and local verification. Subagents skip formatters,
+    linters, and project-wide tests; the parent runs shared proof once.
+{{/if}}
 
-    phase("Find")
-    found = parallel([lambda d=d: agent(d["prompt"], schema=FINDINGS_SCHEMA) for d in DIMENSIONS])
-    findings = dedupe([f for r in found for f in r["findings"]])   # needs everything at once
-    phase("Verify")
-    verdicts = parallel([lambda f=f: agent(verify_prompt(f), schema=VERDICT_SCHEMA) for f in findings])
+<structure>
+Decompose first, then {{#if taskBatch}}batch the independent leaves{{else}}issue one independent task call per leaf in the same turn{{/if}}:
 
-Don't add a barrier just to flatten/map/filter — do that with plain Python between calls. Nested `parallel()` pools each cap independently, so keep total fan-out sane.
+{{#if taskBatch}}
+    task(
+      context: "# Goal\nReview the auth diff...\n# Constraints\nRead-only...\n# Contract\nReturn findings as severity/file/line/fix...",
+      tasks: [
+        { id: "AuthOwner", role: "Auth Storage Reviewer", assignment: "# Target\npackages/ai/src/auth-storage.ts\n# Change\nTrace credential selection...\n# Acceptance\nReturn confirmed findings only..." },
+        { id: "PromptOwner", role: "Prompt Contract Reviewer", assignment: "# Target\npackages/coding-agent/src/prompts/**\n# Change\nCheck active-tool guidance...\n# Acceptance\nReturn mismatches and exact prompt lines..." },
+      ]
+    )
+{{else}}
+    task(
+      role: "Auth Storage Reviewer",
+      assignment: "# Target\npackages/ai/src/auth-storage.ts\n# Change\nReview the auth diff. Shared contract: read-only; return findings as severity/file/line/fix.\n# Acceptance\nReturn confirmed findings only..."
+    )
+    task(
+      role: "Prompt Contract Reviewer",
+      assignment: "# Target\npackages/coding-agent/src/prompts/**\n# Change\nCheck active-tool guidance. Shared contract: read-only; return mismatches and exact prompt lines.\n# Acceptance\nReturn confirmed findings only..."
+    )
+{{/if}}
+
+{{#if taskBatch}}Prefer one wide batch over serial subagent calls when work items do not share files. If tasks overlap, name the overlap and have agents coordinate through IRC before editing.{{else}}Prefer issuing all independent task calls in one assistant turn over serial dispatch when work items do not share files. If tasks overlap, name the overlap and have agents coordinate through IRC before editing.{{/if}}
 </structure>
 
 <patterns>
-Compose the harness the task calls for:
-- **Adversarial verify** — N independent skeptics per finding, each prompted to REFUTE; keep it only if a majority survive. `votes = parallel([lambda i=i: agent(f"Refute: {claim}. refuted=true if unsure.", schema=VERDICT) for i in range(3)])`, then keep when `sum(not v["refuted"] for v in votes) ≥ 2`.
-- **Perspective-diverse verify** — give each verifier a distinct lens (correctness, security, perf, does-it-reproduce) instead of N identical refuters.
-- **Judge panel** — N attempts from different angles, scored by parallel judges; synthesize from the winner, graft the best of the rest.
-- **Loop-until-dry** — for unknown-size discovery, keep spawning finders until K consecutive rounds surface nothing new; dedup against everything SEEN, not just what was confirmed, or it never converges.
-- **Multi-modal sweep** — parallel finders each searching a different way (by-container, by-content, by-entity, by-time), each blind to the others.
-- **Completeness critic** — a final agent that asks "what's missing — modality not run, claim unverified, file unread?"; its answer is the next round.
-- **Budget/count loops** — `while len(bugs) < 10:` to hit a target, or `while budget.total and budget.remaining() > 50_000:` to scale depth to the turn budget; `log()` each round.
-- **No silent caps** — if you bound coverage (top-N, no-retry, sampling), `log()` what you dropped; silent truncation reads as "covered everything" when it didn't.
-
-Scale to the ask: "find any bugs" → a few finders, single-vote verify. "thoroughly audit / be comprehensive" → larger finder pool, 3–5-vote adversarial pass, a synthesis stage.
+- **Adversarial verify** — dispatch skeptical reviewers with distinct targets, then keep only findings the parent can verify against source.
+- **Perspective-diverse review** — use separate correctness, security, performance, and maintainability roles instead of identical reviewers.
+- **Completeness critic** — after the first batch, dispatch one read-only critic that asks what modality, file, claim, or proof was missed.
+- **No silent caps** — if you bound coverage (top-N, no retry, sampling), state what was dropped and why before acting.
+- **Parent owns closure** — subagents return evidence; the parent reads it, resolves contradictions, runs proof, and makes the final decision.
 </patterns>
 
 <execution>
-- Decompose the surface first; capture it in `todo` when it spans phases.
-- Prefer `schema=` for any agent whose output you branch on.
-- After a fan-out returns, YOU own correctness: read the artifacts, run the gate, verify before acting. Subagents do the legwork; they don't get the last word.
-- Keep going until the task is closed — a returned fan-out is a step, not a stopping point.
+- Capture multi-phase workflow state in the visible todo system when available.
+{{#if taskBatch}}- Batch independent subagents in one `task` call.{{else}}- Dispatch independent subagents as separate `task` calls in the same turn.{{/if}}
+- Give every subagent a narrow target, explicit non-goals, and a concrete return packet.
+- After fan-out returns, read the artifacts, patch or decide, and run the shared gate.
+- Keep going until the task is closed — returned fan-out is a step, not a stopping point.
 </execution>
 </system-notice>