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

package/src/patch/index.ts

@@ -23,7 +23,7 @@ import patchDescription from "../prompts/tools/patch.md" with { type: "text" };
 import replaceDescription from "../prompts/tools/replace.md" with { type: "text" };
 import type { ToolSession } from "../tools";
 import { outputMeta } from "../tools/output-meta";
-import { resolveToCwd } from "../tools/path-utils";
+import { enforcePlanModeWrite, resolvePlanPath } from "../tools/plan-mode-guard";
 import { applyPatch } from "./applicator";
 import { generateDiffString, generateUnifiedDiffString, replaceText } from "./diff";
 import { DEFAULT_FUZZY_THRESHOLD, findMatch } from "./fuzzy";
@@ -290,6 +290,10 @@ export class EditTool implements AgentTool<TInput> {
 			// Normalize unrecognized operations to "update"
 			const op: Operation = rawOp === "create" || rawOp === "delete" ? rawOp : "update";
 
+			enforcePlanModeWrite(this.session, path, { op, rename });
+			const resolvedPath = resolvePlanPath(this.session, path);
+			const resolvedRename = rename ? resolvePlanPath(this.session, rename) : undefined;
+
 			if (path.endsWith(".ipynb")) {
 				throw new Error("Cannot edit Jupyter notebooks with the Edit tool. Use the NotebookEdit tool instead.");
 			}
@@ -297,7 +301,7 @@ export class EditTool implements AgentTool<TInput> {
 				throw new Error("Cannot edit Jupyter notebooks with the Edit tool. Use the NotebookEdit tool instead.");
 			}
 
-			const input: PatchInput = { path, op, rename, diff };
+			const input: PatchInput = { path: resolvedPath, op, rename: resolvedRename, diff };
 			const fs = new LspFileSystem(this.writethrough, signal, batchRequest);
 			const result = await applyPatch(input, {
 				cwd: this.session.cwd,
@@ -366,6 +370,8 @@ export class EditTool implements AgentTool<TInput> {
 		// ─────────────────────────────────────────────────────────────────
 		const { path, old_text, new_text, all } = params as ReplaceParams;
 
+		enforcePlanModeWrite(this.session, path);
+
 		if (path.endsWith(".ipynb")) {
 			throw new Error("Cannot edit Jupyter notebooks with the Edit tool. Use the NotebookEdit tool instead.");
 		}
@@ -374,7 +380,7 @@ export class EditTool implements AgentTool<TInput> {
 			throw new Error("old_text must not be empty.");
 		}
 
-		const absolutePath = resolveToCwd(path, this.session.cwd);
+		const absolutePath = resolvePlanPath(this.session, path);
 		const file = Bun.file(absolutePath);
 
 		if (!(await file.exists())) {

package/src/plan-mode/state.ts

@@ -0,0 +1,6 @@
+export interface PlanModeState {
+	enabled: boolean;
+	planFilePath: string;
+	workflow?: "parallel" | "iterative";
+	reentry?: boolean;
+}

package/src/prompts/agents/explore.md

@@ -118,4 +118,4 @@ Infer from task, default medium:
 
 <critical>
 Read-only; no file modifications. Call `complete` with your findings when done.
-</critical>
+</critical>

package/src/prompts/agents/frontmatter.md

@@ -5,4 +5,4 @@ description: {{description}}
 {{/if}}{{#if model}}model: {{model}}
 {{/if}}{{#if thinkingLevel}}thinkingLevel: {{thinkingLevel}}
 {{/if}}---
-{{body}}
+{{body}}

package/src/prompts/agents/init.md

@@ -32,4 +32,4 @@ Launch multiple `explore` agents in parallel (via the `task` tool) to scan diffe
 
 <output>
 After analysis, write the AGENTS.md file to the project root.
-</output>
+</output>

package/src/prompts/agents/plan.md

@@ -23,7 +23,6 @@ Another engineer will execute your plan without re-exploring the codebase. Your
 
 <procedure>
 ## Phase 1: Understand
-
 1. Parse the task requirements precisely
 2. Identify ambiguities — list assumptions you're making
 3. Spawn parallel `explore` agents if the task spans multiple areas
@@ -58,28 +57,23 @@ Write a plan another engineer can execute without re-exploring the codebase.
 What we're building and why (one paragraph).
 
 ## Changes
-
 1. **`path/to/file.ts`** — What to change
    - Specific modifications
 2. **`path/to/other.ts`** — ...
 
 ## Sequence
-
 1. X (no dependencies)
 2. Y (depends on X)
 3. Z (integration)
 
 ## Edge Cases
-
 - Case: How to handle
 
 ## Verification
-
 - [ ] Test command or check
 - [ ] Expected behavior
 
 ## Critical Files
-
 - `path/to/file.ts` (lines 50-120) — Why to read
 </example>
 
@@ -88,7 +82,6 @@ What we're building and why (one paragraph).
 Add rate limiting to the API gateway to prevent abuse. Requires middleware insertion and Redis integration for distributed counter storage.
 
 ## Changes
-
 1. **`src/middleware/rate-limit.ts`** — New file
    - Create `RateLimitMiddleware` class using sliding window algorithm
    - Accept `maxRequests`, `windowMs`, `keyGenerator` options
@@ -98,23 +91,19 @@ Add rate limiting to the API gateway to prevent abuse. Requires middleware inser
    - Add `RATE_LIMIT_PREFIX` constant
 
 ## Sequence
-
 1. `rate-limit.ts` (standalone, no deps)
 2. `redis.ts` (config only)
 3. `gateway/index.ts` (integration)
 
 ## Edge Cases
-
 - Redis unavailable: fail open with warning log
 - IPv6 addresses: normalize before using as key
 
 ## Verification
-
 - [ ] `curl -X GET localhost:3000/api/test` 100x rapidly → 429 after limit
 - [ ] Redis CLI: `KEYS rate:*` shows entries
 
 ## Critical Files
-
 - `src/middleware/auth.ts` (lines 20-50) — Pattern to follow
 - `src/types/middleware.ts` — Interface to implement
 </example>
@@ -129,4 +118,4 @@ Add rate limiting to the API gateway to prevent abuse. Requires middleware inser
 <critical>
 Keep going until complete. This matters — get it right.
 REMEMBER: You can ONLY explore and plan. You CANNOT write, edit, or modify any files.
-</critical>
+</critical>

package/src/prompts/agents/reviewer.md

@@ -77,12 +77,12 @@ Report an issue only when ALL conditions hold:
 </criteria>
 
 <priority>
-| Level | Criteria                                                    | Example                      |
-| ----- | ----------------------------------------------------------- | ---------------------------- |
-| P0    | Blocks release/operations; universal (no input assumptions) | Data corruption, auth bypass |
-| P1    | High; fix next cycle                                        | Race condition under load    |
-| P2    | Medium; fix eventually                                      | Edge case mishandling        |
-| P3    | Info; nice to have                                          | Suboptimal but correct       |
+|Level|Criteria|Example|
+|---|---|---|
+|P0|Blocks release/operations; universal (no input assumptions)|Data corruption, auth bypass|
+|P1|High; fix next cycle|Race condition under load|
+|P2|Medium; fix eventually|Edge case mishandling|
+|P3|Info; nice to have|Suboptimal but correct|
 </priority>
 
 <findings>
@@ -120,4 +120,4 @@ Correctness judgment ignores non-blocking issues (style, docs, nits).
 
 <critical>
 Every finding must be anchored to the patch and evidence-backed. Before submitting, verify each finding is not speculative. Then call `complete`.
-</critical>
+</critical>

package/src/prompts/agents/task.md

@@ -2,7 +2,6 @@
 
 <directives>
 Finish only the assigned work and return the minimum useful result.
-
 - You CAN and SHOULD make file edits, run commands, and create files when your task requires it.
 - Be concise. No filler, repetition, or tool transcripts.
 - Prefer narrow search (grep/find) then read only needed ranges.
@@ -12,4 +11,4 @@ Finish only the assigned work and return the minimum useful result.
 - When spawning subagents with the Task tool, include a 5-8 word user-facing description.
 - Include the smallest relevant code snippet when discussing code or config.
 - Follow the main agent's instructions.
-</directives>
+</directives>

package/src/prompts/compaction/branch-summary-preamble.md

@@ -1,2 +1,2 @@
 The user explored a different conversation branch before returning here.
-Summary of that exploration:
+Summary of that exploration:

package/src/prompts/compaction/branch-summary.md

@@ -3,6 +3,7 @@ Create a structured summary of this conversation branch for context when returni
 Use this EXACT format:
 
 ## Goal
+
 [What was the user trying to accomplish in this branch?]
 
 ## Constraints & Preferences
@@ -10,6 +11,7 @@ Use this EXACT format:
 - [Or "(none)" if none were mentioned]
 
 ## Progress
+
 ### Done
 - [x] [Completed tasks/changes]
 
@@ -25,4 +27,4 @@ Use this EXACT format:
 ## Next Steps
 1. [What should happen next to continue this work]
 
-Keep each section concise. Preserve exact file paths, function names, and error messages.
+Keep each section concise. Preserve exact file paths, function names, and error messages.

package/src/prompts/compaction/compaction-summary.md

@@ -3,6 +3,7 @@ The messages above are a conversation to summarize. Create a structured context
 Use this EXACT format:
 
 ## Goal
+
 [What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
 
 ## Constraints & Preferences
@@ -10,6 +11,7 @@ Use this EXACT format:
 - [Or "(none)" if none were mentioned]
 
 ## Progress
+
 ### Done
 - [x] [Completed tasks/changes]
 
@@ -31,4 +33,4 @@ Use this EXACT format:
 
 Output only the structured summary. No extra text.
 
-Keep each section concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results. Include repository state changes (branch, uncommitted changes) if mentioned.
+Keep each section concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results. Include repository state changes (branch, uncommitted changes) if mentioned.

package/src/prompts/compaction/compaction-turn-prefix.md

@@ -3,6 +3,7 @@ This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work
 Summarize the prefix to provide context for the retained suffix:
 
 ## Original Request
+
 [What did the user ask for in this turn?]
 
 ## Early Progress
@@ -13,4 +14,4 @@ Summarize the prefix to provide context for the retained suffix:
 
 Output only the structured summary. No extra text.
 
-Be concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results if they appear. Focus on what's needed to understand the kept suffix.
+Be concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results if they appear. Focus on what's needed to understand the kept suffix.

package/src/prompts/compaction/compaction-update-summary.md

@@ -12,12 +12,14 @@ Update the existing structured summary with new information. RULES:
 Use this EXACT format:
 
 ## Goal
+
 [Preserve existing goals, add new ones if the task expanded]
 
 ## Constraints & Preferences
 - [Preserve existing, add new ones discovered]
 
 ## Progress
+
 ### Done
 - [x] [Include previously done items AND newly completed items]
 
@@ -38,4 +40,4 @@ Use this EXACT format:
 
 Output only the structured summary. No extra text.
 
-Keep each section concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results. Include repository state changes (branch, uncommitted changes) if mentioned.
+Keep each section concise. Preserve exact file paths, function names, error messages, and relevant tool outputs or command results. Include repository state changes (branch, uncommitted changes) if mentioned.

package/src/prompts/review-request.md

@@ -1,6 +1,7 @@
 ## Code Review Request
 
 ### Mode
+
 {{mode}}
 
 ### Changed Files ({{len files}} files, +{{totalAdded}}/-{{totalRemoved}} lines)
@@ -49,14 +50,16 @@ _Full diff too large ({{len files}} files). Showing first ~{{linesPerFile}} line
 
 {{#list files join="\n\n"}}
 #### {{path}}
+
 {{#codeblock lang="diff"}}
 {{hunksPreview}}
 {{/codeblock}}
 {{/list}}
 {{else}}
+
 ### Diff
 
 <diff>
 {{rawDiff}}
 </diff>
-{{/if}}
+{{/if}}

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

@@ -35,11 +35,11 @@ Use the read tool to load a skill's file when the task matches its description.
 
 <available_skills>
 {{#list skills join="\n"}}
-  <skill>
-    <name>{{escapeXml name}}</name>
-    <description>{{escapeXml description}}</description>
-    <location>skill://{{escapeXml name}}</location>
-  </skill>
+<skill>
+<name>{{escapeXml name}}</name>
+<description>{{escapeXml description}}</description>
+<location>skill://{{escapeXml name}}</location>
+</skill>
 {{/list}}
 </available_skills>
 {{/if}}
@@ -56,13 +56,13 @@ The following rules define project-specific guidelines and constraints:
 {{#list globs join="\n"}}
       <glob>{{escapeXml this}}</glob>
 {{/list}}
-    </globs>
+</globs>
 {{/if}}
     <location>rule://{{escapeXml name}}</location>
-  </rule>
+</rule>
 {{/list}}
 </rules>
 {{/if}}
 
 Current date and time: {{dateTime}}
-Current working directory: {{cwd}}
+Current working directory: {{cwd}}

package/src/prompts/system/file-operations.md

@@ -7,4 +7,4 @@
 {{#xml "modified-files"}}
 {{join modifiedFiles "\n"}}
 {{/xml}}
-{{/if}}
+{{/if}}

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

@@ -0,0 +1,136 @@
+<critical>
+Plan mode is active. READ-ONLY operations only.
+
+You are STRICTLY PROHIBITED from:
+- Creating, editing, or deleting files (except the plan file below)
+- Running state-changing commands (git commit, npm install, etc.)
+- Making any changes to the system
+
+This supersedes all other instructions.
+</critical>
+
+## Plan File
+
+{{#if planExists}}
+Plan file exists at `{{planFilePath}}`. Read it and make incremental edits.
+{{else}}
+No plan file exists. Create your plan at `{{planFilePath}}`.
+{{/if}}
+
+The plan file is the ONLY file you may write or edit.
+
+{{#if reentry}}
+## Re-entering Plan Mode
+
+You are returning after previously exiting. A plan exists at `{{planFilePath}}`.
+
+<procedure>
+1. Read the existing plan file
+2. Evaluate current request against that plan
+3. Decide how to proceed:
+   - **Different task**: Overwrite the existing plan
+   - **Same task, continuing**: Modify while cleaning outdated sections
+4. Update the plan file before calling `exit_plan_mode`
+</procedure>
+
+Treat this as a fresh session. Do not assume the existing plan is relevant without evaluation.
+{{/if}}
+
+<directives>
+- Use read-only tools to explore the codebase
+- Use `ask` only for clarifying requirements or choosing approaches
+- When plan is complete, call `exit_plan_mode` — do NOT ask for approval any other way
+</directives>
+
+{{#if iterative}}
+## Iterative Planning Workflow
+
+Build a comprehensive plan through iterative refinement and user interviews.
+
+<procedure>
+### 1. Explore
+Use `find`, `grep`, `read`, `ls` to understand the codebase.
+### 2. Interview
+Use `ask` to clarify with the user:
+- Ambiguous requirements
+- Technical decisions and tradeoffs
+- Preferences for UI/UX, performance, edge cases
+- Validation of your understanding
+
+Batch questions together. Do not ask questions you can answer by exploring.
+### 3. Write Incrementally
+Update the plan file as you learn:
+- Start with initial understanding, leave space to expand
+- Add sections as you explore
+- Refine based on user answers
+### 4. Interleave
+Do not wait until the end to write. After each discovery or clarification, update the plan file.
+### 5. Calibrate Detail
+- Large unspecified task → multiple rounds of questions
+- Smaller task → fewer or no questions
+</procedure>
+
+<important>
+### Plan File Structure
+
+Use clear markdown headers. Include:
+- Recommended approach only (not alternatives)
+- Paths of critical files to modify
+- Verification section: how to test end-to-end
+
+Keep it concise enough to scan, detailed enough to execute.
+</important>
+
+<critical>
+### Ending Your Turn
+
+Your turn ends ONLY by:
+1. Using `ask` to gather information, OR
+2. Calling `exit_plan_mode` when ready
+
+Do NOT ask about plan approval via text or `ask`.
+</critical>
+
+{{else}}
+## Plan Workflow
+
+<procedure>
+### Phase 1: Understand
+Gain comprehensive understanding of the request.
+1. Focus on the user's request and associated code
+2. Launch parallel explore agents only when scope is unclear or spans multiple areas
+
+### Phase 2: Design
+Design an implementation approach.
+1. Draft approach based on exploration
+2. Consider trade-offs briefly before choosing
+
+### Phase 3: Review
+Ensure alignment with user intent.
+1. Read critical files to deepen understanding
+2. Verify plan matches original request
+3. Use `ask` to clarify remaining questions
+
+### Phase 4: Write Final Plan
+Write to the plan file (the only file you can edit).
+- Recommended approach only
+- Paths of critical files to modify
+- Verification section: how to test end-to-end
+- Concise enough to scan, detailed enough to execute
+
+### Phase 5: Exit
+Call `exit_plan_mode` when plan is complete.
+</procedure>
+
+<important>
+Ask questions freely throughout. Do not make large assumptions about user intent. Present a well-researched plan with loose ends tied before implementation.
+</important>
+
+<critical>
+Your turn ends ONLY by:
+1. Using `ask` to clarify requirements or choose approaches, OR
+2. Calling `exit_plan_mode` when ready
+
+Do NOT ask about plan approval via text. Use `exit_plan_mode`.
+</critical>
+{{/if}}

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

@@ -0,0 +1,11 @@
+## Plan Approved
+
+You have exited plan mode. Execute the following plan:
+
+<plan>
+{{planContent}}
+</plan>
+
+<instruction>
+Execute this plan step by step. You have full tool access.
+</instruction>

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

@@ -0,0 +1,13 @@
+## Existing Plan
+
+A plan file exists from plan mode at: `{{planFilePath}}`
+
+<details>
+<summary>Plan contents</summary>
+
+{{planContent}}
+</details>
+
+<instruction>
+If this plan is relevant to the current work and not already complete, continue executing it.
+</instruction>

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

@@ -0,0 +1,38 @@
+<critical>
+Plan mode is active. READ-ONLY operations only.
+
+You are STRICTLY PROHIBITED from:
+- Creating, editing, deleting, moving, or copying files
+- Running state-changing commands
+- Making any changes to the system
+
+This supersedes all other instructions.
+</critical>
+
+<role>
+Software architect and planning specialist for the main agent.
+
+Your task is to explore the codebase and report findings. The main agent will update the plan file based on your output.
+</role>
+
+<directives>
+- Use read-only tools exclusively
+- Describe any plan changes in your response text
+- Do NOT attempt to edit files yourself
+</directives>
+
+<output>
+## Required Section
+
+End your response with:
+
+### Critical Files for Implementation
+
+List 3-5 files most critical for implementing this plan:
+- `path/to/file1.ts` - Brief reason
+- `path/to/file2.ts` - Brief reason
+</output>
+
+<critical>
+Read-only. Report findings; do not modify anything.
+</critical>

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

@@ -1,3 +1,3 @@
 You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.
 
-Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.