decorated-pi 0.6.0 → 0.7.0

package/README.md

@@ -14,7 +14,7 @@ pi install /path/to/decorated-pi
 
 ### 1. Token Efficiency
 
-Multiple layers of token savings that compound across every session.
+Multiple layers of token savings that compound across every session. **All integrated CLI tools only require installing their respective CLIs — zero config**.
 
 **RTK** — integrates [RTK](https://github.com/rtk-ai/rtk) to compress bash output into structured summaries, so the LLM never sees raw noise.
 
@@ -73,7 +73,7 @@ Zero-config MCP client with built-in servers:
 | Exa | `exa_*` | `https://mcp.exa.ai/mcp` |
 | codegraph | `codegraph_*` | bundled binary |
 
-**Custom servers** in `.pi/agent/mcp.json` (project) or `~/.pi/agent/decorated-pi.json` (global). Project overrides global. Tool prompts and schemas are cached locally so MCP tools are available immediately on startup — no manual `/reload` required even on first install.
+**Custom servers** in `.pi/agent/mcp.json` (project) or `~/.pi/agent/mcp.json` (global). Project overrides global. Tool prompts and schemas are cached locally so MCP tools are available immediately on startup.
 
 ```json
 {
@@ -118,8 +118,8 @@ Example redaction on a `read` / `bash` output:
 ### 5. Other
 
 - `/usage` — token stats with cache‑hit rate, per‑model breakdown (Session / Today / This Week / This Month / All Time)
-- Progressive context — supports subdirectory `AGENTS.md` / `CLAUDE.md` discovery and injection
 - `/retry` — continue after interruption
+- Progressive context — supports subdirectory `AGENTS.md` / `CLAUDE.md` discovery and injection
 - **WakaTime** — coding activity tracking via [WakaTime](https://wakatime.com)
 
 ## Configuration
@@ -129,13 +129,22 @@ Runtime settings in `~/.pi/agent/decorated-pi.json`. Modules can be toggled via
 ```json
 {
   "modules": {
-    "patch": true,
-    "safety": true,
-    "rtk": true,
-    "lsp": true,
-    "smart-at": true,
-    "mcp": true,
-    "wakatime": true
+    "tools": {
+      "patchOverrideEdit": true,
+      "ask": true,
+      "lsp": true,
+      "mcp": true
+    },
+    "hooks": {
+      "secretRedaction": true,
+      "rtk": true,
+      "wakatime": true
+    },
+    "commands": {
+      "atOverride": true,
+      "retry": true,
+      "usage": true
+    }
   }
 }
 ```

package/commands/dp-settings.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { moduleSnapshotChanged } from "../settings.js";
 import { ModuleSettingsComponent } from "../ui/module-settings.js";
 
 export function registerDpSettingsCommand(pi: ExtensionAPI): void {
@@ -14,7 +15,11 @@ export function registerDpSettingsCommand(pi: ExtensionAPI): void {
           (tui, theme, _kb, done) =>
             new ModuleSettingsComponent(tui, theme, () => done(undefined))
         );
-        ctx.ui.notify("Module settings updated. /reload to apply.", "warning");
+        // Only prompt for reload when the effective settings differ from
+        // the snapshot taken when pi loaded the extension.
+        if (moduleSnapshotChanged()) {
+          ctx.ui.notify("Module settings updated. /reload to apply.", "warning");
+        }
         return;
       }
       ctx.ui.notify("dp-settings requires interactive mode.", "warning");

package/hooks/mcp.ts

@@ -31,6 +31,11 @@ function cacheScopeForSource(source: string): "global" | "project" {
   return source === "project" ? "project" : "global";
 }
 
+function canUseServer(config: McpServerConfig, cwd?: string): boolean {
+  if (!config.canUseInProject) return true;
+  return config.canUseInProject(cwd ?? process.cwd());
+}
+
 async function connectAll(
   configs: McpServerConfig[],
   registry: any,
@@ -81,6 +86,15 @@ async function connectAll(
   for (const server of configs) {
     if (watchdogFired) break; // remaining servers are already failed
 
+    if (!canUseServer(server, cachedCwd || undefined)) {
+      allServers.set(server.name, {
+        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
+        state: "failed", toolCount: 0, tools: [],
+        error: "Project is missing required artefacts for this server",
+      });
+      continue;
+    }
+
     const conn = new McpConnection(server.name, server);
     conn.source = server.source;
     try {
@@ -89,6 +103,18 @@ async function connectAll(
         try { await conn.disconnect(); } catch { /* ignore */ }
         return { schemaChanges, hasNewServer };
       }
+      if (conn.tools.length === 0) {
+        // Server connected but advertises no tools. Treat this as a
+        // failed state and do NOT write an empty cache, otherwise a
+        // subsequent /reload will keep using the empty cache forever.
+        try { await conn.disconnect(); } catch { /* ignore */ }
+        allServers.set(server.name, {
+          name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
+          state: "failed", toolCount: 0, tools: [],
+          error: "Server connected but returned no tools (e.g. codegraph without a .codegraph index)",
+        });
+        continue;
+      }
       activeConnections.push(conn);
       const actualTools = conn.tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
       const cachedEntry = cache?.servers[server.name];
@@ -195,6 +221,9 @@ export async function updateConfigEnabled(serverName: string, enabled: boolean):
 export async function refreshServerCache(serverName: string, registry: any): Promise<{ ok: boolean; error?: string }> {
   const config = resolveMcpConfigs(cachedCwd).find(s => s.name === serverName);
   if (!config) return { ok: false, error: `Server "${serverName}" not found in config.` };
+  if (!canUseServer(config, cachedCwd || undefined)) {
+    return { ok: false, error: "Project is missing required artefacts for this server" };
+  }
   const existing = activeConnections.find(c => c.serverName === serverName);
   if (existing) {
     try { await existing.disconnect(); } catch { /* ignore */ }
@@ -204,6 +233,12 @@ export async function refreshServerCache(serverName: string, registry: any): Pro
   conn.source = config.source;
   try {
     await conn.connect(30_000);
+    if (conn.tools.length === 0) {
+      try { await conn.disconnect(); } catch { /* ignore */ }
+      const error = "Server connected but returned no tools (e.g. codegraph without a .codegraph index)";
+      allServers.set(config.name, { name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source, state: "failed", toolCount: 0, tools: [], error });
+      return { ok: false, error };
+    }
     activeConnections.push(conn);
     allServers.set(config.name, {
       name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source,
@@ -242,6 +277,8 @@ export function getCachedMcpConfigs(): McpServerConfig[] {
  * can find it.
  */
 export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerConfig, cwd?: string): Promise<void> {
+  if (!canUseServer(config, cwd)) return;
+
   const scope = cacheScopeForSource(config.source);
   const cache = loadScopedMcpCache(scope, cwd);
   const entry = cache?.servers[config.name];
@@ -262,6 +299,21 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
   conn.source = config.source;
   try {
     await conn.connect(30_000);
+    if (conn.tools.length === 0) {
+      // Empty tool list means the server is not useful. Disconnect and
+      // leave cache untouched so the next /reload retries the connection.
+      try { await conn.disconnect(); } catch { /* ignore */ }
+      allServers.set(config.name, {
+        name: config.name,
+        url: config.url ?? config.command ?? "(unknown)",
+        source: config.source,
+        state: "failed",
+        toolCount: 0,
+        tools: [],
+        error: "Server connected but returned no tools (e.g. codegraph without a .codegraph index)",
+      });
+      return;
+    }
     activeConnections.push(conn);
     const tools: McpToolCache[] = conn.tools.map(t => ({
       name: t.name,

package/hooks/session-title.ts

@@ -40,13 +40,37 @@ export function extractFirstMessage(entries: SessionEntryLike[]): string | undef
   return undefined;
 }
 
+function normalizeTitle(text: string): string | undefined {
+  const nl = text.indexOf("\n");
+  const oneLine = (nl === -1 ? text : text.slice(0, nl)).trim();
+  if (!oneLine) return undefined;
+  if (oneLine.length <= MAX_SESSION_TITLE_LENGTH) return oneLine;
+  return oneLine.slice(0, MAX_SESSION_TITLE_LENGTH - 1) + "…";
+}
+
+function trySetSessionName(ctx: any, pi: ExtensionAPI): void {
+  if (ctx.sessionManager.getSessionName()) return;
+  const title = extractFirstMessage(ctx.sessionManager.getBranch());
+  if (title) (pi as any).setSessionName(title);
+}
+
 export const sessionTitleModule: Module = {
   name: "session-title",
   hooks: {
     session_start: [
       (_event, ctx, pi) => {
+        trySetSessionName(ctx, pi);
+      },
+    ],
+    input: [
+      (event, ctx, pi) => {
+        // Skip if already named, not a fresh interactive message,
+        // or stream steering/follow-up messages.
         if (ctx.sessionManager.getSessionName()) return;
-        const title = extractFirstMessage(ctx.sessionManager.getBranch());
+        if (event.source === "extension") return;
+        if (event.streamingBehavior) return;
+        const text = typeof event.text === "string" ? event.text.trim() : "";
+        const title = normalizeTitle(text);
         if (title) (pi as any).setSessionName(title);
       },
     ],

package/index.ts

@@ -36,9 +36,9 @@ import { setupRtk } from "./hooks/rtk.js";
 import { registerPatchTool } from "./tools/patch/index.js";
 import { registerLspTools } from "./tools/lsp/tools.js";
 import { LspServerManager } from "./tools/lsp/manager.js";
-import { resolveMcpConfigs } from "./tools/mcp/config.js";
+import { registerAskTool } from "./tools/ask/index.js";
+import { resolveMcpConfigs, migrateLegacyGlobalMcpConfig } from "./tools/mcp/config.js";
 import { ensureMcpServerReady } from "./hooks/mcp.js";
-import { CODEGRAPH_GUIDANCE } from "./tools/mcp/builtin/codegraph.js";
 
 import { registerDpModelCommand } from "./commands/dp-model.js";
 import { registerDpSettingsCommand } from "./commands/dp-settings.js";
@@ -46,7 +46,7 @@ import { registerMcpStatusCommand } from "./commands/mcp-status.js";
 import { registerRetryCommand } from "./commands/retry.js";
 import { registerUsageCommand } from "./commands/usage.js";
 
-import { isModuleEnabled } from "./settings.js";
+import { captureModuleSnapshot, isModuleEnabled } from "./settings.js";
 
 // ─── System-prompt guidelines (hard-coded base, per-module imports) ────────
 //
@@ -57,7 +57,7 @@ const BASE_GUIDANCE = [
   "## Decorated Pi Guidance",
   "",
   "### Workflow, how to approach tasks",
-  "- Before acting on a prompt: 1. ensure you fully understand the user's intent — if ambiguous, ask clarifying questions; 2. have researched the existing state — read files, search, investigate. Proceed only when both are clear.",
+  "- Before acting on a prompt, do sufficient research on the existing state — read files, search, investigate — and only proceed once you have a clear picture.",
   "- Exercise caution when performing any **write** operations, especially when you are in a research or exploration phase.",
   "- Before modifying code, match the user's existing code style (naming, formatting, patterns). Do not re-modify lines the user has manually edited since your last change.",
   "",
@@ -66,16 +66,17 @@ const BASE_GUIDANCE = [
 ].join("\n");
 
 /** Build the list of guideline strings to inject, in prompt order.
- *  Always-on rules first, then per-module guidelines (skipping disabled
- *  modules). Add new per-module guidelines by importing the constant
- *  here and pushing it inside an `isModuleEnabled(...)` guard. */
+ *  Always-on rules first, then per-module guidelines. REDACT_GUIDANCE is
+ *  gated by the secretRedaction module; CodeGraph guidance follows the MCP
+ *  server switch chain (mcp module on → codegraph server on → guidance
+ *  injected). The mcp module check lives in `resolveMcpConfigs`, so this
+ *  code only needs to look at the server's own `enabled` flag. */
 function buildGuidelines(): string[] {
   const out: string[] = [
     BASE_GUIDANCE,
-    REDACT_GUIDANCE,             // from hooks/redact.ts — always on (safety module)
-    INJECT_AGENTS_MD_GUIDANCE,   // from hooks/inject-agents-md.ts — always on (smart-at module)
+    INJECT_AGENTS_MD_GUIDANCE,   // from hooks/inject-agents-md.ts — always on
   ];
-  if (isModuleEnabled("codegraph")) out.push(CODEGRAPH_GUIDANCE);
+  if (isModuleEnabled("secretRedaction")) out.push(REDACT_GUIDANCE);
   return out;
 }
 
@@ -96,13 +97,18 @@ function installGuidelines(pi: ExtensionAPI): void {
 }
 
 export default async function (pi: ExtensionAPI) {
+  // Snapshot the module settings that pi is about to load. /dp-settings
+  // compares against this to avoid prompting for reload when the user
+  // has only returned the settings to the currently-loaded state.
+  captureModuleSnapshot();
+
   // ── Skeleton (hooks) ───────────────────────────────────────────────────
   const sk = createSkeleton();
 
   // Order matters for tool_result compose chain:
   //   1. redact → normalize-codeblocks → externalize → track-mtime → inject-agents-md → image-vision → wakatime
   // The first module registered for a given event runs first (compose chain).
-  setupRedact(sk);
+  if (isModuleEnabled("secretRedaction")) setupRedact(sk);
   sk.register(normalizeCodeblocksModule);
   sk.register(externalizeModule);
   sk.register(trackMtimeModule);
@@ -114,22 +120,27 @@ export default async function (pi: ExtensionAPI) {
   // anything else inspects the tool list.
   sk.register(piToolFilterModule);
   sk.register(sessionTitleModule);
-  sk.register(smartAtModule);
-  sk.register(wakatimeModule);
+  if (isModuleEnabled("atOverride")) sk.register(smartAtModule);
+  if (isModuleEnabled("wakatime")) sk.register(wakatimeModule);
 
   // Compaction + RTK (these also install their own pi.on via setup<>()).
   setupCompaction(sk);
-  setupRtk(sk, pi);
-  setupWakatime(sk, pi);
+  if (isModuleEnabled("rtk")) setupRtk(sk, pi);
+  if (isModuleEnabled("wakatime")) setupWakatime(sk, pi);
 
   // ── Tools (conditional on module switches) ────────────────────────────
-  if (isModuleEnabled("patch")) registerPatchTool(pi);
+  if (isModuleEnabled("patchOverrideEdit")) registerPatchTool(pi);
   if (isModuleEnabled("lsp")) registerLspTools(pi, new LspServerManager());
+  if (isModuleEnabled("ask")) registerAskTool(pi);
 
-  // MCP: hook AND tool are gated together. Disabling the module
-  // means no session_start handler runs, no tools register, and no
-  // background connections are attempted.
+  // MCP: hook, tools, and /mcp command are gated together. Disabling the
+  // module means no session_start handler runs, no tools register, no
+  // /mcp command is available, and no background connections are attempted.
   if (isModuleEnabled("mcp")) {
+    // One-time migration: legacy global MCP configs in
+    // ~/.pi/agent/decorated-pi.json move to ~/.pi/agent/mcp.json. Run
+    // explicitly here so `loadGlobalMcpConfigs` stays pure.
+    migrateLegacyGlobalMcpConfig();
     sk.register(mcpModule);
     const configs = resolveMcpConfigs(process.cwd()).filter(s => s.enabled);
     // Per-server readiness: cache hit → register from cache (fast).
@@ -138,6 +149,7 @@ export default async function (pi: ExtensionAPI) {
     for (const config of configs) {
       await ensureMcpServerReady(pi, config, process.cwd());
     }
+    registerMcpStatusCommand(pi);
   }
 
   // ── System-prompt guidelines (single handler, array order = prompt order) ──
@@ -146,9 +158,8 @@ export default async function (pi: ExtensionAPI) {
   // ── Commands ──────────────────────────────────────────────────────────
   registerDpModelCommand(pi);
   registerDpSettingsCommand(pi);
-  registerMcpStatusCommand(pi);
-  registerRetryCommand(pi);
-  registerUsageCommand(pi);
+  if (isModuleEnabled("retry")) registerRetryCommand(pi);
+  if (isModuleEnabled("usage")) registerUsageCommand(pi);
 
   // ── Install skeleton (last) ────────────────────────────────────────────
   sk.install(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decorated-pi",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "decorated-pi is a practical enhancement pack for pi coding agent — token-efficient workflow, cache-friendly design, and smarter tools.",
     "keywords": [
         "pi",
@@ -10,8 +10,9 @@
         "mcp",
         "security",
         "lsp",
-        "language-server",
-        "secret-detection"
+        "lsp-client",
+        "secret-redaction",
+        "codegraph"
     ],
     "license": "MIT",
     "repository": {

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 (增量同步元数据) ─────────────────────────────────────────────