@oh-my-pi/pi-coding-agent 12.18.1 → 12.19.0

package/src/patch/normalize.ts

@@ -206,72 +206,29 @@ export function convertLeadingTabsToSpaces(text: string, spacesPerTab: number):
 // Unicode Normalization
 // ═══════════════════════════════════════════════════════════════════════════
 
-/**
- * Normalize common Unicode punctuation to ASCII equivalents.
- * Allows diffs with ASCII characters to match source files with typographic punctuation.
- */
-export function normalizeUnicode(s: string): string {
-	return s
-		.trim()
-		.split("")
-		.map(c => {
-			const code = c.charCodeAt(0);
-
-			// Various dash/hyphen code-points → ASCII '-'
-			if (
-				code === 0x2010 || // HYPHEN
-				code === 0x2011 || // NON-BREAKING HYPHEN
-				code === 0x2012 || // FIGURE DASH
-				code === 0x2013 || // EN DASH
-				code === 0x2014 || // EM DASH
-				code === 0x2015 || // HORIZONTAL BAR
-				code === 0x2212 // MINUS SIGN
-			) {
-				return "-";
-			}
+const UNICODE_REPLACEMENTS: [RegExp, string][] = [
+	// Various dash/hyphen code-points → ASCII '-'
+	[/[\u2010-\u2015\u2212]/g, "-"],
+	// Fancy single quotes → '
+	[/[\u2018-\u201B]/g, "'"],
+	// Fancy double quotes → "
+	[/[\u201C-\u201F]/g, '"'],
+	// Non-breaking space and other odd spaces → normal space
+	[/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " "],
+	// Not-equal sign → !=
+	[/\u2260/g, "!="],
+	// Vulgar fraction ½ → 1/2
+	[/\u00BD/g, "1/2"],
+	// Zero-width characters → remove
+	[/[\u200B-\u200D\uFEFF]/g, ""],
+];
 
-			// Fancy single quotes → '
-			if (
-				code === 0x2018 || // LEFT SINGLE QUOTATION MARK
-				code === 0x2019 || // RIGHT SINGLE QUOTATION MARK
-				code === 0x201a || // SINGLE LOW-9 QUOTATION MARK
-				code === 0x201b // SINGLE HIGH-REVERSED-9 QUOTATION MARK
-			) {
-				return "'";
-			}
-
-			// Fancy double quotes → "
-			if (
-				code === 0x201c || // LEFT DOUBLE QUOTATION MARK
-				code === 0x201d || // RIGHT DOUBLE QUOTATION MARK
-				code === 0x201e || // DOUBLE LOW-9 QUOTATION MARK
-				code === 0x201f // DOUBLE HIGH-REVERSED-9 QUOTATION MARK
-			) {
-				return '"';
-			}
-
-			// Non-breaking space and other odd spaces → normal space
-			if (
-				code === 0x00a0 || // NO-BREAK SPACE
-				code === 0x2002 || // EN SPACE
-				code === 0x2003 || // EM SPACE
-				code === 0x2004 || // THREE-PER-EM SPACE
-				code === 0x2005 || // FOUR-PER-EM SPACE
-				code === 0x2006 || // SIX-PER-EM SPACE
-				code === 0x2007 || // FIGURE SPACE
-				code === 0x2008 || // PUNCTUATION SPACE
-				code === 0x2009 || // THIN SPACE
-				code === 0x200a || // HAIR SPACE
-				code === 0x202f || // NARROW NO-BREAK SPACE
-				code === 0x205f || // MEDIUM MATHEMATICAL SPACE
-				code === 0x3000 // IDEOGRAPHIC SPACE
-			) {
-				return " ";
-			}
-
-			return c;
-		})
-		.join("");
+export function normalizeUnicode(s: string): string {
+	let result = s.trim();
+	for (const [pattern, replacement] of UNICODE_REPLACEMENTS) {
+		result = result.replace(pattern, replacement);
+	}
+	return result.normalize("NFC");
 }
 
 /**

package/src/patch/shared.ts

@@ -10,13 +10,15 @@ import { renderDiff as renderDiffColored } from "../modes/components/diff";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
 import type { OutputMeta } from "../tools/output-meta";
 import {
+	formatDiagnostics,
+	formatDiffStats,
 	formatExpandHint,
 	formatStatusIcon,
+	formatTitle,
 	getDiffStats,
 	PREVIEW_LIMITS,
 	replaceTabs,
 	shortenPath,
-	ToolUIKit,
 	truncateDiffByHunk,
 } from "../tools/render-utils";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
@@ -120,7 +122,7 @@ function formatStreamingDiff(diff: string, rawPath: string, uiTheme: Theme, labe
 	return text;
 }
 
-function formatStreamingHashlineEdits(edits: unknown[], uiTheme: Theme, ui: ToolUIKit): string {
+function formatStreamingHashlineEdits(edits: unknown[], uiTheme: Theme): string {
 	const MAX_EDITS = 4;
 	const MAX_DST_LINES = 8;
 	let text = "\n\n";
@@ -132,17 +134,17 @@ function formatStreamingHashlineEdits(edits: unknown[], uiTheme: Theme, ui: Tool
 		shownEdits++;
 		if (shownEdits > MAX_EDITS) break;
 		const formatted = formatHashlineEdit(edit);
-		text += uiTheme.fg("toolOutput", ui.truncate(replaceTabs(formatted.srcLabel), 120));
+		text += uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(formatted.srcLabel), 120));
 		text += "\n";
 		if (formatted.dst === "") {
-			text += uiTheme.fg("dim", ui.truncate("  (delete)", 120));
+			text += uiTheme.fg("dim", truncateToWidth("  (delete)", 120));
 			text += "\n";
 			continue;
 		}
 		for (const dstLine of formatted.dst.split("\n")) {
 			shownDstLines++;
 			if (shownDstLines > MAX_DST_LINES) break;
-			text += uiTheme.fg("toolOutput", ui.truncate(replaceTabs(`+ ${dstLine}`), 120));
+			text += uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(`+ ${dstLine}`), 120));
 			text += "\n";
 		}
 		if (shownDstLines > MAX_DST_LINES) break;
@@ -221,15 +223,15 @@ function renderDiffSection(
 	rawPath: string,
 	expanded: boolean,
 	uiTheme: Theme,
-	ui: ToolUIKit,
 	renderDiffFn: (t: string, o?: { filePath?: string }) => string,
 ): string {
 	let text = "";
 	const diffStats = getDiffStats(diff);
-	text += `\n${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${ui.formatDiffStats(
+	text += `\n${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${formatDiffStats(
 		diffStats.added,
 		diffStats.removed,
 		diffStats.hunks,
+		uiTheme,
 	)}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
 
 	const {
@@ -254,7 +256,6 @@ export const editToolRenderer = {
 	mergeCallAndResult: true,
 
 	renderCall(args: EditRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
-		const ui = new ToolUIKit(uiTheme);
 		const rawPath = args.file_path || args.path || "";
 		const filePath = shortenPath(rawPath);
 		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
@@ -270,7 +271,7 @@ export const editToolRenderer = {
 		const opTitle = args.op === "create" ? "Create" : args.op === "delete" ? "Delete" : "Edit";
 		const spinner =
 			options?.spinnerFrame !== undefined ? formatStatusIcon("running", uiTheme, options.spinnerFrame) : "";
-		let text = `${ui.title(opTitle)} ${spinner ? `${spinner} ` : ""}${editIcon} ${pathDisplay}`;
+		let text = `${formatTitle(opTitle, uiTheme)} ${spinner ? `${spinner} ` : ""}${editIcon} ${pathDisplay}`;
 
 		// Show streaming preview of diff/content
 		if (args.previewDiff) {
@@ -278,13 +279,13 @@ export const editToolRenderer = {
 		} else if (args.diff && args.op) {
 			text += formatStreamingDiff(args.diff, rawPath, uiTheme);
 		} else if (args.edits && args.edits.length > 0) {
-			text += formatStreamingHashlineEdits(args.edits, uiTheme, ui);
+			text += formatStreamingHashlineEdits(args.edits, uiTheme);
 		} else if (args.diff) {
 			const previewLines = args.diff.split("\n");
 			const maxLines = 6;
 			text += "\n\n";
 			for (const line of previewLines.slice(0, maxLines)) {
-				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+				text += `${uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(line), 80))}\n`;
 			}
 			if (previewLines.length > maxLines) {
 				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
@@ -294,7 +295,7 @@ export const editToolRenderer = {
 			const maxLines = 6;
 			text += "\n\n";
 			for (const line of previewLines.slice(0, maxLines)) {
-				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+				text += `${uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(line), 80))}\n`;
 			}
 			if (previewLines.length > maxLines) {
 				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
@@ -310,7 +311,6 @@ export const editToolRenderer = {
 		uiTheme: Theme,
 		args?: EditRenderArgs,
 	): Component {
-		const ui = new ToolUIKit(uiTheme);
 		const rawPath = args?.file_path || args?.path || "";
 		const filePath = shortenPath(rawPath);
 		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
@@ -370,18 +370,18 @@ export const editToolRenderer = {
 						text += `\n\n${uiTheme.fg("error", replaceTabs(errorText))}`;
 					}
 				} else if (result.details?.diff) {
-					text += renderDiffSection(result.details.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+					text += renderDiffSection(result.details.diff, rawPath, expanded, uiTheme, renderDiffFn);
 				} else if (editDiffPreview) {
 					if ("error" in editDiffPreview) {
 						text += `\n\n${uiTheme.fg("error", replaceTabs(editDiffPreview.error))}`;
 					} else if (editDiffPreview.diff) {
-						text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+						text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, renderDiffFn);
 					}
 				}
 
 				// Show LSP diagnostics if available
 				if (result.details?.diagnostics) {
-					text += ui.formatDiagnostics(result.details.diagnostics, expanded, (fp: string) =>
+					text += formatDiagnostics(result.details.diagnostics, expanded, uiTheme, (fp: string) =>
 						uiTheme.getLangIcon(getLanguageFromPath(fp)),
 					);
 				}

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

@@ -16,16 +16,6 @@
 </file>
 {{/list}}
 </instructions>
-{{/if}}
-{{#if git.isRepo}}
-## Version Control
-Snapshot; does not update during conversation.
-Current branch: {{git.currentBranch}}
-Main branch: {{git.mainBranch}}
-{{git.status}}
-### History
-{{git.commits}}
-{{/if}}
 </project>
 {{/ifAny}}
 {{#if skills.length}}

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

@@ -10,22 +10,28 @@ Say truth; omit filler. No apologies. No comfort where clarity belongs.
 Push back when warranted: state downside, propose alternative, accept override.
 </identity>
 
+<output_style>
+- No summary closings ("In summary…"). No filler. No emojis. No ceremony.
+- Suppress: "genuinely", "honestly", "straightforward".
+- User execution-mode instructions (do-it-yourself vs delegate) override tool-use defaults.
+- Requirements conflict or are unclear → ask only after exhaustive exploration.
+</output_style>
+
 <discipline>
-Notice the completion reflex before it fires:
-- Urge to produce something that runs
-- Pattern-matching to similar problems
-- Assumption that compiling = correct
-- Satisfaction at "it works" before "works in all cases"
-
-Before writing code, think through:
-- What are my assumptions about input? About environment?
-- What breaks this?
-- What would a malicious caller do?
+**Guard against the completion reflex** — the urge to ship something that compiles before you've understood the problem:
+- Resist pattern-matching to a similar problem before reading this one
+- Compiling ≠ correct; "it works" ≠ "works in all cases"
+**Before acting on any change**, think through:
+- What are my assumptions about input, environment, callers?
+- What breaks this? What would a malicious caller do?
 - Would a tired maintainer misunderstand this?
-- Can this be simpler?
-- Are these abstractions earning their keep?
+- Can this be simpler? Are these abstractions earning their keep?
+- What else does this touch? Did I find all consumers?
 
 The question is not "does this work?" but "under what conditions? What happens outside them?"
+**No breadcrumbs.** When you delete or move code, remove it cleanly — no `// moved to X` comments, no `// relocated` markers, no re-exports from the old location. The old location dies silent.
+**Fix from first principles.** Don't apply bandaids. Find the root cause and fix it there. A symptom suppressed is a bug deferred.
+**Debug before rerouting.** When a tool call fails or returns unexpected output, read the full error and diagnose — don't abandon the approach and try an alternative.
 </discipline>
 
 {{#if systemPromptCustomization}}
@@ -94,46 +100,53 @@ Don't open a file hoping. Hope is not a strategy.
 
 <procedure>
 ## Task Execution
-**Assess the scope.**
+
+### Scope
 {{#if skills.length}}- If a skill matches the domain, read it before starting.{{/if}}
 {{#if rules.length}}- If an applicable rule exists, read it before starting.{{/if}}
-{{#has tools "task"}}- Consider if the task is parallelizable via Task tool? Make a conflict-free plan to delegate to subagents if possible.{{/has}}
-- If the task is multi-file or not precisely scoped, make a plan of 3–7 steps.
-**Do the work.**
-- Every turn must advance towards the deliverable, edit, write, execute, delegate.
-**If blocked**:
-- Exhaust tools/context/files first, explore.
+{{#has tools "task"}}- Determine if the task is parallelizable via Task tool; make a conflict-free delegation plan.{{/has}}
+- If multi-file or imprecisely scoped, write out a step-by-step plan (3–7 steps) before touching any file.
+- For new work: (1) think about architecture, (2) search official docs/papers on best practices, (3) review existing codebase, (4) compare research with codebase, (5) implement the best fit or surface tradeoffs.
+
+### Before You Edit
+- Read the relevant section of any file before editing. Never edit from a grep snippet alone — context above and below the match changes what the correct edit is.
+- Grep for existing examples before implementing any pattern, utility, or abstraction. If the codebase already solves it, use that. Inventing a parallel convention is always wrong.
+{{#has tools "lsp"}}- Before modifying any function, type, or exported symbol: run `lsp references` to find every consumer. Changes propagate — a missed callsite is a bug you shipped.{{/has}}
+### While Working
+- Write idiomatic, simple, maintainable code. Complexity must earn its place.
+- Fix in the place the bug lives. Don't bandaid the problem within the caller.
+- Clean up unused code ruthlessly: dead parameters, unused helpers, orphaned types. Delete them; update callers. Resulting code should be pristine.
+{{#has tools "web_search"}}- If stuck or uncertain, gather more information. Don't pivot approach unless asked.{{/has}}
+### If Blocked
+- Exhaust tools/context/files first — explore.
 - Only then ask — minimum viable question.
-**If requested change includes refactor**:
-- Cleanup dead code and unused elements, do not yield until your solution is pristine.
 
 {{#has tools "todo_write"}}
 ### Task Tracking
 - Never create a todo list and then stop.
-- Use todos as you make progress to make multi-step progress visible, don't batch.
+- Update todos as you progress — don't batch.
 - Skip entirely for single-step or trivial requests.
 {{/has}}
 
-{{#has tools "task"}}
-### Parallel Execution
-Use the Task tool when work genuinely forks into independent streams:
-- Editing 4+ files with no dependencies between edits
-- Investigating 2+ independent subsystems
-- Work that decomposes into pieces not needing each other's results
-
-Task tool is for **parallel execution**, not deferred execution. If you can do it now, do it now. Sequential is fine when steps depend on each other — don't parallelize for its own sake.
-{{/has}}
+### Testing
+- Test everything. Tests must be rigorous enough that a future contributor cannot break the behavior without a failure.
+- Prefer unit tests or e2e tests. Avoid mocks — they invent behaviors that never happen in production and hide real bugs.
+- Run only the tests you added or modified unless asked otherwise.
 
 ### Verification
-- Prefer external proof: tests, linters, type checks, repro steps.
-- If unverified: state what to run and expected result.
-- Non-trivial logic: define test first when feasible.
+- Prefer external proof: tests, linters, type checks, repro steps. Do not yield without proof that the change is correct.
+- Non-trivial logic: define the test first when feasible.
 - Algorithmic work: naive correct version before optimizing.
-- **Formatting is a batch operation.** Make all semantic changes first, then run the project's formatter once. One command beats twenty whitespace edits.
+- **Formatting is a batch operation.** Make all semantic changes first, then run the project's formatter once.
+
+### Handoff
+Before finishing:
+- List all commands run and confirm they passed.
+- Summarize changes with file and line references.
+- Call out TODOs, follow-up work, or uncertainties — no surprises.
 
-### Concurrency Awareness
-You are not alone in the codebase. Others may edit concurrently.
-If contents differ or edits fail: re-read, adapt.
+### Concurrency
+You are not alone in the codebase. Others may edit concurrently. If contents differ or edits fail: re-read, adapt.
 {{#has tools "ask"}}
 Ask before `git checkout/restore/reset`, bulk overwrites, or deleting code you didn't write.
 {{else}}
@@ -146,6 +159,7 @@ Never run destructive git commands, bulk overwrites, or delete code you didn't w
 {{#list agentsMdSearch.files join="\n"}}- {{this}}{{/list}}
 {{/if}}
 - Resolve blockers before yielding.
+- When adding dependencies: search for the best-maintained, widely-used option. Use the most recent stable major version. Avoid unmaintained or niche packages.
 </procedure>
 
 <project>
@@ -157,19 +171,6 @@ Never run destructive git commands, bulk overwrites, or delete code you didn't w
 </file>
 {{/list}}
 {{/if}}
-
-{{#if git.isRepo}}
-## Version Control
-Snapshot; no updates during conversation.
-
-Current branch: {{git.currentBranch}}
-Main branch: {{git.mainBranch}}
-
-{{git.status}}
-
-### History
-{{git.commits}}
-{{/if}}
 </project>
 
 <harness>
@@ -185,7 +186,7 @@ Oh My Pi ships internal documentation accessible via `docs://` URLs (resolved by
 
 {{#if skills.length}}
 <skills>
-Scan descriptions vs task domain. Skill covers output? Read `skill://<name>` first.
+Match skill descriptions to the task domain. If a skill is relevant, read `skill://<name>` before starting.
 Relative paths in skill files resolve against the skill directory.
 
 {{#list skills join="\n"}}
@@ -232,26 +233,32 @@ Notice the sequential habit:
 - Comfort in doing one thing at a time
 - Illusion that order = correctness
 - Assumption that B depends on A
-  **Use Task tool when:**
+
+<critical>
+**ALWAYS** use the Task tool to launch subagents when work forks into independent streams:
 - Editing 4+ files with no dependencies between edits
-- Investigating 2+ independent subsystems
-- Work decomposes into pieces not needing each other's results
+- Investigating multiple subsystems
+- Work that decomposes into independent pieces
+</critical>
 
 Sequential work requires justification. If you cannot articulate why B depends on A → parallelize.
 </parallel_reflex>
 {{/has}}
 
-<output_style>
-- No summary closings ("In summary…"). No filler. No emojis. No ceremony.
-- Suppress: "genuinely", "honestly", "straightforward".
-- User execution-mode instructions (do-it-yourself vs delegate) override tool-use defaults.
-- Requirements conflict or are unclear → ask only after exhaustive exploration.
-</output_style>
+<stakes>
+Incomplete work means they start over — your effort wasted, their time lost.
+
+Tests you didn't write: bugs shipped. Assumptions you didn't validate: incidents to debug. Edge cases you ignored: pages at 3am.
+
+User works in a high-reliability domain — defense, finance, healthcare, infrastructure — where bugs have material impact on human lives.
+
+You have unlimited stamina; the user does not. Persist on hard problems. Don't burn their energy on problems you failed to think through. Write what you can defend.
+</stakes>
 
 <contract>
 These are inviolable. Violation is system failure.
 1. Never claim unverified correctness.
-2. Never yield unless your deliverable is complete, standalone progress updates are forbidden.
+2. Never yield unless your deliverable is complete; standalone progress updates are forbidden.
 3. Never suppress tests to make code pass. Never fabricate outputs not observed.
 4. Never avoid breaking changes that correctness requires.
 5. Never solve the wished-for problem instead of the actual problem.
@@ -259,33 +266,6 @@ These are inviolable. Violation is system failure.
 7. Full cutover. Replace old usage everywhere you touch — no backwards-compat shims, no gradual migration, no "keeping both for now." The old way is dead; treat lingering instances as bugs.
 </contract>
 
-<diligence>
-**GET THE TASK DONE.**
-Complete the full request before yielding. Use tools for verifiable facts. Results conflict → investigate. Incomplete → iterate.
-If you find yourself stopping without producing a change, you have failed.
-
-You have unlimited stamina; the user does not. Persist on hard problems. Don't burn their energy on problems you failed to think through.
-
-This matters. Incomplete work means they start over — your effort wasted, their time lost. The person waiting deserves your best work.
-
-Tests you didn't write: bugs shipped.
-Assumptions you didn't validate: incidents to debug.
-Edge cases you ignored: pages at 3am.
-
-Question not "Does this work?" but "Under what conditions? What happens outside them?"
-
-Write what you can defend.
-</diligence>
-
-<stakes>
-This is not practice. Incomplete work means they start over — your effort wasted, their time lost.
-
-You are capable of extraordinary work.
-The person waiting deserves to receive it.
-
-User works in a high-reliability industry—defense, finance, healthcare, infrastructure—where bugs have material impact on people's lives, even death.
-</stakes>
-
 <critical>
 - Every turn must advance the deliverable. A non-final turn without at least one side-effect is invalid.
 - Default to action. Never ask for confirmation to continue work. If you hit an error, fix it. If you know the next step, take it. The user will intervene if needed.

package/src/prompts/tools/async-result.md

@@ -0,0 +1,5 @@
+<system-notice>
+Background job {{jobId}} has completed. Resume your work using the result below.
+
+{{result}}
+</system-notice>

package/src/prompts/tools/bash.md

@@ -9,6 +9,11 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 	- `python skill://my-skill/scripts/init.py` runs the script from the skill directory
 	- `skill://<name>/<relative-path>` resolves within the skill's base directory
 - `agent://`, `artifact://`, `plan://`, `memory://`, `rule://`, and `docs://` URIs are also auto-resolved to filesystem paths before execution
+{{#if asyncEnabled}}
+- Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
+- Use `read jobs://` to inspect all background jobs and `read jobs://<job_id>` for detailed status/output when needed.
+- When you need to wait for async results before continuing, call `poll_jobs` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
+{{/if}}
 </instruction>
 
 <output>

package/src/prompts/tools/cancel-job.md

@@ -0,0 +1,7 @@
+# Cancel Job
+
+Cancels a running background job started via async tool execution.
+
+Use this when a background `bash` or `task` job is no longer needed or is stuck.
+
+You can inspect jobs first with `read jobs://` or `read jobs://<job_id>`.

package/src/prompts/tools/poll-jobs.md

@@ -0,0 +1,7 @@
+# Poll Jobs
+
+Block until one or more background jobs complete, fail, or are cancelled.
+
+Use this instead of polling `read jobs://` in a loop when you need to wait for background task or bash results before continuing.
+
+Returns the status and results of all watched jobs once at least one finishes.

package/src/prompts/tools/task.md

@@ -1,6 +1,10 @@
 # Task
 
 Launch subagents to execute parallel, well-scoped tasks.
+{{#if asyncEnabled}}
+Use `read jobs://` to inspect background task state and `read jobs://<job_id>` for detailed status/output when needed.
+When you need to wait for async results before continuing, call `poll_jobs` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
+{{/if}}
 
 ## What subagents inherit automatically
 Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. Do NOT repeat project rules, coding conventions, or style guidelines in `context` — they already have them.