xtrm-tools 2.4.0 → 2.4.2

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/config/hooks.json

@@ -48,6 +48,16 @@
         "script": "main-guard-post-push.mjs",
         "timeout": 5000
       },
+      {
+        "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "script": "quality-check.cjs",
+        "timeout": 30000
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "script": "quality-check.py",
+        "timeout": 30000
+      },
       {
         "matcher": "Bash|mcp__serena__find_symbol|mcp__serena__get_symbols_overview|mcp__serena__search_for_pattern|mcp__serena__find_referencing_symbols|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__rename_symbol",
         "script": "gitnexus/gitnexus-hook.cjs",

package/config/pi/extensions/core/adapter.ts

@@ -2,26 +2,14 @@ import * as fs from "node:fs";
 import * as nodePath from "node:path";
 
 import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
+import { PI_MUTATING_FILE_TOOLS } from "./guard-rules";
 
 export class EventAdapter {
 	/**
 	 * Checks if the tool event is a mutating file operation (write, edit, etc).
 	 */
 	static isMutatingFileTool(event: ToolCallEvent<any, any>): boolean {
-		const tools = [
-			"write",
-			"edit",
-			"replace_content",
-			"replace_lines",
-			"delete_lines",
-			"insert_at_line",
-			"create_text_file",
-			"rename_symbol",
-			"replace_symbol_body",
-			"insert_after_symbol",
-			"insert_before_symbol",
-		];
-		return tools.includes(event.toolName);
+		return PI_MUTATING_FILE_TOOLS.includes(event.toolName);
 	}
 
 	/**

package/config/pi/extensions/core/guard-rules.ts

@@ -0,0 +1,70 @@
+// Canonical guard-rule constants for Pi extensions.
+// Mirrors hooks/guard-rules.mjs with Pi-specific tool naming where needed.
+
+export const PI_MUTATING_FILE_TOOLS = [
+	"write",
+	"edit",
+	"replace_content",
+	"replace_lines",
+	"delete_lines",
+	"insert_at_line",
+	"create_text_file",
+	"rename_symbol",
+	"replace_symbol_body",
+	"insert_after_symbol",
+	"insert_before_symbol",
+];
+
+export const SAFE_BASH_PREFIXES = [
+	"git status",
+	"git log",
+	"git diff",
+	"git show",
+	"git blame",
+	"git branch",
+	"git fetch",
+	"git remote",
+	"git config",
+	"git pull",
+	"git stash",
+	"git worktree",
+	"git checkout -b",
+	"git switch -c",
+	"gh",
+	"bd",
+	"touch .beads/",
+	"npx gitnexus",
+];
+
+export const DANGEROUS_BASH_PATTERNS = [
+	"sed\\s+-i",
+	"echo\\s+[^\\n]*>",
+	"printf\\s+[^\\n]*>",
+	"cat\\s+[^\\n]*>",
+	"tee\\b",
+	"(?:^|\\s)(?:vim|nano|vi)\\b",
+	"(?:^|\\s)mv\\b",
+	"(?:^|\\s)cp\\b",
+	"(?:^|\\s)rm\\b",
+	"(?:^|\\s)mkdir\\b",
+	"(?:^|\\s)touch\\b",
+	"(?:^|\\s)chmod\\b",
+	"(?:^|\\s)chown\\b",
+	">>",
+	"(?:^|\\s)git\\s+add\\b",
+	"(?:^|\\s)git\\s+commit\\b",
+	"(?:^|\\s)git\\s+merge\\b",
+	"(?:^|\\s)git\\s+push\\b",
+	"(?:^|\\s)git\\s+reset\\b",
+	"(?:^|\\s)git\\s+checkout\\b",
+	"(?:^|\\s)git\\s+rebase\\b",
+	"(?:^|\\s)git\\s+stash\\b",
+	"(?:^|\\s)npm\\s+install\\b",
+	"(?:^|\\s)bun\\s+install\\b",
+	"(?:^|\\s)bun\\s+add\\b",
+	"(?:^|\\s)node\\s+(?:-e|--eval)\\b",
+	"(?:^|\\s)bun\\s+(?:-e|--eval)\\b",
+	"(?:^|\\s)python\\s+-c\\b",
+	"(?:^|\\s)perl\\s+-e\\b",
+	"(?:^|\\s)ruby\\s+-e\\b",
+];

package/config/pi/extensions/core/session-state.ts

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+export type SessionPhase =
+  | 'claimed'
+  | 'phase1-done'
+  | 'waiting-merge'
+  | 'conflicting'
+  | 'pending-cleanup'
+  | 'merged'
+  | 'cleanup-done';
+
+export interface SessionState {
+  issueId: string;
+  branch: string;
+  worktreePath: string;
+  prNumber: number | null;
+  prUrl: string | null;
+  phase: SessionPhase;
+  conflictFiles: string[];
+  startedAt: string;
+  lastChecked: string;
+}
+
+const SESSION_STATE_FILE = '.xtrm-session-state.json';
+
+export function findSessionStateFile(startCwd: string): string | null {
+  let current = path.resolve(startCwd || process.cwd());
+  for (;;) {
+    const candidate = path.join(current, SESSION_STATE_FILE);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function readSessionState(startCwd: string): SessionState | null {
+  const filePath = findSessionStateFile(startCwd);
+  if (!filePath) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (!parsed.issueId || !parsed.branch || !parsed.worktreePath || !parsed.phase) return null;
+    return {
+      issueId: String(parsed.issueId),
+      branch: String(parsed.branch),
+      worktreePath: String(parsed.worktreePath),
+      prNumber: parsed.prNumber ?? null,
+      prUrl: parsed.prUrl ?? null,
+      phase: parsed.phase,
+      conflictFiles: Array.isArray(parsed.conflictFiles) ? parsed.conflictFiles.map(String) : [],
+      startedAt: String(parsed.startedAt || ''),
+      lastChecked: String(parsed.lastChecked || ''),
+    } as SessionState;
+  } catch {
+    return null;
+  }
+}

package/config/pi/extensions/main-guard.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ToolCallEvent } from "@mariozechner/pi-coding-agent";
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import { SubprocessRunner, EventAdapter, Logger } from "./core/lib";
+import { SAFE_BASH_PREFIXES, DANGEROUS_BASH_PATTERNS } from "./core/guard-rules";
 
 const logger = new Logger({ namespace: "main-guard" });
 
@@ -37,12 +38,14 @@ export default function (pi: ExtensionAPI) {
 		// 2. Safety Check: Dangerous Commands (Global)
 		if (isToolCallEventType("bash", event)) {
 			const cmd = event.input.command.trim();
-			if (cmd.includes("rm -rf") && !cmd.includes("--help")) {
+			const dangerousRegexes = DANGEROUS_BASH_PATTERNS.map((pattern) => new RegExp(pattern));
+			const dangerousMatch = dangerousRegexes.some((rx) => rx.test(cmd));
+			if (dangerousMatch && !cmd.includes("--help")) {
 				if (ctx.hasUI) {
 					const ok = await ctx.ui.confirm("Dangerous Command", `Allow execution of: ${cmd}?`);
 					if (!ok) return { block: true, reason: "Blocked by user confirmation" };
 				} else {
-					return { block: true, reason: "Dangerous command 'rm -rf' blocked in non-interactive mode" };
+					return { block: true, reason: "Dangerous command blocked in non-interactive mode" };
 				}
 			}
 		}
@@ -78,18 +81,11 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				// Safe allowlist
-				const SAFE_BASH_PATTERNS = [
-					/^git\s+(status|log|diff|branch|show|describe|fetch|remote|config)\b/,
-					/^git\s+pull\b/,
-					/^git\s+stash\b/,
-					/^git\s+worktree\b/,
-					/^git\s+checkout\s+-b\s+\S+/,
-					/^git\s+switch\s+-c\s+\S+/,
-					...protectedBranches.map(b => new RegExp(`^git\\s+reset\\s+--hard\\s+origin/${b}\\b`)),
-					/^gh\s+/,
-					/^bd\s+/,
-					/^touch\s+\.beads\//,
-				];
+				const safePrefixRegexes = SAFE_BASH_PREFIXES.map((prefix) =>
+					new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`),
+				);
+				const safeResetRegexes = protectedBranches.map((b) => new RegExp(`^git\\s+reset\\s+--hard\\s+origin/${b}\\b`));
+				const SAFE_BASH_PATTERNS = [...safePrefixRegexes, ...safeResetRegexes];
 
 				if (SAFE_BASH_PATTERNS.some(p => p.test(cmd))) {
 					return undefined;

package/config/pi/extensions/plan-mode/README.md

@@ -0,0 +1,65 @@
+# Plan Mode Extension
+
+Read-only exploration mode for safe code analysis.
+
+## Features
+
+- **Read-only tools**: Restricts available tools to read, bash, grep, find, ls, question
+- **Bash allowlist**: Only read-only bash commands are allowed
+- **Plan extraction**: Extracts numbered steps from `Plan:` sections
+- **Progress tracking**: Widget shows completion status during execution
+- **[DONE:n] markers**: Explicit step completion tracking
+- **Session persistence**: State survives session resume
+
+## Commands
+
+- `/plan` - Toggle plan mode
+- `/todos` - Show current plan progress
+- `Ctrl+Alt+P` - Toggle plan mode (shortcut)
+
+## Usage
+
+1. Enable plan mode with `/plan` or `--plan` flag
+2. Ask the agent to analyze code and create a plan
+3. The agent should output a numbered plan under a `Plan:` header:
+
+```
+Plan:
+1. First step description
+2. Second step description
+3. Third step description
+```
+
+4. Choose "Execute the plan" when prompted
+5. During execution, the agent marks steps complete with `[DONE:n]` tags
+6. Progress widget shows completion status
+
+## How It Works
+
+### Plan Mode (Read-Only)
+- Only read-only tools available
+- Bash commands filtered through allowlist
+- Agent creates a plan without making changes
+
+### Execution Mode
+- Full tool access restored
+- Agent executes steps in order
+- `[DONE:n]` markers track completion
+- Widget shows progress
+
+### Command Allowlist
+
+Safe commands (allowed):
+- File inspection: `cat`, `head`, `tail`, `less`, `more`
+- Search: `grep`, `find`, `rg`, `fd`
+- Directory: `ls`, `pwd`, `tree`
+- Git read: `git status`, `git log`, `git diff`, `git branch`
+- Package info: `npm list`, `npm outdated`, `yarn info`
+- System info: `uname`, `whoami`, `date`, `uptime`
+
+Blocked commands:
+- File modification: `rm`, `mv`, `cp`, `mkdir`, `touch`
+- Git write: `git add`, `git commit`, `git push`
+- Package install: `npm install`, `yarn add`, `pip install`
+- System: `sudo`, `kill`, `reboot`
+- Editors: `vim`, `nano`, `code`

package/config/pi/extensions/plan-mode/index.ts

@@ -0,0 +1,340 @@
+/**
+ * Plan Mode Extension
+ *
+ * Read-only exploration mode for safe code analysis.
+ * When enabled, only read-only tools are available.
+ *
+ * Features:
+ * - /plan command or Ctrl+Alt+P to toggle
+ * - Bash restricted to allowlisted read-only commands
+ * - Extracts numbered plan steps from "Plan:" sections
+ * - [DONE:n] markers to complete steps during execution
+ * - Progress tracking widget during execution
+ */
+
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { AssistantMessage, TextContent } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Key } from "@mariozechner/pi-tui";
+import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.js";
+
+// Tools
+const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "questionnaire"];
+const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write"];
+
+// Type guard for assistant messages
+function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
+	return m.role === "assistant" && Array.isArray(m.content);
+}
+
+// Extract text content from an assistant message
+function getTextContent(message: AssistantMessage): string {
+	return message.content
+		.filter((block): block is TextContent => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+export default function planModeExtension(pi: ExtensionAPI): void {
+	let planModeEnabled = false;
+	let executionMode = false;
+	let todoItems: TodoItem[] = [];
+
+	pi.registerFlag("plan", {
+		description: "Start in plan mode (read-only exploration)",
+		type: "boolean",
+		default: false,
+	});
+
+	function updateStatus(ctx: ExtensionContext): void {
+		// Footer status
+		if (executionMode && todoItems.length > 0) {
+			const completed = todoItems.filter((t) => t.completed).length;
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("accent", `📋 ${completed}/${todoItems.length}`));
+		} else if (planModeEnabled) {
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("warning", "⏸ plan"));
+		} else {
+			ctx.ui.setStatus("plan-mode", undefined);
+		}
+
+		// Widget showing todo list
+		if (executionMode && todoItems.length > 0) {
+			const lines = todoItems.map((item) => {
+				if (item.completed) {
+					return (
+						ctx.ui.theme.fg("success", "☑ ") + ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(item.text))
+					);
+				}
+				return `${ctx.ui.theme.fg("muted", "☐ ")}${item.text}`;
+			});
+			ctx.ui.setWidget("plan-todos", lines);
+		} else {
+			ctx.ui.setWidget("plan-todos", undefined);
+		}
+	}
+
+	function togglePlanMode(ctx: ExtensionContext): void {
+		planModeEnabled = !planModeEnabled;
+		executionMode = false;
+		todoItems = [];
+
+		if (planModeEnabled) {
+			pi.setActiveTools(PLAN_MODE_TOOLS);
+			ctx.ui.notify(`Plan mode enabled. Tools: ${PLAN_MODE_TOOLS.join(", ")}`);
+		} else {
+			pi.setActiveTools(NORMAL_MODE_TOOLS);
+			ctx.ui.notify("Plan mode disabled. Full access restored.");
+		}
+		updateStatus(ctx);
+	}
+
+	function persistState(): void {
+		pi.appendEntry("plan-mode", {
+			enabled: planModeEnabled,
+			todos: todoItems,
+			executing: executionMode,
+		});
+	}
+
+	pi.registerCommand("plan", {
+		description: "Toggle plan mode (read-only exploration)",
+		handler: async (_args, ctx) => togglePlanMode(ctx),
+	});
+
+	pi.registerCommand("todos", {
+		description: "Show current plan todo list",
+		handler: async (_args, ctx) => {
+			if (todoItems.length === 0) {
+				ctx.ui.notify("No todos. Create a plan first with /plan", "info");
+				return;
+			}
+			const list = todoItems.map((item, i) => `${i + 1}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
+			ctx.ui.notify(`Plan Progress:\n${list}`, "info");
+		},
+	});
+
+	pi.registerShortcut(Key.ctrlAlt("p"), {
+		description: "Toggle plan mode",
+		handler: async (ctx) => togglePlanMode(ctx),
+	});
+
+	// Block destructive bash commands in plan mode
+	pi.on("tool_call", async (event) => {
+		if (!planModeEnabled || event.toolName !== "bash") return;
+
+		const command = event.input.command as string;
+		if (!isSafeCommand(command)) {
+			return {
+				block: true,
+				reason: `Plan mode: command blocked (not allowlisted). Use /plan to disable plan mode first.\nCommand: ${command}`,
+			};
+		}
+	});
+
+	// Filter out stale plan mode context when not in plan mode
+	pi.on("context", async (event) => {
+		if (planModeEnabled) return;
+
+		return {
+			messages: event.messages.filter((m) => {
+				const msg = m as AgentMessage & { customType?: string };
+				if (msg.customType === "plan-mode-context") return false;
+				if (msg.role !== "user") return true;
+
+				const content = msg.content;
+				if (typeof content === "string") {
+					return !content.includes("[PLAN MODE ACTIVE]");
+				}
+				if (Array.isArray(content)) {
+					return !content.some(
+						(c) => c.type === "text" && (c as TextContent).text?.includes("[PLAN MODE ACTIVE]"),
+					);
+				}
+				return true;
+			}),
+		};
+	});
+
+	// Inject plan/execution context before agent starts
+	pi.on("before_agent_start", async () => {
+		if (planModeEnabled) {
+			return {
+				message: {
+					customType: "plan-mode-context",
+					content: `[PLAN MODE ACTIVE]
+You are in plan mode - a read-only exploration mode for safe code analysis.
+
+Restrictions:
+- You can only use: read, bash, grep, find, ls, questionnaire
+- You CANNOT use: edit, write (file modifications are disabled)
+- Bash is restricted to an allowlist of read-only commands
+
+Ask clarifying questions using the questionnaire tool.
+Use brave-search skill via bash for web research.
+
+Create a detailed numbered plan under a "Plan:" header:
+
+Plan:
+1. First step description
+2. Second step description
+...
+
+Do NOT attempt to make changes - just describe what you would do.`,
+					display: false,
+				},
+			};
+		}
+
+		if (executionMode && todoItems.length > 0) {
+			const remaining = todoItems.filter((t) => !t.completed);
+			const todoList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
+			return {
+				message: {
+					customType: "plan-execution-context",
+					content: `[EXECUTING PLAN - Full tool access enabled]
+
+Remaining steps:
+${todoList}
+
+Execute each step in order.
+After completing a step, include a [DONE:n] tag in your response.`,
+					display: false,
+				},
+			};
+		}
+	});
+
+	// Track progress after each turn
+	pi.on("turn_end", async (event, ctx) => {
+		if (!executionMode || todoItems.length === 0) return;
+		if (!isAssistantMessage(event.message)) return;
+
+		const text = getTextContent(event.message);
+		if (markCompletedSteps(text, todoItems) > 0) {
+			updateStatus(ctx);
+		}
+		persistState();
+	});
+
+	// Handle plan completion and plan mode UI
+	pi.on("agent_end", async (event, ctx) => {
+		// Check if execution is complete
+		if (executionMode && todoItems.length > 0) {
+			if (todoItems.every((t) => t.completed)) {
+				const completedList = todoItems.map((t) => `~~${t.text}~~`).join("\n");
+				pi.sendMessage(
+					{ customType: "plan-complete", content: `**Plan Complete!** ✓\n\n${completedList}`, display: true },
+					{ triggerTurn: false },
+				);
+				executionMode = false;
+				todoItems = [];
+				pi.setActiveTools(NORMAL_MODE_TOOLS);
+				updateStatus(ctx);
+				persistState(); // Save cleared state so resume doesn't restore old execution mode
+			}
+			return;
+		}
+
+		if (!planModeEnabled || !ctx.hasUI) return;
+
+		// Extract todos from last assistant message
+		const lastAssistant = [...event.messages].reverse().find(isAssistantMessage);
+		if (lastAssistant) {
+			const extracted = extractTodoItems(getTextContent(lastAssistant));
+			if (extracted.length > 0) {
+				todoItems = extracted;
+			}
+		}
+
+		// Show plan steps and prompt for next action
+		if (todoItems.length > 0) {
+			const todoListText = todoItems.map((t, i) => `${i + 1}. ☐ ${t.text}`).join("\n");
+			pi.sendMessage(
+				{
+					customType: "plan-todo-list",
+					content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
+					display: true,
+				},
+				{ triggerTurn: false },
+			);
+		}
+
+		const choice = await ctx.ui.select("Plan mode - what next?", [
+			todoItems.length > 0 ? "Execute the plan (track progress)" : "Execute the plan",
+			"Stay in plan mode",
+			"Refine the plan",
+		]);
+
+		if (choice?.startsWith("Execute")) {
+			planModeEnabled = false;
+			executionMode = todoItems.length > 0;
+			pi.setActiveTools(NORMAL_MODE_TOOLS);
+			updateStatus(ctx);
+
+			const execMessage =
+				todoItems.length > 0
+					? `Execute the plan. Start with: ${todoItems[0].text}`
+					: "Execute the plan you just created.";
+			pi.sendMessage(
+				{ customType: "plan-mode-execute", content: execMessage, display: true },
+				{ triggerTurn: true },
+			);
+		} else if (choice === "Refine the plan") {
+			const refinement = await ctx.ui.editor("Refine the plan:", "");
+			if (refinement?.trim()) {
+				pi.sendUserMessage(refinement.trim());
+			}
+		}
+	});
+
+	// Restore state on session start/resume
+	pi.on("session_start", async (_event, ctx) => {
+		if (pi.getFlag("plan") === true) {
+			planModeEnabled = true;
+		}
+
+		const entries = ctx.sessionManager.getEntries();
+
+		// Restore persisted state
+		const planModeEntry = entries
+			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "plan-mode")
+			.pop() as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean } } | undefined;
+
+		if (planModeEntry?.data) {
+			planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled;
+			todoItems = planModeEntry.data.todos ?? todoItems;
+			executionMode = planModeEntry.data.executing ?? executionMode;
+		}
+
+		// On resume: re-scan messages to rebuild completion state
+		// Only scan messages AFTER the last "plan-mode-execute" to avoid picking up [DONE:n] from previous plans
+		const isResume = planModeEntry !== undefined;
+		if (isResume && executionMode && todoItems.length > 0) {
+			// Find the index of the last plan-mode-execute entry (marks when current execution started)
+			let executeIndex = -1;
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i] as { type: string; customType?: string };
+				if (entry.customType === "plan-mode-execute") {
+					executeIndex = i;
+					break;
+				}
+			}
+
+			// Only scan messages after the execute marker
+			const messages: AssistantMessage[] = [];
+			for (let i = executeIndex + 1; i < entries.length; i++) {
+				const entry = entries[i];
+				if (entry.type === "message" && "message" in entry && isAssistantMessage(entry.message as AgentMessage)) {
+					messages.push(entry.message as AssistantMessage);
+				}
+			}
+			const allText = messages.map(getTextContent).join("\n");
+			markCompletedSteps(allText, todoItems);
+		}
+
+		if (planModeEnabled) {
+			pi.setActiveTools(PLAN_MODE_TOOLS);
+		}
+		updateStatus(ctx);
+	});
+}