decorated-pi 0.6.0 → 0.7.1

package/settings.ts

@@ -35,14 +35,32 @@ export interface McpServerEntry {
 }
 
 export interface ModuleSettings {
-  safety?: boolean;
-  lsp?: boolean;
-  "smart-at"?: boolean;
-  patch?: boolean;
-  mcp?: boolean;
-  wakatime?: boolean;
-  "rtk"?: boolean;
-  codegraph?: boolean;
+  tools?: {
+    /** Replace Pi native edit/write with the patch tool. */
+    patchOverrideEdit?: boolean;
+    /** Interactive ask tool for user clarification (blocks loop until answered). */
+    ask?: boolean;
+    /** Language server diagnostics, hover, definition, references, symbols, rename. */
+    lsp?: boolean;
+    /** MCP client with builtin servers (context7, exa, codegraph). */
+    mcp?: boolean;
+  };
+  hooks?: {
+    /** Redact secrets from read/bash output before model context. */
+    secretRedaction?: boolean;
+    /** Rewrite bash through system RTK when available. */
+    "rtk"?: boolean;
+    /** Send coding activity heartbeats to WakaTime. */
+    wakatime?: boolean;
+  };
+  commands?: {
+    /** Project-aware file search replacing default autocomplete. */
+    atOverride?: boolean;
+    /** /retry command to continue after interruption. */
+    retry?: boolean;
+    /** /usage command for token stats. */
+    usage?: boolean;
+  };
 }
 
 export interface UsageIndexEntry {
@@ -62,7 +80,13 @@ export interface DecoratedPiConfig {
 
 export function loadConfig(): DecoratedPiConfig {
   try {
-    if (fs.existsSync(CONFIG_FILE)) return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+    if (fs.existsSync(CONFIG_FILE)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) as DecoratedPiConfig;
+      if (migrateModuleSettings(config)) {
+        saveConfig(config);
+      }
+      return config;
+    }
   } catch {}
   return {};
 }
@@ -152,42 +176,157 @@ export function setCompactModelKey(key: string | null) {
 // ─── Module Switches ──────────────────────────────────────────────────────────
 
 const DEFAULT_MODULES: Required<ModuleSettings> = {
-  safety: true,
-  lsp: true,
-  "smart-at": true,
-  patch: true,
-  mcp: true,
-  wakatime: true,
-  "rtk": true,
-  codegraph: false,  // opt-in: heavy binary, not everyone wants it
+  tools: {
+    patchOverrideEdit: true,
+    ask: true,
+    lsp: true,
+    mcp: true,
+  },
+  hooks: {
+    secretRedaction: true,
+    "rtk": true,
+    wakatime: true,
+  },
+  commands: {
+    atOverride: true,
+    retry: true,
+    usage: true,
+  },
 };
 
-export function isModuleEnabled(name: keyof ModuleSettings): boolean {
+/** Maps every module name to its category. Used by isModuleEnabled/setModuleEnabled. */
+const MODULE_TO_CATEGORY: Record<string, keyof ModuleSettings> = {
+  patchOverrideEdit: "tools",
+  ask: "tools",
+  lsp: "tools",
+  mcp: "tools",
+  secretRedaction: "hooks",
+  "rtk": "hooks",
+  wakatime: "hooks",
+  atOverride: "commands",
+  retry: "commands",
+  usage: "commands",
+};
+
+/** Legacy flat module keys that were renamed. Applied before flat→nested migration. */
+const LEGACY_MODULE_KEYS: Record<string, string> = {
+  patch: "patchOverrideEdit",
+  safety: "secretRedaction",
+};
+
+/**
+ * Migrate module settings to the nested tools/hooks/commands layout.
+ * Handles three legacy shapes:
+ *   1. Flat config with current names (patchOverrideEdit, secretRedaction, ...)
+ *   2. Flat config with old names (patch, safety)
+ *   3. Nested config with old inner names (tools.patch, hooks.safety)
+ * Already-correct nested configs are left untouched.
+ */
+function migrateModuleSettings(config: DecoratedPiConfig): boolean {
+  if (!config.modules) return false;
+
+  let migrated = false;
+  const result: ModuleSettings = {};
+
+  // Start from any already-nested values.
+  if (config.modules.tools) result.tools = { ...config.modules.tools };
+  if (config.modules.hooks) result.hooks = { ...config.modules.hooks };
+  if (config.modules.commands) result.commands = { ...config.modules.commands };
+
+  // Rename legacy keys inside already-nested categories.
+  function renameInCategory(
+    category: keyof ModuleSettings,
+    oldKey: string,
+    newKey: string,
+  ) {
+    const cat = result[category] as Record<string, boolean> | undefined;
+    if (cat && oldKey in cat && !(newKey in cat)) {
+      cat[newKey] = cat[oldKey];
+      delete cat[oldKey];
+      migrated = true;
+    }
+  }
+  renameInCategory("tools", "patch", "patchOverrideEdit");
+  renameInCategory("hooks", "safety", "secretRedaction");
+  renameInCategory("commands", "smart-at", "atOverride");
+
+  // Migrate flat keys into nested categories.
+  const flatMapping: Record<string, [keyof ModuleSettings, string]> = {
+    patchOverrideEdit: ["tools", "patchOverrideEdit"],
+    ask: ["tools", "ask"],
+    lsp: ["tools", "lsp"],
+    mcp: ["tools", "mcp"],
+    secretRedaction: ["hooks", "secretRedaction"],
+    "rtk": ["hooks", "rtk"],
+    wakatime: ["hooks", "wakatime"],
+    atOverride: ["commands", "atOverride"],
+    retry: ["commands", "retry"],
+    usage: ["commands", "usage"],
+    patch: ["tools", "patchOverrideEdit"],
+    safety: ["hooks", "secretRedaction"],
+    "smart-at": ["commands", "atOverride"],
+  };
+
+  for (const [key, value] of Object.entries(config.modules)) {
+    if (key === "tools" || key === "hooks" || key === "commands") continue;
+    const mapping = flatMapping[key];
+    if (!mapping) continue;
+    const [category, newKey] = mapping;
+    if (!result[category]) result[category] = {} as any;
+    const cat = result[category] as Record<string, boolean>;
+    if (!(newKey in cat)) {
+      cat[newKey] = value as boolean;
+    }
+    migrated = true;
+  }
+
+  if (!migrated) return false;
+  config.modules = result;
+  return true;
+}
+
+export function isModuleEnabled(name: string): boolean {
+  const category = MODULE_TO_CATEGORY[name];
+  if (!category) return true;
   const modules = loadConfig().modules ?? {};
-  return modules[name] ?? DEFAULT_MODULES[name] ?? true;
+  const cat = modules[category] as Record<string, boolean> | undefined;
+  const defaults = DEFAULT_MODULES[category] as Record<string, boolean>;
+  if (cat && name in cat) return cat[name];
+  return defaults[name] ?? true;
 }
 
-export function setModuleEnabled(name: keyof ModuleSettings, enabled: boolean) {
-  const modules = { ...loadConfig().modules };
-  modules[name] = enabled;
+export function setModuleEnabled(name: string, enabled: boolean) {
+  const category = MODULE_TO_CATEGORY[name];
+  if (!category) return;
+  const modules: ModuleSettings = { ...loadConfig().modules };
+  modules[category] = { ...(modules[category] ?? {}), [name]: enabled } as any;
   saveConfig({ modules });
 }
 
 export function getAllModuleSettings(): Required<ModuleSettings> {
   const modules = loadConfig().modules ?? {};
-  return { ...DEFAULT_MODULES, ...modules };
+  return {
+    tools: { ...DEFAULT_MODULES.tools, ...modules.tools },
+    hooks: { ...DEFAULT_MODULES.hooks, ...modules.hooks },
+    commands: { ...DEFAULT_MODULES.commands, ...modules.commands },
+  };
 }
 
-// ─── Codegraph (drives the builtin MCP server's auto-enable) ───────────────
-
 /**
- * True when the user has enabled the codegraph module via /dp-settings.
- * Default is OFF (opt-in) — `modules.codegraph` defaults to `false`.
- * When true, the builtin MCP server is enabled and the CodeGraph
- * guidance section is injected into the system prompt.
+ * Snapshot of the module settings that pi is currently running with.
+ * Captured once when the extension loads; /dp-settings compares the
+ * current effective settings against this snapshot to decide whether a
+ * reload is actually necessary.
  */
-export function isCodegraphModuleEnabled(): boolean {
-  return isModuleEnabled("codegraph");
+let loadedModuleSnapshot: Required<ModuleSettings> | null = null;
+
+export function captureModuleSnapshot(): void {
+  loadedModuleSnapshot = getAllModuleSettings();
+}
+
+export function moduleSnapshotChanged(): boolean {
+  if (!loadedModuleSnapshot) return true;
+  return JSON.stringify(loadedModuleSnapshot) !== JSON.stringify(getAllModuleSettings());
 }
 
 // ─── Usage index (增量同步元数据) ─────────────────────────────────────────────

package/tools/ask/index.ts

@@ -0,0 +1,93 @@
+/**
+ * ask — ask the user one or more questions and return their answers.
+ *
+ * Supports free text, single-choice, and multiple-choice questions.
+ * Uses a custom TUI component so multiple questions can be presented
+ * together and navigated with Tab / Shift+Tab.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { AskComponent, type AskAnswer, type AskQuestion } from "../../ui/ask.js";
+
+const askQuestionSchema = Type.Object({
+  id: Type.String({ description: "Unique identifier for this question in the result." }),
+  type: Type.Union(
+    [Type.Literal("text"), Type.Literal("single"), Type.Literal("multi")],
+    { description: "text = free input, single = one option, multi = many options" },
+  ),
+  question: Type.String({ description: "Question text shown to the user." }),
+  options: Type.Optional(Type.Array(Type.String(), { description: "Options for single or multi choice." })),
+  default: Type.Optional(Type.String({ description: "Default answer. For multi, comma-separated values." })),
+  allowCustom: Type.Optional(Type.Boolean({
+    description: "For single/multi: append an \"Other\" row that toggles into a free-text input. Lets the user enter a custom answer not in the preset list.",
+  })),
+});
+
+function formatAnswer(q: AskQuestion, value: string | string[]): string {
+  if (q.type === "text") return value as string;
+  if (q.type === "single") return value as string;
+  return (value as string[]).join(", ");
+}
+
+export function formatAnswers(questions: AskQuestion[], answers: { id: string; value: string | string[] }[]): string {
+  const lines: string[] = [];
+  for (const q of questions) {
+    const a = answers.find((x) => x.id === q.id);
+    if (!a) continue;
+    lines.push(`${q.question}: ${formatAnswer(q, a.value)}`);
+  }
+  return lines.join("\n");
+}
+
+export function registerAskTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "ask",
+    label: "Ask user",
+    description: "Ask the user one or more questions and return their answers. Supports free text, single choice, and multiple choice. Use when you need clarification or a decision before continuing.",
+    promptSnippet: "Ask the user one or more clarifying questions",
+    promptGuidelines: [
+      "Before acting on a prompt, ensure you fully understand the user's intent — if ambiguous, ask clarifying questions using the ask tool.",
+    ],
+    parameters: Type.Object({
+      questions: Type.Array(askQuestionSchema, { minItems: 1, description: "Questions to ask. User navigates between them with Tab / Shift+Tab." }),
+    }),
+    execute: async (_id, params, _signal, _update, ctx) => {
+      if (!ctx.hasUI) {
+        return {
+          content: [{ type: "text", text: "ask tool requires an interactive UI session." }],
+          isError: true,
+          details: {},
+        };
+      }
+
+      // Validate options for single/multi.
+      for (const q of params.questions) {
+        if ((q.type === "single" || q.type === "multi") && (!q.options || q.options.length === 0)) {
+          return {
+            content: [{ type: "text", text: `Question "${q.id}" (${q.type}) requires at least one option.` }],
+            isError: true,
+            details: {},
+          };
+        }
+      }
+
+      const answers = await ctx.ui.custom<AskAnswer[] | undefined>(
+        (tui, theme, _kb, done) => new AskComponent(tui, theme, params.questions, done),
+      );
+
+      if (!answers) {
+        return {
+          content: [{ type: "text", text: "User cancelled the questions." }],
+          isError: false,
+          details: { cancelled: true },
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: formatAnswers(params.questions, answers) }],
+        details: { answers },
+      };
+    },
+  });
+}

package/tools/mcp/builtin/codegraph.ts

@@ -1,45 +1,21 @@
 /**
- * codegraph builtin MCP server — config + system-prompt guidance.
+ * codegraph builtin MCP server — config + project artefact check.
  *
- * Injected by `index.ts` → `buildGuidelines()` when the codegraph
- * module is enabled (see `isModuleEnabled("codegraph")` in settings).
+ * Enabled state is controlled like any other MCP server: through the
+ * MCP config (global `~/.pi/agent/mcp.json` under `mcpServers`, or
+ * project `.pi/agent/mcp.json`) or via the `/mcp` command. There is no
+ * separate /dp-settings toggle; codegraph is just one MCP server.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { McpServerConfig } from "../config.js";
-import { isCodegraphModuleEnabled } from "../../../settings.js";
 
 export const CODEGRAPH_BUILTIN: Omit<McpServerConfig, "source"> = {
     name: "codegraph",
     command: "codegraph",
     args: ["serve", "--mcp"],
-    enabled: false, // overridden by isCodegraphModuleEnabled() at resolve time
+    enabled: false,
     description:
-        "Local code knowledge graph (colbymchenry/codegraph). Enable via /dp-settings.",
+        "Local code knowledge graph (colbymchenry/codegraph). Enable via /mcp.",
+    canUseInProject: (cwd: string) => fs.existsSync(path.join(cwd, ".codegraph")),
 };
-
-/** Predicate for `resolveMcpConfigs` to gate the codegraph server. */
-export function codegraphEnabled(): boolean {
-    return isCodegraphModuleEnabled();
-}
-
-export const CODEGRAPH_GUIDANCE = [
-    "### CodeGraph, code source map",
-    "- This project's `codegraph_*` MCP tools are enabled. The graph is a pre-built index; grep/glob/Read of source code is repeating work the index already did.",
-    "",
-    "#### When to reach for it",
-    '- Starting any task that touches code → `codegraph_explore("how does X work")` or `codegraph_files`',
-    "- Looking for where a symbol is defined → `codegraph_search <name>`",
-    "- Reading a function's body → `codegraph_node <name>` (or `codegraph_explore`)",
-    "- Tracing call flow → `codegraph_callers` / `codegraph_callees`",
-    "- Assessing refactor risk → `codegraph_impact <name>`",
-    "",
-    "#### Do NOT do this",
-    "- `ls`, `find`, `grep -rn`, `rg` to discover symbols → use `codegraph_search`",
-    "- `read` of an entire file to find a function → use `codegraph_explore` first",
-    '- Reading 3+ files to understand a module → use `codegraph_explore("how does X work")`',
-    "- `bash` with `cat`, `head`, `sed` to view source → use `codegraph_node` or `read` (single file only)",
-    "",
-    "#### If it errors",
-    '- "Project not initialized" → ask the user to run `codegraph init -i` in their terminal',
-    "- Empty results → fall back to grep/Read (the index is best-effort, not authoritative)",
-    "- Tool timeout → `codegraph_status` to check; if indexer is dead, fall back",
-].join("\n");

package/tools/mcp/builtin/index.ts

@@ -5,11 +5,11 @@
 import type { McpServerConfig } from "../config.js";
 import { CONTEXT7_BUILTIN } from "./context7.js";
 import { EXA_BUILTIN } from "./exa.js";
-import { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE } from "./codegraph.js";
+import { CODEGRAPH_BUILTIN } from "./codegraph.js";
 
 export { CONTEXT7_BUILTIN } from "./context7.js";
 export { EXA_BUILTIN } from "./exa.js";
-export { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE, codegraphEnabled } from "./codegraph.js";
+export { CODEGRAPH_BUILTIN } from "./codegraph.js";
 
 /** All builtin servers — flat list for `resolveMcpConfigs` to merge. */
 export const BUILTIN_MCP_SERVERS: Omit<McpServerConfig, "source">[] = [

package/tools/mcp/config.ts

@@ -5,16 +5,20 @@
  * hit sets defaults; later sources can override specific fields.
  *
  * Persistence locations:
- *   - global: `~/.pi/agent/decorated-pi.json` (under `mcpServers`)
+ *   - global: `~/.pi/agent/mcp.json` (under `mcpServers`)
  *   - project: `<cwd>/.pi/agent/mcp.json` (under `mcpServers`)
+ *
+ * Legacy: global MCP servers used to live in `~/.pi/agent/decorated-pi.json`
+ * under `mcpServers`. `loadGlobalMcpConfigs()` automatically migrates that
+ * data to `~/.pi/agent/mcp.json` on first read.
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
-import { loadConfig } from "../../settings.js";
+import { isModuleEnabled } from "../../settings.js";
 import type { DependencyStatus } from "../../hooks/skeleton.js";
-import { BUILTIN_MCP_SERVERS, codegraphEnabled } from "./builtin/index.js";
+import { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
 export { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
@@ -27,6 +31,12 @@ export interface McpServerConfig {
   description?: string;
   enabled: boolean;
   source: "builtin" | "global" | "project";
+  /** Optional predicate: return false if this server cannot be used in the given project. */
+  canUseInProject?: (cwd: string) => boolean;
+}
+
+function globalMcpJsonPath(): string {
+  return path.join(os.homedir(), ".pi", "agent", "mcp.json");
 }
 
 function readMcpJson(filePath: string): Record<string, { url?: string; command?: string; args?: string[]; env?: Record<string, string>; enabled?: boolean; description?: string }> | null {
@@ -41,6 +51,64 @@ function readMcpJson(filePath: string): Record<string, { url?: string; command?:
   }
 }
 
+/**
+ * One-time migration: older versions stored global MCP servers in
+ * `~/.pi/agent/decorated-pi.json` under `mcpServers`. Move that data to
+ * the dedicated `~/.pi/agent/mcp.json` file so global and project configs
+ * are symmetric.
+ *
+ * Rules:
+ *   - Only runs when the legacy file has at least one `mcpServers` entry.
+ *   - For each legacy server name, if `mcp.json` already has an entry with
+ *     the same name, the legacy entry is skipped (new file wins).
+ *   - Idempotent: after running once, the legacy file no longer has
+ *     `mcpServers`, so a second call is a no-op.
+ */
+export function migrateLegacyGlobalMcpConfig(): void {
+  const legacyPath = path.join(os.homedir(), ".pi", "agent", "decorated-pi.json");
+  const newPath = globalMcpJsonPath();
+
+  let legacy: Record<string, any> | null = null;
+  try {
+    legacy = JSON.parse(fs.readFileSync(legacyPath, "utf-8"));
+  } catch {
+    return;
+  }
+  if (!legacy || !legacy.mcpServers || typeof legacy.mcpServers !== "object") return;
+  if (Object.keys(legacy.mcpServers).length === 0) return;
+
+  // Load existing new file (if any). If it is corrupt, leave everything
+  // alone — safer than clobbering.
+  let newConfig: Record<string, any> = { mcpServers: {} };
+  if (fs.existsSync(newPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(newPath, "utf-8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        newConfig = parsed;
+        if (!newConfig.mcpServers || typeof newConfig.mcpServers !== "object") {
+          newConfig.mcpServers = {};
+        }
+      }
+    } catch {
+      return;
+    }
+  }
+
+  // Merge: only add legacy entries that don't already exist in the new file.
+  for (const [name, entry] of Object.entries(legacy.mcpServers)) {
+    if (!(name in newConfig.mcpServers)) {
+      newConfig.mcpServers[name] = entry;
+    }
+  }
+
+  const dir = path.dirname(newPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(newPath, JSON.stringify(newConfig, null, 2) + "\n", "utf-8");
+
+  delete legacy.mcpServers;
+  fs.writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + "\n", "utf-8");
+}
+
 /** Load project-level MCP configs from cwd only. */
 export function loadProjectMcpConfigs(cwd: string): McpServerConfig[] {
   const configs: McpServerConfig[] = [];
@@ -69,18 +137,18 @@ export function loadProjectMcpConfigs(cwd: string): McpServerConfig[] {
   return configs;
 }
 
-/** Load global MCP configs from ~/.pi/agent/decorated-pi.json. */
+/** Load global MCP configs from ~/.pi/agent/mcp.json. */
 export function loadGlobalMcpConfigs(): McpServerConfig[] {
-  const config = loadConfig();
-  if (!config.mcpServers) return [];
+  const servers = readMcpJson(globalMcpJsonPath());
+  if (!servers) return [];
 
-  return Object.entries(config.mcpServers).map(([name, entry]) => ({
+  return Object.entries(servers).map(([name, entry]) => ({
     name,
     url: entry.url,
     command: entry.command,
     args: entry.args,
     env: entry.env,
-    description: (entry as any).description as string | undefined,
+    description: entry.description,
     enabled: entry.enabled !== false,
     source: "global" as const,
   }));
@@ -96,16 +164,17 @@ export function isSseUrl(url: string): boolean {
  * Later sources override earlier ones for the same server name.
  */
 export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
+  // The mcp module switch is the master switch. When it is off, no MCP
+  // server config is considered active — this keeps the chain simple:
+  // mcp off → all servers off → no codegraph guidance.
+  if (!isModuleEnabled("mcp")) return [];
+
   const byName = new Map<string, McpServerConfig>();
 
-  // Builtin (lowest priority). The codegraph entry's `enabled` flag is
-  // computed at resolve time from the dp-settings module toggle.
+  // Builtin (lowest priority). Use the builtin's own `enabled` default.
+  // Servers can be enabled via the `/mcp` command or by editing mcp.json.
   for (const s of BUILTIN_MCP_SERVERS) {
-    if (s.name === "codegraph") {
-      byName.set(s.name, { ...s, enabled: codegraphEnabled(), source: "builtin" });
-    } else {
-      byName.set(s.name, { ...s, source: "builtin" });
-    }
+    byName.set(s.name, { ...s, source: "builtin" });
   }
 
   // Global — preserve url/command/description from builtin if not overridden
@@ -121,6 +190,7 @@ export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
         env: s.env ?? existing.env,
         description: s.description ?? existing.description,
         source: "global",
+        canUseInProject: s.canUseInProject ?? existing.canUseInProject,
       });
     } else {
       byName.set(s.name, s);
@@ -140,6 +210,7 @@ export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
         env: s.env ?? existing.env,
         description: s.description ?? existing.description,
         source: "project",
+        canUseInProject: s.canUseInProject ?? existing.canUseInProject,
       });
     } else {
       byName.set(s.name, s);
@@ -201,13 +272,14 @@ export function toggleMcpServerEnabled(
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(filePath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
     } else {
-      const config = loadConfig();
-      config.mcpServers = config.mcpServers || {};
-      config.mcpServers[serverName] = { ...(config.mcpServers[serverName] || {}), enabled };
-      const configPath = path.join(os.homedir(), ".pi/agent/decorated-pi.json");
-      const dir = path.dirname(configPath);
+      const filePath = globalMcpJsonPath();
+      const raw = readMcpJsonSafe(filePath) || { mcpServers: {} };
+      const servers = raw.mcpServers ?? {};
+      servers[serverName] = { ...(servers[serverName] || {}), enabled };
+      raw.mcpServers = servers;
+      const dir = path.dirname(filePath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs.writeFileSync(filePath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
     }
     return true;
   } catch {

package/tools/patch/core.ts

@@ -1076,12 +1076,18 @@ interface LineRange {
   endLine: number;
 }
 
-/** Build line offset table: offsets[i] = character offset of line i+1 (1-based) */
+/** Build line offset table: offsets[i] = character offset of line i+1 (1-based).
+ *  If the content does not end with a newline, the final line has no
+ *  trailing marker; push an extra offset at content.length so callers
+ *  like lineAtOffset / extractLineRange handle the last line correctly. */
 function buildLineOffsets(content: string): number[] {
   const offsets = [0];
   for (let i = 0; i < content.length; i++) {
     if (content[i] === "\n") offsets.push(i + 1);
   }
+  if (content.length > 0 && content[content.length - 1] !== "\n") {
+    offsets.push(content.length);
+  }
   return offsets;
 }
 

package/tools/patch/index.ts

@@ -215,8 +215,9 @@ export function registerPatchTool(pi: ExtensionAPI): void {
     ].join("\n"),
     promptSnippet: "Edits a file using exact string replacement, with anchor support.",
     promptGuidelines: [
-      "Always prefer modifying files with patch tool over bash commands or python scripts.",
-      "To prevent hallucinations: 1. Keep each edit batch ≤ 5 changes; 2. Process remaining revisions in sequential steps",
+      "The patch tool is the preferred way to modify files — use it over the write tool (full overwrite) or the bash tool (sed/echo).",
+      "When editing an existing file, use patch instead of write to avoid overwriting changes made since the file was last read.",
+      "To prevent hallucinations: 1. Keep each edit batch ≤ 5 changes; 2. Process remaining revisions in sequential steps.",
       "On repeated failures: read the file first to confirm information accuracy.",
     ],
     parameters: PatchSchema,