@mrclrchtr/supi-debug 5.0.0 → 6.0.0

package/README.md

@@ -27,7 +27,7 @@ pi install ./packages/supi-debug
 After install, this package wires the shared debug registry into three user-facing surfaces:
 
 - `/supi-debug` — show recent debug events in a readable TUI report
-- `supi_debug` — let the model query recent debug events during troubleshooting
+- `debug` — let the model query recent debug events during troubleshooting
 - `/supi-settings` integration — configure whether events are captured and how much data is exposed
 
 It also registers a **Debug** provider section for `/supi-context`, and ships a `/supi-tooling-retro` prompt template for post-task retrospective feedback on the SuPi tooling used in the completed task.
@@ -78,14 +78,14 @@ keeps the conversation focused; expand only when you need the details.
 
 ### Seeing full details without expanding
 
-The agent-facing `supi_debug` tool returns the expanded plain-text
+The agent-facing `debug` tool returns the expanded plain-text
 representation, subject to PI's standard tool-output truncation limits. This is
 useful for automated troubleshooting flows while protecting the model context
 from very large event payloads.
 
 ## Filters
 
-Both `/supi-debug` and `supi_debug` support the same basic filters:
+Both `/supi-debug` and `debug` support the same basic filters:
 
 - `source`
 - `level`
@@ -93,7 +93,7 @@ Both `/supi-debug` and `supi_debug` support the same basic filters:
 - exact `operationId`
 - `limit`
 
-For historical sessions, pass `sessionFile` to `supi_debug`, or
+For historical sessions, pass `sessionFile` to `debug`, or
 `sessionFile=<path>` to `/supi-debug`. Historical sessions never retain raw data.
 The tool also accepts `includeRaw` for live-session data when settings allow it. A Debug Operation ID groups direct request ownership only. It is not a security identity, distributed trace, raw Pi Tool-call identity, or time-window correlation.
 
@@ -108,7 +108,7 @@ Available settings:
 - `maxEvents` — maximum retained events in memory
 
 Historical inspection works for events captured after this version is loaded. For example, an
-agent can call `supi_debug` with `sessionFile` set to a PI session JSONL path.
+agent can call `debug` with `sessionFile` set to a PI session JSONL path.
 
 Defaults come from the shared debug registry:
 

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
-    "./debug": "./src/debug-registry.ts",
+    "./debug": "./src/debug.ts",
     "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./evidence-badge.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,9 +4,6 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
-// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
-export * from "./debug-timing.ts";
-
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {

package/node_modules/@mrclrchtr/supi-core/src/debug.ts

@@ -0,0 +1,9 @@
+// Debug domain entry for `@mrclrchtr/supi-core/debug`.
+//
+// Kept separate from debug-registry.ts so debug-timing.ts can import the
+// registry without creating an import cycle through the barrel re-export.
+
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Capture and inspect SuPi debug events",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "5.0.0"
+    "@mrclrchtr/supi-core": "6.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/prompts/supi-tooling-retro.md

@@ -2,30 +2,35 @@
 description: Retrospect on SuPi tooling used during the completed task
 ---
 
-Produce a compact, evidence-based retrospective of the task that just ended. Evaluate SuPi-provided tools, skills, prompts, extensions, and injected context—not the entire suite in the abstract.
+Produce a compact, evidence-based retrospective of the task that just ended. Evaluate the SuPi surfaces that were available and relevant: tools, skills, prompts, extensions, injected context or guidance, documentation, settings, and human-only TUI commands. Do not evaluate the entire suite in the abstract. Do not evaluate pi-core behavior.
 
 ## Evidence rules
 
 - Reconstruct the retrospective from this session only. Do not invent tool calls, outcomes, failures, token costs, or user impact.
-- Tag claims as `[observed]`, `[inferred]`, or `[unknown]`. An observed claim is supported by the transcript or a tool result; an inferred claim is plausible but untested.
-- Use the exact surface name shown in the session. Do not treat a tool being available but unused as evidence that it failed.
-- If no SuPi surface was used or relevant, say so explicitly. Do not manufacture a wishlist; list only task-specific, plausible missed help.
-- Do not make tool calls or perform follow-up investigation. Stop after writing the retrospective.
+- You may query the `debug` tool to verify event-level claims. You may query `cache_forensics` when it is available to verify cache-related claims. Use such queries only for verification, and keep them few. Do not perform any other tool calls or follow-up investigation. Stop after you write the retrospective.
+- Tag every claim as `[observed]`, `[inferred]`, or `[unknown]`. An observed claim is supported by the transcript, a tool result, or an evidence query. An inferred claim is plausible but untested.
+- Rate the impact of each surfaced item as `high`, `medium`, or `low`. The impact is the degree to which the item changed the task outcome or its cost.
+- Use the exact surface name that appears in the session. Do not treat an available but unused tool as evidence of failure.
+- If no SuPi surface was used or relevant, say so explicitly. Do not build a wishlist. List only task-specific, plausible missed help.
 
 ## Evaluate
 
-- Actual SuPi surfaces used: what they enabled, where they fell short, and any failure or friction.
-- Missed opportunities: a relevant unused tool (like supi-code-intelligence tools) or context source, and why it was missed—discoverability, guidance, timing, capability, or not applicable.
+- SuPi surfaces that were actually used: what they enabled, where they fell short, and any failure or friction.
+- Failed or mis-parameterized tool calls: SuPi surface calls that failed or were rejected for wrong, missing, or invalid parameters, including calls corrected on retry. Name the cause: agent misuse, ambiguous tool description, missing guidance (promptSnippet or promptGuidelines), a schema gap, or a tool bug.
+- Recognized problems or bugs: concrete defects in SuPi surfaces, such as crashes, wrong output, failed calls for valid usage, regressions, inconsistent behavior, or guidance that led to a wrong action. Do not report defects in the project's own code.
+- Missed opportunities: a relevant unused tool (for example a supi-code-intelligence tool) or context source, and why it was missed. Name the cause: discoverability, guidance, timing, capability, or not applicable.
 - Missing pieces: a concrete utility, capability, documentation page, example, or output improvement that would have changed this task.
 - Noise: redundant instructions, repeated advice without added value, stale or irrelevant context, excessive output, unnecessary long paths, poor timing, or misleading guidance. Do not criticize necessary context without naming the avoidable cost.
-- Keep SuPi/tooling recommendations separate from general code or project recommendations.
+- Keep SuPi or tooling recommendations separate from general code or project recommendations.
 
 ## Output rules
 
-- Keep the result under about 500 words and specific to this task.
-- Prefer concrete evidence and observed friction over generic praise or a general feature wishlist.
-- If a section has no supported item, write `None identified` and explain the evidence limit briefly.
-- Include at most three recommendations. Each must name a changeable surface (tool, prompt, skill, docs, guidance, or feature), the proposed change, and the expected benefit. Do not recommend “use the tool more” unless discoverability is the identified cause.
+- Keep the result under about 600 words and specific to this task.
+- Open with a one-line overall verdict on SuPi tooling for this task.
+- Give each item a confidence tag and an impact rating. `None identified` lines need neither.
+- Prefer concrete evidence and observed friction over generic praise or a feature wishlist.
+- If a section has no supported item, write `None identified` and briefly explain the evidence limit.
+- Include at most three recommendations. Each must name a changeable surface (tool, prompt, skill, docs, guidance, or feature), the proposed change, and the expected benefit. Recommended changes may target tool descriptions, parameter schemas, or guidance, especially when they address the Failed or mis-parameterized tool calls listed above. Do not recommend "use the tool more" unless discoverability is the identified cause.
 - Do not edit files, open issues, update OpenSpec artifacts, or take any other follow-up action.
 
 ## Required output
@@ -34,29 +39,39 @@ Produce a compact, evidence-based retrospective of the task that just ended. Eva
 
 **Task completed**: <1–2 sentence summary>
 
+**Verdict**: <one line: the overall state of SuPi tooling for this task and its biggest lever>
+
 ### Tools used
-- `[observed]` **`<tool, skill, prompt, extension, or context>`** — concrete help, friction, or failure.
+- `[observed · impact: high|medium|low]` **`<surface>`** — concrete help, friction, or failure.
 - If none: `None identified — no SuPi surface materially participated in this task.`
 
+### Failed or mis-parameterized tool calls
+- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the call, the invalid or missing parameter, the outcome, and the cause: agent misuse, ambiguous description, missing guidance, schema gap, or tool bug. Include near misses: a call rejected once and corrected on retry is stronger evidence than a clean pass.
+- If none: `None identified — every SuPi call used valid parameters.`
+
+### Recognized problems or bugs
+- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the concrete defect (crash, wrong behavior, regression, inconsistency) and how it affected the task. Do not repeat ordinary friction that belongs under Tools used, and do not repeat parameter-caused call failures that belong under Failed or mis-parameterized tool calls.
+- If none: `None identified — no defect surfaced in this task.`
+
 ### Missed opportunities
-- `[inferred]` **`<surface>`** — task-specific help it might have provided; cause: discoverability, guidance, timing, capability, or not applicable.
+- `[inferred · impact: high|medium|low]` **`<surface>`** — task-specific help it might have provided. Name the cause: discoverability, guidance, timing, capability, or not applicable.
 - If none: `None identified — do not infer a gap from non-use alone.`
 
 ### Missing pieces
-- `[observed|inferred]` **`<utility, feature, docs, example, or output change>`** — the concrete gap and how it affected this task.
+- `[observed|inferred · impact: high|medium|low]` **`<utility, feature, docs, example, or output change>`** — the concrete gap and how it affected this task.
 - If none: `None identified.`
 
 ### Unhelpful or noisy context
-- `[observed]` **`<instruction, context, or output>`** — what was unnecessary or costly and how it could be reduced or better timed.
+- `[observed|inferred · impact: high|medium|low]` **`<instruction, context, or output>`** — what was unnecessary or costly, and how it could be reduced or better timed.
 - If none: `None identified.`
 
 ### Prioritized recommendations
 1. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
 2. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
 3. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
-- Include only supported recommendations; if none are supported, write `None identified`.
+- Include only supported recommendations. If none are supported, write `None identified`.
 
 ### Confidence / evidence
-- Direct evidence: <what the session demonstrates>
+- Direct evidence: <what the session and any evidence queries demonstrate>
 - Inference: <what is plausible but untested>
-- Limits: <what the session cannot establish>
+- Limits: <what the session cannot establish>

package/src/command.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getDebugEvents } from "@mrclrchtr/supi-core/debug";
 import { resolveToolPath } from "@mrclrchtr/supi-core/path";
-import { formatDebugEvents, truncateDebugOutput } from "./output.ts";
+import { formatDebugEvents, truncateDebugOutput } from "./format-events.ts";
 import type { DebugToolParams } from "./query.ts";
 import { parseDebugCommandArgs } from "./query.ts";
 import { createDebugMessageDetails } from "./renderer.ts";

package/src/config.ts

@@ -0,0 +1,83 @@
+// Debug config loading and live registry synchronization.
+
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import {
+  clearDebugEvents,
+  configureDebugRegistry,
+  DEBUG_REGISTRY_DEFAULTS,
+  type DebugAgentAccess,
+} from "@mrclrchtr/supi-core/debug";
+
+export const DEBUG_SECTION = "debug";
+
+export interface DebugConfig extends Record<string, unknown> {
+  enabled: boolean;
+  agentAccess: DebugAgentAccess;
+  maxEvents: number;
+}
+
+export const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
+
+function normalizeAgentAccess(value: string): DebugAgentAccess {
+  return value === "off" || value === "raw" ? value : "sanitized";
+}
+
+export function normalizeMaxEvents(value: string | number): number {
+  const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
+}
+
+function normalizeEnabled(value: unknown): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (
+      normalized === "true" ||
+      normalized === "on" ||
+      normalized === "1" ||
+      normalized === "yes"
+    ) {
+      return true;
+    }
+    if (
+      normalized === "false" ||
+      normalized === "off" ||
+      normalized === "0" ||
+      normalized === "no" ||
+      normalized === ""
+    ) {
+      return false;
+    }
+    return DEBUG_DEFAULTS.enabled;
+  }
+
+  if (value === 1) return true;
+  if (value === 0) return false;
+  return DEBUG_DEFAULTS.enabled;
+}
+
+export function loadDebugConfig(cwd: string): DebugConfig {
+  const config = loadSupiConfig(DEBUG_SECTION, cwd, DEBUG_DEFAULTS);
+  return {
+    enabled: normalizeEnabled(config.enabled),
+    agentAccess: normalizeAgentAccess(String(config.agentAccess)),
+    maxEvents: normalizeMaxEvents(config.maxEvents),
+  };
+}
+
+export function applyDebugConfig(cwd: string): DebugConfig {
+  const config = loadDebugConfig(cwd);
+  configureDebugRegistry(config);
+  return config;
+}
+
+export function syncLiveDebugRegistry(cwd: string): DebugConfig {
+  const config = applyDebugConfig(cwd);
+  if (!config.enabled) {
+    clearDebugEvents();
+  }
+  return config;
+}

package/src/debug.ts

@@ -1,112 +1,28 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { AgentToolUpdateCallback, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerContextProvider } from "@mrclrchtr/supi-core/context";
 import {
   clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  type DebugAgentAccess,
-  type DebugEventQuery,
-  type DebugEventView,
-  getDebugEvents,
   getDebugSummary,
-  isDebugOperationId,
   subscribeDebugEvents,
 } from "@mrclrchtr/supi-core/debug";
-import { resolveToolPath } from "@mrclrchtr/supi-core/path";
 import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
-import { Type } from "typebox";
 import { registerDebugCommand } from "./command.ts";
-import { formatDebugEvents, truncateDebugOutput } from "./output.ts";
-import type { DebugToolParams } from "./query.ts";
-import { createDebugRenderDetails } from "./render-details.ts";
 import {
-  registerDebugMessageRenderer,
-  renderDebugToolCall,
-  renderDebugToolResult,
-} from "./renderer.ts";
-import { DEBUG_EVENT_ENTRY_TYPE, readSessionDebugEvents } from "./session-events.ts";
+  applyDebugConfig,
+  DEBUG_DEFAULTS,
+  DEBUG_SECTION,
+  normalizeMaxEvents,
+  syncLiveDebugRegistry,
+} from "./config.ts";
+import { registerDebugMessageRenderer } from "./renderer.ts";
+import { DEBUG_EVENT_ENTRY_TYPE } from "./session-events.ts";
 import { maybeLogLoadStatus } from "./status-log.ts";
-import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
+import { registerDebugTool } from "./tool/debug/register.ts";
 
 const baseDir = dirname(dirname(fileURLToPath(import.meta.url)));
 
-const DEBUG_SECTION = "debug";
-interface DebugConfig extends Record<string, unknown> {
-  enabled: boolean;
-  agentAccess: DebugAgentAccess;
-  maxEvents: number;
-}
-
-const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
-
-function normalizeAgentAccess(value: string): DebugAgentAccess {
-  return value === "off" || value === "raw" ? value : "sanitized";
-}
-
-function normalizeMaxEvents(value: string | number): number {
-  const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
-}
-
-function normalizeEnabled(value: unknown): boolean {
-  if (typeof value === "boolean") {
-    return value;
-  }
-
-  if (typeof value === "string") {
-    const normalized = value.trim().toLowerCase();
-    if (
-      normalized === "true" ||
-      normalized === "on" ||
-      normalized === "1" ||
-      normalized === "yes"
-    ) {
-      return true;
-    }
-    if (
-      normalized === "false" ||
-      normalized === "off" ||
-      normalized === "0" ||
-      normalized === "no" ||
-      normalized === ""
-    ) {
-      return false;
-    }
-    return DEBUG_DEFAULTS.enabled;
-  }
-
-  if (value === 1) return true;
-  if (value === 0) return false;
-  return DEBUG_DEFAULTS.enabled;
-}
-
-function loadDebugConfig(cwd: string): DebugConfig {
-  const config = loadSupiConfig(DEBUG_SECTION, cwd, DEBUG_DEFAULTS);
-  return {
-    enabled: normalizeEnabled(config.enabled),
-    agentAccess: normalizeAgentAccess(String(config.agentAccess)),
-    maxEvents: normalizeMaxEvents(config.maxEvents),
-  };
-}
-
-function applyDebugConfig(cwd: string): DebugConfig {
-  const config = loadDebugConfig(cwd);
-  configureDebugRegistry(config);
-  return config;
-}
-
-function syncLiveDebugRegistry(cwd: string): DebugConfig {
-  const config = applyDebugConfig(cwd);
-  if (!config.enabled) {
-    clearDebugEvents();
-  }
-  return config;
-}
-
 function registerDebugSettings(pi: ExtensionAPI): void {
   registerSettings(
     pi,
@@ -158,106 +74,6 @@ function buildSummaryData(): Record<string, string | number> | null {
   return data;
 }
 
-interface DebugProgressDetails {
-  scannedLines: number;
-  persistedEventCount: number;
-  matchedEvents: number;
-}
-
-function reportDebugProgress(
-  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
-  progress: DebugProgressDetails,
-): void {
-  onUpdate?.({
-    content: [
-      {
-        type: "text",
-        text: `Reading persisted debug events: ${progress.matchedEvents} matching events found.`,
-      },
-    ],
-    details: progress,
-  });
-}
-
-interface DebugToolExecutionOptions {
-  config: DebugConfig;
-  cwd: string;
-  signal?: AbortSignal;
-  onUpdate?: AgentToolUpdateCallback<unknown>;
-}
-
-async function buildToolResult(params: DebugToolParams, options: DebugToolExecutionOptions) {
-  const { config, cwd, signal, onUpdate } = options;
-  if (!config.enabled && !params.sessionFile) {
-    throw new Error(
-      "SuPi debug event capture is disabled. Enable Debug in /supi-settings to retain events.",
-    );
-  }
-
-  if (config.agentAccess === "off") {
-    throw new Error("Agent access to SuPi debug events is disabled.");
-  }
-
-  const filters = {
-    operationId: params.operationId,
-    source: params.source,
-    level: params.level,
-    category: params.category,
-    limit: params.limit,
-  };
-  const query: DebugEventQuery = {
-    ...filters,
-    includeRaw: params.includeRaw,
-    allowRaw: config.agentAccess === "raw",
-  };
-  let events: DebugEventView[];
-  let rawAccessDenied: boolean;
-  let rawDataUnavailable = false;
-  let persistedEventCount: number | undefined;
-  if (params.sessionFile) {
-    const sessionFile = resolveToolPath(cwd, params.sessionFile);
-    const persisted =
-      signal || onUpdate
-        ? await readSessionDebugEvents(sessionFile, filters, {
-            signal,
-            onProgress: (progress) => reportDebugProgress(onUpdate, progress),
-          })
-        : await readSessionDebugEvents(sessionFile, filters);
-    events = persisted.events;
-    persistedEventCount = persisted.persistedEventCount;
-    rawAccessDenied = Boolean(params.includeRaw);
-    rawDataUnavailable = rawAccessDenied;
-  } else {
-    const result = getDebugEvents(query);
-    events = result.events;
-    rawAccessDenied = result.rawAccessDenied;
-  }
-  const output = truncateDebugOutput(
-    formatDebugEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
-  );
-  const details = createDebugRenderDetails(events, {
-    enabled: config.enabled,
-    agentAccess: config.agentAccess,
-    sessionFile: params.sessionFile,
-    rawAccessDenied,
-    rawDataUnavailable,
-    persistedEventCount,
-    eventCount: events.length,
-    emptyReason:
-      events.length === 0
-        ? persistedEventCount === 0
-          ? "no-persisted-events"
-          : "no-matches"
-        : undefined,
-    truncation: output.truncation,
-  });
-
-  return {
-    content: [{ type: "text" as const, text: output.text }],
-    details,
-  };
-}
-
 /** Register the shared SuPi debug command, settings, context summary, and agent tool. */
 export default function debugExtension(pi: ExtensionAPI) {
   applyDebugConfig(process.cwd());
@@ -290,45 +106,5 @@ export default function debugExtension(pi: ExtensionAPI) {
   });
 
   registerDebugCommand(pi, applyDebugConfig, normalizeMaxEvents);
-
-  pi.registerTool({
-    name: "supi_debug",
-    label: "SuPi Debug",
-    description: toolDescription,
-    promptSnippet,
-    promptGuidelines,
-    parameters: Type.Object({
-      operationId: Type.Optional(
-        Type.String({
-          description: "Filter by exact Debug Operation ID",
-          pattern: "^op-[A-Za-z0-9_-]{21}[AQgw]$",
-        }),
-      ),
-      source: Type.Optional(Type.String({ description: "Filter by extension source, e.g. lsp" })),
-      level: Type.Optional(
-        StringEnum(["debug", "info", "warning", "error"], {
-          description: "Filter by debug level",
-        }),
-      ),
-      category: Type.Optional(Type.String({ description: "Filter by event category" })),
-      limit: Type.Optional(Type.Number({ description: "Maximum number of events to return" })),
-      sessionFile: Type.Optional(
-        Type.String({ description: "PI session JSONL file containing persisted debug events" }),
-      ),
-      includeRaw: Type.Optional(
-        Type.Boolean({ description: "Request raw event data when settings permit it" }),
-      ),
-    }),
-    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      const query = params as DebugToolParams;
-      if (query.operationId !== undefined && !isDebugOperationId(query.operationId)) {
-        throw new Error("Invalid Debug Operation ID");
-      }
-      const config = applyDebugConfig(ctx.cwd);
-      return buildToolResult(query, { config, cwd: ctx.cwd, signal, onUpdate });
-    },
-    renderCall: renderDebugToolCall,
-    renderResult: renderDebugToolResult,
-  });
+  registerDebugTool(pi);
 }

package/src/renderer.ts

@@ -1,9 +1,7 @@
 import {
   type ExtensionAPI,
   formatSize,
-  keyHint,
   type Theme,
-  type ToolRenderResultOptions,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -20,55 +18,6 @@ const DEBUG_REPORT_TYPE = "supi-debug-report";
 const MAX_RENDER_LINES = 240;
 const MAX_RENDER_BYTES = 16 * 1024;
 
-interface DebugToolResult {
-  content?: Array<{ type: string; text?: string }>;
-  details?: unknown;
-}
-
-interface DebugCallArgs {
-  operationId?: unknown;
-  source?: unknown;
-  level?: unknown;
-  category?: unknown;
-  limit?: unknown;
-  sessionFile?: unknown;
-  includeRaw?: unknown;
-}
-
-function boundedCallValue(value: unknown, maxLength = 80): string | undefined {
-  if (typeof value !== "string" && typeof value !== "number") return undefined;
-  const text = String(value);
-  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}…` : text;
-}
-
-function formatCallArgs(args: unknown): string {
-  const input = (args ?? {}) as DebugCallArgs;
-  const filters: string[] = [];
-  const operationId = boundedCallValue(input.operationId);
-  const source = boundedCallValue(input.source);
-  const level = boundedCallValue(input.level);
-  const category = boundedCallValue(input.category);
-  const limit = boundedCallValue(input.limit);
-  const sessionFile = boundedCallValue(input.sessionFile);
-
-  if (operationId) filters.push(`operationId=${operationId}`);
-  if (source) filters.push(`source=${source}`);
-  if (level) filters.push(`level=${level}`);
-  if (category) filters.push(`category=${category}`);
-  if (limit) filters.push(`limit=${limit}`);
-  if (sessionFile) filters.push(`sessionFile=${sessionFile}`);
-  if (input.includeRaw === true) filters.push("raw");
-  return filters.join(" ");
-}
-
-/** Render the compact human-facing call header for `supi_debug`. */
-export function renderDebugToolCall(args: unknown, theme: Theme): Text {
-  const callArgs = formatCallArgs(args);
-  let content = theme.fg("toolTitle", "supi_debug");
-  if (callArgs) content += ` ${theme.fg("dim", callArgs)}`;
-  return new Text(content, 0, 0);
-}
-
 function formatLevel(theme: Theme, level: string): string {
   const color =
     level === "error"
@@ -162,7 +111,7 @@ function buildEventLines(details: DebugRenderDetails, theme: Theme): string[] {
   return lines;
 }
 
-function renderExpandedReport(details: DebugRenderDetails, theme: Theme): string {
+export function renderExpandedReport(details: DebugRenderDetails, theme: Theme): string {
   const notes = buildDetailNotes(details, theme);
   const noteText = notes.join("\n");
   const noteBytes = new TextEncoder().encode(noteText).byteLength;
@@ -177,55 +126,6 @@ function renderExpandedReport(details: DebugRenderDetails, theme: Theme): string
   return [...bodyLines, ...notes].join("\n");
 }
 
-function renderToolSummary(details: DebugRenderDetails, theme: Theme): string {
-  if (details.eventCount === 0) {
-    return details.emptyReason === "no-persisted-events"
-      ? theme.fg("muted", "No persisted debug events")
-      : theme.fg("muted", "No matching debug events");
-  }
-
-  let summary = `${details.eventCount} event${details.eventCount === 1 ? "" : "s"}`;
-  if (details.omittedEventCount > 0) summary += ` · ${details.omittedEventCount} omitted`;
-  if (details.eventDataTruncated) summary += " · data bounded";
-  if (details.truncation?.truncated) summary += " · output truncated";
-  if (details.rawDataUnavailable || details.rawAccessDenied) summary += " · raw unavailable";
-  return theme.fg("muted", summary);
-}
-
-function renderProgress(details: unknown, expanded: boolean, theme: Theme): Text {
-  const progress =
-    typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {};
-  const scannedLines =
-    typeof progress.scannedLines === "number" ? progress.scannedLines.toLocaleString("en-US") : "?";
-  const matchedEvents =
-    typeof progress.matchedEvents === "number"
-      ? progress.matchedEvents.toLocaleString("en-US")
-      : "?";
-  const line = `Reading persisted debug events… ${scannedLines} lines scanned · ${matchedEvents} matches`;
-  return new Text(theme.fg("warning", expanded ? line : "Reading persisted debug events…"), 0, 0);
-}
-
-/** Render the compact or expanded result for the `supi_debug` tool. */
-export function renderDebugToolResult(
-  result: DebugToolResult,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-  context: { isError: boolean },
-): Text {
-  if (options.isPartial) return renderProgress(result.details, options.expanded, theme);
-  if (context.isError) return new Text(theme.fg("error", "supi_debug failed"), 0, 0);
-
-  const details = readDebugRenderDetails(result.details);
-  if (!options.expanded) {
-    let summary = renderToolSummary(details, theme);
-    if (details.eventCount > 0)
-      summary += theme.fg("dim", ` ${keyHint("app.tools.expand", "to expand")}`);
-    return new Text(summary, 0, 0);
-  }
-
-  return new Text(renderExpandedReport(details, theme), 0, 0);
-}
-
 function renderEmptyMessage(content: unknown, details: DebugRenderDetails, theme: Theme): Text {
   const text =
     typeof content === "string"

package/src/tool/debug/execute.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isDebugOperationId } from "@mrclrchtr/supi-core/debug";
+import { applyDebugConfig } from "../../config.ts";
+import type { DebugToolParams } from "../../query.ts";
+import { buildToolResult } from "./result.ts";
+
+type DebugExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
+
+/** Build the debug tool execute function. */
+export function makeDebugExecute(): DebugExecute {
+  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+  return async (_toolCallId, params, signal, onUpdate, ctx) => {
+    const query = params as DebugToolParams;
+    if (query.operationId !== undefined && !isDebugOperationId(query.operationId)) {
+      throw new Error("Invalid Debug Operation ID");
+    }
+    const config = applyDebugConfig(ctx.cwd);
+    return buildToolResult(query, { config, cwd: ctx.cwd, signal, onUpdate });
+  };
+}

package/src/tool/{guidance.ts → debug/guidance.ts}

@@ -1,11 +1,11 @@
-// Prompt guidance and tool description for the supi_debug tool.
+// Prompt guidance and tool description for the debug tool.
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
 export const toolDescription = `Fetch recent SuPi debug events, or sanitized persisted events from a PI session JSONL via sessionFile, with optional exact Debug Operation ID and event filters. Raw data is available only for the live session when allowed. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first).`;
 
-export const promptSnippet = "supi_debug — fetch live or persisted SuPi debug events";
+export const promptSnippet = "debug — fetch live or persisted SuPi debug events";
 
 export const promptGuidelines = [
-  "Use supi_debug for SuPi failures, fallback reasons, or session debug events; pass sessionFile to inspect a prior session and request raw data only when explicitly asked and settings allow it.",
+  "Use debug for SuPi failures, fallback reasons, or session debug events; pass sessionFile to inspect a prior session and request raw data only when explicitly asked and settings allow it.",
 ];

package/src/tool/debug/register.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { renderDebugToolCall, renderDebugToolResult } from "./render.ts";
+import { debugSpec } from "./spec.ts";
+
+/** Register the debug agent tool. */
+export function registerDebugTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    ...debugSpec,
+    description: toolDescription,
+    promptSnippet,
+    promptGuidelines,
+    renderCall: renderDebugToolCall,
+    renderResult: renderDebugToolResult,
+  });
+}

package/src/tool/debug/render.ts

@@ -0,0 +1,105 @@
+/** Transcript renderers for the debug tool. */
+
+import { keyHint, type Theme, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type DebugRenderDetails, readDebugRenderDetails } from "../../render-details.ts";
+import { renderExpandedReport } from "../../renderer.ts";
+
+interface DebugToolResult {
+  content?: Array<{ type: string; text?: string }>;
+  details?: unknown;
+}
+
+interface DebugCallArgs {
+  operationId?: unknown;
+  source?: unknown;
+  level?: unknown;
+  category?: unknown;
+  limit?: unknown;
+  sessionFile?: unknown;
+  includeRaw?: unknown;
+}
+
+function boundedCallValue(value: unknown, maxLength = 80): string | undefined {
+  if (typeof value !== "string" && typeof value !== "number") return undefined;
+  const text = String(value);
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}…` : text;
+}
+
+function formatCallArgs(args: unknown): string {
+  const input = (args ?? {}) as DebugCallArgs;
+  const filters: string[] = [];
+  const operationId = boundedCallValue(input.operationId);
+  const source = boundedCallValue(input.source);
+  const level = boundedCallValue(input.level);
+  const category = boundedCallValue(input.category);
+  const limit = boundedCallValue(input.limit);
+  const sessionFile = boundedCallValue(input.sessionFile);
+
+  if (operationId) filters.push(`operationId=${operationId}`);
+  if (source) filters.push(`source=${source}`);
+  if (level) filters.push(`level=${level}`);
+  if (category) filters.push(`category=${category}`);
+  if (limit) filters.push(`limit=${limit}`);
+  if (sessionFile) filters.push(`sessionFile=${sessionFile}`);
+  if (input.includeRaw === true) filters.push("raw");
+  return filters.join(" ");
+}
+/** Render the compact human-facing call header for `debug`. */
+export function renderDebugToolCall(args: unknown, theme: Theme): Text {
+  const callArgs = formatCallArgs(args);
+  let content = theme.fg("toolTitle", "debug");
+  if (callArgs) content += ` ${theme.fg("dim", callArgs)}`;
+  return new Text(content, 0, 0);
+}
+
+function renderToolSummary(details: DebugRenderDetails, theme: Theme): string {
+  if (details.eventCount === 0) {
+    return details.emptyReason === "no-persisted-events"
+      ? theme.fg("muted", "No persisted debug events")
+      : theme.fg("muted", "No matching debug events");
+  }
+
+  let summary = `${details.eventCount} event${details.eventCount === 1 ? "" : "s"}`;
+  if (details.omittedEventCount > 0) summary += ` · ${details.omittedEventCount} omitted`;
+  if (details.eventDataTruncated) summary += " · data bounded";
+  if (details.truncation?.truncated) summary += " · output truncated";
+  if (details.rawDataUnavailable || details.rawAccessDenied) summary += " · raw unavailable";
+  return theme.fg("muted", summary);
+}
+
+function renderProgress(details: unknown, expanded: boolean, theme: Theme): Text {
+  const progress =
+    typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {};
+  const scannedLines =
+    typeof progress.scannedLines === "number" ? progress.scannedLines.toLocaleString("en-US") : "?";
+  const matchedEvents =
+    typeof progress.matchedEvents === "number"
+      ? progress.matchedEvents.toLocaleString("en-US")
+      : "?";
+  const line = `Reading persisted debug events… ${scannedLines} lines scanned · ${matchedEvents} matches`;
+  return new Text(theme.fg("warning", expanded ? line : "Reading persisted debug events…"), 0, 0);
+}
+
+/** Render the compact or expanded result for the `debug` tool. */
+
+/** Render the compact or expanded result for the `debug` tool. */
+export function renderDebugToolResult(
+  result: DebugToolResult,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  context: { isError: boolean },
+): Text {
+  if (options.isPartial) return renderProgress(result.details, options.expanded, theme);
+  if (context.isError) return new Text(theme.fg("error", "debug failed"), 0, 0);
+
+  const details = readDebugRenderDetails(result.details);
+  if (!options.expanded) {
+    let summary = renderToolSummary(details, theme);
+    if (details.eventCount > 0)
+      summary += theme.fg("dim", ` ${keyHint("app.tools.expand", "to expand")}`);
+    return new Text(summary, 0, 0);
+  }
+
+  return new Text(renderExpandedReport(details, theme), 0, 0);
+}

package/src/tool/debug/result.ts

@@ -0,0 +1,113 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import {
+  type DebugEventQuery,
+  type DebugEventView,
+  getDebugEvents,
+} from "@mrclrchtr/supi-core/debug";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
+import type { DebugConfig } from "../../config.ts";
+import { formatDebugEvents, truncateDebugOutput } from "../../format-events.ts";
+import type { DebugToolParams } from "../../query.ts";
+import { createDebugRenderDetails } from "../../render-details.ts";
+import { readSessionDebugEvents } from "../../session-events.ts";
+
+interface DebugProgressDetails {
+  scannedLines: number;
+  persistedEventCount: number;
+  matchedEvents: number;
+}
+
+function reportDebugProgress(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  progress: DebugProgressDetails,
+): void {
+  onUpdate?.({
+    content: [
+      {
+        type: "text",
+        text: `Reading persisted debug events: ${progress.matchedEvents} matching events found.`,
+      },
+    ],
+    details: progress,
+  });
+}
+
+export interface DebugToolExecutionOptions {
+  config: DebugConfig;
+  cwd: string;
+  signal?: AbortSignal;
+  onUpdate?: AgentToolUpdateCallback<unknown>;
+}
+
+/** Assemble the model-facing debug tool result for one query. */
+export async function buildToolResult(params: DebugToolParams, options: DebugToolExecutionOptions) {
+  const { config, cwd, signal, onUpdate } = options;
+  if (!config.enabled && !params.sessionFile) {
+    throw new Error(
+      "SuPi debug event capture is disabled. Enable Debug in /supi-settings to retain events.",
+    );
+  }
+
+  if (config.agentAccess === "off") {
+    throw new Error("Agent access to SuPi debug events is disabled.");
+  }
+
+  const filters = {
+    operationId: params.operationId,
+    source: params.source,
+    level: params.level,
+    category: params.category,
+    limit: params.limit,
+  };
+  const query: DebugEventQuery = {
+    ...filters,
+    includeRaw: params.includeRaw,
+    allowRaw: config.agentAccess === "raw",
+  };
+  let events: DebugEventView[];
+  let rawAccessDenied: boolean;
+  let rawDataUnavailable = false;
+  let persistedEventCount: number | undefined;
+  if (params.sessionFile) {
+    const sessionFile = resolveToolPath(cwd, params.sessionFile);
+    const persisted =
+      signal || onUpdate
+        ? await readSessionDebugEvents(sessionFile, filters, {
+            signal,
+            onProgress: (progress) => reportDebugProgress(onUpdate, progress),
+          })
+        : await readSessionDebugEvents(sessionFile, filters);
+    events = persisted.events;
+    persistedEventCount = persisted.persistedEventCount;
+    rawAccessDenied = Boolean(params.includeRaw);
+    rawDataUnavailable = rawAccessDenied;
+  } else {
+    const result = getDebugEvents(query);
+    events = result.events;
+    rawAccessDenied = result.rawAccessDenied;
+  }
+  const output = truncateDebugOutput(
+    formatDebugEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
+  );
+  const details = createDebugRenderDetails(events, {
+    enabled: config.enabled,
+    agentAccess: config.agentAccess,
+    sessionFile: params.sessionFile,
+    rawAccessDenied,
+    rawDataUnavailable,
+    persistedEventCount,
+    eventCount: events.length,
+    emptyReason:
+      events.length === 0
+        ? persistedEventCount === 0
+          ? "no-persisted-events"
+          : "no-matches"
+        : undefined,
+    truncation: output.truncation,
+  });
+
+  return {
+    content: [{ type: "text" as const, text: output.text }],
+    details,
+  };
+}

package/src/tool/debug/spec.ts

@@ -0,0 +1,35 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { makeDebugExecute } from "./execute.ts";
+
+export const DEBUG_TOOL_NAME = "debug";
+export const DEBUG_TOOL_LABEL = "SuPi Debug";
+
+/** Canonical provider-facing metadata for the debug tool. */
+export const debugSpec = {
+  name: DEBUG_TOOL_NAME,
+  label: DEBUG_TOOL_LABEL,
+  parameters: Type.Object({
+    operationId: Type.Optional(
+      Type.String({
+        description: "Filter by exact Debug Operation ID",
+        pattern: "^op-[A-Za-z0-9_-]{21}[AQgw]$",
+      }),
+    ),
+    source: Type.Optional(Type.String({ description: "Filter by extension source, e.g. lsp" })),
+    level: Type.Optional(
+      StringEnum(["debug", "info", "warning", "error"], {
+        description: "Filter by debug level",
+      }),
+    ),
+    category: Type.Optional(Type.String({ description: "Filter by event category" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of events to return" })),
+    sessionFile: Type.Optional(
+      Type.String({ description: "PI session JSONL file containing persisted debug events" }),
+    ),
+    includeRaw: Type.Optional(
+      Type.Boolean({ description: "Request raw event data when settings permit it" }),
+    ),
+  }),
+  execute: makeDebugExecute(),
+} as const;