decorated-pi 0.7.1 → 0.7.3

package/hooks/mcp.ts

@@ -21,7 +21,7 @@ interface ServerStatus {
   name: string;
   url: string;
   source: string;
-  state: "connecting" | "connected" | "failed" | "disabled" | "waiting_reload";
+  state: "connecting" | "connected" | "failed" | "disabled" | "waiting reload";
   toolCount: number;
   tools: Array<{ name: string; description?: string; inputSchema?: Record<string, unknown> }>;
   error?: string;
@@ -36,6 +36,45 @@ function canUseServer(config: McpServerConfig, cwd?: string): boolean {
   return config.canUseInProject(cwd ?? process.cwd());
 }
 
+function markServerFailed(config: McpServerConfig, error: string): void {
+  allServers.set(config.name, {
+    name: config.name,
+    url: config.url ?? config.command ?? "(unknown)",
+    source: config.source,
+    state: "failed",
+    toolCount: 0,
+    tools: [],
+    error,
+  });
+}
+
+function markServerConnected(config: McpServerConfig, tools: McpToolCache[]): void {
+  allServers.set(config.name, {
+    name: config.name,
+    url: config.url ?? config.command ?? "(unknown)",
+    source: config.source,
+    state: "connected",
+    toolCount: tools.length,
+    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+  });
+}
+
+function markServerState(
+  name: string,
+  state: "disabled" | "waiting reload" | "connecting",
+  config: { url?: string; command?: string; source: string } | undefined,
+): void {
+  allServers.set(name, {
+    name,
+    url: config?.url ?? config?.command ?? "(unknown)",
+    source: config?.source ?? "unknown",
+    state,
+    toolCount: 0,
+    tools: [],
+  });
+}
+
+
 async function connectAll(
   configs: McpServerConfig[],
   registry: any,
@@ -51,7 +90,7 @@ async function connectAll(
   // every caller's updates are visible.
   allServers.clear();
   for (const s of configs) {
-    allServers.set(s.name, { name: s.name, url: s.url ?? s.command ?? "(unknown)", source: s.source, state: "connecting", toolCount: 0, tools: [] });
+    markServerState(s.name, "connecting", s);
   }
 
   // Watchdog: the inner Promise.race in McpConnection.connect() has a
@@ -87,11 +126,7 @@ async function connectAll(
     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",
-      });
+      markServerFailed(server, "Project is missing required artefacts for this server");
       continue;
     }
 
@@ -108,11 +143,7 @@ async function connectAll(
         // 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)",
-        });
+        markServerFailed(server, "Server connected but returned no tools (e.g. codegraph without a .codegraph index)");
         continue;
       }
       activeConnections.push(conn);
@@ -134,19 +165,13 @@ async function connectAll(
           schemaChanges.push(`${server.name} (${parts.join(', ')})`);
         }
       }
-      allServers.set(server.name, {
-        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-        state: "connected", toolCount: conn.tools.length, tools: actualTools,
-      });
       const tools: McpToolCache[] = conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+      markServerConnected(server, tools);
       updateServerCache(server.name, { tools, cachedAt: Date.now() }, cacheScopeForSource(server.source), cachedCwd || undefined);
     } catch (err) {
       if (watchdogFired) return { schemaChanges, hasNewServer };
       const msg = err instanceof Error ? err.message : String(err);
-      allServers.set(server.name, {
-        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-        state: "failed", toolCount: 0, tools: [], error: msg,
-      });
+      markServerFailed(server, msg);
     }
   }
 
@@ -174,7 +199,7 @@ export function getMcpStatus(): ServerStatus[] {
     // or was toggled enabled after startup and needs /reload.
     result.push({
       name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source,
-      state: config.enabled ? "waiting_reload" : "disabled",
+      state: config.enabled ? "waiting reload" : "disabled",
       toolCount: cachedEntry?.tools.length ?? 0, tools: cachedEntry?.tools ?? [],
     });
   }
@@ -194,35 +219,23 @@ export async function updateConfigEnabled(serverName: string, enabled: boolean):
       activeConnections = activeConnections.filter(c => c.serverName !== serverName);
     }
     // Mark the server as disabled in allServers (or add it if absent).
-    allServers.set(serverName, {
-      name: serverName,
-      url: config?.url ?? config?.command ?? "(unknown)",
-      source: config?.source ?? "unknown",
-      state: "disabled",
-      toolCount: 0,
-      tools: [],
-    });
+    markServerState(serverName, "disabled", config ?? undefined);
     return;
   }
 
   // Re-enabling at runtime: the config is now enabled but tools aren't
   // registered until the next session_start. Mark it as waiting_reload
   // so the user sees exactly why the server isn't usable yet.
-  allServers.set(serverName, {
-    name: serverName,
-    url: config?.url ?? config?.command ?? "(unknown)",
-    source: config?.source ?? "unknown",
-    state: "waiting reload",
-    toolCount: 0,
-    tools: [],
-  });
+  markServerState(serverName, "waiting reload", config ?? undefined);
 }
 
 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 error = "Project is missing required artefacts for this server";
+    markServerFailed(config, error);
+    return { ok: false, error };
   }
   const existing = activeConnections.find(c => c.serverName === serverName);
   if (existing) {
@@ -236,21 +249,17 @@ export async function refreshServerCache(serverName: string, registry: any): Pro
     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 });
+      markServerFailed(config, error);
       return { ok: false, error };
     }
     activeConnections.push(conn);
-    allServers.set(config.name, {
-      name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source,
-      state: "connected", toolCount: conn.tools.length,
-      tools: conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
-    });
     const tools: McpToolCache[] = conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+    markServerConnected(config, tools);
     updateServerCache(config.name, { tools, cachedAt: Date.now() }, cacheScopeForSource(config.source), cachedCwd || undefined);
     return { ok: true };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    allServers.set(config.name, { name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source, state: "failed", toolCount: 0, tools: [], error: msg });
+    markServerFailed(config, msg);
     return { ok: false, error: msg };
   }
 }
@@ -277,7 +286,10 @@ export function getCachedMcpConfigs(): McpServerConfig[] {
  * can find it.
  */
 export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerConfig, cwd?: string): Promise<void> {
-  if (!canUseServer(config, cwd)) return;
+  if (!canUseServer(config, cwd)) {
+    markServerFailed(config, "Project is missing required artefacts for this server");
+    return;
+  }
 
   const scope = cacheScopeForSource(config.source);
   const cache = loadScopedMcpCache(scope, cwd);
@@ -303,15 +315,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
       // 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)",
-      });
+      markServerFailed(config, "Server connected but returned no tools (e.g. codegraph without a .codegraph index)");
       return;
     }
     activeConnections.push(conn);
@@ -320,6 +324,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
       description: t.description,
       inputSchema: t.inputSchema,
     }));
+    markServerConnected(config, tools);
     updateServerCache(config.name, { tools, cachedAt: Date.now() }, scope, cwd);
     for (const t of tools) {
       try {
@@ -328,15 +333,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    allServers.set(config.name, {
-      name: config.name,
-      url: config.url ?? config.command ?? "(unknown)",
-      source: config.source,
-      state: "failed",
-      toolCount: 0,
-      tools: [],
-      error: `No cache and initial connect failed: ${msg}`,
-    });
+    markServerFailed(config, `No cache and initial connect failed: ${msg}`);
   }
 }
 

package/hooks/pi-tool-filter.ts

@@ -2,6 +2,7 @@
  * pi-tool-filter — unregister pi native tools that are replaced by our extensions.
  *
  *   edit   → replaced by patch
+ *   write  → replaced by patch
  *   grep   → replaced by bash
  *   find   → replaced by bash
  *   ls     → replaced by bash
@@ -9,7 +10,7 @@
 
 import type { Module, Skeleton } from "./skeleton.js";
 
-const TOOLS_TO_DROP = new Set(["edit", "grep", "find", "ls"]);
+const TOOLS_TO_DROP = new Set(["edit", "write", "grep", "find", "ls"]);
 
 export const piToolFilterModule: Module = {
   name: "pi-tool-filter",

package/hooks/rtk.ts

@@ -1,32 +1,26 @@
 /**
  * rtk — rewrite bash commands through system-installed RTK.
  *
- * Uses `rtk rewrite` as a preflight. If RTK is not installed, this module is inactive.
- * When a rewritten RTK command fails, the original command is executed once as fallback.
+ * Uses `rtk rewrite` as a preflight against pi's built-in bash tool. If RTK is
+ * not installed, this module is inactive. When a rewritten RTK command fails,
+ * the original command is executed once as fallback.
+ *
+ * We do NOT register our own bash tool. We hook the existing one via
+ * `tool_call` (rewrite the command before it runs) and `tool_result` (fall
+ * back to the original on error). Overriding bash via `pi.registerTool` would
+ * conflict with other extensions (e.g. pi-sandbox) that also override bash.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBashToolDefinition, createLocalBashOperations } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { execFileSync, spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
 import * as path from "node:path";
 import type { Module, Skeleton } from "./skeleton.js";
+import { resolveDependency } from "../settings.js";
 
 // ─── Locating RTK ─────────────────────────────────────────────────────────
 
 export function findSystemRtk(): string | null {
-  try {
-    if (process.platform === "win32") {
-      const output = execFileSync("where", ["rtk"], { encoding: "utf-8" }).trim();
-      return output.split(/\r?\n/)[0] || null;
-    }
-    const shell = process.env.SHELL || "sh";
-    return execFileSync(shell, ["-lc", "command -v rtk"], { encoding: "utf-8" }).trim() || null;
-  } catch {
-    return null;
-  }
+  return resolveDependency("rtk");
 }
 
 export function shellQuote(value: string): string {
@@ -45,49 +39,12 @@ export function rewriteWithRtk(command: string, rtkPath: string): string | null
   return buildRtkCommand(raw, rtkPath);
 }
 
-// ─── Bash tool registration ──────────────────────────────────────────────
-
-interface PiShellSettings {
-  shellPath?: string;
-  shellCommandPrefix?: string;
-}
-
-function readJsonObject(filePath: string): Record<string, unknown> {
-  try {
-    if (!fs.existsSync(filePath)) return {};
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    return parsed && typeof parsed === "object" ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function loadPiShellSettings(cwd: string): PiShellSettings {
-  const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
-  const globalSettings = readJsonObject(path.join(agentDir, "settings.json"));
-  const projectSettings = readJsonObject(path.join(cwd, ".pi", "settings.json"));
-  const merged = { ...globalSettings, ...projectSettings } as Record<string, unknown>;
-  const result: PiShellSettings = {};
-  if (typeof merged.shellPath === "string" && merged.shellPath.trim()) result.shellPath = merged.shellPath;
-  if (typeof merged.shellCommandPrefix === "string" && merged.shellCommandPrefix.trim()) {
-    result.shellCommandPrefix = merged.shellCommandPrefix;
-  }
-  return result;
-}
+// ─── Fallback execution ──────────────────────────────────────────────────
 
 export function appendStatus(text: string, status: string): string {
   return text ? `${text}\n\n${status}` : status;
 }
 
-export function formatBashCallWithTag(args: { command?: unknown; timeout?: unknown }, theme: any, showTag: boolean): string {
-  const command = typeof args?.command === "string" ? args.command : null;
-  const timeout = typeof args?.timeout === "number" ? args.timeout : undefined;
-  const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
-  const commandDisplay = command === null ? theme.fg("error", "<invalid command>") : command || theme.fg("toolOutput", "...");
-  const tag = showTag ? theme.fg("borderAccent", " [RTK]") : "";
-  return theme.fg("toolTitle", theme.bold(`$ ${commandDisplay}`)) + timeoutSuffix + tag;
-}
-
 export async function executeOriginalBash(command: string, cwd: string, timeout: number | undefined, signal?: AbortSignal) {
   const ops = createLocalBashOperations();
   const chunks: Buffer[] = [];
@@ -158,48 +115,19 @@ export const rtkModule: Module = {
   },
 };
 
-export function setupRtk(sk: Skeleton, pi: ExtensionAPI): void {
+export function setupRtk(sk: Skeleton): void {
   rtkBinary = findSystemRtk();
-  sk.declareDependency({
-    label: "rtk",
-    check: () => findSystemRtk() !== null,
-    hint: "Install RTK so bash rewrite/tagging can activate.",
-  });
-  if (!rtkBinary) return;
-
-  // Register a wrapped bash tool that shows [RTK] tag in TUI.
-  const shellSettings = loadPiShellSettings(process.cwd());
-  const bashTool = createBashToolDefinition(process.cwd(), {
-    shellPath: shellSettings.shellPath,
-    commandPrefix: shellSettings.shellCommandPrefix,
-  });
-  const baseRenderCall = bashTool.renderCall?.bind(bashTool);
-
-  if (baseRenderCall) {
-    bashTool.renderCall = (args: any, theme: any, context: any) => {
-      const command = typeof args?.command === "string" ? args.command : "";
-      if (!command) {
-        const text = context.lastComponent ?? new Text("", 0, 0);
-        const placeholder = theme.fg("toolOutput", "...");
-        text.setText(theme.fg("toolTitle", theme.bold(`$ ${placeholder}`)));
-        return text;
-      }
-      const component = baseRenderCall(args, theme, context);
-      const predicted = command
-        ? (rewriteabilityCache.get(command) ?? (() => {
-            const value = rewriteWithRtk(command, rtkBinary!) !== null;
-            rewriteabilityCache.set(command, value);
-            return value;
-          })())
-        : false;
-      const rewritten = rewrittenCommands.has(context.toolCallId) || predicted;
-      if (component instanceof Text) {
-        component.setText(formatBashCallWithTag(args, theme, rewritten));
-      }
-      return component;
-    };
+  if (!rtkBinary) {
+    sk.declareMissing({
+      name: "rtk",
+      module: "rtk",
+      hint: "Install RTK so bash rewrite can activate.",
+    });
+    return;
   }
 
-  pi.registerTool(bashTool);
+  // Hook pi's built-in bash tool via tool_call/tool_result. We deliberately do
+  // not call pi.registerTool — that would shadow pi's bash and conflict with
+  // any other extension that also overrides bash (e.g. pi-sandbox).
   sk.register(rtkModule);
 }

package/hooks/skeleton.ts

@@ -2,15 +2,16 @@
  * Skeleton — the only place that calls pi.on(...) for hooks.
  *
  *   sk.register(module)         → installs module's hook handlers
- *   sk.declareDependency({...}) → skeleton checks on session_start
+ *   sk.declareDependency({...}) → check now, report on session_start
  *   sk.declareGuideline("...") → skeleton injects on before_agent_start
- *   sk.install(pi)             → call once, after all setup<X> calls
+ *   sk.install(pi)              → call once, after all setup<X> calls
  *
  * Handlers receive (event, ctx, pi) so they can call pi.* APIs
  * (setSessionName, registerTool, appendEntry, etc.).
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isDontBother } from "../settings.js";
 
 // ─── Event union ───────────────────────────────────────────────────────────
 
@@ -42,13 +43,24 @@ export type ComposeHandler<E extends HookEvent> = (
   pi: ExtensionAPI,
 ) => any | Promise<any>;
 
+/** Result: each handler sees the original event; the last non-undefined
+ *  return value wins. Matches runner.emit()'s behavior for `session_before_*`
+ *  events, where the runner collects a single `{ cancel?, compaction? }`
+ *  result from all extensions. Use for events whose contract is "the
+ *  extension either overrides or steps aside". */
+export type ResultHandler<E extends HookEvent> = (
+  event: any,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+) => any | Promise<any>;
+
 export interface Module {
   readonly name: string;
   readonly hooks: {
     session_start?: ParallelHandler<"session_start">[];
     session_shutdown?: ParallelHandler<"session_shutdown">[];
     session_compact?: ParallelHandler<"session_compact">[];
-    session_before_compact?: ParallelHandler<"session_before_compact">[];
+    session_before_compact?: ResultHandler<"session_before_compact">[];
     before_agent_start?: ComposeHandler<"before_agent_start">[];
     agent_start?: ParallelHandler<"agent_start">[];
     agent_end?: ParallelHandler<"agent_end">[];
@@ -61,9 +73,9 @@ export interface Module {
 // ─── Declarations ──────────────────────────────────────────────────────────
 
 export interface Dependency {
-  label: string;
-  check: () => boolean;
+  name: string;
   hint?: string;
+  module?: string;
 }
 
 /** Collected result shape for a module's declared dependency. Modules
@@ -73,9 +85,12 @@ export interface Dependency {
  *  uses `Dependency.check` directly rather than collecting statuses. */
 export interface DependencyStatus {
   module: string;
+  /** Binary/config key, not necessarily the resolved absolute path. */
   label: string;
   state: "ok" | "missing";
   detail: string;
+  /** Resolved executable path when state is ok. */
+  path?: string;
 }
 
 // ─── Skeleton ──────────────────────────────────────────────────────────────
@@ -86,9 +101,23 @@ const COMPOSE_EVENTS = new Set<HookEvent>([
   "tool_result",
 ]);
 
+/** Events whose handler return value is propagated to the extension runner
+ *  (no chaining — each handler sees the original event, last non-undefined
+ *  return wins). Required for `session_before_compact`, whose contract is
+ *  `{ cancel?, compaction? }`; without this, hooks can't override pi's
+ *  default compaction. */
+const RESULT_EVENTS = new Set<HookEvent>([
+  "session_before_compact",
+]);
+
 export interface Skeleton {
   register(module: Module): void;
-  declareDependency(dep: Dependency): void;
+  /** Returns whether the dependency check passed right now. */
+  /** Declare that a binary dependency is missing. Module calls this
+   *   after its own which() lookup failed. Skeleton dedupes by name,
+   *   honors `dependencies[name].dontBother`, and shows a single
+   *   "run /dp-settings" notification on session_start. */
+  declareMissing(dep: Omit<Dependency, "module"> & { module?: string }): void;
   install(pi: ExtensionAPI): void;
   inspect(): Inspection;
 }
@@ -96,13 +125,14 @@ export interface Skeleton {
 export interface Inspection {
   modules: string[];
   events: Record<string, Array<{ module: string; order: number }>>;
-  dependencies: Array<{ label: string; hint?: string }>;
+  dependencies: Array<{ name: string; module?: string; hint?: string }>;
 }
 
 export function createSkeleton(): Skeleton {
   const modules: Module[] = [];
   const registry = new Map<HookEvent, Array<{ module: string; handler: (event: any, ctx: ExtensionContext, pi: ExtensionAPI) => any }>>();
   const dependencies: Dependency[] = [];
+  let dependencyNotifyTimer: ReturnType<typeof setTimeout> | undefined;
 
   function collect(mod: Module) {
     for (const [event, handlers] of Object.entries(mod.hooks)) {
@@ -121,8 +151,10 @@ export function createSkeleton(): Skeleton {
       collect(mod);
     },
 
-    declareDependency(dep) {
-      dependencies.push(dep);
+    declareMissing(dep) {
+      // Dedupe by name — multiple modules may depend on the same binary.
+      if (dependencies.some((d) => d.name === dep.name)) return;
+      dependencies.push(dep as Dependency);
     },
 
     install(pi) {
@@ -138,6 +170,15 @@ export function createSkeleton(): Skeleton {
             }
             return current === event ? undefined : current;
           });
+        } else if (RESULT_EVENTS.has(event)) {
+          pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
+            let result;
+            for (const { handler } of handlers) {
+              const r = await handler(event, ctx, pi);
+              if (r !== undefined) result = r;
+            }
+            return result;
+          });
         } else {
           pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
             for (const { handler } of handlers) await handler(event, ctx, pi);
@@ -146,21 +187,43 @@ export function createSkeleton(): Skeleton {
       }
 
       // Skeleton-owned: dependency check on session_start.
-      pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
+      // Defer with setTimeout(0) so the notification fires AFTER pi's
+      // startup/reload UI rebuild (rebuildChatFromMessages); otherwise it
+      // is appended to the chat and immediately wiped.
+      const runDependencyCheck = (ctx: ExtensionContext) => {
         if (!ctx.hasUI) return;
-        const hints: string[] = [];
-        let anyMissing = false;
-        for (const dep of dependencies) {
-          let ok = false;
-          try { ok = dep.check(); } catch { ok = false; }
-          if (!ok) {
-            anyMissing = true;
-            if (dep.hint) hints.push(`  [${dep.label}] ${dep.hint}`);
+        if (dependencyNotifyTimer) clearTimeout(dependencyNotifyTimer);
+        dependencyNotifyTimer = setTimeout(() => {
+          dependencyNotifyTimer = undefined;
+          const missing: string[] = [];
+          for (const dep of dependencies) {
+            // dontBother flag silences the notification per-binary.
+            if (isDontBother(dep.name)) continue;
+            missing.push(dep.name);
           }
-        }
-        if (anyMissing) {
-          ctx.ui.notify(`[decorated-pi] missing dependencies:\n${hints.join("\n")}`, "info");
-        }
+          if (missing.length) {
+            try {
+              ctx.ui.notify(
+                `[decorated-pi] Some dependencies are missing (${missing.length}). Run /dp-settings → Dependencies to configure.`,
+                "info",
+              );
+            } catch {
+              // Extension context may be stale if another reload/session switch happened.
+            }
+          }
+        }, 0);
+      };
+      pi.on("session_start", async (event: any, ctx: ExtensionContext) => {
+        // Only check on cold startup and explicit reload — other reasons
+        // (new/resume/fork) inherit the existing session's tool/runtime
+        // and don't need a fresh check.
+        if (event.reason !== "startup" && event.reason !== "reload") return;
+        runDependencyCheck(ctx);
+      });
+      pi.on("session_shutdown", async () => {
+        if (!dependencyNotifyTimer) return;
+        clearTimeout(dependencyNotifyTimer);
+        dependencyNotifyTimer = undefined;
       });
 
       // Skeleton-owned: system-prompt options sort for cache stability.
@@ -179,7 +242,7 @@ export function createSkeleton(): Skeleton {
       return {
         modules: modules.map((m) => m.name),
         events,
-        dependencies: dependencies.map((d) => ({ label: d.label, hint: d.hint })),
+        dependencies: dependencies.map((d) => ({ name: d.name, module: d.module, hint: d.hint })),
       };
     },
   };