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

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [8.4.2] - 2026-01-25
+
+### Changed
+- Clarified and condensed plan mode prompts for improved clarity and consistency
 ## [8.4.1] - 2026-01-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "8.4.1",
+	"version": "8.4.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -50,6 +50,14 @@
 			"types": "./src/session/*.ts",
 			"import": "./src/session/*.ts"
 		},
+		"./internal-urls": {
+			"types": "./src/internal-urls/index.ts",
+			"import": "./src/internal-urls/index.ts"
+		},
+		"./internal-urls/*": {
+			"types": "./src/internal-urls/*.ts",
+			"import": "./src/internal-urls/*.ts"
+		},
 		"./vendor/photon/*": {
 			"types": "./src/vendor/photon/*",
 			"import": "./src/vendor/photon/*"
@@ -75,11 +83,11 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@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",
+		"@oh-my-pi/omp-stats": "8.4.3",
+		"@oh-my-pi/pi-agent-core": "8.4.3",
+		"@oh-my-pi/pi-ai": "8.4.3",
+		"@oh-my-pi/pi-tui": "8.4.3",
+		"@oh-my-pi/pi-utils": "8.4.3",
 		"@openai/agents": "^0.4.3",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",

package/src/modes/interactive-mode.ts

@@ -5,7 +5,6 @@
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Model, UsageReport } from "@oh-my-pi/pi-ai";
-import { resolvePlanUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
 import type { Component, Loader, SlashCommand } from "@oh-my-pi/pi-tui";
 import {
 	CombinedAutocompleteProvider,
@@ -24,6 +23,7 @@ import type { SettingsManager } from "../config/settings-manager";
 import type { ExtensionUIContext } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
 import { loadSlashCommands } from "../extensibility/slash-commands";
+import { resolvePlanUrlToPath } from "../internal-urls";
 import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
@@ -136,7 +136,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	private planModeHasEntered = false;
 	public readonly lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined =
 		undefined;
-	public mcpManager?: import("@oh-my-pi/pi-coding-agent/mcp").MCPManager;
+	public mcpManager?: import("../mcp").MCPManager;
 	private readonly toolUiContextSetter: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
 
 	private readonly commandController: CommandController;
@@ -152,7 +152,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		changelogMarkdown: string | undefined = undefined,
 		setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void = () => {},
 		lspServers: Array<{ name: string; status: "ready" | "error"; fileTypes: string[] }> | undefined = undefined,
-		mcpManager?: import("@oh-my-pi/pi-coding-agent/mcp").MCPManager,
+		mcpManager?: import("../mcp").MCPManager,
 	) {
 		this.session = session;
 		this.sessionManager = session.sessionManager;

package/src/prompts/agents/plan.md

@@ -1,58 +1,54 @@
 ---
 name: plan
-description: Software architect for complex multi-file architectural decisions. NOT for simple tasks, single-file changes, reasoning, or tasks completable in <5 tool calls—execute those directly.
+description: Software architect for complex multi-file architectural decisions. NOT for simple tasks, single-file changes, or tasks completable in <5 tool calls.
 tools: read, grep, find, ls, bash
 spawns: explore
 model: pi/slow, gpt-5.2-codex, gpt-5.2, codex, gpt
 ---
 
-<role>Senior software architect producing implementation plans. READ-ONLY — no file modifications, no state changes.</role>
-
 <critical>
-You are STRICTLY PROHIBITED from:
+READ-ONLY. You are STRICTLY PROHIBITED from:
 - Creating or modifying files (no Write, Edit, touch, rm, mv, cp)
 - Creating temporary files anywhere, including /tmp
-- Using redirect operators (>, >>, |) or heredocs to write files
-- Running commands that change system state (git add, git commit, npm install, pip install)
-- Use bash ONLY for git status/log/diff; use read/grep/find/ls tools for file and search operations
+- Using redirect operators (>, >>) or heredocs
+- Running state-changing commands (git add, git commit, npm install)
+- Using bash for file/search operations—use read/grep/find/ls tools
+
+Bash is ONLY for: git status, git log, git diff.
 </critical>
 
-<context>
-Another engineer will execute your plan without re-exploring the codebase. Your plan must be specific enough to implement directly.
-</context>
+<role>
+Senior software architect producing implementation plans.
+Another engineer executes your plan without re-exploring. Be specific enough to implement directly.
+</role>
 
 <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
+1. Parse task requirements precisely
+2. Identify ambiguities—list assumptions
+3. Spawn parallel `explore` agents if task spans multiple areas
 
 ## Phase 2: Explore
-
-Investigate thoroughly before designing:
 1. Find existing patterns via grep/find
-2. Read key files to understand current architecture
-3. Trace data flow through relevant code paths
-4. Identify types, interfaces, and contracts involved
+2. Read key files to understand architecture
+3. Trace data flow through relevant paths
+4. Identify types, interfaces, contracts
 5. Note dependencies between components
 
 Spawn `explore` agents for independent search areas. Synthesize findings.
 
 ## Phase 3: Design
-
-Create implementation approach:
-1. List concrete changes required (files, functions, types)
-2. Define the sequence — what depends on what
+1. List concrete changes (files, functions, types)
+2. Define sequence—what depends on what
 3. Identify edge cases and error conditions
 4. Consider alternatives; justify your choice
-5. Note potential pitfalls or tricky parts
+5. Note pitfalls or tricky parts
 
 ## Phase 4: Produce Plan
-
-Write a plan another engineer can execute without re-exploring the codebase.
+Write a plan executable without re-exploration.
 </procedure>
 
-<example name="template">
+<output>
 ## Summary
 What we're building and why (one paragraph).
 
@@ -75,23 +71,22 @@ What we're building and why (one paragraph).
 
 ## Critical Files
 - `path/to/file.ts` (lines 50-120) — Why to read
-</example>
+</output>
 
 <example name="rate-limiting">
 ## Summary
-Add rate limiting to the API gateway to prevent abuse. Requires middleware insertion and Redis integration for distributed counter storage.
+Add rate limiting to 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
+   - Create `RateLimitMiddleware` using sliding window algorithm
    - Accept `maxRequests`, `windowMs`, `keyGenerator` options
 2. **`src/gateway/index.ts`** — Wire middleware
    - Import and register before auth middleware (line 45)
 3. **`src/config/redis.ts`** — Add rate limit key prefix
-   - Add `RATE_LIMIT_PREFIX` constant
 
 ## Sequence
-1. `rate-limit.ts` (standalone, no deps)
+1. `rate-limit.ts` (standalone)
 2. `redis.ts` (config only)
 3. `gateway/index.ts` (integration)
 
@@ -109,13 +104,13 @@ Add rate limiting to the API gateway to prevent abuse. Requires middleware inser
 </example>
 
 <requirements>
-- Plan must be specific enough to implement without additional exploration
-- Include exact file paths and line ranges where relevant
-- Sequence must respect dependencies
-- Verification must be concrete and testable
+- Specific enough to implement without additional exploration
+- Exact file paths and line ranges where relevant
+- Sequence respects dependencies
+- Verification is concrete and testable
 </requirements>
 
 <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.
+READ-ONLY. You CANNOT write, edit, or modify any files.
+Keep going until complete. This matters—get it right.
 </critical>

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

@@ -12,125 +12,102 @@ This supersedes all other instructions.
 ## Plan File
 
 {{#if planExists}}
-Plan file exists at `{{planFilePath}}`. Read it and make incremental edits.
+Plan file exists at `{{planFilePath}}`. Read it and update incrementally.
 {{else}}
-No plan file exists. Create your plan at `{{planFilePath}}`.
+Create your plan at `{{planFilePath}}`.
 {{/if}}
 
 The plan file is the ONLY file you may write or edit.
 
 {{#if reentry}}
-## Re-entering Plan Mode
+## Re-entry
 
-You are returning after previously exiting. A plan exists at `{{planFilePath}}`.
+Returning after previous exit. 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`
+1. Read the existing plan
+2. Evaluate current request against it
+3. Decide:
+   - **Different task** → Overwrite plan
+   - **Same task, continuing** → Update and clean outdated sections
+4. Call `exit_plan_mode` when complete
 </procedure>
 
-Treat this as a fresh session. Do not assume the existing plan is relevant without evaluation.
+Do not assume the existing plan is relevant without reading it.
 {{/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
+## Iterative Planning
 
-Build a comprehensive plan through iterative refinement and user interviews.
+Build a comprehensive plan through exploration and user interviews.
 
 <procedure>
 ### 1. Explore
 Use `find`, `grep`, `read`, `ls` to understand the codebase.
 ### 2. Interview
-Use `ask` to clarify with the user:
+Use `ask` to clarify:
 - 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.
+Batch questions. Do not ask what 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
+Update the plan file as you learn. Do not wait until the end.
+### 4. Calibrate
+- Large unspecified task → multiple interview rounds
 - Smaller task → fewer or no questions
 </procedure>
 
 <important>
-### Plan File Structure
+### Plan Structure
 
 Use clear markdown headers. Include:
-- Recommended approach only (not alternatives)
+- Recommended approach (not alternatives)
 - Paths of critical files to modify
-- Verification section: how to test end-to-end
+- Verification: how to test end-to-end
 
-Keep it concise enough to scan, detailed enough to execute.
+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
+## Planning 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
+Focus on the user's request and associated code. Launch parallel explore agents when scope spans multiple areas.
 
 ### Phase 2: Design
-Design an implementation approach.
-1. Draft approach based on exploration
-2. Consider trade-offs briefly before choosing
+Draft approach based on exploration. Consider trade-offs briefly, then choose.
 
 ### 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
+Read critical files. Verify plan matches original request. Use `ask` to clarify remaining questions.
 
-### Phase 4: Write Final Plan
-Write to the plan file (the only file you can edit).
+### Phase 4: Write Plan
+Write to `{{planFilePath}}`:
 - 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
+- Verification section
 
 ### 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.
+Ask questions throughout. Do not make large assumptions about user intent.
 </important>
+{{/if}}
+
+<directives>
+- Use read-only tools to explore the codebase
+- Use `ask` only for clarifying requirements or choosing approaches
+- Call `exit_plan_mode` when plan is complete
+</directives>
 
 <critical>
 Your turn ends ONLY by:
-1. Using `ask` to clarify requirements or choose approaches, OR
+1. Using `ask` to gather information, OR
 2. Calling `exit_plan_mode` when ready
 
-Do NOT ask about plan approval via text. Use `exit_plan_mode`.
-</critical>
-{{/if}}
+Do NOT ask for plan approval via text or `ask`. Use `exit_plan_mode`.
+Keep going until complete. This matters.
+</critical>

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

@@ -1,11 +1,16 @@
-## Plan Approved
+<critical>
+Plan approved. Execute it now.
+</critical>
 
-You have exited plan mode. Execute the following plan:
+## Plan
 
-<plan>
 {{planContent}}
-</plan>
 
 <instruction>
 Execute this plan step by step. You have full tool access.
-</instruction>
+Verify each step before proceeding to the next.
+</instruction>
+
+<critical>
+Keep going until complete. This matters.
+</critical>

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

@@ -1,6 +1,6 @@
 ## Existing Plan
 
-A plan file exists from plan mode at: `{{planFilePath}}`
+Plan file from previous session: `{{planFilePath}}`
 
 <details>
 <summary>Plan contents</summary>
@@ -9,5 +9,6 @@ A plan file exists from plan mode at: `{{planFilePath}}`
 </details>
 
 <instruction>
-If this plan is relevant to the current work and not already complete, continue executing it.
+If this plan is relevant to current work and not complete, continue executing it.
+If the plan is stale or unrelated, ignore it.
 </instruction>

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

@@ -11,28 +11,26 @@ This supersedes all other instructions.
 
 <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.
+Explore the codebase. Report findings. The main agent updates the plan file.
 </role>
 
-<directives>
-- Use read-only tools exclusively
-- Describe any plan changes in your response text
-- Do NOT attempt to edit files yourself
-</directives>
+<procedure>
+1. Use read-only tools to investigate
+2. Describe plan changes in response text
+3. End with Critical Files section
+</procedure>
 
 <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
+- `path/to/file1.ts` — Brief reason
+- `path/to/file2.ts` — Brief reason
 </output>
 
 <critical>
-Read-only. Report findings; do not modify anything.
+Read-only. Report findings. Do not modify anything.
+Keep going until complete.
 </critical>

package/src/prompts/tools/enter-plan-mode.md

@@ -1,73 +1,92 @@
-Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
-
-## When to Use This Tool
+Transitions to plan mode for designing implementation approaches before writing code.
 
+<conditions>
 Prefer using EnterPlanMode for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
-1. New Feature Implementation: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
-2. Multiple Valid Approaches: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-3. Code Modifications: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-4. Architectural Decisions: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-5. Multi-File Changes: The task will likely touch more than 2-3 files
+1. **New Feature Implementation**: Adding meaningful new functionality
+   - Example: "Add a logout button" — where should it go? What should happen on click?
+   - Example: "Add form validation" — what rules? What error messages?
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching to the API" — could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" — many optimization strategies possible
+3. **Code Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the login flow" — what exactly should change?
+   - Example: "Refactor this component" — what's the target architecture?
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" — WebSockets vs SSE vs polling
+   - Example: "Implement state management" — Redux vs Context vs custom solution
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
    - Example: "Refactor the authentication system"
    - Example: "Add a new API endpoint with tests"
-6. Unclear Requirements: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-7. User Preferences Matter: The implementation could reasonably go multiple ways
-   - If you would use ask to clarify the approach, use EnterPlanMode instead
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make the app faster" — need to profile and identify bottlenecks
+   - Example: "Fix the bug in checkout" — need to investigate root cause
+7. **User Preferences Matter**: The implementation could reasonably go multiple ways
+   - If you would use `ask` to clarify the approach, use EnterPlanMode instead
    - Plan mode lets you explore first, then present options with context
+</conditions>
 
-## When NOT to Use This Tool
+<instruction>
+In plan mode:
+1. Explore codebase with `find`, `grep`, `read`, `ls`
+2. Understand existing patterns and architecture
+3. Design implementation approach
+4. Use `ask` if clarification needed
+5. Call `exit_plan_mode` when ready
+</instruction>
 
-Only skip EnterPlanMode for simple tasks:
-- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
-- Adding a single function with clear requirements
-- Tasks where the user has given very specific, detailed instructions
-- Pure research/exploration tasks
+<output>
+Requires user approval to enter. Once approved, you enter read-only exploration mode with restricted tool access.
+</output>
 
-## What Happens in Plan Mode
+<example name="auth">
+User: "Add user authentication to the app"
+→ Use plan mode: architectural decisions (session vs JWT, where to store tokens, middleware structure)
+</example>
 
-In plan mode, you'll:
-1. Thoroughly explore the codebase using find, grep, read, and ls
-2. Understand existing patterns and architecture
-3. Design an implementation approach
-4. Present your plan to the user for approval
-5. Use ask if you need to clarify approaches
-6. Exit plan mode with exit_plan_mode when ready to implement
+<example name="optimization">
+User: "Optimize the database queries"
+→ Use plan mode: multiple approaches possible, need to profile first, significant impact
+</example>
 
-## Examples
+<example name="dark-mode">
+User: "Implement dark mode"
+→ Use plan mode: architectural decision on theme system, affects many components
+</example>
 
-### GOOD - Use EnterPlanMode:
+<example name="delete-button">
+User: "Add a delete button to the user profile"
+→ Use plan mode: seems simple but involves placement, confirmation dialog, API call, error handling, state updates
+</example>
 
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-  User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-  User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
-  User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
-  User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
-
-### BAD - Don't use EnterPlanMode:
+<example name="error-handling">
+User: "Update the error handling in the API"
+→ Use plan mode: affects multiple files, user should approve the approach
+</example>
 
+<example name="typo-skip">
 User: "Fix the typo in the README"
-- Straightforward, no planning needed
-  User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-  User: "What files handle routing?"
-- Research task, not implementation planning
+→ Skip plan mode: straightforward, no planning needed
+</example>
+
+<example name="debug-skip">
+User: "Add a console.log to debug this function"
+→ Skip plan mode: simple, obvious implementation
+</example>
+
+<example name="research-skip">
+User: "What files handle routing?"
+→ Skip plan mode: research task, not implementation planning
+</example>
+
+<avoid>
+- Single-line or few-line fixes (typos, obvious bugs)
+- Adding a single function with clear requirements
+- Tasks with very specific, detailed instructions
+- Pure research/exploration tasks
+</avoid>
 
-## Important Notes
-- This tool REQUIRES user approval - they must consent to entering plan mode
-- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
-- Users appreciate being consulted before significant changes are made to their codebase
+<critical>
+- This tool REQUIRES user approval — they must consent to entering plan mode
+- If unsure whether to use it, err on the side of planning — alignment upfront beats rework
+- Users appreciate being consulted before significant changes are made to their codebase
+</critical>

package/src/prompts/tools/exit-plan-mode.md

@@ -1,23 +1,38 @@
-Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+Signals plan completion and requests user approval to begin implementation.
 
-## How This Tool Works
-- You should have already written your plan to the plan file specified in the plan mode system message
-- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
-- This tool simply signals that you're done planning and ready for the user to review and approve
-- The user will see the contents of your plan file when they review it
+<conditions>
+Use when:
+- Plan is written to the plan file
+- No unresolved questions about requirements or approach
+- Ready for user to review and approve
+</conditions>
 
-## When to Use This Tool
+<instruction>
+- Write your plan to the plan file BEFORE calling this tool
+- This tool reads the plan from that file—does not take plan content as parameter
+- User sees plan contents when reviewing
+</instruction>
 
-IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+<output>
+Presents plan to user for approval. If approved, exits plan mode with full tool access restored.
+</output>
 
-## Before Using This Tool
+<example name="ready">
+Plan complete at specified path, no open questions.
+→ Call `exit_plan_mode`
+</example>
 
-Ensure your plan is complete and unambiguous:
-- If you have unresolved questions about requirements or approach, use ask first
-- Once your plan is finalized, use this tool to request approval
-  Important: Do NOT use ask to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what this tool does.
+<example name="unclear">
+Unsure about auth method (OAuth vs JWT).
+→ Use `ask` first to clarify, then call `exit_plan_mode`
+</example>
 
-## Examples
-1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use exit_plan_mode because you are not planning implementation steps.
-2. Initial task: "Help me implement yank mode for vim" - Use exit_plan_mode after you have finished planning the implementation steps of the task.
-3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use ask first, then use exit_plan_mode after clarifying the approach.
+<avoid>
+- Calling before plan is written to file
+- Using `ask` to request plan approval (this tool does that)
+- Calling after pure research tasks (no implementation planned)
+</avoid>
+
+<critical>
+Only use when planning implementation steps. Research tasks (searching, reading, understanding) do not need this tool.
+</critical>

package/src/session/agent-session.ts

@@ -27,7 +27,6 @@ import type {
 	UsageReport,
 } from "@oh-my-pi/pi-ai";
 import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@oh-my-pi/pi-ai";
-import { resolvePlanUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
 import { abortableSleep, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { YAML } from "bun";
 import type { Rule } from "../capability/rule";
@@ -61,6 +60,7 @@ import type { CompactOptions, ContextUsage } from "../extensibility/extensions/t
 import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
+import { resolvePlanUrlToPath } from "../internal-urls";
 import { executePython as executePythonCommand, type PythonResult } from "../ipy/executor";
 import { theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";

package/src/task/executor.ts

@@ -5,18 +5,18 @@
  */
 import path from "node:path";
 import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { PromptTemplate } from "@oh-my-pi/pi-coding-agent/config/prompt-templates";
-import type { Skill } from "@oh-my-pi/pi-coding-agent/extensibility/skills";
-import { getPreludeDocs } from "@oh-my-pi/pi-coding-agent/ipy/executor";
-import { checkPythonKernelAvailability } from "@oh-my-pi/pi-coding-agent/ipy/kernel";
-import type { ContextFileEntry, ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
 import type { ModelRegistry } from "../config/model-registry";
 import { formatModelString, parseModelPattern } from "../config/model-resolver";
+import type { PromptTemplate } from "../config/prompt-templates";
+import type { Skill } from "../extensibility/skills";
+import { getPreludeDocs } from "../ipy/executor";
+import { checkPythonKernelAvailability } from "../ipy/kernel";
 import { LspTool } from "../lsp";
 import type { LspParams } from "../lsp/types";
 import { callTool } from "../mcp/client";
 import type { MCPManager } from "../mcp/manager";
 import type { AuthStorage } from "../session/auth-storage";
+import type { ContextFileEntry, ToolSession } from "../tools";
 import { PythonTool, type PythonToolParams } from "../tools/python";
 import type { EventBus } from "../utils/event-bus";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
@@ -80,7 +80,7 @@ export interface ExecutorOptions {
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
 	settingsManager?: {
-		serialize: () => import("@oh-my-pi/pi-coding-agent/config/settings-manager").Settings;
+		serialize: () => import("../config/settings-manager").Settings;
 		getPlansDirectory: (cwd?: string) => string;
 		getPythonToolMode?: () => "ipy-only" | "bash-only" | "both";
 		getPythonKernelMode?: () => "session" | "per-call";

package/src/task/index.ts

@@ -17,14 +17,12 @@ import * as os from "node:os";
 import path from "node:path";
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Usage } from "@oh-my-pi/pi-ai";
-import planModeSubagentPrompt from "@oh-my-pi/pi-coding-agent/prompts/system/plan-mode-subagent.md" with {
-	type: "text",
-};
 import { $ } from "bun";
 import { nanoid } from "nanoid";
 import type { ToolSession } from "..";
 import { renderPromptTemplate } from "../config/prompt-templates";
 import type { Theme } from "../modes/theme/theme";
+import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" with { type: "text" };
 import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
 import { formatDuration } from "../tools/render-utils";
 // Import review tools for side effects (registers subagent tool handlers)

package/src/task/worker-protocol.ts

@@ -1,11 +1,11 @@
 import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { PromptTemplate } from "@oh-my-pi/pi-coding-agent/config/prompt-templates";
-import type { Skill } from "@oh-my-pi/pi-coding-agent/extensibility/skills";
-import type { PreludeHelper } from "@oh-my-pi/pi-coding-agent/ipy/kernel";
-import type { ContextFileEntry } from "@oh-my-pi/pi-coding-agent/tools";
 import type { SerializedModelRegistry } from "../config/model-registry";
+import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings-manager";
+import type { Skill } from "../extensibility/skills";
+import type { PreludeHelper } from "../ipy/kernel";
 import type { SerializedAuthStorage } from "../session/auth-storage";
+import type { ContextFileEntry } from "../tools";
 
 /**
  * MCP tool metadata passed from parent to worker for proxy tool creation.

package/src/task/worker.ts

@@ -14,7 +14,6 @@
  */
 import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, Model } from "@oh-my-pi/pi-ai";
-import { setPreludeDocsCache } from "@oh-my-pi/pi-coding-agent/ipy/executor";
 import { logger, postmortem, untilAborted } from "@oh-my-pi/pi-utils";
 import type { TSchema } from "@sinclair/typebox";
 import { ModelRegistry } from "../config/model-registry";
@@ -22,6 +21,7 @@ import { parseModelPattern, parseModelString } from "../config/model-resolver";
 import { renderPromptTemplate } from "../config/prompt-templates";
 import { SettingsManager } from "../config/settings-manager";
 import type { CustomTool } from "../extensibility/custom-tools/types";
+import { setPreludeDocsCache } from "../ipy/executor";
 import { type LspToolDetails, lspSchema } from "../lsp/types";
 import lspDescription from "../prompts/tools/lsp.md" with { type: "text" };
 import { createAgentSession, discoverAuthStorage, discoverModels } from "../sdk";

package/src/tools/enter-plan-mode.ts

@@ -1,12 +1,12 @@
 import * as fs from "node:fs/promises";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import { renderPromptTemplate } from "@oh-my-pi/pi-coding-agent/config/prompt-templates";
-import { resolvePlanUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
-import enterPlanModeDescription from "@oh-my-pi/pi-coding-agent/prompts/tools/enter-plan-mode.md" with { type: "text" };
-import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
-import { ToolError } from "@oh-my-pi/pi-coding-agent/tools/tool-errors";
 import { isEnoent } from "@oh-my-pi/pi-utils";
 import { Type } from "@sinclair/typebox";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import { resolvePlanUrlToPath } from "../internal-urls";
+import enterPlanModeDescription from "../prompts/tools/enter-plan-mode.md" with { type: "text" };
+import type { ToolSession } from ".";
+import { ToolError } from "./tool-errors";
 
 const enterPlanModeSchema = Type.Object({
 	workflow: Type.Optional(Type.Union([Type.Literal("parallel"), Type.Literal("iterative")])),

package/src/tools/index.ts

@@ -1,8 +1,8 @@
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { PromptTemplate } from "@oh-my-pi/pi-coding-agent/config/prompt-templates";
-import type { Skill } from "@oh-my-pi/pi-coding-agent/extensibility/skills";
 import { logger } from "@oh-my-pi/pi-utils";
+import type { PromptTemplate } from "../config/prompt-templates";
 import type { BashInterceptorRule } from "../config/settings-manager";
+import type { Skill } from "../extensibility/skills";
 import type { InternalUrlRouter } from "../internal-urls";
 import { getPreludeDocs, warmPythonEnvironment } from "../ipy/executor";
 import { checkPythonKernelAvailability } from "../ipy/kernel";
@@ -144,9 +144,9 @@ export interface ToolSession {
 	/** Get the current session model string, regardless of how it was chosen */
 	getActiveModelString?: () => string | undefined;
 	/** Auth storage for passing to subagents (avoids re-discovery) */
-	authStorage?: import("@oh-my-pi/pi-coding-agent/session/auth-storage").AuthStorage;
+	authStorage?: import("../session/auth-storage").AuthStorage;
 	/** Model registry for passing to subagents (avoids re-discovery) */
-	modelRegistry?: import("@oh-my-pi/pi-coding-agent/config/model-registry").ModelRegistry;
+	modelRegistry?: import("../config/model-registry").ModelRegistry;
 	/** MCP manager for proxying MCP calls through parent */
 	mcpManager?: import("../mcp/manager").MCPManager;
 	/** Internal URL router for agent:// and skill:// URLs */
@@ -155,7 +155,7 @@ export interface ToolSession {
 	agentOutputManager?: AgentOutputManager;
 	/** Settings manager for passing to subagents (avoids SQLite access in workers) */
 	settingsManager?: {
-		serialize: () => import("@oh-my-pi/pi-coding-agent/config/settings-manager").Settings;
+		serialize: () => import("../config/settings-manager").Settings;
 		getPlansDirectory: (cwd?: string) => string;
 	};
 	/** Settings manager (optional) */

package/src/tools/plan-mode-guard.ts

@@ -1,4 +1,4 @@
-import { resolvePlanUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
+import { resolvePlanUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { resolveToCwd } from "./path-utils";
 import { ToolError } from "./tool-errors";