bashkit 0.3.0 → 0.3.2

package/dist/index.js

@@ -65,8 +65,25 @@ function createLazySingleton(factory) {
   };
 }
 
+// src/sandbox/ripgrep.ts
+async function getBundledRgPath() {
+  try {
+    const { rgPath } = await import("@vscode/ripgrep");
+    return rgPath;
+  } catch {
+    return;
+  }
+}
+function getBundledRgPathSync() {
+  try {
+    const { rgPath } = __require("@vscode/ripgrep");
+    return rgPath;
+  } catch {
+    return;
+  }
+}
+
 // src/sandbox/ensure-tools.ts
-import { rgPath as bundledRgPath } from "@vscode/ripgrep";
 var RIPGREP_VERSION = "14.1.0";
 var ARCH_MAP = {
   x86_64: "x86_64-unknown-linux-musl",
@@ -74,10 +91,13 @@ var ARCH_MAP = {
   arm64: "aarch64-unknown-linux-gnu"
 };
 async function ensureSandboxTools(sandbox) {
-  const bundledCheck = await sandbox.exec(`test -x "${bundledRgPath}" && echo found`);
-  if (bundledCheck.stdout.includes("found")) {
-    sandbox.rgPath = bundledRgPath;
-    return;
+  const bundledRgPath = await getBundledRgPath();
+  if (bundledRgPath) {
+    const bundledCheck = await sandbox.exec(`test -x "${bundledRgPath}" && echo found`);
+    if (bundledCheck.stdout.includes("found")) {
+      sandbox.rgPath = bundledRgPath;
+      return;
+    }
   }
   const tmpCheck = await sandbox.exec("test -x /tmp/rg && echo found");
   if (tmpCheck.stdout.includes("found")) {
@@ -229,9 +249,9 @@ async function createE2BSandbox(config = {}) {
 }
 // src/sandbox/local.ts
 import { existsSync, mkdirSync } from "node:fs";
-import { rgPath as bundledRgPath2 } from "@vscode/ripgrep";
 function createLocalSandbox(config = {}) {
   const workingDirectory = config.cwd || "/tmp";
+  const rgPath = getBundledRgPathSync();
   if (!existsSync(workingDirectory)) {
     mkdirSync(workingDirectory, { recursive: true });
   }
@@ -271,7 +291,7 @@ function createLocalSandbox(config = {}) {
   };
   return {
     exec,
-    rgPath: bundledRgPath2,
+    rgPath,
     async readFile(path) {
       const fullPath = path.startsWith("/") ? path : `${workingDirectory}/${path}`;
       const file = Bun.file(fullPath);
@@ -595,6 +615,184 @@ var DEFAULT_CONFIG = {
 // src/tools/ask-user.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
+
+// src/utils/debug.ts
+import { appendFileSync } from "node:fs";
+var state = {
+  mode: "off",
+  logs: [],
+  counters: new Map,
+  parentStack: []
+};
+var MAX_STRING_LENGTH = 1000;
+var MAX_ARRAY_ITEMS = 10;
+function initDebugMode() {
+  const envValue = process.env.BASHKIT_DEBUG;
+  if (!envValue) {
+    state.mode = "off";
+    return;
+  }
+  if (envValue === "1" || envValue === "stderr") {
+    state.mode = "stderr";
+  } else if (envValue === "json") {
+    state.mode = "json";
+  } else if (envValue === "memory") {
+    state.mode = "memory";
+  } else if (envValue.startsWith("file:")) {
+    state.mode = "file";
+    state.filePath = envValue.slice(5);
+  } else {
+    state.mode = "stderr";
+  }
+}
+initDebugMode();
+function isDebugEnabled() {
+  return state.mode !== "off";
+}
+function generateId(tool) {
+  const count = (state.counters.get(tool) || 0) + 1;
+  state.counters.set(tool, count);
+  return `${tool}-${count}`;
+}
+function truncateString(str) {
+  if (str.length <= MAX_STRING_LENGTH)
+    return str;
+  return `${str.slice(0, MAX_STRING_LENGTH)}... [truncated, ${str.length - MAX_STRING_LENGTH} more chars]`;
+}
+function summarize(data, depth = 0) {
+  if (depth > 5)
+    return "[nested object]";
+  if (data === null || data === undefined)
+    return data;
+  if (typeof data === "string") {
+    return truncateString(data);
+  }
+  if (typeof data === "number" || typeof data === "boolean") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    const truncated = data.length > MAX_ARRAY_ITEMS;
+    const items = data.slice(0, MAX_ARRAY_ITEMS).map((item) => summarize(item, depth + 1));
+    if (truncated) {
+      return [...items, `[${data.length - MAX_ARRAY_ITEMS} more items]`];
+    }
+    return items;
+  }
+  if (typeof data === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      result[key] = summarize(value, depth + 1);
+    }
+    return result;
+  }
+  return String(data);
+}
+function emitEvent(event) {
+  if (state.mode === "off")
+    return;
+  switch (state.mode) {
+    case "memory":
+      state.logs.push(event);
+      break;
+    case "json":
+      process.stderr.write(`${JSON.stringify(event)}
+`);
+      break;
+    case "file":
+      if (state.filePath) {
+        appendFileSync(state.filePath, `${JSON.stringify(event)}
+`);
+      }
+      break;
+    case "stderr":
+    default:
+      formatHumanReadable(event);
+      break;
+  }
+}
+function formatHumanReadable(event) {
+  const indent = "  ".repeat(state.parentStack.length);
+  if (event.event === "start") {
+    const inputSummary = event.input ? Object.entries(event.input).map(([k, v]) => `${k}=${JSON.stringify(v)}`).slice(0, 3).join(" ") : "";
+    process.stderr.write(`${indent}[bashkit:${event.tool}] → ${inputSummary}
+`);
+  } else if (event.event === "end") {
+    const summaryStr = event.summary ? Object.entries(event.summary).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(" ") : "";
+    process.stderr.write(`${indent}[bashkit:${event.tool}] ← ${event.duration_ms}ms ${summaryStr}
+`);
+  } else if (event.event === "error") {
+    process.stderr.write(`${indent}[bashkit:${event.tool}] ✗ ${event.error}
+`);
+  }
+}
+function debugStart(tool, input) {
+  if (state.mode === "off")
+    return "";
+  const id = generateId(tool);
+  const parent = state.parentStack.length > 0 ? state.parentStack[state.parentStack.length - 1] : undefined;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "start",
+    input: input ? summarize(input) : undefined,
+    parent
+  };
+  emitEvent(event);
+  return id;
+}
+function debugEnd(id, tool, options) {
+  if (state.mode === "off" || !id)
+    return;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "end",
+    output: options.output ? summarize(options.output) : undefined,
+    summary: options.summary,
+    duration_ms: options.duration_ms
+  };
+  emitEvent(event);
+}
+function debugError(id, tool, error) {
+  if (state.mode === "off" || !id)
+    return;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "error",
+    error: error instanceof Error ? error.message : error
+  };
+  emitEvent(event);
+}
+function pushParent(id) {
+  if (state.mode === "off" || !id)
+    return;
+  state.parentStack.push(id);
+}
+function popParent() {
+  if (state.mode === "off")
+    return;
+  state.parentStack.pop();
+}
+function getDebugLogs() {
+  return [...state.logs];
+}
+function clearDebugLogs() {
+  state.logs = [];
+  state.counters.clear();
+  state.parentStack = [];
+}
+function reinitDebugMode() {
+  state.logs = [];
+  state.counters.clear();
+  state.parentStack = [];
+  initDebugMode();
+}
+
+// src/tools/ask-user.ts
 var questionOptionSchema = z.object({
   label: z.string().describe("The display text for this option. Should be concise (1-5 words). Add '(Recommended)' suffix for suggested options."),
   description: z.string().optional().describe("Explanation of what this option means or its implications.")
@@ -644,22 +842,46 @@ function createAskUserTool(config) {
     description: ASK_USER_DESCRIPTION,
     inputSchema: zodSchema(askUserInputSchema),
     execute: async (input) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("ask-user", {
+        hasQuestion: !!input.question,
+        questionCount: input.questions?.length ?? 0,
+        question: input.question ? input.question.length > 100 ? `${input.question.slice(0, 100)}...` : input.question : undefined
+      }) : "";
       try {
         if (!input.question && !input.questions) {
-          return {
-            error: "Either 'question' or 'questions' must be provided"
-          };
+          const error2 = "Either 'question' or 'questions' must be provided";
+          if (debugId)
+            debugError(debugId, "ask-user", error2);
+          return { error: error2 };
         }
         if (input.questions && input.questions.length > 0) {
           if (normalizedConfig.onStructuredQuestions) {
             const answers = await normalizedConfig.onStructuredQuestions(input.questions);
             const firstKey = Object.keys(answers)[0];
             const firstAnswer = answers[firstKey];
+            const durationMs2 = Math.round(performance.now() - startTime);
+            if (debugId) {
+              debugEnd(debugId, "ask-user", {
+                summary: {
+                  type: "structured",
+                  answerCount: Object.keys(answers).length
+                },
+                duration_ms: durationMs2
+              });
+            }
             return {
               answer: Array.isArray(firstAnswer) ? firstAnswer.join(", ") : firstAnswer,
               answers
             };
           }
+          const durationMs = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "ask-user", {
+              summary: { type: "structured", awaiting: true },
+              duration_ms: durationMs
+            });
+          }
           return {
             questions: input.questions,
             awaiting_response: true
@@ -668,18 +890,36 @@ function createAskUserTool(config) {
         if (input.question) {
           if (normalizedConfig.onQuestion) {
             const answer = await normalizedConfig.onQuestion(input.question);
+            const durationMs2 = Math.round(performance.now() - startTime);
+            if (debugId) {
+              debugEnd(debugId, "ask-user", {
+                summary: { type: "simple", hasAnswer: true },
+                duration_ms: durationMs2
+              });
+            }
             return { answer };
           }
+          const durationMs = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "ask-user", {
+              summary: { type: "simple", awaiting: true },
+              duration_ms: durationMs
+            });
+          }
           return {
             question: input.question,
             awaiting_response: true
           };
         }
-        return { error: "No question provided" };
+        const error = "No question provided";
+        if (debugId)
+          debugError(debugId, "ask-user", error);
+        return { error };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "ask-user", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -743,12 +983,18 @@ function createBashTool(sandbox, config) {
       description: _description,
       run_in_background: _run_in_background
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("bash", {
+        command: command.length > 200 ? `${command.slice(0, 200)}...` : command,
+        timeout
+      }) : "";
       if (config?.blockedCommands) {
         for (const blocked of config.blockedCommands) {
           if (command.includes(blocked)) {
-            return {
-              error: `Command blocked: contains '${blocked}'`
-            };
+            const error = `Command blocked: contains '${blocked}'`;
+            if (debugId)
+              debugError(debugId, "bash", error);
+            return { error };
           }
         }
       }
@@ -767,6 +1013,18 @@ function createBashTool(sandbox, config) {
           stderr = stderr.slice(0, maxOutputLength) + `
 [output truncated, ${stderr.length - maxOutputLength} chars omitted]`;
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "bash", {
+            summary: {
+              exitCode: result.exitCode,
+              stdoutLen: result.stdout.length,
+              stderrLen: result.stderr.length,
+              interrupted: result.interrupted
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           stdout,
           stderr,
@@ -775,9 +1033,10 @@ function createBashTool(sandbox, config) {
           duration_ms: result.durationMs
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "bash", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -822,29 +1081,48 @@ function createEditTool(sandbox, config) {
       new_string,
       replace_all = false
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("edit", {
+        file_path,
+        old_string: old_string.length > 100 ? `${old_string.slice(0, 100)}...` : old_string,
+        replace_all
+      }) : "";
       if (old_string === new_string) {
-        return { error: "old_string and new_string must be different" };
+        const error = "old_string and new_string must be different";
+        if (debugId)
+          debugError(debugId, "edit", error);
+        return { error };
       }
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
       }
       try {
         const exists = await sandbox.fileExists(file_path);
         if (!exists) {
-          return { error: `File not found: ${file_path}` };
+          const error = `File not found: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         const content = await sandbox.readFile(file_path);
         const occurrences = content.split(old_string).length - 1;
         if (occurrences === 0) {
-          return { error: `String not found in file: "${old_string}"` };
+          const error = `String not found in file: "${old_string}"`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         if (!replace_all && occurrences > 1) {
-          return {
-            error: `String appears ${occurrences} times in file. Use replace_all=true to replace all, or provide a more unique string.`
-          };
+          const error = `String appears ${occurrences} times in file. Use replace_all=true to replace all, or provide a more unique string.`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         let newContent;
         let replacements;
@@ -856,15 +1134,23 @@ function createEditTool(sandbox, config) {
           replacements = 1;
         }
         await sandbox.writeFile(file_path, newContent);
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "edit", {
+            summary: { replacements },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Successfully edited ${file_path}`,
           file_path,
           replacements
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "edit", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -931,33 +1217,44 @@ In plan mode, you'll:
 - This tool REQUIRES user approval - they must consent to entering plan mode
 - If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
 - Users appreciate being consulted before significant changes`;
-function createEnterPlanModeTool(state, onEnter) {
+function createEnterPlanModeTool(state2, onEnter) {
   return tool4({
     description: ENTER_PLAN_MODE_DESCRIPTION,
     inputSchema: zodSchema4(enterPlanModeInputSchema),
     execute: async ({
       reason
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("enter-plan-mode", { reason }) : "";
       try {
-        if (state.isActive) {
-          return {
-            error: "Already in planning mode. Use ExitPlanMode to exit."
-          };
+        if (state2.isActive) {
+          const error = "Already in planning mode. Use ExitPlanMode to exit.";
+          if (debugId)
+            debugError(debugId, "enter-plan-mode", error);
+          return { error };
         }
-        state.isActive = true;
-        state.enteredAt = new Date;
-        state.reason = reason;
+        state2.isActive = true;
+        state2.enteredAt = new Date;
+        state2.reason = reason;
         if (onEnter) {
           await onEnter(reason);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "enter-plan-mode", {
+            summary: { mode: "planning" },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Entered planning mode: ${reason}. Use Read, Grep, and Glob to explore. Call ExitPlanMode when ready with a plan.`,
           mode: "planning"
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "enter-plan-mode", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -997,19 +1294,32 @@ function createExitPlanModeTool(onPlanSubmit) {
     execute: async ({
       plan
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("exit-plan-mode", {
+        planLength: plan.length,
+        planPreview: plan.length > 200 ? `${plan.slice(0, 200)}...` : plan
+      }) : "";
       try {
         let approved;
         if (onPlanSubmit) {
           approved = await onPlanSubmit(plan);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "exit-plan-mode", {
+            summary: { approved },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: approved ? "Plan approved, proceeding with execution" : "Plan submitted for review",
           approved
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "exit-plan-mode", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1042,28 +1352,47 @@ function createGlobTool(sandbox, config) {
       path
     }) => {
       const searchPath = path || ".";
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("glob", { pattern, path: searchPath }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => searchPath.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${searchPath}` };
+          const error = `Path not allowed: ${searchPath}`;
+          if (debugId)
+            debugError(debugId, "glob", error);
+          return { error };
         }
       }
       try {
-        const result = await sandbox.exec(`find ${searchPath} -type f -name "${pattern}" 2>/dev/null | head -1000`, { timeout: config?.timeout });
+        const findFlag = pattern.includes("/") ? "-path" : "-name";
+        const findPattern = pattern.includes("/") && !pattern.startsWith("*") ? `*/${pattern}` : pattern;
+        const result = await sandbox.exec(`find ${searchPath} -type f ${findFlag} "${findPattern}" 2>/dev/null | head -1000`, { timeout: config?.timeout });
         if (result.exitCode !== 0 && result.stderr) {
-          return { error: result.stderr };
+          const error = result.stderr;
+          if (debugId)
+            debugError(debugId, "glob", error);
+          return { error };
         }
         const matches = result.stdout.split(`
 `).filter(Boolean).map((p) => p.trim());
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "glob", {
+            summary: { count: matches.length },
+            output: matches.slice(0, 10),
+            duration_ms: durationMs
+          });
+        }
         return {
           matches,
           count: matches.length,
           search_path: searchPath
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "glob", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1130,17 +1459,31 @@ function createGrepTool(sandbox, config) {
         multiline
       } = input;
       const searchPath = path || ".";
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("grep", {
+        pattern,
+        path: searchPath,
+        output_mode,
+        glob,
+        type,
+        caseInsensitive,
+        multiline
+      }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => searchPath.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${searchPath}` };
+          const error = `Path not allowed: ${searchPath}`;
+          if (debugId)
+            debugError(debugId, "grep", error);
+          return { error };
         }
       }
       try {
         if (!sandbox.rgPath) {
-          return {
-            error: "Ripgrep not available. Call ensureSandboxTools(sandbox) before using Grep with remote sandboxes."
-          };
+          const error = "Ripgrep not available. Call ensureSandboxTools(sandbox) before using Grep with remote sandboxes.";
+          if (debugId)
+            debugError(debugId, "grep", error);
+          return { error };
         }
         const cmd = buildRipgrepCommand({
           rgPath: sandbox.rgPath,
@@ -1156,17 +1499,48 @@ function createGrepTool(sandbox, config) {
           multiline
         });
         const result = await sandbox.exec(cmd, { timeout: config?.timeout });
+        const durationMs = Math.round(performance.now() - startTime);
+        let output;
         if (output_mode === "files_with_matches") {
-          return parseFilesOutput(result.stdout);
+          output = parseFilesOutput(result.stdout);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                fileCount: output.count,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         } else if (output_mode === "count") {
-          return parseCountOutput(result.stdout);
+          output = parseCountOutput(result.stdout);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                total: output.total,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         } else {
-          return parseContentOutput(result.stdout, head_limit, offset);
+          output = parseContentOutput(result.stdout, head_limit, offset);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                matchCount: output.total_matches,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         }
+        return output;
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "grep", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1357,20 +1731,35 @@ function createReadTool(sandbox, config) {
       offset,
       limit
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("read", { file_path, offset, limit }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
       }
       try {
         const exists = await sandbox.fileExists(file_path);
         if (!exists) {
-          return { error: `Path not found: ${file_path}` };
+          const error = `Path not found: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
         const isDir = await sandbox.isDirectory(file_path);
         if (isDir) {
           const entries = await sandbox.readDir(file_path);
+          const durationMs2 = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "read", {
+              summary: { type: "directory", count: entries.length },
+              duration_ms: durationMs2
+            });
+          }
           return {
             type: "directory",
             entries,
@@ -1396,9 +1785,10 @@ function createReadTool(sandbox, config) {
             "dylib"
           ];
           if (binaryExtensions.includes(ext || "")) {
-            return {
-              error: `Cannot read binary file: ${file_path} (file exists, ${content.length} bytes). Use appropriate tools to process ${ext?.toUpperCase()} files (e.g., Python scripts for PDFs).`
-            };
+            const error = `Cannot read binary file: ${file_path} (file exists, ${content.length} bytes). Use appropriate tools to process ${ext?.toUpperCase()} files (e.g., Python scripts for PDFs).`;
+            if (debugId)
+              debugError(debugId, "read", error);
+            return { error };
           }
         }
         const allLines = content.split(`
@@ -1406,9 +1796,10 @@ function createReadTool(sandbox, config) {
         const totalLines = allLines.length;
         const maxLinesWithoutLimit = config?.maxFileSize || 500;
         if (!limit && totalLines > maxLinesWithoutLimit) {
-          return {
-            error: `File is large (${totalLines} lines). Use 'offset' and 'limit' to read in chunks. Example: offset=1, limit=100 for first 100 lines.`
-          };
+          const error = `File is large (${totalLines} lines). Use 'offset' and 'limit' to read in chunks. Example: offset=1, limit=100 for first 100 lines.`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
         const startLine = offset ? offset - 1 : 0;
         const endLine = limit ? startLine + limit : allLines.length;
@@ -1417,6 +1808,18 @@ function createReadTool(sandbox, config) {
           line_number: startLine + i + 1,
           content: line
         }));
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "read", {
+            summary: {
+              type: "text",
+              totalLines,
+              returnedLines: lines.length,
+              bytes: content.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           type: "text",
           content: selectedLines.join(`
@@ -1425,9 +1828,10 @@ function createReadTool(sandbox, config) {
           total_lines: totalLines
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "read", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1461,22 +1865,29 @@ function createSkillTool(config) {
     execute: async ({
       name
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("skill", { name, availableSkills: Object.keys(skills) }) : "";
       try {
         const skill = skills[name];
         if (!skill) {
           const available = Object.keys(skills);
           if (available.length === 0) {
-            return { error: "No skills are available." };
+            const error2 = "No skills are available.";
+            if (debugId)
+              debugError(debugId, "skill", error2);
+            return { error: error2 };
           }
-          return {
-            error: `Skill '${name}' not found. Available skills: ${available.join(", ")}`
-          };
+          const error = `Skill '${name}' not found. Available skills: ${available.join(", ")}`;
+          if (debugId)
+            debugError(debugId, "skill", error);
+          return { error };
         }
         let instructions;
         if (!sandbox) {
-          return {
-            error: `Cannot load skill '${name}': no sandbox provided to read ${skill.path}`
-          };
+          const error = `Cannot load skill '${name}': no sandbox provided to read ${skill.path}`;
+          if (debugId)
+            debugError(debugId, "skill", error);
+          return { error };
         }
         const content = await sandbox.readFile(skill.path);
         const frontmatterEnd = content.indexOf(`
@@ -1489,6 +1900,17 @@ function createSkillTool(config) {
         if (onActivate) {
           await onActivate(skill, instructions);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "skill", {
+            summary: {
+              skillName: skill.name,
+              instructionLength: instructions.length,
+              hasAllowedTools: !!skill.allowedTools
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           name: skill.name,
           instructions,
@@ -1496,9 +1918,10 @@ function createSkillTool(config) {
           message: skill.allowedTools ? `Skill '${name}' activated. Restricted to tools: ${skill.allowedTools.join(", ")}` : `Skill '${name}' activated. Follow the instructions below.`
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "skill", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1593,6 +2016,11 @@ function createWebFetchTool(config) {
     providerOptions,
     execute: async (input) => {
       const { url, prompt } = input;
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("web-fetch", {
+        url,
+        prompt: prompt.length > 200 ? `${prompt.slice(0, 200)}...` : prompt
+      }) : "";
       try {
         const { content, finalUrl } = await fetchContent(url, apiKey, provider);
         const result = await generateText({
@@ -1603,6 +2031,16 @@ Content from ${url}:
 
 ${content}`
         });
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "web-fetch", {
+            summary: {
+              contentLength: content.length,
+              responseLength: result.text.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           response: result.text,
           url,
@@ -1612,15 +2050,18 @@ ${content}`
         if (error && typeof error === "object" && "status" in error) {
           const statusCode = error.status;
           const message = error.message || "API request failed";
+          if (debugId)
+            debugError(debugId, "web-fetch", `${message} (status: ${statusCode})`);
           return {
             error: message,
             status_code: statusCode,
             retryable: RETRYABLE_STATUS_CODES.includes(statusCode)
           };
         }
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "web-fetch", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1716,12 +2157,22 @@ function createWebSearchTool(config) {
     providerOptions,
     execute: async (input) => {
       const { query, allowed_domains, blocked_domains } = input;
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("web-search", { query, allowed_domains, blocked_domains }) : "";
       try {
         const results = await searchContent(apiKey, provider, {
           query,
           allowedDomains: allowed_domains,
           blockedDomains: blocked_domains
         });
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "web-search", {
+            summary: { resultCount: results.length },
+            output: results.slice(0, 5).map((r) => ({ title: r.title, url: r.url })),
+            duration_ms: durationMs
+          });
+        }
         return {
           results,
           total_results: results.length,
@@ -1731,15 +2182,18 @@ function createWebSearchTool(config) {
         if (error && typeof error === "object" && "status" in error) {
           const statusCode = error.status;
           const message = error.message || "API request failed";
+          if (debugId)
+            debugError(debugId, "web-search", `${message} (status: ${statusCode})`);
           return {
             error: message,
             status_code: statusCode,
             retryable: RETRYABLE_STATUS_CODES.includes(statusCode)
           };
         }
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "web-search", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1775,29 +2229,43 @@ function createWriteTool(sandbox, config) {
       file_path,
       content
     }) => {
+      const startTime = performance.now();
       const byteLength = Buffer.byteLength(content, "utf-8");
+      const debugId = isDebugEnabled() ? debugStart("write", { file_path, contentLength: byteLength }) : "";
       if (config?.maxFileSize && byteLength > config.maxFileSize) {
-        return {
-          error: `File content exceeds maximum size of ${config.maxFileSize} bytes (got ${byteLength})`
-        };
+        const error = `File content exceeds maximum size of ${config.maxFileSize} bytes (got ${byteLength})`;
+        if (debugId)
+          debugError(debugId, "write", error);
+        return { error };
       }
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "write", error);
+          return { error };
         }
       }
       try {
         await sandbox.writeFile(file_path, content);
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "write", {
+            summary: { bytes_written: byteLength },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Successfully wrote to ${file_path}`,
           bytes_written: byteLength,
           file_path
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "write", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1844,16 +2312,22 @@ var eventCounter = 0;
 function generateEventId() {
   return `subagent-${Date.now()}-${++eventCounter}`;
 }
-function filterTools(allTools, allowedTools) {
-  if (!allowedTools)
-    return allTools;
-  const filtered = {};
-  for (const name of allowedTools) {
-    if (allTools[name]) {
-      filtered[name] = allTools[name];
+function filterTools(allTools, allowedTools, additionalTools) {
+  let result;
+  if (allowedTools) {
+    result = {};
+    for (const name of allowedTools) {
+      if (allTools[name]) {
+        result[name] = allTools[name];
+      }
     }
+  } else {
+    result = allTools;
   }
-  return filtered;
+  if (additionalTools) {
+    result = { ...result, ...additionalTools };
+  }
+  return result;
 }
 function createTaskTool(config) {
   const {
@@ -1875,10 +2349,20 @@ function createTaskTool(config) {
       tools: customTools
     }) => {
       const startTime = performance.now();
+      const typeConfig = subagentTypes[subagent_type] || {};
+      const debugId = isDebugEnabled() ? debugStart("task", {
+        subagent_type,
+        description,
+        tools: [
+          ...customTools ?? typeConfig.tools ?? Object.keys(allTools),
+          ...Object.keys(typeConfig.additionalTools ?? {})
+        ]
+      }) : "";
+      if (debugId)
+        pushParent(debugId);
       try {
-        const typeConfig = subagentTypes[subagent_type] || {};
         const model = typeConfig.model || defaultModel;
-        const tools = filterTools(allTools, customTools ?? typeConfig.tools);
+        const tools = filterTools(allTools, customTools ?? typeConfig.tools, typeConfig.additionalTools);
         const systemPrompt = system_prompt ?? typeConfig.systemPrompt;
         const commonOptions = {
           model,
@@ -1949,6 +2433,19 @@ function createTaskTool(config) {
             }
           });
           const durationMs2 = Math.round(performance.now() - startTime);
+          if (debugId) {
+            popParent();
+            debugEnd(debugId, "task", {
+              summary: {
+                tokens: {
+                  input: usage2.inputTokens,
+                  output: usage2.outputTokens
+                },
+                steps: response.messages?.length
+              },
+              duration_ms: durationMs2
+            });
+          }
           return {
             result: text,
             usage: usage2.inputTokens !== undefined && usage2.outputTokens !== undefined ? {
@@ -1976,6 +2473,19 @@ function createTaskTool(config) {
           input_tokens: result.usage.inputTokens,
           output_tokens: result.usage.outputTokens
         } : undefined;
+        if (debugId) {
+          popParent();
+          debugEnd(debugId, "task", {
+            summary: {
+              tokens: {
+                input: result.usage.inputTokens,
+                output: result.usage.outputTokens
+              },
+              steps: result.steps?.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           result: result.text,
           usage,
@@ -1985,6 +2495,10 @@ function createTaskTool(config) {
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId) {
+          popParent();
+          debugError(debugId, "task", errorMessage);
+        }
         return { error: errorMessage };
       }
     }
@@ -2032,15 +2546,22 @@ var TODO_WRITE_DESCRIPTION = `Use this tool to create and manage a structured ta
 - Keep exactly ONE task in_progress at any time
 - ONLY mark completed when FULLY accomplished
 - If blocked/errors, keep in_progress and create new task for the blocker`;
-function createTodoWriteTool(state, onUpdate) {
+function createTodoWriteTool(state2, onUpdate) {
   return tool14({
     description: TODO_WRITE_DESCRIPTION,
     inputSchema: zodSchema14(todoWriteInputSchema),
     execute: async ({
       todos
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("todo-write", {
+        todoCount: todos.length,
+        pending: todos.filter((t) => t.status === "pending").length,
+        in_progress: todos.filter((t) => t.status === "in_progress").length,
+        completed: todos.filter((t) => t.status === "completed").length
+      }) : "";
       try {
-        state.todos = todos;
+        state2.todos = todos;
         if (onUpdate) {
           onUpdate(todos);
         }
@@ -2050,14 +2571,22 @@ function createTodoWriteTool(state, onUpdate) {
           in_progress: todos.filter((t) => t.status === "in_progress").length,
           completed: todos.filter((t) => t.status === "completed").length
         };
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "todo-write", {
+            summary: stats,
+            duration_ms: durationMs
+          });
+        }
         return {
           message: "Todo list updated successfully",
           stats
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "todo-write", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -2306,20 +2835,20 @@ function pruneMessagesByTokens(messages, config) {
 }
 
 // src/utils/compact-conversation.ts
-async function compactConversation(messages, config, state = { conversationSummary: "" }) {
+async function compactConversation(messages, config, state2 = { conversationSummary: "" }) {
   const currentTokens = estimateMessagesTokens(messages);
   const threshold = config.compactionThreshold ?? 0.85;
   const limit = config.maxTokens * threshold;
   if (currentTokens < limit) {
-    return { messages, state, didCompact: false };
+    return { messages, state: state2, didCompact: false };
   }
   const protectCount = config.protectRecentMessages ?? 10;
   const recentMessages = messages.slice(-protectCount);
   const oldMessages = messages.slice(0, -protectCount);
   if (oldMessages.length === 0) {
-    return { messages, state, didCompact: false };
+    return { messages, state: state2, didCompact: false };
   }
-  const newSummary = await summarizeMessages(oldMessages, config.summarizerModel, config.taskContext, state.conversationSummary);
+  const newSummary = await summarizeMessages(oldMessages, config.summarizerModel, config.taskContext, state2.conversationSummary);
   const compactedMessages = [
     {
       role: "user",
@@ -2854,10 +3383,13 @@ async function createDirectory(sandbox, path) {
 export {
   skillsToXml,
   setupAgentEnvironment,
+  reinitDebugMode,
   pruneMessagesByTokens,
   parseSkillMetadata,
   loadSkillBundles,
   loadSkillBundle,
+  isDebugEnabled,
+  getDebugLogs,
   getContextStatus,
   fetchSkills,
   fetchSkill,
@@ -2889,6 +3421,7 @@ export {
   contextNeedsCompaction,
   contextNeedsAttention,
   compactConversation,
+  clearDebugLogs,
   cached,
   anthropicPromptCacheMiddlewareV2,
   anthropicPromptCacheMiddleware,