@oh-my-pi/pi-coding-agent 12.19.3 → 13.0.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [13.0.0] - 2026-02-22
+### Added
+
+- Added `getTodoPhases()` and `setTodoPhases()` methods to ToolSession API for managing todo state programmatically
+- Added `getLatestTodoPhasesFromEntries()` export to retrieve todo phases from session history
+- Added `local://` protocol for session-scoped scratch space to store large intermediate artifacts, subagent handoffs, and reusable planning artifacts
+- Added `title` parameter to `exit_plan_mode` tool to specify the final plan artifact name when approving a plan
+- Added `LocalProtocolHandler` for resolving `local://` URLs to session-scoped file storage
+- Added `renameApprovedPlanFile` function to finalize approved plans with user-specified titles
+
+### Changed
+
+- Changed todo state management from file-based (`todos.json`) to in-memory session cache for improved performance and consistency
+- Changed todo phases to sync from session branch history when branching or rewriting entries
+- Changed `TodoWriteTool` to update session cache instead of writing to disk, with automatic persistence through session entries
+- Changed XML tag from `<swarm-context>` to `<context>` in subagent prompts and task rendering
+- Changed system reminder XML tags from underscore to kebab-case format (`<system-reminder>`)
+- Changed plan storage from `plan://` protocol to `local://PLAN.md` for draft plans and `local://<title>.md` for finalized approved plans
+- Changed plan mode to use session artifacts directory for plan storage instead of separate plans directory
+- Updated system prompt to document `local://` protocol and internal URL expansion behavior
+- Updated `exit_plan_mode` tool documentation to require `title` parameter and explain plan finalization workflow
+- Updated `write` tool documentation to recommend `local://` for large temporary artifacts and subagent handoffs
+- Updated `task` tool documentation to recommend using `local://` for large intermediate outputs in subagent context
+- Replaced `docs://` protocol with `pi://` for accessing embedded documentation files
+- Renamed `DocsProtocolHandler` to `PiProtocolHandler` for internal documentation URL resolution
+- Removed `artifactsDir` parameter from Python executor options; artifact storage now uses `artifactPath` only
+- Renamed prompt file from `read_path.md` to `read-path.md` for consistency
+- Updated system prompt XML tags to use kebab-case (e.g., `system-reminder`, `system-interrupt`) for consistency
+- Refactored bash tool to use `NO_PAGER_ENV` constant for environment variable management
+- Updated internal URL expansion to support optional `noEscape` parameter for unescaped path resolution
+
+### Removed
+
+- Removed `plan://` protocol handler and related plan directory resolution logic
+- Removed `PlanProtocolHandler` and `resolvePlanUrlToPath` exports from internal URLs module
+
+### Fixed
+
+- Fixed todo reminder XML tags from underscore to kebab-case format (`system-reminder`)
+
 ## [12.19.3] - 2026-02-22
 ### Added
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "12.19.3",
+	"version": "13.0.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "12.19.3",
-		"@oh-my-pi/pi-agent-core": "12.19.3",
-		"@oh-my-pi/pi-ai": "12.19.3",
-		"@oh-my-pi/pi-natives": "12.19.3",
-		"@oh-my-pi/pi-tui": "12.19.3",
-		"@oh-my-pi/pi-utils": "12.19.3",
+		"@oh-my-pi/omp-stats": "13.0.0",
+		"@oh-my-pi/pi-agent-core": "13.0.0",
+		"@oh-my-pi/pi-ai": "13.0.0",
+		"@oh-my-pi/pi-natives": "13.0.0",
+		"@oh-my-pi/pi-tui": "13.0.0",
+		"@oh-my-pi/pi-utils": "13.0.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

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

@@ -14,7 +14,7 @@ Use null for: cross-cutting changes, project-wide refactoring.
 
 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.
+Prefer scopes from <common-scopes> over inventing new.
 ## 2. Generate Details (0-6 items)
 
 Each detail:
@@ -55,7 +55,7 @@ user_visible: false for: internal refactoring, performance optimizations (unless
 Omit changelog_category when user_visible false.
 </instructions>
 
-<output_format>
+<output-format>
 Call create_conventional_analysis with:
 
 {
@@ -74,7 +74,7 @@ Call create_conventional_analysis with:
 ],
 "issue_refs": []
 }
-</output_format>
+</output-format>
 
 <example name="feature-with-api">
 {

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

@@ -1,37 +1,37 @@
 {{#if context_files}}
-<project_context>
+<project-context>
 {{#each context_files}}
 <file path="{{ path }}">
 {{ content }}
 </file>
 {{/each}}
-</project_context>
+</project-context>
 {{/if}}
 {{#if user_context}}
-<user_context>
+<user-context>
 {{ user_context }}
-</user_context>
+</user-context>
 {{/if}}
 {{#if types_description}}
-<commit_types>
+<commit-types>
 {{ types_description }}
-</commit_types>
+</commit-types>
 {{/if}}
-<diff_statistics>
+<diff-statistics>
 {{ stat }}
-</diff_statistics>
-<scope_candidates>
+</diff-statistics>
+<scope-candidates>
 {{ scope_candidates }}
-</scope_candidates>
+</scope-candidates>
 {{#if common_scopes}}
-<common_scopes>
+<common-scopes>
 {{ common_scopes }}
-</common_scopes>
+</common-scopes>
 {{/if}}
 {{#if recent_commits}}
-<style_patterns>
+<style-patterns>
 {{ recent_commits }}
-</style_patterns>
+</style-patterns>
 {{/if}}
 <diff>
 {{ diff }}

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

@@ -16,12 +16,12 @@ You're expert changelog writer analyzing git diffs to produce Keep a Changelog e
 - Breaking Changes: API-incompatible changes (use sparingly)
 </categories>
 
-<entry_format>
+<entry-format>
 - Start with past-tense verb (Added, Fixed, Implemented, Updated)
 - Describe user-visible impact, not implementation
 - Name specific feature, option, or behavior
 - Keep 1-2 lines, no trailing periods
-</entry_format>
+</entry-format>
 
 <examples>
 Good:
@@ -42,9 +42,9 @@ Breaking Changes:
 Internal refactoring, code style changes, test-only modifications, minor doc updates.
 </exclude>
 
-<output_format>
+<output-format>
 Return ONLY valid JSON; no markdown fences or 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,15 +3,15 @@ Changelog: {{ changelog_path }}
 {{#if is_package_changelog}}Scope: Package-level changelog. Omit package name prefix from entries.{{/if}}
 </context>
 {{#if existing_entries}}
-<existing_entries>
+<existing-entries>
 Already documented—skip these:
 {{ existing_entries }}
-</existing_entries>
+</existing-entries>
 {{/if}}
 
-<diff_summary>
+<diff-summary>
 {{ stat }}
-</diff_summary>
+</diff-summary>
 
 <diff>
 {{ diff }}

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

@@ -14,11 +14,11 @@ Include: functions, methods, types, API changes, behavior/logic changes, error h
 Exclude: import reordering, whitespace/formatting, comment-only changes, debug statements.
 </scope>
 
-<output_format>
+<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>
+</output-format>
 
 Observations only. Classification in reduce phase.

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

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

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

@@ -9,13 +9,13 @@ Determine:
 3. DETAILS: 3–4 summary points (max 6)
 4. CHANGELOG: Metadata for user-visible changes
 </instructions>
-<scope_rules>
+<scope-rules>
 - Component name if >=60% changes target it
 - null if spread across multiple components
 - scope_candidates as primary source
 - Valid: specific component names (api, parser, config, etc.)
-</scope_rules>
-<output_format>
+</scope-rules>
+<output-format>
 Each detail point:
 - Start with past-tense verb (added, fixed, moved, extracted)
 - Under 120 chars, ends with period
@@ -23,7 +23,7 @@ Each detail point:
 Priority: user-visible behavior > performance/security > architecture > internal implementation
 changelog_category: Added|Changed|Fixed|Deprecated|Removed|Security
 user_visible: true for features, user-facing bugs, breaking changes, security
-</output_format>
+</output-format>
 <example>
 Input observations:
 - api/client.ts: added token refresh guard to prevent duplicate refreshes

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

@@ -1,17 +1,17 @@
 {{#if types_description}}
-<type_definitions>
+<type-definitions>
 {{ types_description }}
-</type_definitions>
+</type-definitions>
 {{/if}}
 
 <observations>
 {{ observations }}
 </observations>
 
-<diff_statistics>
+<diff-statistics>
 {{ stat }}
-</diff_statistics>
+</diff-statistics>
 
-<scope_candidates>
+<scope-candidates>
 {{ scope_candidates }}
-</scope_candidates>
+</scope-candidates>

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

@@ -10,7 +10,7 @@ Output: ONLY description after "{{ commit_type }}{{ scope_prefix }}:"; max {{ ch
 4. One focused concept per message
 </instructions>
 
-<verb_reference>
+<verb-reference>
 |Type|Use|
 |---|---|
 |feat|added, introduced, implemented, enabled|
@@ -20,7 +20,7 @@ Output: ONLY description after "{{ commit_type }}{{ scope_prefix }}:"; max {{ ch
 |docs|documented, clarified, expanded|
 |build|upgraded, pinned, configured|
 |chore|cleaned, removed, renamed, organized|
-</verb_reference>
+</verb-reference>
 <examples>
 feat | TLS encryption added to HTTP client for MITM prevention
 -> added TLS support to prevent man-in-the-middle attacks
@@ -33,6 +33,6 @@ perf | Batch processing optimized to reduce memory allocations
 build | Updated serde to fix CVE-2024-1234
 -> upgraded serde to 1.0.200 for CVE-2024-1234
 </examples>
-<banned_words>
+<banned-words>
 comprehensive, various, several, improved, enhanced, quickly, simply, basically, this change, this commit, now
-</banned_words>
+</banned-words>

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

@@ -1,13 +1,13 @@
 {{#if user_context}}
-<user_context>
+<user-context>
 {{ user_context }}
-</user_context>
+</user-context>
 {{/if}}
 
-<detail_points>
+<detail-points>
 {{ details }}
-</detail_points>
+</detail-points>
 
-<diff_stat>
+<diff-stat>
 {{ stat }}
-</diff_stat>
+</diff-stat>

package/src/discovery/helpers.ts

@@ -112,6 +112,16 @@ export function parseThinkingLevel(frontmatter: Record<string, unknown>): Thinki
 	return undefined;
 }
 
+export function parseBoolean(value: unknown): boolean | undefined {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+	return undefined;
+}
+
 /**
  * Parse a comma-separated string into an array of trimmed, non-empty strings.
  */
@@ -194,6 +204,7 @@ export interface ParsedAgentFields {
 	model?: string[];
 	output?: unknown;
 	thinkingLevel?: ThinkingLevel;
+	blocking?: boolean;
 }
 
 /**
@@ -238,8 +249,9 @@ export function parseAgentFields(frontmatter: Record<string, unknown>): ParsedAg
 	const output = frontmatter.output !== undefined ? frontmatter.output : undefined;
 	const model = parseModelList(frontmatter.model);
 	const thinkingLevel = parseThinkingLevel(frontmatter);
+	const blocking = parseBoolean(frontmatter.blocking);
 
-	return { name, description, tools, spawns, model, output, thinkingLevel };
+	return { name, description, tools, spawns, model, output, thinkingLevel, blocking };
 }
 
 async function globIf(