@pencil-agent/nano-pencil 1.14.2 → 1.14.4

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.14.2",
-  "commitHash": "62cd264",
+  "version": "1.14.4",
+  "commitHash": "092b256",
   "branch": "main",
-  "builtAt": "2026-05-26T18:24:58.388Z"
+  "builtAt": "2026-05-27T16:26:12.388Z"
 }

package/dist/builtin-extensions.d.ts

@@ -5,6 +5,7 @@
  * [HERE]: builtin-extensions.ts - built-in extension registry for NanoPencil
  */
 export type BuiltinExtensionRiskLevel = "passive" | "command" | "tool" | "background" | "write-capable";
+export type BuiltinExtensionTestContract = "lifecycle" | "external-process" | "resource-discovery" | "write-guard";
 export interface BuiltinExtension {
     id: string;
     category: "default" | "optional" | "package";
@@ -14,6 +15,9 @@ export interface BuiltinExtension {
     startsTimers: boolean;
     writesWorkspace: boolean;
     externalProcess: boolean;
+    resourceDiscovery?: boolean;
+    testContracts?: readonly BuiltinExtensionTestContract[];
+    testFiles?: readonly string[];
 }
 export declare const builtInExtensions: readonly BuiltinExtension[];
 /**

package/dist/builtin-extensions.js

@@ -33,29 +33,29 @@ const BUNDLED_RECAP_EXTENSION = join(__dirname, "extensions", "defaults", "recap
 const BUNDLED_DEBUG_EXTENSION = join(__dirname, "extensions", "defaults", "debug", "index.js");
 const BUNDLED_MCP_EXTENSION = join(__dirname, "extensions", "defaults", "mcp", "index.js");
 export const builtInExtensions = [
-    { id: "diagnostics", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: true, writesWorkspace: false, externalProcess: false },
-    { id: "sal", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
+    { id: "diagnostics", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: true, writesWorkspace: false, externalProcess: false, testContracts: ["lifecycle"], testFiles: ["test/diagnostic-buffer-throttle.test.ts", "test/diagnostics-runtime.test.ts"] },
+    { id: "sal", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false, testContracts: ["lifecycle"], testFiles: ["test/sal-lifecycle.test.ts"] },
     { id: "token-save", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "nanomem", category: "package", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "link-world", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
-    { id: "browser", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
+    { id: "nanomem", category: "package", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false, testContracts: ["lifecycle"], testFiles: ["packages/mem-core/test/extension-commands.test.ts"] },
+    { id: "link-world", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, resourceDiscovery: true, testContracts: ["external-process", "resource-discovery"], testFiles: ["test/link-world-extension-registration.test.ts"] },
+    { id: "browser", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, resourceDiscovery: true, testContracts: ["external-process", "resource-discovery"], testFiles: ["test/browser-extension-registration.test.ts"] },
     { id: "security-audit", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "soul", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "presence", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: true, startsTimers: true, writesWorkspace: false, externalProcess: false },
+    { id: "soul", category: "default", defaultEnabled: true, riskLevel: "passive", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
+    { id: "presence", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: true, startsTimers: true, writesWorkspace: false, externalProcess: false, testContracts: ["lifecycle"], testFiles: ["test/presence-opening.test.ts", "test/presence-locale.test.ts"] },
     { id: "interview", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "grub", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
-    { id: "loop", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: true, writesWorkspace: false, externalProcess: false },
+    { id: "grub", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, testContracts: ["lifecycle", "external-process"], testFiles: ["test/grub-controller.test.ts"] },
+    { id: "loop", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: true, writesWorkspace: false, externalProcess: false, testContracts: ["lifecycle"], testFiles: ["test/loop-lifecycle.test.ts"] },
     { id: "plan", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "discipline", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "subagent", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
-    { id: "team", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
-    { id: "idle-think", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: true, startsTimers: true, writesWorkspace: false, externalProcess: true },
+    { id: "discipline", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false, resourceDiscovery: true, testContracts: ["resource-discovery"], testFiles: ["test/discipline-extension.test.ts", "test/extension-smoke.test.ts"] },
+    { id: "subagent", category: "default", defaultEnabled: true, riskLevel: "tool", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, testContracts: ["external-process"], testFiles: ["test/subagent-parser.test.ts", "test/worktree-manager.test.ts"] },
+    { id: "team", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, testContracts: ["lifecycle", "external-process"], testFiles: ["test/team-runtime.test.ts"] },
+    { id: "idle-think", category: "default", defaultEnabled: true, riskLevel: "background", requiresUI: true, startsTimers: true, writesWorkspace: false, externalProcess: true, testContracts: ["lifecycle", "external-process"], testFiles: ["test/idle-think-runtime.test.ts", "test/extension-smoke.test.ts"] },
     { id: "btw", category: "default", defaultEnabled: true, riskLevel: "command", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
     { id: "recap", category: "default", defaultEnabled: true, riskLevel: "command", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
     { id: "debug", category: "default", defaultEnabled: true, riskLevel: "command", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: false },
-    { id: "mcp", category: "default", defaultEnabled: true, riskLevel: "command", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true },
-    { id: "simplify", category: "optional", defaultEnabled: false, riskLevel: "write-capable", requiresUI: false, startsTimers: false, writesWorkspace: true, externalProcess: true },
-    { id: "export-html", category: "optional", defaultEnabled: false, riskLevel: "write-capable", requiresUI: false, startsTimers: false, writesWorkspace: true, externalProcess: false },
+    { id: "mcp", category: "default", defaultEnabled: true, riskLevel: "command", requiresUI: false, startsTimers: false, writesWorkspace: false, externalProcess: true, resourceDiscovery: true, testContracts: ["external-process", "resource-discovery"], testFiles: ["test/resource-discovery-contract.test.ts"] },
+    { id: "simplify", category: "optional", defaultEnabled: false, riskLevel: "write-capable", requiresUI: false, startsTimers: false, writesWorkspace: true, externalProcess: true, testContracts: ["external-process", "write-guard"], testFiles: ["test/simplify-extension.test.ts"] },
+    { id: "export-html", category: "optional", defaultEnabled: false, riskLevel: "write-capable", requiresUI: false, startsTimers: false, writesWorkspace: true, externalProcess: false, testContracts: ["write-guard"], testFiles: ["test/extension-smoke.test.ts", "test/export-html-branch-navigation.test.ts"] },
 ];
 /** Find package root from current module location (containing package.json with nano-pencil related name) */
 function findPackageRoot(startDir) {

package/dist/core/config/settings-manager.d.ts

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SettingsManager class, two-tier settings (global + project-local)
+ * [WHO]: SettingsManager class, two-tier settings (global + project-local), agent loop defaults
  * [FROM]: Depends on ai, node:fs, proper-lockfile, config.ts
  * [TO]: Consumed by index.ts, main.ts, core/runtime/sdk.ts, cli/config-selector.ts, extensions/defaults/team/index.ts, modes/interactive/components/model-selector.ts, modes/interactive/components/config-selector.ts, and test files
  * [HERE]: core/config/settings-manager.ts - user preferences aggregation
@@ -20,6 +20,9 @@ export interface RetrySettings {
     baseDelayMs?: number;
     maxDelayMs?: number;
 }
+export interface AgentLoopSettings {
+    maxToolResultBatchSizeChars?: number;
+}
 export interface TerminalSettings {
     showImages?: boolean;
     clearOnShrink?: boolean;
@@ -65,6 +68,7 @@ export interface Settings {
     defaultModel?: string;
     defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
     agentLoopFramework?: AgentLoopFrameworkSettingInput;
+    agentLoop?: AgentLoopSettings;
     transport?: TransportSetting;
     steeringMode?: "all" | "one-at-a-time";
     followUpMode?: "all" | "one-at-a-time";
@@ -218,6 +222,9 @@ export declare class SettingsManager {
     getDefaultThinkingLevel(): "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | undefined;
     setDefaultThinkingLevel(level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh"): void;
     getAgentLoopFramework(): AgentLoopFrameworkSetting | undefined;
+    getAgentLoopSettings(): {
+        maxToolResultBatchSizeChars: number;
+    };
     setAgentLoopFramework(framework: AgentLoopFrameworkSettingInput | undefined): void;
     getTransport(): TransportSetting;
     setTransport(transport: TransportSetting): void;

package/dist/core/config/settings-manager.js

@@ -4,6 +4,7 @@ import lockfile from "proper-lockfile";
 import { APP_NAME, CONFIG_DIR_NAME } from "../../config.js";
 import { defaultAgentDirContext } from "../agent-dir/agent-dir-context.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
+const DEFAULT_MAX_TOOL_RESULT_BATCH_SIZE_CHARS = 200_000;
 export function normalizeAgentLoopFrameworkSetting(value) {
     if (value === "high-intelligence")
         return "standard";
@@ -574,6 +575,14 @@ export class SettingsManager {
     getAgentLoopFramework() {
         return normalizeAgentLoopFrameworkSetting(this.settings.agentLoopFramework);
     }
+    getAgentLoopSettings() {
+        const configured = this.settings.agentLoop?.maxToolResultBatchSizeChars;
+        return {
+            maxToolResultBatchSizeChars: typeof configured === "number" && Number.isFinite(configured) && configured > 0
+                ? Math.floor(configured)
+                : DEFAULT_MAX_TOOL_RESULT_BATCH_SIZE_CHARS,
+        };
+    }
     setAgentLoopFramework(framework) {
         const normalized = normalizeAgentLoopFrameworkSetting(framework);
         if (normalized === undefined) {

package/dist/core/extensions/runner.d.ts

@@ -1,8 +1,8 @@
 /**
- * [WHO]: ExtensionRunner class, lifecycle management, event emission
- * [FROM]: Depends on agent-core, ai, tui, modes/theme, session-manager, types.ts
- * [TO]: Consumed by core/extensions/index.ts, core/extensions/wrapper.ts
- * [HERE]: core/extensions/runner.ts - extension execution and lifecycle management
+ * [WHO]: ExtensionRunner class, lifecycle management, event emission, slash-command dispatch chokepoint (invokeCommand), telemetry sink wiring (setTelemetrySink)
+ * [FROM]: Depends on agent-core, ai, tui, modes/theme, session-manager, types.ts, core/telemetry (ExtensionTelemetrySink + classifyArgsSignature for the P1 ext_command_events writer)
+ * [TO]: Consumed by core/extensions/index.ts, core/extensions/wrapper.ts, core/runtime/agent-session.ts (delegates command dispatch via invokeCommand)
+ * [HERE]: core/extensions/runner.ts - extension execution and lifecycle management; owns the single try/catch around command.handler so telemetry can wrap every invocation regardless of caller mode
  */
 import type { AgentMessage } from "@pencil-agent/agent-core";
 import type { ImageContent } from "@pencil-agent/ai";
@@ -11,6 +11,7 @@ import type { ResourceDiagnostic } from "../diagnostics.js";
 import type { KeybindingsConfig } from "../keybindings.js";
 import type { ModelRegistry } from "../model-registry.js";
 import type { SessionManager } from "../session/session-manager.js";
+import { type ExtensionTelemetrySink, type LlmCallEventInput } from "../telemetry/index.js";
 import type { BeforeAgentStartEvent, BeforeAgentStartEventResult, ContextEvent, Extension, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFlag, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, InputEvent, InputEventResult, InputSource, MessageRenderer, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, SessionBeforeCompactResult, SessionBeforeForkResult, SessionBeforeSwitchResult, SessionBeforeTreeResult, ToolCallEvent, ToolCallEventResult, ToolResultEvent, ToolResultEventResult, UserBashEvent, UserBashEventResult } from "./types.js";
 /** Combined result from all before_agent_start handlers */
 interface BeforeAgentStartCombinedResult {
@@ -90,6 +91,7 @@ export declare class ExtensionRunner {
     private shutdownHandler;
     private shortcutDiagnostics;
     private commandDiagnostics;
+    private telemetrySink?;
     private _beforeAgentStartTimeoutMs;
     private get beforeAgentStartTimeoutMs();
     private readonly beforeAgentStartTimeoutSentinel;
@@ -127,6 +129,70 @@ export declare class ExtensionRunner {
         extensionPath: string;
     }>;
     getCommand(name: string): RegisteredCommand | undefined;
+    /**
+     * Returns the owning Extension for a given slash command name. Used by the
+     * telemetry middleware to stamp `extension_name` on each ext_command_events
+     * row. Falls back to undefined when no extension claims the command.
+     */
+    private findCommandOwner;
+    /**
+     * Derive a short, stable extension name from an Extension record. For
+     * built-ins (extensions/defaults/<name>) and most user extensions
+     * (packages/<name>) the directory basename is the right answer.
+     */
+    private deriveExtensionName;
+    /**
+     * Attach (or replace) the extension telemetry sink. The runner owns sink
+     * lifecycle from this point — invokeCommand() will fire-and-forget one
+     * `ext_command_events` row per invocation, and writeLlmCallEvent() (called
+     * from extension-core-bindings) writes one `ext_llm_calls` row per
+     * extension-initiated LLM call. Passing the noop sink (the factory's
+     * default when no insforge credentials exist) is the safe way to disable
+     * telemetry without scattering null-checks at the call sites.
+     */
+    setTelemetrySink(sink: ExtensionTelemetrySink): void;
+    /**
+     * Passthrough used by core/runtime/extension-core-bindings.ts after each
+     * extension-initiated LLM call. The runner owns the sink; the binding
+     * doesn't import it directly to keep its concerns scoped to LLM plumbing.
+     */
+    writeLlmCallEvent(input: LlmCallEventInput): void;
+    /**
+     * Wrap an extension hook handler invocation in three layers:
+     *
+     *   1. AsyncLocalStorage frame so any LLM call placed by the handler gets
+     *      attributed to this extension + hook + isUserInitiated=false in
+     *      ext_llm_calls.
+     *   2. Wall-clock timing measurement (only when the sample roll passes).
+     *   3. One fire-and-forget ext_hook_events row per sampled invocation,
+     *      capturing duration_ms + ok + error_code + sample_rate.
+     *
+     * High-frequency hooks (tool_*) are sampled at 10% so the table doesn't
+     * drown in tool-execution rows; the sample_rate column on each row lets
+     * dashboards extrapolate with `count(*) * 1/sample_rate`. Sampling decision
+     * sits inside the AsyncLocalStorage frame so even skipped-emit hooks still
+     * attribute their LLM calls.
+     */
+    private invokeHookHandler;
+    /**
+     * Single chokepoint for slash command dispatch. All modes (interactive /
+     * print / rpc / acp) funnel through agent-session._tryExecuteExtensionCommand,
+     * which calls this method. The wrapper measures wall-clock duration,
+     * captures outcome (ok / error / cancelled), and emits one telemetry row
+     * per invocation. Errors are still routed through emitError() so existing
+     * UI surfaces (toasts, logs) keep working unchanged.
+     *
+     * Returns `{ found: false }` when no extension owns the command, letting
+     * the caller fall through to built-in command handling without emitting a
+     * telemetry row for an unknown command.
+     */
+    invokeCommand(commandName: string, args: string, ctx: ExtensionCommandContext, metadata?: {
+        sessionId?: string | null;
+        runId?: string | null;
+        variant?: string | null;
+    }): Promise<{
+        found: boolean;
+    }>;
     /**
      * Request a graceful shutdown. Called by extension tools and event handlers.
      * The actual shutdown behavior is provided by the mode via bindExtensions().

package/dist/core/extensions/runner.js

@@ -1,4 +1,5 @@
 import { theme } from "../../modes/interactive/theme/theme.js";
+import { classifyArgsSignature, HOOK_SAMPLE_RATES, runWithExtCallerContext, } from "../telemetry/index.js";
 // Keybindings for these actions cannot be overridden by extensions
 const RESERVED_ACTIONS_FOR_EXTENSION_CONFLICTS = [
     "interrupt",
@@ -108,6 +109,7 @@ export class ExtensionRunner {
     shutdownHandler = () => { };
     shortcutDiagnostics = [];
     commandDiagnostics = [];
+    telemetrySink;
     _beforeAgentStartTimeoutMs = 1500;
     get beforeAgentStartTimeoutMs() { return this._beforeAgentStartTimeoutMs ?? 1500; }
     beforeAgentStartTimeoutSentinel = Symbol("before_agent_start_timeout");
@@ -378,6 +380,184 @@ export class ExtensionRunner {
         }
         return undefined;
     }
+    /**
+     * Returns the owning Extension for a given slash command name. Used by the
+     * telemetry middleware to stamp `extension_name` on each ext_command_events
+     * row. Falls back to undefined when no extension claims the command.
+     */
+    findCommandOwner(name) {
+        for (const ext of this.extensions) {
+            if (ext.commands.has(name))
+                return ext;
+        }
+        return undefined;
+    }
+    /**
+     * Derive a short, stable extension name from an Extension record. For
+     * built-ins (extensions/defaults/<name>) and most user extensions
+     * (packages/<name>) the directory basename is the right answer.
+     */
+    deriveExtensionName(ext) {
+        const path = ext.path || ext.resolvedPath || "";
+        const segments = path.replace(/\/+$/, "").split(/[\\/]/);
+        return segments[segments.length - 1] || "unknown";
+    }
+    /**
+     * Attach (or replace) the extension telemetry sink. The runner owns sink
+     * lifecycle from this point — invokeCommand() will fire-and-forget one
+     * `ext_command_events` row per invocation, and writeLlmCallEvent() (called
+     * from extension-core-bindings) writes one `ext_llm_calls` row per
+     * extension-initiated LLM call. Passing the noop sink (the factory's
+     * default when no insforge credentials exist) is the safe way to disable
+     * telemetry without scattering null-checks at the call sites.
+     */
+    setTelemetrySink(sink) {
+        this.telemetrySink = sink;
+    }
+    /**
+     * Passthrough used by core/runtime/extension-core-bindings.ts after each
+     * extension-initiated LLM call. The runner owns the sink; the binding
+     * doesn't import it directly to keep its concerns scoped to LLM plumbing.
+     */
+    writeLlmCallEvent(input) {
+        try {
+            this.telemetrySink?.writeLlmCallEvent(input);
+        }
+        catch {
+            // Telemetry must never destabilize the LLM call path.
+        }
+    }
+    /**
+     * Wrap an extension hook handler invocation in three layers:
+     *
+     *   1. AsyncLocalStorage frame so any LLM call placed by the handler gets
+     *      attributed to this extension + hook + isUserInitiated=false in
+     *      ext_llm_calls.
+     *   2. Wall-clock timing measurement (only when the sample roll passes).
+     *   3. One fire-and-forget ext_hook_events row per sampled invocation,
+     *      capturing duration_ms + ok + error_code + sample_rate.
+     *
+     * High-frequency hooks (tool_*) are sampled at 10% so the table doesn't
+     * drown in tool-execution rows; the sample_rate column on each row lets
+     * dashboards extrapolate with `count(*) * 1/sample_rate`. Sampling decision
+     * sits inside the AsyncLocalStorage frame so even skipped-emit hooks still
+     * attribute their LLM calls.
+     */
+    invokeHookHandler(ext, hookName, fn) {
+        const extensionName = this.deriveExtensionName(ext);
+        const ctx = {
+            extensionName,
+            callerContext: `hook:${hookName}`,
+            isUserInitiated: false,
+        };
+        return runWithExtCallerContext(ctx, async () => {
+            const sampleRate = HOOK_SAMPLE_RATES[hookName] ?? 1.0;
+            if (sampleRate < 1.0 && Math.random() >= sampleRate) {
+                return await fn();
+            }
+            const recordedAt = new Date();
+            const startPerf = performance.now();
+            let ok = true;
+            let errorCode = null;
+            try {
+                return await fn();
+            }
+            catch (err) {
+                ok = false;
+                errorCode = err instanceof Error ? err.constructor.name : "unknown";
+                throw err;
+            }
+            finally {
+                try {
+                    this.telemetrySink?.writeHookEvent({
+                        extensionName,
+                        hookName,
+                        durationMs: Math.round(performance.now() - startPerf),
+                        ok,
+                        errorCode,
+                        sampleRate,
+                        recordedAt,
+                    });
+                }
+                catch {
+                    // Telemetry never destabilizes hook dispatch.
+                }
+            }
+        });
+    }
+    /**
+     * Single chokepoint for slash command dispatch. All modes (interactive /
+     * print / rpc / acp) funnel through agent-session._tryExecuteExtensionCommand,
+     * which calls this method. The wrapper measures wall-clock duration,
+     * captures outcome (ok / error / cancelled), and emits one telemetry row
+     * per invocation. Errors are still routed through emitError() so existing
+     * UI surfaces (toasts, logs) keep working unchanged.
+     *
+     * Returns `{ found: false }` when no extension owns the command, letting
+     * the caller fall through to built-in command handling without emitting a
+     * telemetry row for an unknown command.
+     */
+    async invokeCommand(commandName, args, ctx, metadata) {
+        const command = this.getCommand(commandName);
+        if (!command)
+            return { found: false };
+        const ownerExt = this.findCommandOwner(commandName);
+        const extensionName = ownerExt ? this.deriveExtensionName(ownerExt) : "unknown";
+        const startedAt = new Date();
+        const startPerf = performance.now();
+        let outcome = "ok";
+        let errorCode = null;
+        let thrown;
+        const argsSig = classifyArgsSignature(args);
+        const callerCtx = {
+            extensionName,
+            callerContext: argsSig === "no-args" ? `command:/${commandName}` : `command:/${commandName} ${argsSig}`,
+            isUserInitiated: true,
+            sessionId: metadata?.sessionId ?? null,
+            runId: metadata?.runId ?? null,
+            variant: metadata?.variant ?? null,
+        };
+        try {
+            await runWithExtCallerContext(callerCtx, () => command.handler(args, ctx));
+        }
+        catch (err) {
+            outcome = "error";
+            errorCode = err instanceof Error ? err.constructor.name : "unknown";
+            thrown = err;
+            this.emitError({
+                extensionPath: `command:${commandName}`,
+                event: "command",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const durationMs = Math.round(performance.now() - startPerf);
+        const endedAt = new Date();
+        try {
+            this.telemetrySink?.writeCommandEvent({
+                extensionName,
+                commandName,
+                argsSignature: argsSig,
+                argsLength: args.length,
+                outcome,
+                errorCode,
+                durationMs,
+                startedAt,
+                endedAt,
+                sessionId: metadata?.sessionId ?? null,
+                runId: metadata?.runId ?? null,
+                variant: metadata?.variant ?? null,
+            });
+        }
+        catch {
+            // Sink emission must never bring down command dispatch.
+        }
+        // Even though we logged the error to telemetry + emitError, callers
+        // expecting the thrown error (e.g. AgentSession previously re-caught it
+        // silently) won't see it. This matches the original behaviour: the old
+        // _tryExecuteExtensionCommand swallowed the error after emitError too.
+        void thrown;
+        return { found: true };
+    }
     /**
      * Request a graceful shutdown. Called by extension tools and event handlers.
      * The actual shutdown behavior is provided by the mode via bindExtensions().
@@ -444,7 +624,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, event.type, () => handler(event, ctx));
                     if (this.isSessionBeforeEvent(event) && handlerResult) {
                         result = handlerResult;
                         if (result.cancel) {
@@ -476,7 +656,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = (await handler(currentEvent, ctx));
+                    const handlerResult = (await this.invokeHookHandler(ext, "tool_result", () => handler(currentEvent, ctx)));
                     if (!handlerResult)
                         continue;
                     if (handlerResult.content !== undefined) {
@@ -521,7 +701,7 @@ export class ExtensionRunner {
             if (!handlers || handlers.length === 0)
                 continue;
             for (const handler of handlers) {
-                const handlerResult = await handler(event, ctx);
+                const handlerResult = await this.invokeHookHandler(ext, "tool_call", () => handler(event, ctx));
                 if (handlerResult) {
                     result = handlerResult;
                     if (result.block) {
@@ -540,7 +720,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "user_bash", () => handler(event, ctx));
                     if (handlerResult) {
                         return handlerResult;
                     }
@@ -569,7 +749,7 @@ export class ExtensionRunner {
             for (const handler of handlers) {
                 try {
                     const event = { type: "context", messages: currentMessages };
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "context", () => handler(event, ctx));
                     if (handlerResult && handlerResult.messages) {
                         currentMessages = handlerResult.messages;
                     }
@@ -605,7 +785,7 @@ export class ExtensionRunner {
                         images,
                         systemPrompt: currentSystemPrompt,
                     };
-                    const handlerResult = await this.withTimeout(handler(event, ctx), this.beforeAgentStartTimeoutMs);
+                    const handlerResult = await this.withTimeout(this.invokeHookHandler(ext, "before_agent_start", () => handler(event, ctx)), this.beforeAgentStartTimeoutMs);
                     if (handlerResult === this.beforeAgentStartTimeoutSentinel) {
                         this.reportBeforeAgentStartTimeout(ext.path);
                         continue;
@@ -663,7 +843,7 @@ export class ExtensionRunner {
             for (const handler of handlers) {
                 try {
                     const event = { type: "resources_discover", cwd, reason };
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "resources_discover", () => handler(event, ctx));
                     const result = handlerResult;
                     if (result?.skillPaths?.length) {
                         skillPaths.push(...result.skillPaths.map((path) => ({ path, extensionPath: ext.path })));
@@ -698,7 +878,7 @@ export class ExtensionRunner {
             for (const handler of ext.handlers.get("input") ?? []) {
                 try {
                     const event = { type: "input", text: currentText, images: currentImages, source };
-                    const result = (await handler(event, ctx));
+                    const result = (await this.invokeHookHandler(ext, "input", () => handler(event, ctx)));
                     if (result?.action === "handled")
                         return result;
                     if (result?.action === "transform") {

package/dist/core/extensions/types.d.ts

@@ -685,10 +685,17 @@ export interface MessageRenderOptions {
     expanded: boolean;
 }
 export type MessageRenderer<T = unknown> = (message: CustomMessage<T>, options: MessageRenderOptions, theme: Theme) => Component | undefined;
+export interface ArgumentCompletionContext {
+    commandName: string;
+    argumentText: string;
+    argumentPrefix: string;
+    tokenIndex: number;
+    previousTokens: string[];
+}
 export interface RegisteredCommand {
     name: string;
     description?: string;
-    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
+    getArgumentCompletions?: (argumentPrefix: string, context?: ArgumentCompletionContext) => AutocompleteItem[] | null;
     handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
 /** Handler function type for events */

package/dist/core/i18n/slash-commands.d.ts

@@ -5,8 +5,19 @@
  * [HERE]: core/i18n/slash-commands.ts - English slash command translations
  */
 export declare const slashCommands: {
+    categories: {
+        core: string;
+        model: string;
+        memory: string;
+        session: string;
+        workflow: string;
+        agents: string;
+        tools: string;
+        admin: string;
+    };
     settings: string;
     model: string;
+    thinking: string;
     "agent-loop": string;
     "scoped-models": string;
     apikey: string;
@@ -24,6 +35,7 @@ export declare const slashCommands: {
     usage: string;
     changelog: string;
     hotkeys: string;
+    resources: string;
     fork: string;
     tree: string;
     login: string;

package/dist/core/i18n/slash-commands.js

@@ -5,16 +5,27 @@
  * [HERE]: core/i18n/slash-commands.ts - English slash command translations
  */
 export const slashCommands = {
+    categories: {
+        core: "Core",
+        model: "Models",
+        memory: "Memory",
+        session: "Sessions",
+        workflow: "Workflows",
+        agents: "Agents",
+        tools: "Tools",
+        admin: "Admin",
+    },
     settings: "Open settings menu",
     model: "Select model (opens selector UI)",
-    "agent-loop": "Set standard or weak-model-compatible agent loop for this session",
-    "scoped-models": "Enable/disable models for Ctrl+P cycling",
+    thinking: "Choose reasoning depth for the current model",
+    "agent-loop": "Choose how the agent keeps working through a task",
+    "scoped-models": "Choose which models appear in quick switching",
     apikey: "Update API key for current provider",
     mcp: "Manage MCP servers (list, enable, disable)",
     soul: "Show AI personality and stats (Soul)",
     persona: "Switch AI persona/personality pack",
     memory: "Show project memory and knowledge (NanoMem)",
-    dream: "Consolidate project memory (NanoMem)",
+    dream: "Refresh long-term project memory (NanoMem)",
     export: "Export session to HTML file",
     share: "Share session as a secret GitHub gist",
     copy: "Copy last agent message to clipboard",
@@ -24,6 +35,7 @@ export const slashCommands = {
     usage: "Show token usage and cost stats",
     changelog: "Show changelog entries",
     hotkeys: "Show all keyboard shortcuts",
+    resources: "Show loaded extensions, prompts, skills, and themes",
     fork: "Create a new fork from a previous message",
     tree: "Navigate session tree (switch branches)",
     login: "Login with OAuth provider",
@@ -34,7 +46,7 @@ export const slashCommands = {
     compact: "Manually compact the session context",
     resume: "Resume a different session",
     reload: "Reload extensions, skills, prompts, and themes",
-    "link-world": "Install link-world for internet access (Twitter, YouTube, etc.)",
+    "link-world": "Set up internet access tools",
     quit: "Quit NanoPencil",
     language: "Switch language (English/Chinese)",
 };

package/dist/core/i18n/slash-commands.zh.d.ts

@@ -5,8 +5,19 @@
  * [HERE]: core/i18n/slash-commands.zh.ts - Chinese slash command translations
  */
 export declare const slashCommands: {
+    categories: {
+        core: string;
+        model: string;
+        memory: string;
+        session: string;
+        workflow: string;
+        agents: string;
+        tools: string;
+        admin: string;
+    };
     settings: string;
     model: string;
+    thinking: string;
     "agent-loop": string;
     "scoped-models": string;
     apikey: string;
@@ -24,6 +35,7 @@ export declare const slashCommands: {
     usage: string;
     changelog: string;
     hotkeys: string;
+    resources: string;
     fork: string;
     tree: string;
     login: string;