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

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "8.4.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.4.0",
-		"@oh-my-pi/pi-agent-core": "8.4.0",
-		"@oh-my-pi/pi-ai": "8.4.0",
-		"@oh-my-pi/pi-tui": "8.4.0",
-		"@oh-my-pi/pi-utils": "8.4.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/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/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";

package/src/internal-urls/plan-protocol.ts

@@ -0,0 +1,95 @@
+/**
+ * Protocol handler for plan:// URLs.
+ *
+ * Resolves plan references to plan files under the plans directory.
+ *
+ * URL forms:
+ * - plan://<sessionId> (defaults to plan.md)
+ * - plan://<sessionId>/plan.md
+ * - plan://<plan-id>.md (resolves directly under plans dir)
+ */
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface PlanProtocolOptions {
+	getPlansDirectory: (cwd?: string) => string;
+	cwd: string;
+}
+
+function parsePlanUrl(input: string): InternalUrl {
+	let parsed: URL;
+	try {
+		parsed = new URL(input);
+	} catch {
+		throw new Error(`Invalid URL: ${input}`);
+	}
+
+	const hostMatch = input.match(/^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i);
+	let rawHost = hostMatch ? hostMatch[2] : parsed.hostname;
+	try {
+		rawHost = decodeURIComponent(rawHost);
+	} catch {
+		// Leave rawHost as-is if decoding fails.
+	}
+	(parsed as InternalUrl).rawHost = rawHost;
+	return parsed as InternalUrl;
+}
+
+function normalizeRelativePath(host: string, pathname: string): string {
+	const trimmedHost = host.replace(/^\/+/, "").replace(/\/+$/, "");
+	const trimmedPath = pathname.replace(/^\/+/, "");
+
+	if (!trimmedHost) {
+		throw new Error("plan:// URL requires a session or plan identifier");
+	}
+
+	if (trimmedPath) {
+		return path.join(trimmedHost, trimmedPath);
+	}
+
+	if (trimmedHost.endsWith(".md")) {
+		return trimmedHost;
+	}
+
+	return path.join(trimmedHost, "plan.md");
+}
+
+export function resolvePlanUrlToPath(input: string | InternalUrl, options: PlanProtocolOptions): string {
+	const url = typeof input === "string" ? parsePlanUrl(input) : input;
+	const host = url.rawHost || url.hostname;
+	const relativePath = normalizeRelativePath(host, url.pathname ?? "");
+	const plansDir = path.resolve(options.getPlansDirectory(options.cwd));
+	const resolved = path.resolve(plansDir, relativePath);
+
+	if (resolved !== plansDir && !resolved.startsWith(`${plansDir}${path.sep}`)) {
+		throw new Error("plan:// URL escapes the plans directory");
+	}
+
+	return resolved;
+}
+
+export class PlanProtocolHandler implements ProtocolHandler {
+	readonly scheme = "plan";
+
+	constructor(private readonly options: PlanProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const planPath = resolvePlanUrlToPath(url, this.options);
+		try {
+			const content = await Bun.file(planPath).text();
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+				sourcePath: planPath,
+			};
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(`Plan file not found: ${url.href}`);
+			}
+			throw error;
+		}
+	}
+}