@pencil-agent/nano-pencil 1.14.3 → 1.14.5

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.14.3",
-  "commitHash": "1a4f55a",
+  "version": "1.14.5",
+  "commitHash": "5845e2c",
   "branch": "main",
-  "builtAt": "2026-05-27T01:43:40.032Z"
+  "builtAt": "2026-05-28T06:36:42.739Z"
 }

package/dist/cli/args.d.ts

@@ -4,7 +4,7 @@
  * [TO]: Consumed by main.ts, core/model-resolver.ts
  * [HERE]: cli/args.ts - CLI argument parsing and help display
  */
-import type { ThinkingLevel } from "@pencil-agent/agent-core";
+import { type AgentLoopFrameworkInput, type AgentLoopPolicyOptions, type ThinkingLevel } from "@pencil-agent/agent-core";
 import { type ToolName } from "../core/tools/index.js";
 export type Mode = "text" | "json" | "rpc";
 export interface Args {
@@ -29,6 +29,16 @@ export interface Args {
     extensions?: string[];
     noExtensions?: boolean;
     print?: boolean;
+    /** In text print mode, emit the final agent loop result as stderr JSON. */
+    printLoopResult?: boolean;
+    /** In print mode, exit non-zero when the final agent result is an error. */
+    failOnAgentError?: boolean;
+    /** In print mode, exit non-zero when any tool permission denial occurred. */
+    failOnToolDenial?: boolean;
+    /** Non-persistent agent loop framework override for this process/session. */
+    agentLoopFramework?: AgentLoopFrameworkInput;
+    /** Non-persistent loop policy overrides for this process/session. */
+    loopPolicy?: Pick<AgentLoopPolicyOptions, "maxTurnsPerPrompt" | "maxToolCallsPerPrompt" | "maxToolConcurrency" | "maxToolResultBatchSizeChars" | "outputTokenBudget" | "maxOutputTokenRecoveryAttempts" | "maxModelErrorRecoveryAttempts" | "maxStopHookContinuations">;
     export?: string;
     noSkills?: boolean;
     skills?: string[];

package/dist/cli/args.js

@@ -1,3 +1,10 @@
+/**
+ * [WHO]: Args, Mode, parseArgs(), printHelp()
+ * [FROM]: Depends on agent-core, chalk, config.ts, core/tools
+ * [TO]: Consumed by main.ts, core/model-resolver.ts
+ * [HERE]: cli/args.ts - CLI argument parsing and help display
+ */
+import { normalizeAgentLoopFramework, } from "@pencil-agent/agent-core";
 import chalk from "chalk";
 import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
 import { allTools } from "../core/tools/index.js";
@@ -5,12 +12,45 @@ const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh
 export function isValidThinkingLevel(level) {
     return VALID_THINKING_LEVELS.includes(level);
 }
+function parseAgentLoopFramework(value) {
+    const normalized = normalizeAgentLoopFramework(value);
+    if (normalized === "standard" || normalized === "weak-model-compatible") {
+        return normalized;
+    }
+    return undefined;
+}
+function parsePositiveIntegerOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a positive integer.`));
+    return undefined;
+}
+function parseNonNegativeIntegerOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed >= 0)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a non-negative integer.`));
+    return undefined;
+}
+function parseUnitIntervalOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0 && parsed <= 1)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a number in (0, 1].`));
+    return undefined;
+}
+function setLoopPolicyOption(result, key, value) {
+    result.loopPolicy = result.loopPolicy ?? {};
+    result.loopPolicy[key] = value;
+}
 export function parseArgs(args, extensionFlags) {
     const result = {
         messages: [],
         fileArgs: [],
         unknownFlags: new Map(),
     };
+    const outputTokenBudget = {};
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
@@ -89,6 +129,75 @@ export function parseArgs(args, extensionFlags) {
         else if (arg === "--print" || arg === "-p") {
             result.print = true;
         }
+        else if (arg === "--print-loop-result") {
+            result.printLoopResult = true;
+        }
+        else if (arg === "--fail-on-agent-error") {
+            result.failOnAgentError = true;
+        }
+        else if (arg === "--fail-on-tool-denial") {
+            result.failOnToolDenial = true;
+        }
+        else if (arg === "--agent-loop" && i + 1 < args.length) {
+            const framework = args[++i];
+            const normalized = parseAgentLoopFramework(framework);
+            if (normalized) {
+                result.agentLoopFramework = normalized;
+            }
+            else {
+                console.error(chalk.yellow(`Warning: Invalid agent loop framework "${framework}". Valid values: standard, weak-model-compatible.`));
+            }
+        }
+        else if (arg === "--max-turns-per-prompt" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxTurnsPerPrompt", value);
+        }
+        else if (arg === "--max-tool-calls-per-prompt" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolCallsPerPrompt", value);
+        }
+        else if (arg === "--max-tool-concurrency" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolConcurrency", value);
+        }
+        else if (arg === "--max-tool-result-batch-size-chars" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolResultBatchSizeChars", value);
+        }
+        else if (arg === "--output-token-budget" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.targetTokens = value;
+        }
+        else if (arg === "--output-token-budget-threshold" && i + 1 < args.length) {
+            const value = parseUnitIntervalOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.thresholdPct = value;
+        }
+        else if (arg === "--output-token-budget-continuations" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.maxContinuations = value;
+        }
+        else if (arg === "--max-output-token-recovery-attempts" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxOutputTokenRecoveryAttempts", value);
+        }
+        else if (arg === "--max-model-error-recovery-attempts" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxModelErrorRecoveryAttempts", value);
+        }
+        else if (arg === "--max-stop-hook-continuations" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxStopHookContinuations", value);
+        }
         else if (arg === "--export" && i + 1 < args.length) {
             result.export = args[++i];
         }
@@ -168,6 +277,13 @@ export function parseArgs(args, extensionFlags) {
             result.messages.push(arg);
         }
     }
+    if (outputTokenBudget.targetTokens !== undefined) {
+        setLoopPolicyOption(result, "outputTokenBudget", {
+            targetTokens: outputTokenBudget.targetTokens,
+            thresholdPct: outputTokenBudget.thresholdPct,
+            maxContinuations: outputTokenBudget.maxContinuations,
+        });
+    }
     return result;
 }
 export function printHelp() {
@@ -194,6 +310,20 @@ ${chalk.bold("Options:")}
   --append-system-prompt <text>  Append text or file contents to the system prompt
   --mode <mode>                  Output mode: text (default), json, or rpc
   --print, -p                    Non-interactive mode: process prompt and exit
+  --print-loop-result            In text print mode, write final loop result JSON to stderr
+  --fail-on-agent-error          In print mode, exit non-zero when final loop result is an error
+  --fail-on-tool-denial          In print mode, exit non-zero when tools were denied
+  --agent-loop <framework>       Override loop framework: standard or weak-model-compatible
+  --max-turns-per-prompt <n>     Stop a prompt after n assistant turns
+  --max-tool-calls-per-prompt <n> Stop a prompt after n tool calls
+  --max-tool-concurrency <n>     Max concurrent safe tool calls in compatible loop
+  --max-tool-result-batch-size-chars <n> Max aggregate tool result chars per turn
+  --output-token-budget <n>      Continue when final output is below n tokens
+  --output-token-budget-threshold <n> Continuation threshold ratio in (0,1], default loop policy
+  --output-token-budget-continuations <n> Max output-budget continuations
+  --max-output-token-recovery-attempts <n> Max recovery turns after output-token stops
+  --max-model-error-recovery-attempts <n> Max in-loop model error recoveries
+  --max-stop-hook-continuations <n> Max stop-hook validation continuations
   --continue, -c                 Continue previous session
   --resume, -r                   Select a session to resume
   --session <path>               Use specific session file

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/index.d.ts

@@ -8,6 +8,6 @@ export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from
 export { createExtensionRuntime, discoverAndLoadExtensions, loadExtensionFromFactory, loadExtensions, } from "./loader.js";
 export type { ExtensionErrorListener, ForkHandler, NavigateTreeHandler, NewSessionHandler, ShutdownHandler, SwitchSessionHandler, } from "./runner.js";
 export { ExtensionRunner } from "./runner.js";
-export type { AgentEndEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppAction, AppendEntryHandler, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditToolCallEvent, EditToolResultEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionForkEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WriteToolCallEvent, WriteToolResultEvent, } from "./types.js";
+export type { AgentEndEvent, AgentResultEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppAction, AppendEntryHandler, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditToolCallEvent, EditToolResultEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionForkEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WriteToolCallEvent, WriteToolResultEvent, } from "./types.js";
 export { isBashToolResult, isEditToolResult, isFindToolResult, isGrepToolResult, isLsToolResult, isReadToolResult, isToolCallEventType, isWriteToolResult, } from "./types.js";
 export { wrapRegisteredTool, wrapRegisteredTools, wrapToolsWithExtensions, wrapToolWithExtensions, } from "./wrapper.js";

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") {