feat: /debug v2.0

已将 VersperClaw 的 /debug 从被动日志阅读技能完全替换为 Openclaude /debug-mode 的主动插桩调试工作流。

改动文件

┌───────────────────────────────┬──────┬──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 文件 │ 操作 │ 说明 │
├───────────────────────────────┼──────┼──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ src/tools/DebugSessionTool.ts │ 新建 │ 移植自 Openclaude，管理 .versperclaw-debug/ 目录（init/begin_run/begin_verify/read_log/cleanup） │
├───────────────────────────────┼──────┼──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ src/tools.ts │ 修改 │ 导入并注册 DebugSessionTool 到工具列表 │
├───────────────────────────────┼──────┼──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ src/skills/bundled/debug.ts │ 重写 │ 从被动日志分析替换为 8 步 CHECKPOINT 工作流 │
└───────────────────────────────┴──────┴──────────────────────────────────────────────────────────────────────────────────────────────────┘

新 /debug 工作流

1. Step 0 — 确认 bug 信息完整
2. Step 1 — 阅读代码，制定探针计划
3. Step 2 — 用 DebugSession 工具初始化调试目录
4. Step 3 — 在源码插入 DEBUG PROBE 探针（支持 JS/TS/Python/Go/Rust 等）
5. Step 4 — 复现 bug，收集日志（多 RUN 对比）
6. Step 5 — 基于日志证据定位根因
7. Step 6 — 修复并用 VERIFY run 验证
8. Step 7 — 自动清理所有探针代码

与之前对比

- 之前：只读 session debug log，被动分析
- 现在：插桩 + 复现 + 验证闭环，主动诊断

src/skills/bundled/debug.ts

@@ -1,103 +1,204 @@
 import { open, stat } from 'fs/promises'
-import { VERSPER_CLAW_GUIDE_AGENT_TYPE } from 'src/tools/AgentTool/built-in/versperClawGuideAgent.js'
-import { getSettingsFilePathForSource } from 'src/utils/settings/settings.js'
-import { enableDebugLogging, getDebugLogPath } from '../../utils/debug.js'
-import { errorMessage, isENOENT } from '../../utils/errors.js'
-import { formatFileSize } from '../../utils/format.js'
+import { DEBUG_SESSION_TOOL_NAME } from 'src/tools/DebugSessionTool.js'
+import { AGENT_TOOL_NAME } from 'src/tools/AgentTool/constants.js'
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js'
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js'
 import { registerBundledSkill } from '../bundledSkills.js'
 
-const DEFAULT_DEBUG_LINES_READ = 20
-const TAIL_READ_BYTES = 64 * 1024
+const ALLOWED_TOOLS = [
+  FILE_READ_TOOL_NAME,
+  GLOB_TOOL_NAME,
+  GREP_TOOL_NAME,
+  FILE_EDIT_TOOL_NAME,
+  FILE_WRITE_TOOL_NAME,
+  BASH_TOOL_NAME,
+  AGENT_TOOL_NAME,
+  DEBUG_SESSION_TOOL_NAME,
+]
+
+const DEBUG_SESSION_DIR = '.versperclaw-debug'
+
+function buildDebugPrompt(args: string): string {
+  const issue = args.trim() || 'The user did not provide a bug description yet.'
+
+  return `# /debug - Runtime Debugging
+
+You are in VersperClaw debug mode. Debug mode is evidence-driven: insert temporary probes, collect runtime data, identify the root cause from logs, fix, verify, and clean up.
+
+Debug artifact directory: \`${DEBUG_SESSION_DIR}/\`
+Runtime log file: \`${DEBUG_SESSION_DIR}/debug.log\`
+Use the \`${DEBUG_SESSION_TOOL_NAME}\` tool to initialize the session, add run separators, read logs, add verify separators, and clean up the debug directory.
+
+## User Issue
+
+${issue}
+
+## Mandatory Checkpoints
+
+Print each checkpoint marker exactly before moving past that step:
+
+- \`CHECKPOINT 0: Context gathered\`
+- \`CHECKPOINT 1: Probe plan created - N probes planned\`
+- \`CHECKPOINT 2: Log collector initialized\`
+- \`CHECKPOINT 3: N probes inserted into source files\`
+- \`CHECKPOINT 4: N log entries collected\`
+- \`CHECKPOINT 5: Root cause identified with log evidence\`
+- \`CHECKPOINT 6: Fix applied and verified with probes\`
+- \`CHECKPOINT 7: All probes removed, cleanup complete\`
+
+Hard rules:
+
+1. Do not print CHECKPOINT 5 until checkpoints 1-4 are complete.
+2. Do not propose or apply a fix until you can cite specific collected log entries, except for asking the user for missing reproduction details.
+3. Probe insertion must use the Edit tool to physically add probe blocks to source files.
+4. Probe cleanup must use the Edit tool to remove every probe block.
+5. Before final response, grep for \`DEBUG PROBE\`; no probe code may remain.
+6. Use at most 3 instrumentation iterations. If still unresolved, summarize evidence and ask for the next reproduction clue.
+
+## Workflow
+
+### Step 0: Triage
+
+If the user did not provide expected behavior, actual behavior, reproduction steps, consistency, and relevant errors, ask only for the missing details. If enough context is already present, continue.
+
+After this, print:
+\`CHECKPOINT 0: Context gathered\`
+
+### Step 1: Understand and Plan Probes
+
+Read relevant code. Form 2-3 hypotheses. Plan minimal probes on critical paths.
+
+Output a compact table:
+
+| # | File:Line | Label | Variables | Hypothesis |
+|---|-----------|-------|-----------|------------|
+
+Choose logging strategy:
+
+- CLI, server, worker, script: file-based logging to \`${DEBUG_SESSION_DIR}/debug.log\`.
+- Browser or frontend-only: \`console.log\` probes with \`[DEBUG PROBE N]\`; ask the user to paste console output if it cannot be captured directly.
+
+Then print:
+\`CHECKPOINT 1: Probe plan created - N probes planned\`
+
+### Step 2: Initialize Debug Session
+
+Call \`${DEBUG_SESSION_TOOL_NAME}\` with \`{"action":"init"}\` for file-based or hybrid logging.
+
+Then print:
+\`CHECKPOINT 2: Log collector initialized\`
+
+### Step 3: Insert Probes
+
+Every probe block must include START and END markers:
+
+\`\`\`ts
+// DEBUG PROBE [1] label
+try {
+  require('fs').appendFileSync('${DEBUG_SESSION_DIR}/debug.log', \`[\${new Date().toISOString()}] [js] file.ts:42 | label | value=\${JSON.stringify(value)}\\n\`)
+} catch {}
+// DEBUG PROBE END [1]
+\`\`\`
+
+Python probe example:
+
+\`\`\`py
+# DEBUG PROBE [1] label
+try:
+    import datetime
+    open("${DEBUG_SESSION_DIR}/debug.log", "a").write(f"[{datetime.datetime.now().isoformat()}] [python] file.py:42 | label | value={value}\\n")
+except Exception:
+    pass
+# DEBUG PROBE END [1]
+\`\`\`
+
+Go probe example:
+
+\`\`\`go
+// DEBUG PROBE [1] label
+import "os"
+f, _ := os.OpenFile("${DEBUG_SESSION_DIR}/debug.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+if f != nil {
+    fmt.Fprintf(f, "[%s] [go] file.go:42 | label | value=%v\\n", time.Now().Format(time.RFC3339), value)
+    f.Close()
+}
+// DEBUG PROBE END [1]
+\`\`\`
+
+Rust probe example:
+
+\`\`\`rust
+// DEBUG PROBE [1] label
+{
+    use std::fs::OpenOptions;
+    use std::io::Write;
+    if let Ok(mut f) = OpenOptions::new().create(true).append(true).open("${DEBUG_SESSION_DIR}/debug.log") {
+        writeln!(f, "[{}] [rust] file.rs:42 | label | value={:?}", chrono::Utc::now().to_rfc3339(), value).ok();
+    }
+}
+// DEBUG PROBE END [1]
+\`\`\`
+
+For other languages, adapt the probe to that language's normal append-to-file API. Keep the same \`DEBUG PROBE [N]\` / \`DEBUG PROBE END [N]\` markers, timestamp, file:line, label, and observed variables.
+
+Probe code must observe only; it must not alter program behavior.
+If a probe requires a temporary import, include, or helper function, wrap that temporary addition in its own \`DEBUG PROBE [N]\` / \`DEBUG PROBE END [N]\` markers too.
+
+Then print:
+\`CHECKPOINT 3: N probes inserted into source files\`
+
+### Step 4: Reproduce and Collect Logs
+
+For file-based runs, call \`${DEBUG_SESSION_TOOL_NAME}\` with \`{"action":"begin_run","label":"short label"}\` before each reproduction command. Run the reproduction with Bash. For intermittent issues, collect 2-3 runs.
+
+Read logs with \`${DEBUG_SESSION_TOOL_NAME}\` using \`{"action":"read_log","tailLines":200}\`.
+
+Then print:
+\`CHECKPOINT 4: N log entries collected\`
+
+### Step 5: Analyze Evidence
+
+Analyze ordering, missing probes, unexpected values, duplicates, timing gaps, and before/after differences. Cite exact log lines.
+
+Then print:
+\`CHECKPOINT 5: Root cause identified with log evidence\`
+
+### Step 6: Fix and Verify
+
+Apply the smallest targeted fix. Keep probes in place. Call \`${DEBUG_SESSION_TOOL_NAME}\` with \`{"action":"begin_verify","label":"fix verification"}\`, rerun reproduction, then read logs again.
+
+Compare failing runs and VERIFY logs. The problematic value, ordering, or missing path must be corrected.
+
+Then print:
+\`CHECKPOINT 6: Fix applied and verified with probes\`
+
+### Step 7: Cleanup
+
+Remove all probe blocks from source files using Edit. Search with Grep for \`DEBUG PROBE\` and continue cleanup until there are zero matches. Then call \`${DEBUG_SESSION_TOOL_NAME}\` with \`{"action":"cleanup"}\`.
+
+Then print:
+\`CHECKPOINT 7: All probes removed, cleanup complete\`
+
+## Final Response
+
+Summarize the root cause, the log evidence, the fix, the verification result, and cleanup status.`
+}
 
 export function registerDebugSkill(): void {
   registerBundledSkill({
     name: 'debug',
     description:
-      process.env.USER_TYPE === 'ant'
-        ? 'Debug your current VersperClaw session by reading the session debug log. Includes all event logging'
-        : 'Enable debug logging for this session and help diagnose issues',
-    allowedTools: ['Read', 'Grep', 'Glob'],
-    argumentHint: '[issue description]',
-    // disableModelInvocation so that the user has to explicitly request it in
-    // interactive mode and so the description does not take up context.
+      'Runtime debug mode: insert temporary probes, collect logs, identify root cause, fix, verify, and clean up.',
+    allowedTools: ALLOWED_TOOLS,
+    argumentHint: '<bug description>',
     disableModelInvocation: true,
     userInvocable: true,
     async getPromptForCommand(args) {
-      // Non-ants don't write debug logs by default — turn logging on now so
-      // subsequent activity in this session is captured.
-      const wasAlreadyLogging = enableDebugLogging()
-      const debugLogPath = getDebugLogPath()
-
-      let logInfo: string
-      try {
-        // Tail the log without reading the whole thing - debug logs grow
-        // unbounded in long sessions and reading them in full spikes RSS.
-        const stats = await stat(debugLogPath)
-        const readSize = Math.min(stats.size, TAIL_READ_BYTES)
-        const startOffset = stats.size - readSize
-        const fd = await open(debugLogPath, 'r')
-        try {
-          const { buffer, bytesRead } = await fd.read({
-            buffer: Buffer.alloc(readSize),
-            position: startOffset,
-          })
-          const tail = buffer
-            .toString('utf-8', 0, bytesRead)
-            .split('\n')
-            .slice(-DEFAULT_DEBUG_LINES_READ)
-            .join('\n')
-          logInfo = `Log size: ${formatFileSize(stats.size)}\n\n### Last ${DEFAULT_DEBUG_LINES_READ} lines\n\n\`\`\`\n${tail}\n\`\`\``
-        } finally {
-          await fd.close()
-        }
-      } catch (e) {
-        logInfo = isENOENT(e)
-          ? 'No debug log exists yet — logging was just enabled.'
-          : `Failed to read last ${DEFAULT_DEBUG_LINES_READ} lines of debug log: ${errorMessage(e)}`
-      }
-
-      const justEnabledSection = wasAlreadyLogging
-        ? ''
-        : `
-## Debug Logging Just Enabled
-
-Debug logging was OFF for this session until now. Nothing prior to this /debug invocation was captured.
-
-Tell the user that debug logging is now active at \`${debugLogPath}\`, ask them to reproduce the issue, then re-read the log. If they can't reproduce, they can also restart with \`claude --debug\` to capture logs from startup.
-`
-
-      const prompt = `# Debug Skill
-
-Help the user debug an issue they're encountering in this current VersperClaw session.
-${justEnabledSection}
-## Session Debug Log
-
-The debug log for the current session is at: \`${debugLogPath}\`
-
-${logInfo}
-
-For additional context, grep for [ERROR] and [WARN] lines across the full file.
-
-## Issue Description
-
-${args || 'The user did not describe a specific issue. Read the debug log and summarize any errors, warnings, or notable issues.'}
-
-## Settings
-
-Remember that settings are in:
-* user - ${getSettingsFilePathForSource('userSettings')}
-* project - ${getSettingsFilePathForSource('projectSettings')}
-* local - ${getSettingsFilePathForSource('localSettings')}
-
-## Instructions
-
-1. Review the user's issue description
-2. The last ${DEFAULT_DEBUG_LINES_READ} lines show the debug file format. Look for [ERROR] and [WARN] entries, stack traces, and failure patterns across the file
-3. Consider launching the ${VERSPER_CLAW_GUIDE_AGENT_TYPE} subagent to understand the relevant Claude Code features
-4. Explain what you found in plain language
-5. Suggest concrete fixes or next steps
-`
-      return [{ type: 'text', text: prompt }]
+      return [{ type: 'text', text: buildDebugPrompt(args) }]
     },
   })
 }

src/tools.ts

@@ -78,6 +78,7 @@ import { LSPTool } from './tools/LSPTool/LSPTool.js'
 import { ListMcpResourcesTool } from './tools/ListMcpResourcesTool/ListMcpResourcesTool.js'
 import { ReadMcpResourceTool } from './tools/ReadMcpResourceTool/ReadMcpResourceTool.js'
 import { ToolSearchTool } from './tools/ToolSearchTool/ToolSearchTool.js'
+import { DebugSessionTool } from './tools/DebugSessionTool.js'
 import { FriendEmotionTool } from './tools/FriendEmotionTool.js'
 import { FriendScreenObserveTool } from './tools/FriendScreenObserveTool.js'
 import { EnterPlanModeTool } from './tools/EnterPlanModeTool/EnterPlanModeTool.js'
@@ -247,6 +248,8 @@ export function getAllBaseTools(): Tools {
     ...(getPowerShellTool() ? [getPowerShellTool()] : []),
     ...(SnipTool ? [SnipTool] : []),
     ...(process.env.NODE_ENV === 'test' ? [TestingPermissionTool] : []),
+    // Debug session tool — used by /debug for runtime probe debugging
+    DebugSessionTool,
     // Friend VRM desktop pet tools — enabled when the plugin is active
     FriendEmotionTool,
     FriendScreenObserveTool,

src/tools/DebugSessionTool.ts

@@ -0,0 +1,315 @@
+/**
+ * DebugSessionTool — manage the .versperclaw-debug runtime debugging directory.
+ *
+ * Ported from Openclaude's DebugSessionTool.
+ * Used by /debug to manage log sessions, separators, tail-reading, and cleanup.
+ */
+import { appendFile, mkdir, open, readFile, rm, stat, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../Tool.js'
+import { getCwd } from '../utils/cwd.js'
+import { lazySchema } from '../utils/lazySchema.js'
+import { jsonStringify } from '../utils/slowOperations.js'
+
+export const DEBUG_SESSION_TOOL_NAME = 'DebugSession'
+const DEBUG_SESSION_DIR = '.versperclaw-debug'
+const DEBUG_SESSION_LOG_FILE = 'debug.log'
+const DEBUG_SESSION_STATE_FILE = 'state'
+
+const DEFAULT_TAIL_LINES = 200
+const MAX_TAIL_LINES = 1000
+const TAIL_READ_BYTES = 512 * 1024
+
+type DebugState = {
+  runCount: number
+}
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    action: z
+      .enum(['init', 'begin_run', 'begin_verify', 'read_log', 'cleanup'])
+      .describe('Debug session action to perform.'),
+    label: z
+      .string()
+      .max(120)
+      .optional()
+      .describe('Optional label for run or verification separators.'),
+    tailLines: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TAIL_LINES)
+      .optional()
+      .describe('Number of log lines to read for read_log. Default: 200.'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+type Input = z.infer<InputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    success: z.boolean(),
+    action: z.enum(['init', 'begin_run', 'begin_verify', 'read_log', 'cleanup']),
+    debugDir: z.string(),
+    logFile: z.string(),
+    message: z.string(),
+    runNumber: z.number().optional(),
+    log: z.string().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+function getPaths() {
+  const cwd = getCwd()
+  const debugDir = join(cwd, DEBUG_SESSION_DIR)
+  return {
+    cwd,
+    debugDir,
+    logFile: join(debugDir, DEBUG_SESSION_LOG_FILE),
+    stateFile: join(debugDir, DEBUG_SESSION_STATE_FILE),
+  }
+}
+
+function formatLabel(label: string | undefined): string {
+  const trimmed = label?.trim()
+  return trimmed ? ` | ${trimmed.replace(/\s+/g, ' ')}` : ''
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return (error as { code?: string } | null)?.code === code
+}
+
+function isENOENT(error: unknown): boolean {
+  return hasErrorCode(error, 'ENOENT')
+}
+
+async function ensureDebugDir(): Promise<ReturnType<typeof getPaths>> {
+  const paths = getPaths()
+  await mkdir(paths.debugDir, { recursive: true })
+  return paths
+}
+
+async function ensureStateFile(stateFile: string): Promise<void> {
+  const fh = await open(stateFile, 'a')
+  await fh.close()
+}
+
+function parseDebugState(content: string): DebugState {
+  const trimmed = content.trim()
+  if (!trimmed) return { runCount: 0 }
+
+  try {
+    const parsed = JSON.parse(trimmed) as { runCount?: unknown }
+    if (
+      typeof parsed.runCount === 'number' &&
+      Number.isInteger(parsed.runCount) &&
+      parsed.runCount >= 0
+    ) {
+      return { runCount: parsed.runCount }
+    }
+  } catch {
+    // Fall back to the legacy run_count=N format below.
+  }
+
+  const legacyMatch = trimmed.match(/run_count=(\d+)/)
+  if (legacyMatch) {
+    return { runCount: Number.parseInt(legacyMatch[1]!, 10) }
+  }
+
+  return { runCount: 0 }
+}
+
+async function readDebugState(stateFile: string): Promise<DebugState> {
+  try {
+    const content = await readFile(stateFile, 'utf8')
+    return parseDebugState(content)
+  } catch (error) {
+    if (isENOENT(error)) return { runCount: 0 }
+    throw error
+  }
+}
+
+async function writeDebugState(
+  stateFile: string,
+  state: DebugState,
+): Promise<void> {
+  await writeFile(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+async function readLogTail(logFile: string, tailLines: number): Promise<string> {
+  let stats
+  try {
+    stats = await stat(logFile)
+  } catch (error) {
+    if (isENOENT(error)) return ''
+    throw error
+  }
+
+  const readSize = Math.min(stats.size, TAIL_READ_BYTES)
+  if (readSize === 0) return ''
+
+  const fd = await open(logFile, 'r')
+  try {
+    const { buffer, bytesRead } = await fd.read({
+      buffer: Buffer.alloc(readSize),
+      position: stats.size - readSize,
+    })
+    return buffer
+      .toString('utf8', 0, bytesRead)
+      .split('\n')
+      .slice(-tailLines)
+      .join('\n')
+  } finally {
+    await fd.close()
+  }
+}
+
+export const DebugSessionTool = buildTool({
+  name: DEBUG_SESSION_TOOL_NAME,
+  searchHint: 'manage runtime debug log sessions',
+  maxResultSizeChars: 200_000,
+  strict: true,
+  async description() {
+    return 'Manage the fixed .versperclaw-debug runtime debugging directory, log separators, log reading, and cleanup.'
+  },
+  async prompt() {
+    return `Use ${DEBUG_SESSION_TOOL_NAME} only during /debug runtime debugging.
+
+Actions:
+- init: create .versperclaw-debug/, reset debug.log, and reset the run counter.
+- begin_run: append a RUN #N separator before reproducing the bug.
+- begin_verify: append a VERIFY separator before validating a fix.
+- read_log: read the tail of debug.log.
+- cleanup: delete .versperclaw-debug/ after all DEBUG PROBE blocks have been removed from source files.`
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isReadOnly(input: Input) {
+    return input.action === 'read_log'
+  },
+  toAutoClassifierInput(input: Input) {
+    return input.action
+  },
+  userFacingName() {
+    return 'DebugSession'
+  },
+  getActivityDescription(input) {
+    const action = input?.action ?? 'debug'
+    return `Managing debug session: ${action}`
+  },
+  renderToolUseMessage(input) {
+    return `Debug session ${input.action ?? 'operation'}`
+  },
+  async checkPermissions(input, context) {
+    if (input.action === 'read_log') {
+      return { behavior: 'allow' as const, updatedInput: input }
+    }
+    // For non-read actions, check if the tool is in the always-allow list
+    const rules = context.getAppState().toolPermissionContext.alwaysAllowRules.command
+    if (rules?.some(rule => rule === '*' || rule === DEBUG_SESSION_TOOL_NAME)) {
+      return { behavior: 'allow' as const, updatedInput: input }
+    }
+    return {
+      behavior: 'ask' as const,
+      message: `Run debug session action: ${input.action}`,
+    }
+  },
+  async call(input: Input) {
+    const tailLines = input.tailLines ?? DEFAULT_TAIL_LINES
+
+    if (input.action === 'cleanup') {
+      const paths = getPaths()
+      await rm(paths.debugDir, { recursive: true, force: true })
+      return {
+        data: {
+          success: true,
+          action: input.action,
+          debugDir: paths.debugDir,
+          logFile: paths.logFile,
+          message: `Removed ${DEBUG_SESSION_DIR}/`,
+        },
+      }
+    }
+
+    if (input.action === 'read_log') {
+      const paths = getPaths()
+      const log = await readLogTail(paths.logFile, tailLines)
+      return {
+        data: {
+          success: true,
+          action: input.action,
+          debugDir: paths.debugDir,
+          logFile: paths.logFile,
+          log,
+          message: log
+            ? `Read last ${tailLines} lines from ${DEBUG_SESSION_LOG_FILE}`
+            : `${DEBUG_SESSION_LOG_FILE} is empty or has not been created yet`,
+        },
+      }
+    }
+
+    const paths = await ensureDebugDir()
+
+    if (input.action === 'init') {
+      await writeFile(paths.logFile, '', 'utf8')
+      await writeDebugState(paths.stateFile, { runCount: 0 })
+      return {
+        data: {
+          success: true,
+          action: input.action,
+          debugDir: paths.debugDir,
+          logFile: paths.logFile,
+          message: `Initialized ${DEBUG_SESSION_DIR}/`,
+        },
+      }
+    }
+
+    if (input.action === 'begin_run') {
+      await ensureStateFile(paths.stateFile)
+      const state = await readDebugState(paths.stateFile)
+      const runNumber = state.runCount + 1
+      await writeDebugState(paths.stateFile, { runCount: runNumber })
+      const separator = `\n========== RUN #${runNumber}${formatLabel(input.label)} | ${new Date().toISOString()} ==========\n`
+      await appendFile(paths.logFile, separator, 'utf8')
+      return {
+        data: {
+          success: true,
+          action: input.action,
+          debugDir: paths.debugDir,
+          logFile: paths.logFile,
+          runNumber,
+          message: `Started RUN #${runNumber}`,
+        },
+      }
+    }
+
+    if (input.action === 'begin_verify') {
+      const separator = `\n========== VERIFY${formatLabel(input.label)} | ${new Date().toISOString()} ==========\n`
+      await appendFile(paths.logFile, separator, 'utf8')
+      return {
+        data: {
+          success: true,
+          action: input.action,
+          debugDir: paths.debugDir,
+          logFile: paths.logFile,
+          message: 'Started VERIFY run',
+        },
+      }
+    }
+
+    const _exhaustive: never = input.action
+    return _exhaustive
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: jsonStringify(output),
+    }
+  },
+} satisfies ToolDef<InputSchema, OutputSchema>)