@pi-minimal/plan-mode 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-minimal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @pi-minimal/plan-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`/plan` toggles plan mode. When on, the system prompt tells the agent to stay
+read-only and output a plan. Nothing is blocked: the agent is trusted to obey.
+
+## Install
+
+```sh
+pi install ~/Code/pi-minimal/plan-mode
+```
+
+## Settings
+
+Put settings in `~/.pi/agent/settings.json` (global) or `.pi/settings.json`
+(project), under `"pi-minimal"."plan-mode"`. Merge the keys; do not overwrite
+the file. Settings are read at session start (use `/reload`).
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `keyboardShortcut` | string (key id) | `ctrl+alt+p` | Shortcut that toggles plan mode. No pi default uses it. Some terminals need Alt/Option set as Meta, and multiplexers such as tmux may drop modifiers. If it does not work, pick another key. |
+
+```json
+{ "pi-minimal": { "plan-mode": { "keyboardShortcut": "ctrl+alt+o" } } }
+```

package/index.ts

@@ -0,0 +1,42 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PROMPT_PLAN_MODE_OFF, PROMPT_PLAN_MODE_ON, PROMPT_PLAN_MODE_REMINDER } from "./prompts.js";
+import { loadSettings } from "./settings.js";
+
+export default function (pi: ExtensionAPI) {
+	let on = false;
+	let used = false; // only sessions that used /plan at least once get a section in the prompt.
+
+	const togglePlanMode = (ctx: ExtensionContext) => {
+		on = !on;
+		used ||= on;
+		ctx.ui.setStatus("plan-mode", on ? ctx.ui.theme.fg("warning", "⏸ plan") : undefined);
+		ctx.ui.notify(`Plan mode ${on ? "ON" : "OFF"} (from your next message)`, "info");
+	};
+
+	pi.registerCommand("plan", {
+		description: "Toggle read-only plan mode (prompt-enforced)",
+		handler: async (_args, ctx) => togglePlanMode(ctx),
+	});
+
+	// Read at session_start: settings are not available while the extension loads.
+	pi.on("session_start", () => {
+		const { keyboardShortcut } = loadSettings(pi);
+		pi.registerShortcut(keyboardShortcut, { description: "Toggle plan mode", handler: togglePlanMode });
+	});
+
+	// pi diffs the section into the transcript only when its text changes.
+	pi.on("before_agent_start", (event) => {
+		if (used) event.systemPromptOptions.sections.plan_mode = on ? PROMPT_PLAN_MODE_ON : PROMPT_PLAN_MODE_OFF;
+	});
+
+	// Short reminder (not stored in the transcript) to avoid the agent forgetting that plan mode is on during long runs.
+	pi.on("context", (event) => {
+		if (!on) return;
+		return {
+			messages: [
+				...event.messages,
+				{ role: "user", content: [{ type: "text", text: PROMPT_PLAN_MODE_REMINDER }], timestamp: Date.now() },
+			],
+		};
+	});
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@pi-minimal/plan-mode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Minimal plan mode for pi: /plan toggles a read-only instruction in the system prompt.",
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "check": "tsc -p ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/EviHex/pi-minimal.git",
+    "directory": "plan-mode"
+  },
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "prompts.ts",
+    "settings.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts.ts

@@ -0,0 +1,9 @@
+export const PROMPT_PLAN_MODE_ON = `PLAN MODE is ON. Read and investigate only. Change nothing: no files, repo state, processes, docs, or remote data.
+- Allowed: reading files, searching, read-only commands (ls, rg, cat, git/jj log|diff|status), and read-only API/MCP calls (get, list, search, read-only queries).
+- Forbidden: anything that writes: edit/write tools, sed -i, writing to files with > or >> or tee (/dev/null or /tmp is fine), rm/mv/cp, installs, commits or checkouts, kill, POST/PUT/PATCH/DELETE requests, and MCP/API calls that create, update, or delete (databases, configs, Datadog dashboards, monitors, documentation). Do not delegate such work to subagents.
+- If you are not sure a command is read-only, do not run it. Put it in the plan.
+- The user runs /plan to exit plan mode before you execute it.`;
+
+export const PROMPT_PLAN_MODE_OFF = "Plan mode is OFF. You may read and write freely.";
+
+export const PROMPT_PLAN_MODE_REMINDER = "<system-reminder>Plan mode is ON: no state-altering action allowed.</system-reminder>";

package/settings.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+/** What the user can configure in settings.json, under "pi-minimal"."plan-mode" */
+export interface PlanModeSettings {
+	/** Keyboard shortcut to toggle plan mode. */
+	keyboardShortcut: KeyId;
+}
+
+/** Fallback when keys are not configured */
+const DEFAULT_SETTINGS: PlanModeSettings = {
+	keyboardShortcut: "ctrl+alt+p"
+};
+
+export function loadSettings(pi: ExtensionAPI): PlanModeSettings {
+	const file = pi.getSettings() as { "pi-minimal"?: { "plan-mode"?: Partial<PlanModeSettings> } };
+	return { ...DEFAULT_SETTINGS, ...file["pi-minimal"]?.["plan-mode"] };
+}