@oh-my-pi/pi-coding-agent 8.3.0 → 8.4.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [8.4.1] - 2026-01-25
+
+### Added
+- Added core plan mode with plan file approval workflow and tool gating
+- Added plan:// internal URLs for plan file access and subagent plan-mode system prompt
+- Added plan mode toggle shortcut with paused status indicator
+
+### Fixed
+- Fixed plan reference injection and workflow prompt parameters for plan mode
+- Fixed tool downloads hanging on slow/blocked GitHub by adding timeouts and zip extraction fallback
+- Fixed missing UI notification when tools are downloaded or installed on demand
+## [8.4.0] - 2026-01-25
+
+### Added
+- Added extension API to set working/loading messages during streaming
+- Added task worker propagation of context files, skills, and prompt templates
+- Added subagent option to skip Python preflight checks when Python tooling is unused
+- Model field now accepts string arrays for fallback model prioritization
+
+### Changed
+- Merged patch application warnings into edit tool diagnostics output
+- Cached Python prelude docs for subagent workers to avoid repeated warmups
+- Simplified image placeholders inserted on paste to match Claude-style markers
+
+### Fixed
+- Rewrote empty or corrupted session files to restore valid headers
+- Improved patch applicator ambiguity errors with match previews and overlap detection
+- Fixed Task tool agent model resolution to honor comma-separated model lists
 ## [8.3.0] - 2026-01-25
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "8.3.0",
+	"version": "8.4.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -75,11 +75,11 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@oh-my-pi/omp-stats": "8.3.0",
-		"@oh-my-pi/pi-agent-core": "8.3.0",
-		"@oh-my-pi/pi-ai": "8.3.0",
-		"@oh-my-pi/pi-tui": "8.3.0",
-		"@oh-my-pi/pi-utils": "8.3.0",
+		"@oh-my-pi/omp-stats": "8.4.1",
+		"@oh-my-pi/pi-agent-core": "8.4.1",
+		"@oh-my-pi/pi-ai": "8.4.1",
+		"@oh-my-pi/pi-tui": "8.4.1",
+		"@oh-my-pi/pi-utils": "8.4.1",
 		"@openai/agents": "^0.4.3",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",

package/scripts/format-prompts.ts

@@ -3,16 +3,22 @@
  * Format prompt files (mixed XML + Markdown + Handlebars).
  *
  * Rules:
- * 1. No blank line between "text:" and following list/block
+ * 1. No blank line before list items
  * 2. No blank line after opening XML tag or Handlebars block
  * 3. No blank line before closing XML tag or Handlebars block
- * 4. Collapse 2+ blank lines to single blank line
- * 5. Trim trailing whitespace (preserve indentation)
- * 6. Ensure single newline at EOF
+ * 4. Strip leading whitespace from closing XML tags and Handlebars (lines starting with {{)
+ * 5. Compact markdown tables (remove padding)
+ * 6. Collapse 2+ blank lines to single blank line
+ * 7. Trim trailing whitespace (preserve indentation)
+ * 8. No trailing newline at EOF
  */
 import { Glob } from "bun";
 
 const PROMPTS_DIR = new URL("../src/prompts/", import.meta.url).pathname;
+const COMMIT_PROMPTS_DIR = new URL("../src/commit/prompts/", import.meta.url).pathname;
+const AGENTIC_PROMPTS_DIR = new URL("../src/commit/agentic/prompts/", import.meta.url).pathname;
+
+const PROMPT_DIRS = [PROMPTS_DIR, COMMIT_PROMPTS_DIR, AGENTIC_PROMPTS_DIR];
 
 // Opening XML tag (not self-closing, not closing)
 const OPENING_XML = /^<([a-z_-]+)(?:\s+[^>]*)?>$/;
@@ -22,12 +28,38 @@ const CLOSING_XML = /^<\/([a-z_-]+)>$/;
 const OPENING_HBS = /^\{\{#/;
 // Handlebars block end: {{/if}}, {{/has}}, {{/list}}, etc.
 const CLOSING_HBS = /^\{\{\//;
-// Line ending with colon (intro to a list) - handles **bold:** too
-const ENDS_WITH_COLON = /:\**\s*$/;
-// List item or Handlebars conditional that acts like list
-const LIST_OR_BLOCK = /^(\s*)[-*]|\d+\.\s|^\{\{#/;
+// List item (- or * or 1.)
+const LIST_ITEM = /^[-*]|\d+\.\s/;
 // Code fence
 const CODE_FENCE = /^```/;
+// Table row
+const TABLE_ROW = /^\|.*\|$/;
+// Table separator (|---|---|)
+const TABLE_SEP = /^\|[-:\s|]+\|$/;
+
+/** Compact a table row by trimming cell padding */
+function compactTableRow(line: string): string {
+	// Split by |, trim each cell, rejoin
+	const cells = line.split("|");
+	return cells.map((c) => c.trim()).join("|");
+}
+
+/** Compact a table separator row */
+function compactTableSep(line: string): string {
+	// Normalize to minimal |---|---|
+	const cells = line.split("|").filter((c) => c.trim());
+	const normalized = cells.map((c) => {
+		const trimmed = c.trim();
+		// Preserve alignment markers
+		const left = trimmed.startsWith(":");
+		const right = trimmed.endsWith(":");
+		if (left && right) return ":---:";
+		if (left) return ":---";
+		if (right) return "---:";
+		return "---";
+	});
+	return "|" + normalized.join("|") + "|";
+}
 
 function formatPrompt(content: string): string {
 	const lines = content.split("\n");
@@ -37,9 +69,6 @@ function formatPrompt(content: string): string {
 	for (let i = 0; i < lines.length; i++) {
 		let line = lines[i];
 
-		// Trim trailing whitespace (preserve leading)
-		line = line.trimEnd();
-
 		const trimmed = line.trim();
 
 		// Track code blocks - don't modify inside them
@@ -54,6 +83,20 @@ function formatPrompt(content: string): string {
 			continue;
 		}
 
+		// Strip leading whitespace from closing XML tags and Handlebars
+		if (CLOSING_XML.test(trimmed) || trimmed.startsWith("{{")) {
+			line = trimmed;
+		} else if (TABLE_SEP.test(trimmed)) {
+			// Compact table separator
+			line = compactTableSep(trimmed);
+		} else if (TABLE_ROW.test(trimmed)) {
+			// Compact table row
+			line = compactTableRow(trimmed);
+		} else {
+			// Trim trailing whitespace (preserve leading for non-closing-tags)
+			line = line.trimEnd();
+		}
+
 		const isBlank = trimmed === "";
 
 		// Skip blank lines that violate our rules
@@ -61,8 +104,8 @@ function formatPrompt(content: string): string {
 			const prevLine = result[result.length - 1]?.trim() ?? "";
 			const nextLine = lines[i + 1]?.trim() ?? "";
 
-			// Rule 1: No blank between "text:" and list/block
-			if (ENDS_WITH_COLON.test(prevLine) && LIST_OR_BLOCK.test(nextLine)) {
+			// Rule 1: No blank line before list items
+			if (LIST_ITEM.test(nextLine)) {
 				continue;
 			}
 
@@ -93,11 +136,10 @@ function formatPrompt(content: string): string {
 		result.push(line);
 	}
 
-	// Rule 6: Single newline at EOF
+	// Rule 8: No trailing newline at EOF
 	while (result.length > 0 && result[result.length - 1].trim() === "") {
 		result.pop();
 	}
-	result.push("");
 
 	return result.join("\n");
 }
@@ -106,24 +148,24 @@ async function main() {
 	const glob = new Glob("**/*.md");
 	const files: string[] = [];
 	let changed = 0;
+	const check = process.argv.includes("--check");
 
-	for await (const path of glob.scan(PROMPTS_DIR)) {
-		files.push(path);
+	for (const dir of PROMPT_DIRS) {
+		for await (const path of glob.scan(dir)) {
+			files.push(`${dir}${path}`);
+		}
 	}
 
-	const check = process.argv.includes("--check");
-
-	for (const relativePath of files) {
-		const fullPath = `${PROMPTS_DIR}${relativePath}`;
+	for (const fullPath of files) {
 		const original = await Bun.file(fullPath).text();
 		const formatted = formatPrompt(original);
 
 		if (original !== formatted) {
 			if (check) {
-				console.log(`Would format: ${relativePath}`);
+				console.log(`Would format: ${fullPath}`);
 			} else {
 				await Bun.write(fullPath, formatted);
-				console.log(`Formatted: ${relativePath}`);
+				console.log(`Formatted: ${fullPath}`);
 			}
 			changed++;
 		}

package/src/commit/agentic/prompts/session-user.md

@@ -19,7 +19,6 @@ You may include entries from this list in the propose_changelog `deletions` fiel
 {{name}}:
 {{#list items prefix="- " join="\n"}}{{this}}{{/list}}
 {{/each}}
-
 {{/each}}
 {{/if}}
 

package/src/commit/agentic/prompts/split-confirm.md

@@ -1 +1 @@
-Split commit plan has {{count}} commits. Proceed? (y/N): 
+Split commit plan has {{count}} commits. Proceed? (y/N):

package/src/commit/agentic/prompts/system.md

@@ -37,4 +37,4 @@ Tool guidance:
 ## Changelog Requirements
 
 If changelog targets are provided, you MUST call `propose_changelog` before finishing.
-If you propose a split commit plan, include changelog target files in the relevant commit changes.
+If you propose a split commit plan, include changelog target files in the relevant commit changes.

package/src/commit/prompts/analysis-system.md

@@ -4,7 +4,6 @@ You are a senior release engineer who writes precise, changelog-ready commit cla
 
 <instructions>
 Classify this git diff into conventional commit format. Get this right — it affects release notes and semantic versioning.
-
 ## 1. Determine Scope
 
 Apply scope when 60%+ of line changes target a single component:
@@ -16,7 +15,6 @@ Use null for: cross-cutting changes, no dominant component, project-wide refacto
 Forbidden scopes (use null): src, lib, include, tests, benches, examples, docs, project name, app, main, entire, all, misc.
 
 Prefer scopes from <common_scopes> over inventing new ones.
-
 ## 2. Generate Details (0-6 items)
 
 Each detail:
@@ -39,17 +37,16 @@ Priority: user-visible -> perf/security -> architecture -> internal.
 Exclude: import changes, whitespace, formatting, trivial renames, debug prints, comment-only, file moves without modification.
 
 State only visible rationale. If unclear, use neutral: "Updated logic for correctness."
-
 ## 3. Assign Changelog Metadata
 
-| Condition | changelog_category |
-|-----------|--------------------|
-| New public API, feature, capability | "Added" |
-| Modified existing behavior | "Changed" |
-| Bug fix, correction | "Fixed" |
-| Feature marked for removal | "Deprecated" |
-| Feature/API removed | "Removed" |
-| Security fix or improvement | "Security" |
+|Condition|changelog_category|
+|---|---|
+|New public API, feature, capability|"Added"|
+|Modified existing behavior|"Changed"|
+|Bug fix, correction|"Fixed"|
+|Feature marked for removal|"Deprecated"|
+|Feature/API removed|"Removed"|
+|Security fix or improvement|"Security"|
 
 user_visible: true for: new features, APIs, breaking changes, user-affecting bug fixes, user-facing docs, security fixes.
 
@@ -62,20 +59,20 @@ Omit changelog_category when user_visible is false.
 Call create_conventional_analysis with:
 
 {
-  "type": "feat|fix|refactor|docs|test|chore|style|perf|build|ci|revert",
-  "scope": "component-name" | null,
-  "details": [
-    {
-      "text": "Past-tense description ending with period.",
-      "changelog_category": "Added|Changed|Fixed|Deprecated|Removed|Security",
-      "user_visible": true
-    },
-    {
-      "text": "Internal change description.",
-      "user_visible": false
-    }
-  ],
-  "issue_refs": []
+"type": "feat|fix|refactor|docs|test|chore|style|perf|build|ci|revert",
+"scope": "component-name" | null,
+"details": [
+{
+"text": "Past-tense description ending with period.",
+"changelog_category": "Added|Changed|Fixed|Deprecated|Removed|Security",
+"user_visible": true
+},
+{
+"text": "Internal change description.",
+"user_visible": false
+}
+],
+"issue_refs": []
 }
 </output_format>
 
@@ -152,4 +149,4 @@ Call create_conventional_analysis with:
 </example>
 </examples>
 
-Be thorough. This matters.
+Be thorough. This matters.

package/src/commit/prompts/analysis-user.md

@@ -38,4 +38,4 @@
 
 <diff>
 {{ diff }}
-</diff>
+</diff>

package/src/commit/prompts/changelog-system.md

@@ -2,7 +2,6 @@ You are an expert changelog writer who analyzes git diffs and produces Keep a Ch
 
 <instructions>
 Analyze the diff and return JSON changelog entries.
-
 1. Identify user-visible changes only
 2. Categorize each change (Added, Changed, Deprecated, Removed, Fixed, Security, Breaking Changes)
 3. Write entries starting with past-tense verb describing user impact
@@ -53,4 +52,4 @@ Return ONLY valid JSON. No markdown fences, no explanation.
 
 With entries: {"entries": {"Added": ["entry 1"], "Fixed": ["entry 2"]}}
 No changelog-worthy changes: {"entries": {}}
-</output_format>
+</output_format>

package/src/commit/prompts/changelog-user.md

@@ -3,7 +3,6 @@ Changelog: {{ changelog_path }}
 {{#if is_package_changelog}}Scope: Package-level changelog. Omit package name prefix from entries.{{/if}}
 </context>
 {{#if existing_entries}}
-
 <existing_entries>
 Already documented—skip these:
 {{ existing_entries }}
@@ -16,4 +15,4 @@ Already documented—skip these:
 
 <diff>
 {{ diff }}
-</diff>
+</diff>

package/src/commit/prompts/file-observer-system.md

@@ -2,7 +2,6 @@
 
 <instructions>
 Extract factual observations from the diff. This matters—be precise.
-
 1. Use past-tense verb + specific target + optional purpose
 2. Max 100 characters per observation
 3. Consolidate related changes (e.g., "renamed 5 helper functions")
@@ -17,10 +16,9 @@ Exclude: import reordering, whitespace/formatting, comment-only changes, debug s
 
 <output_format>
 Plain list, no preamble, no summary, no markdown formatting.
-
 - added 'parse_config()' function for TOML configuration loading
 - removed deprecated 'legacy_init()' and all callers
 - changed 'Connection::new()' to accept '&Config' instead of individual params
 </output_format>
 
-Observations only. Classification happens in reduce phase.
+Observations only. Classification happens in reduce phase.

package/src/commit/prompts/file-observer-user.md

@@ -2,8 +2,7 @@
 {{ diff }}
 </file>
 {{#if context_header}}
-
 <related_files>
 {{ context_header }}
 </related_files>
-{{/if}}
+{{/if}}

package/src/commit/prompts/reduce-system.md

@@ -41,20 +41,20 @@ Input observations:
 
 Output:
 {
-  "type": "fix",
-  "scope": "api",
-  "details": [
-    {
-      "text": "Added token refresh guard to prevent duplicate refreshes.",
-      "changelog_category": "Fixed",
-      "user_visible": true
-    },
-    {
-      "text": "Introduced retry wrapper for 429 responses.",
-      "changelog_category": "Fixed",
-      "user_visible": true
-    }
-  ],
-  "issue_refs": []
+"type": "fix",
+"scope": "api",
+"details": [
+{
+"text": "Added token refresh guard to prevent duplicate refreshes.",
+"changelog_category": "Fixed",
+"user_visible": true
+},
+{
+"text": "Introduced retry wrapper for 429 responses.",
+"changelog_category": "Fixed",
+"user_visible": true
+}
+],
+"issue_refs": []
 }
-</example>
+</example>

package/src/commit/prompts/reduce-user.md

@@ -14,4 +14,4 @@
 
 <scope_candidates>
 {{ scope_candidates }}
-</scope_candidates>
+</scope_candidates>

package/src/commit/prompts/summary-retry.md

@@ -1,4 +1,3 @@
 {{#if base_context}}
 {{ base_context }}
-
-{{/if}}Previous summary failed validation: {{ errors }}
+{{/if}}Previous summary failed validation: {{ errors }}

package/src/commit/prompts/summary-system.md

@@ -15,15 +15,15 @@ Get this right.
 </instructions>
 
 <verb_reference>
-| Type     | Use instead                                     |
-|----------|-------------------------------------------------|
-| feat     | added, introduced, implemented, enabled         |
-| fix      | corrected, resolved, patched, addressed         |
-| refactor | restructured, reorganized, migrated, simplified |
-| perf     | optimized, reduced, eliminated, accelerated     |
-| docs     | documented, clarified, expanded                 |
-| build    | upgraded, pinned, configured                    |
-| chore    | cleaned, removed, renamed, organized            |
+|Type|Use instead|
+|---|---|
+|feat|added, introduced, implemented, enabled|
+|fix|corrected, resolved, patched, addressed|
+|refactor|restructured, reorganized, migrated, simplified|
+|perf|optimized, reduced, eliminated, accelerated|
+|docs|documented, clarified, expanded|
+|build|upgraded, pinned, configured|
+|chore|cleaned, removed, renamed, organized|
 </verb_reference>
 
 <examples>
@@ -49,4 +49,4 @@ comprehensive, various, several, improved, enhanced, quickly, simply, basically,
 
 <output_format>
 Output the description text only. Include motivation, name specifics, stay focused.
-</output_format>
+</output_format>

package/src/commit/prompts/summary-user.md

@@ -10,4 +10,4 @@
 
 <diff_stat>
 {{ stat }}
-</diff_stat>
+</diff_stat>

package/src/commit/prompts/types-description.md

@@ -1,2 +1,2 @@
 Types: feat, fix, refactor, perf, docs, test, build, ci, chore, style, revert.
-Format: <type>(<scope>): <summary> with past-tense summary.
+Format: <type>(<scope>): <summary> with past-tense summary.

package/src/config/keybindings.ts

@@ -23,6 +23,7 @@ export type AppAction =
 	| "cycleModelForward"
 	| "cycleModelBackward"
 	| "selectModel"
+	| "togglePlanMode"
 	| "expandTools"
 	| "toggleThinking"
 	| "externalEditor"
@@ -55,6 +56,7 @@ export const DEFAULT_APP_KEYBINDINGS: Record<AppAction, KeyId | KeyId[]> = {
 	cycleModelForward: "ctrl+p",
 	cycleModelBackward: "shift+ctrl+p",
 	selectModel: "ctrl+l",
+	togglePlanMode: "alt+shift+p",
 	historySearch: "ctrl+r",
 	expandTools: "ctrl+o",
 	toggleThinking: "ctrl+t",
@@ -82,6 +84,7 @@ const APP_ACTIONS: AppAction[] = [
 	"cycleModelForward",
 	"cycleModelBackward",
 	"selectModel",
+	"togglePlanMode",
 	"historySearch",
 	"expandTools",
 	"toggleThinking",

package/src/config/model-registry.ts

@@ -19,12 +19,18 @@ import type { AuthStorage } from "../session/auth-storage";
 
 const Ajv = (AjvModule as any).default || AjvModule;
 
+const OpenRouterRoutingSchema = Type.Object({
+	only: Type.Optional(Type.Array(Type.String())),
+	order: Type.Optional(Type.Array(Type.String())),
+});
+
 // Schema for OpenAI compatibility settings
 const OpenAICompatSchema = Type.Object({
 	supportsStore: Type.Optional(Type.Boolean()),
 	supportsDeveloperRole: Type.Optional(Type.Boolean()),
 	supportsReasoningEffort: Type.Optional(Type.Boolean()),
 	maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
+	openRouterRouting: Type.Optional(OpenRouterRoutingSchema),
 });
 
 // Schema for custom model definition
@@ -36,6 +42,7 @@ const ModelDefinitionSchema = Type.Object({
 			Type.Literal("openai-completions"),
 			Type.Literal("openai-responses"),
 			Type.Literal("openai-codex-responses"),
+			Type.Literal("azure-openai-responses"),
 			Type.Literal("anthropic-messages"),
 			Type.Literal("google-generative-ai"),
 			Type.Literal("google-vertex"),
@@ -63,6 +70,7 @@ const ProviderConfigSchema = Type.Object({
 			Type.Literal("openai-completions"),
 			Type.Literal("openai-responses"),
 			Type.Literal("openai-codex-responses"),
+			Type.Literal("azure-openai-responses"),
 			Type.Literal("anthropic-messages"),
 			Type.Literal("google-generative-ai"),
 			Type.Literal("google-vertex"),

package/src/config/settings-manager.ts

@@ -155,6 +155,7 @@ export interface TodoCompletionSettings {
 export type StatusLineSegmentId =
 	| "pi"
 	| "model"
+	| "plan_mode"
 	| "path"
 	| "git"
 	| "subagents"
@@ -547,6 +548,10 @@ export class SettingsManager {
 		return { ...this.settings };
 	}
 
+	getPlansDirectory(_cwd: string = this.cwd ?? process.cwd()): string {
+		return path.join(getAgentDir(), "plans");
+	}
+
 	/**
 	 * Access the underlying agent storage (null for in-memory settings).
 	 */

package/src/discovery/helpers.ts

@@ -156,13 +156,23 @@ export function parseArrayOrCSV(value: unknown): string[] | undefined {
 	return undefined;
 }
 
+/**
+ * Parse model field into a prioritized list.
+ */
+export function parseModelList(value: unknown): string[] | undefined {
+	const parsed = parseArrayOrCSV(value);
+	if (!parsed) return undefined;
+	const normalized = parsed.map(entry => entry.trim()).filter(Boolean);
+	return normalized.length > 0 ? normalized : undefined;
+}
+
 /** Parsed agent fields from frontmatter (excludes source/filePath/systemPrompt) */
 export interface ParsedAgentFields {
 	name: string;
 	description: string;
 	tools?: string[];
 	spawns?: string[] | "*";
-	model?: string;
+	model?: string[];
 	output?: unknown;
 	thinkingLevel?: ThinkingLevel;
 }
@@ -202,7 +212,7 @@ export function parseAgentFields(frontmatter: Record<string, unknown>): ParsedAg
 	}
 
 	const output = frontmatter.output !== undefined ? frontmatter.output : undefined;
-	const model = typeof frontmatter.model === "string" ? frontmatter.model : undefined;
+	const model = parseModelList(frontmatter.model);
 	const thinkingLevel = parseThinkingLevel(frontmatter);
 
 	return { name, description, tools, spawns, model, output, thinkingLevel };

package/src/extensibility/extensions/runner.ts

@@ -85,6 +85,7 @@ const noOpUIContext: ExtensionUIContext = {
 	input: async (_title, _placeholder, _dialogOptions) => undefined,
 	notify: () => {},
 	setStatus: () => {},
+	setWorkingMessage: () => {},
 	setWidget: () => {},
 	setFooter: () => {},
 	setHeader: () => {},

package/src/extensibility/extensions/types.ts

@@ -69,6 +69,9 @@ export interface ExtensionUIContext {
 	/** Set status text in the footer/status bar. Pass undefined to clear. */
 	setStatus(key: string, text: string | undefined): void;
 
+	/** Set the working/loading message shown during streaming. Call with no argument to restore default. */
+	setWorkingMessage(message?: string): void;
+
 	/** Set a widget to display above the editor. Accepts string array or component factory. */
 	setWidget(key: string, content: string[] | undefined): void;
 	setWidget(key: string, content: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined): void;

package/src/internal-urls/index.ts

@@ -22,6 +22,7 @@
 export { AgentProtocolHandler, type AgentProtocolOptions } from "./agent-protocol";
 export { ArtifactProtocolHandler, type ArtifactProtocolOptions } from "./artifact-protocol";
 export { applyQuery, parseQuery, pathToQuery } from "./json-query";
+export { PlanProtocolHandler, type PlanProtocolOptions, resolvePlanUrlToPath } from "./plan-protocol";
 export { InternalUrlRouter } from "./router";
 export { RuleProtocolHandler, type RuleProtocolOptions } from "./rule-protocol";
 export { SkillProtocolHandler, type SkillProtocolOptions } from "./skill-protocol";